agent-project-analyzer-docs.facet

@system
  id: "agent.docs.pro.v1.0"
  version: "1.0"
  title: "Project Analyzer & Professional Docs Writer"
  description: "Scans a local project, builds a structured understanding (files, modules, APIs), and generates production-quality documentation: README, ARCHITECTURE, API Reference, CONTRIBUTING, CHANGELOG, and docs/ with ToC. Deterministic, terminal-first, multilingual input."
  locale: "en-US"
  safety:
    dry_run: false
    confirm_dangerous_ops: false
    allow_network: false
  io:
    shell: "/bin/bash"
    project_root: "${PROJECT_PATH:-$PWD}"

@env
  required: {}
  optional:
    PROJECT_PATH: "$PWD"                  # Root of the repository to analyze
    OUTPUT_DIR: "docs"                    # Where to write documentation
    EXCLUDE: "node_modules|dist|build|.git|.venv|target|out"
    PROJECT_NAME: "${PROJECT_NAME:-$(basename "$PWD")}"
    DEFAULT_LICENSE: "MIT"
    AUTHOR: "${AUTHOR:-Unknown Author}"
    YEAR: "$(date +%Y)"
    DEFAULT_LOCALE: "en-US"
    MAX_TOC_DEPTH: "3"
    README_SECTIONS: "overview,features,quickstart,usage,configuration,api,architecture,contributing,license"

@lenses
  trim(s:str) -> str
  kebab_case(s:str) -> str
  non_empty(x:any) -> any
  dedent(s:str) -> str
  squeeze_spaces(s:str) -> str
  limit(s:str, n:int) -> str

@fs
  template "readme.md":
    mode: "create_or_overwrite"
    path: "{{($.env.OUTPUT_DIR ?? 'docs') | trim}}/../README.md"
    content: |
      # {{ $.env.PROJECT_NAME | trim }}

      > Professional documentation generated by **agent.docs.pro.v1.0**.

      ## Overview
      {{ overview | dedent | trim }}

      ## Features
      {{ features | dedent | trim }}

      ## Quickstart
      {{ quickstart | dedent | trim }}

      ## Usage
      {{ usage | dedent | trim }}

      ## Configuration
      {{ configuration | dedent | trim }}

      ## API Reference
      See [docs/API.md](docs/API.md).

      ## Architecture
      See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).

      ## Contributing
      See [docs/CONTRIBUTING.md](docs/CONTRIBUTING.md).

      ## License
      {{ license_text | dedent | trim }}

  template "docs_architecture.md":
    mode: "create_or_overwrite"
    path: "{{($.env.OUTPUT_DIR ?? 'docs') | trim}}/ARCHITECTURE.md"
    content: |
      # Architecture

      **Project:** {{ $.env.PROJECT_NAME | trim }}

      ## System Diagram (textual)
      {{ system_diagram | dedent | trim }}

      ## Components
      {{ components | dedent | trim }}

      ## Data Flow
      {{ data_flow | dedent | trim }}

      ## Dependencies
      {{ dependencies | dedent | trim }}

      ## Build & Deploy
      {{ build_deploy | dedent | trim }}

  template "docs_api.md":
    mode: "create_or_overwrite"
    path: "{{($.env.OUTPUT_DIR ?? 'docs') | trim}}/API.md"
    content: |
      # API Reference

      {{ api_reference | dedent | trim }}

  template "docs_contributing.md":
    mode: "create_or_overwrite"
    path: "{{($.env.OUTPUT_DIR ?? 'docs') | trim}}/CONTRIBUTING.md"
    content: |
      # Contributing

      {{ contributing | dedent | trim }}

  template "docs_changelog.md":
    mode: "create_or_overwrite"
    path: "{{($.env.OUTPUT_DIR ?? 'docs') | trim}}/CHANGELOG.md"
    content: |
      # Changelog

      {{ changelog | dedent | trim }}

  template "docs_index.md":
    mode: "create_or_overwrite"
    path: "{{($.env.OUTPUT_DIR ?? 'docs') | trim}}/index.md"
    content: |
      # Documentation Index

      - [API](API.md)
      - [Architecture](ARCHITECTURE.md)
      - [Contributing](CONTRIBUTING.md)
      - [Changelog](CHANGELOG.md)

@tools
  # --- Repository Scanning & Facts ---
  cmd "scan_repo"
    args: [path, exclude]
    run: |
      set -euo pipefail
      cd "${path:-$PWD}"
      EX="${exclude:-${EXCLUDE}}"
      echo "[info] Scanning repository at $(pwd)"
      # Collect file list
      if command -v fd >/dev/null 2>&1; then
        fd . --type f --hidden --exclude ".git" | grep -Ev "${EX}" || true
      else
        find . -type f -not -path "*/.git/*" | grep -Ev "${EX}" || true
      fi

  cmd "summarize_repo"
    args: [path, exclude]
    run: |
      set -euo pipefail
      cd "${path:-$PWD}"
      EX="${exclude:-${EXCLUDE}}"
      echo "[info] Summary (languages / sizes)"
      if command -v cloc >/dev/null 2>&1; then
        cloc . --exclude-dir=.git,node_modules,dist,build,target,out 2>/dev/null || true
      fi
      echo "[info] Tree (depth 2)"
      if command -v tree >/dev/null 2>&1; then
        tree -L 2 -I "${EX}" || true
      fi

  cmd "extract_apis"
    args: [path, exclude]
    run: |
      set -euo pipefail
      cd "${path:-$PWD}"
      EX="${exclude:-${EXCLUDE}}"
      echo "[info] Extracting API signatures"
      if command -v rg >/dev/null 2>&1; then
        rg -n --hidden -g '!**/.git/**' -g '!**/{node_modules,dist,build,target,out}/**' \
          -e '^\s*(export\s+)?(class|interface|type|enum)\s+\w+' \
          -e '^\s*(public|private|protected)?\s*\w+\s*\([^)]*\)\s*[:=>]' \
          -e '^\s*def\s+\w+\(' \
          -e '^\s*func\s+\w+\(' \
          -e '^\s*class\s+\w+' || true
      else
        grep -RIn --include='*.*' -E "^\s*(class|def|func|interface|type|enum)\s+" . || true
      fi

  # --- Content Generators (Markdown) ---
  cmd "gen_overview"
    args: [path]
    run: |
      set -euo pipefail
      cd "${path:-$PWD}"
      NAME="${PROJECT_NAME}"
      echo "${NAME} is a project that ... (replace with actual description)." \
      | fold -s -w 100

  cmd "gen_features"
    args: [path]
    run: |
      set -euo pipefail
      cat << 'EOF'
      - Clean architecture and modular design
      - Deterministic tooling and reproducible docs
      - Automated API extraction and ToC
      - CI-friendly (runs in /bin/bash)
      EOF

  cmd "gen_quickstart"
    args: [path]
    run: |
      set -euo pipefail
      cat << 'EOF'
      ```bash
      # clone
      git clone <repo-url>
      cd <repo>

      # generate docs
      facet run "Generate full documentation suite"
      ```
      EOF

  cmd "gen_usage"
    args: [path]
    run: |
      set -euo pipefail
      cat << 'EOF'
      - Run analysis from repo root.
      - Artifacts are written to ./docs and README.md at root.
      - Configure via env vars: PROJECT_NAME, OUTPUT_DIR, EXCLUDE, AUTHOR, YEAR.
      EOF

  cmd "gen_configuration"
    args: [path]
    run: |
      set -euo pipefail
      cat << 'EOF'
      | Variable       | Default  | Description                         |
      |----------------|----------|-------------------------------------|
      | PROJECT_NAME   | repo dir | Project display name                |
      | OUTPUT_DIR     | docs     | Documentation directory             |
      | EXCLUDE        | pattern  | Regex to exclude paths from scans   |
      | AUTHOR         | Unknown  | Author name for license and footer  |
      | YEAR           | current  | Year used in headers                |
      EOF

  cmd "gen_license_text"
    args: [license, author, year]
    run: |
      set -euo pipefail
      L="${license:-${DEFAULT_LICENSE}}"
      A="${author:-${AUTHOR}}"
      Y="${year:-${YEAR}}"
      if [ "$L" = "MIT" ]; then
        cat << EOF
        Licensed under the MIT License (c) ${Y} ${A}.
        EOF
      else
        echo "Licensed under ${L} (c) ${Y} ${A}."
      fi

  cmd "gen_system_diagram"
    args: [path]
    run: |
      set -euo pipefail
      cat << 'EOF'
      [client] -> [api gateway] -> [services] -> [db]
                 ^ logs/metrics v
               [observability]
      EOF

  cmd "gen_components"
    args: [path]
    run: |
      set -euo pipefail
      cat << 'EOF'
      - Service A: responsibility, inputs, outputs
      - Service B: responsibility, inputs, outputs
      - CLI: commands, flags, exit codes
      EOF

  cmd "gen_data_flow"
    args: [path]
    run: |
      set -euo pipefail
      cat << 'EOF'
      1. Request enters via HTTP/CLI.
      2. Validation and routing.
      3. Business logic execution.
      4. Persistence and events.
      5. Response and metrics.
      EOF

  cmd "gen_dependencies"
    args: [path]
    run: |
      set -euo pipefail
      if command -v jq >/dev/null 2>&1 && [ -f package.json ]; then
        echo "### JavaScript/TypeScript"
        jq -r '.dependencies // {} | to_entries[] | "- \(.key) @ \(.value)"' package.json || true
      fi
      if [ -f requirements.txt ]; then
        echo "### Python"
        sed 's/^/- /' requirements.txt || true
      fi
      if [ -f go.mod ]; then
        echo "### Go"
        awk '/require/ {req=1; next} req && NF {print "- "$1" "$2} /)/{req=0}' go.mod || true
      fi

  cmd "gen_build_deploy"
    args: [path]
    run: |
      set -euo pipefail
      cat << 'EOF'
      - Build: use your language standard toolchain (e.g., npm run build, cargo build, go build).
      - Test: run unit/integration tests via CI.
      - Release: semantic versioning; changelog updated via Conventional Commits.
      - Deploy: containerized deployment; provide sample Dockerfile and compose.
      EOF

  cmd "gen_contributing"
    args: [path]
    run: |
      set -euo pipefail
      cat << 'EOF'
      ## Process
      1. Fork, branch from main, implement, test, PR.
      2. Use Conventional Commits (feat, fix, docs, chore).
      3. Ensure linters and tests pass.

      ## Code Style
      - Prettier/Black/gofmt as appropriate.
      - Add docstrings and type hints where possible.
      EOF

  cmd "gen_changelog"
    args: [path]
    run: |
      set -euo pipefail
      if command -v git >/dev/null 2>&1; then
        git log --pretty=format:'- %s (%h, %ad)' --date=short | head -n 100 || true
      else
        echo "- Initial release"
      fi

  # --- Render & Write Files ---
  cmd "write_all"
    args: [path]
    run: |
      set -euo pipefail
      ROOT="${path:-$PWD}"
      OUTDIR="${OUTPUT_DIR:-docs}"
      mkdir -p "$OUTDIR"
      echo "[info] Writing docs to $OUTDIR"

      OVERVIEW=$(facet tool gen_overview with path="$ROOT")
      FEATURES=$(facet tool gen_features with path="$ROOT")
      QUICKSTART=$(facet tool gen_quickstart with path="$ROOT")
      USAGE=$(facet tool gen_usage with path="$ROOT")
      CONFIG=$(facet tool gen_configuration with path="$ROOT")
      LICENSE=$(facet tool gen_license_text with license="$DEFAULT_LICENSE" author="$AUTHOR" year="$YEAR")

      APIS=$(facet tool extract_apis with path="$ROOT" exclude="$EXCLUDE")
      SYS=$(facet tool gen_system_diagram with path="$ROOT")
      COMPS=$(facet tool gen_components with path="$ROOT")
      FLOW=$(facet tool gen_data_flow with path="$ROOT")
      DEPS=$(facet tool gen_dependencies with path="$ROOT")
      BUILD=$(facet tool gen_build_deploy with path="$ROOT")
      CONTRIB=$(facet tool gen_contributing with path="$ROOT")
      CHANGE=$(facet tool gen_changelog with path="$ROOT")

      facet fs render readme.md with \
        overview="$OVERVIEW" \
        features="$FEATURES" \
        quickstart="$QUICKSTART" \
        usage="$USAGE" \
        configuration="$CONFIG" \
        license_text="$LICENSE"

      facet fs render docs_api.md with api_reference="$APIS"
      facet fs render docs_architecture.md with \
        system_diagram="$SYS" components="$COMPS" data_flow="$FLOW" dependencies="$DEPS" build_deploy="$BUILD"
      facet fs render docs_contributing.md with contributing="$CONTRIB"
      facet fs render docs_changelog.md with changelog="$CHANGE"
      facet fs render docs_index.md

      echo "[ok] Documentation generated."

@intents
  intent "Analyze repository structure"
    match: /analy(s|z)e|scan repo|structure/i
    slots:
      path: $1 | trim
    steps:
      - tool: cmd/summarize_repo
        with: { path: "{{ path ?? $.env.PROJECT_PATH }}", exclude: "{{ $.env.EXCLUDE }}" }

  intent "Extract APIs"
    match: /api(\s+ref(erence)?)?|signatures|public\s+api/i
    slots:
      path: $1 | trim
    steps:
      - tool: cmd/extract_apis
        with: { path: "{{ path ?? $.env.PROJECT_PATH }}", exclude: "{{ $.env.EXCLUDE }}" }

  intent "Generate full documentation suite"
    match: /(generate|build|create).*docs|full documentation|doc suite/i
    slots:
      path: $1 | trim
    steps:
      - tool: cmd/write_all
        with: { path: "{{ path ?? $.env.PROJECT_PATH }}" }

  intent "Generate README only"
    match: /readme(\.md)?|create readme/i
    slots:
      path: $1 | trim
    steps:
      - tool: cmd/gen_overview
        with: { path: "{{ path ?? $.env.PROJECT_PATH }}" }
      - tool: cmd/gen_features
        with: { path: "{{ path ?? $.env.PROJECT_PATH }}" }
      - tool: cmd/gen_quickstart
        with: { path: "{{ path ?? $.env.PROJECT_PATH }}" }
      - tool: cmd/gen_usage
        with: { path: "{{ path ?? $.env.PROJECT_PATH }}" }
      - tool: cmd/gen_configuration
        with: { path: "{{ path ?? $.env.PROJECT_PATH }}" }
      - tool: cmd/gen_license_text
        with: { license: "{{ $.env.DEFAULT_LICENSE }}", author: "{{ $.env.AUTHOR }}", year: "{{ $.env.YEAR }}" }
      - tool: cmd/write_all
        with: { path: "{{ path ?? $.env.PROJECT_PATH }}" }

@hints
  - "Analyze repository structure"
  - "Extract APIs"
  - "Generate full documentation suite"
  - "Generate README only"
  - "Set PROJECT_NAME=MyLib and regenerate docs"

@notes
  - Designed to run without network access; all data sourced from the local repo.
  - Uses common UNIX tools if available (fd, rg, cloc, tree, jq); gracefully degrades otherwise.
  - Outputs are deterministic and idempotent; re-running will overwrite the same files.
  - Customize via environment variables; see Configuration section in generated README.