action.yml

name: 'roam-code Analysis'
description: 'Pre-indexed code intelligence for AI coding agents — health scoring, quality gates, SARIF output'
branding:
  icon: 'search'
  color: 'blue'

inputs:
  version:
    description: 'roam-code version to install (default: latest)'
    required: false
    default: 'latest'
  commands:
    description: 'Space-separated roam commands to run (default: "health")'
    required: false
    default: 'health'
  changed-only:
    description: 'Incremental mode: adapt commands to changed files + dependents when possible (true/false)'
    required: false
    default: 'false'
  changed-depth:
    description: 'Transitive depth for changed-only dependent expansion (used by roam affected)'
    required: false
    default: '3'
  base-ref:
    description: 'Optional explicit base ref/SHA for changed-only mode (default: PR base SHA or push before SHA)'
    required: false
    default: ''
  sarif:
    description: 'Upload SARIF results to GitHub Code Scanning (true/false)'
    required: false
    default: 'false'
  sarif-commands:
    description: 'Space-separated commands to export as SARIF (`auto` = SARIF-capable subset of `commands`)'
    required: false
    default: 'auto'
  sarif-category:
    description: 'Base category for SARIF upload (job/python suffixes are auto-appended)'
    required: false
    default: 'roam-code'
  sarif-max-runs:
    description: 'Pre-upload SARIF cap: maximum runs kept in combined payload'
    required: false
    default: '20'
  sarif-max-results:
    description: 'Pre-upload SARIF cap: maximum results per run'
    required: false
    default: '25000'
  sarif-max-bytes:
    description: 'Pre-upload SARIF cap: maximum JSON bytes for combined SARIF'
    required: false
    default: '10000000'
  comment:
    description: 'Post sticky PR comment with results (true/false)'
    required: false
    default: 'true'
  gate:
    description: 'Quality gate expression (supports key ops + trend functions like velocity(metric)<=0). Empty = no gate.'
    required: false
    default: ''
  cache:
    description: 'Cache the SQLite index between runs (true/false)'
    required: false
    default: 'true'
  python-version:
    description: 'Python version to use'
    required: false
    default: '3.11'

outputs:
  health-score:
    description: 'The health score (0-100) if health command was run'
    value: ${{ steps.run-analysis.outputs.health-score }}
  exit-code:
    description: 'The exit code from roam commands (0=success, 5=gate failure)'
    value: ${{ steps.run-analysis.outputs.exit-code }}
  sarif-file:
    description: 'Path to generated SARIF file (if sarif input is true)'
    value: ${{ steps.generate-sarif.outputs.sarif-file }}
  sarif-category:
    description: 'Resolved SARIF upload category'
    value: ${{ steps.generate-sarif.outputs.sarif-category }}
  sarif-truncated:
    description: 'Whether SARIF guardrails truncated runs/results before upload'
    value: ${{ steps.generate-sarif.outputs.sarif-truncated }}
  sarif-results:
    description: 'Result count in final SARIF payload after guardrails'
    value: ${{ steps.generate-sarif.outputs.sarif-results }}
  changed-only:
    description: 'Whether changed-only mode was enabled'
    value: ${{ steps.run-analysis.outputs.changed-only }}
  base-ref:
    description: 'Resolved base ref used for changed-only mode'
    value: ${{ steps.run-analysis.outputs.base-ref }}
  affected-count:
    description: 'Detected changed+dependent file count in changed-only mode'
    value: ${{ steps.run-analysis.outputs.affected-count }}

runs:
  using: 'composite'
  steps:
    # ---- 1. Setup Python ----------------------------------------------------
    - name: Set up Python
      uses: actions/setup-python@v5
      with:
        python-version: ${{ inputs.python-version }}

    # ---- 2. Cache pip packages ----------------------------------------------
    - name: Cache pip packages
      if: inputs.cache == 'true'
      uses: actions/cache@v4
      with:
        path: ~/.cache/pip
        key: roam-pip-${{ runner.os }}-py${{ inputs.python-version }}-${{ inputs.version }}
        restore-keys: |
          roam-pip-${{ runner.os }}-py${{ inputs.python-version }}-

    # ---- 3. Cache roam index (SQLite DB) ------------------------------------
    - name: Cache roam index
      if: inputs.cache == 'true'
      uses: actions/cache@v4
      with:
        path: .roam/
        key: roam-index-${{ runner.os }}-${{ hashFiles('**/*.py', '**/*.js', '**/*.ts', '**/*.go', '**/*.rs', '**/*.java', '**/*.rb', '**/*.php', '**/*.cs', '**/*.c', '**/*.cpp') }}
        restore-keys: |
          roam-index-${{ runner.os }}-

    # ---- 4. Install roam-code -----------------------------------------------
    - name: Install roam-code
      shell: bash
      run: |
        if [ "${{ inputs.version }}" = "latest" ]; then
          pip install --quiet roam-code
        else
          pip install --quiet "roam-code==${{ inputs.version }}"
        fi

    # ---- 5. Build/refresh index ---------------------------------------------
    - name: Build index
      shell: bash
      run: roam init

    # ---- 6. Run analysis commands -------------------------------------------
    - name: Run analysis
      id: run-analysis
      shell: bash
      run: |
        COMMANDS="${{ inputs.commands }}"
        CHANGED_ONLY="${{ inputs.changed-only }}"
        CHANGED_DEPTH="${{ inputs.changed-depth }}"
        BASE_REF_INPUT="${{ inputs.base-ref }}"
        EVENT_NAME="${{ github.event_name }}"
        PR_BASE_SHA="${{ github.event.pull_request.base.sha }}"
        PUSH_BEFORE_SHA="${{ github.event.before }}"
        FINAL_EXIT=0
        RESULTS_DIR="${RUNNER_TEMP}/roam-results"
        mkdir -p "${RESULTS_DIR}"
        AFFECTED_LIST_FILE="${RUNNER_TEMP}/roam-affected-files.txt"
        : > "${AFFECTED_LIST_FILE}"
        BASE_REF=""
        AFFECTED_COUNT=0

        # Resolve incremental analysis baseline for changed-only mode.
        if [ "${CHANGED_ONLY}" = "true" ]; then
          if [ -n "${BASE_REF_INPUT}" ]; then
            BASE_REF="${BASE_REF_INPUT}"
          elif [ "${EVENT_NAME}" = "pull_request" ] && [ -n "${PR_BASE_SHA}" ]; then
            BASE_REF="${PR_BASE_SHA}"
          elif [ -n "${PUSH_BEFORE_SHA}" ] && [ "${PUSH_BEFORE_SHA}" != "0000000000000000000000000000000000000000" ]; then
            BASE_REF="${PUSH_BEFORE_SHA}"
          fi

          if [ -n "${BASE_REF}" ]; then
            AFFECTED_PLAN="${RUNNER_TEMP}/roam-affected-plan.tmp"
            set +e
            roam --json affected --base "${BASE_REF}" --depth "${CHANGED_DEPTH}" > "${AFFECTED_PLAN}" 2>/dev/null
            PLAN_EXIT=$?
            set -e

            if [ ${PLAN_EXIT} -eq 0 ]; then
              AFFECTED_COUNT=$(python3 - "${AFFECTED_PLAN}" "${AFFECTED_LIST_FILE}" <<'PY'
        import json
        import sys
        from pathlib import Path

        plan_path = Path(sys.argv[1])
        out_path = Path(sys.argv[2])
        paths = []

        try:
            data = json.loads(plan_path.read_text(encoding="utf-8", errors="replace"))
        except Exception:
            out_path.write_text("", encoding="utf-8")
            print(0)
            raise SystemExit(0)

        for p in data.get("affected_direct", []) or data.get("changed_files", []):
            if isinstance(p, str):
                paths.append(p)

        for item in data.get("affected_transitive_1", []):
            if isinstance(item, dict):
                p = item.get("file")
                if p:
                    paths.append(p)

        for item in data.get("affected_transitive_2plus", []):
            if isinstance(item, dict):
                p = item.get("file")
                if p:
                    paths.append(p)

        deduped = []
        seen = set()
        for p in paths:
            if p and p not in seen:
                deduped.append(p)
                seen.add(p)

        out_path.write_text("\n".join(deduped), encoding="utf-8")
        print(len(deduped))
        PY
              )
            else
              echo "::warning::Could not compute affected file set; using per-command changed detection."
            fi
          else
            echo "::warning::changed-only requested but no base ref was resolved; using per-command changed detection."
          fi
        fi

        for CMD in ${COMMANDS}; do
          ARGS=("${CMD}")

          if [ "${CHANGED_ONLY}" = "true" ]; then
            case "${CMD}" in
              verify|syntax-check|test-gaps|suggest-reviewers|file)
                if [ -s "${AFFECTED_LIST_FILE}" ]; then
                  while IFS= read -r FILE_PATH; do
                    if [ -n "${FILE_PATH}" ]; then
                      ARGS+=("${FILE_PATH}")
                    fi
                  done < "${AFFECTED_LIST_FILE}"
                else
                  ARGS+=("--changed")
                fi
                ;;
              api-changes)
                if [ -n "${BASE_REF}" ]; then
                  ARGS+=("--base" "${BASE_REF}")
                fi
                ARGS+=("--changed")
                ;;
              pr-risk)
                if [ -n "${BASE_REF}" ]; then
                  ARGS+=("${BASE_REF}..HEAD")
                fi
                ;;
              pr-diff)
                if [ -n "${BASE_REF}" ]; then
                  ARGS+=("--range" "${BASE_REF}..HEAD")
                fi
                ;;
              semantic-diff)
                if [ -n "${BASE_REF}" ]; then
                  ARGS+=("--base" "${BASE_REF}")
                fi
                ;;
              affected)
                if [ -n "${BASE_REF}" ]; then
                  ARGS+=("--base" "${BASE_REF}")
                fi
                ARGS+=("--depth" "${CHANGED_DEPTH}")
                ;;
              *)
                ;;
            esac
          fi

          # Separate stdout (the JSON envelope, what callers consume)
          # from stderr (progress + warnings, surfaced in workflow logs).
          # Merging the two streams into the .json file used to break
          # downstream JSON parsers when a command logged a warning to
          # stderr that landed in the file.
          echo "::group::roam ${ARGS[*]}"
          set +e
          roam --json "${ARGS[@]}" \
            > "${RESULTS_DIR}/${CMD}.json" \
            2> "${RESULTS_DIR}/${CMD}.stderr"
          CMD_EXIT=$?
          set -e

          # Validate the JSON before downstream steps consume it. If the
          # output is non-JSON (e.g. a Python crash trace), wrap in a
          # structured error envelope so dependents see a deterministic
          # shape.
          if ! python3 -c "import json,sys; json.load(open('${RESULTS_DIR}/${CMD}.json'))" 2>/dev/null; then
            python3 - <<EOF > "${RESULTS_DIR}/${CMD}.json"
        import json, pathlib
        stdout = pathlib.Path("${RESULTS_DIR}/${CMD}.json").read_text(encoding="utf-8", errors="replace")
        stderr = pathlib.Path("${RESULTS_DIR}/${CMD}.stderr").read_text(encoding="utf-8", errors="replace")
        json.dump({
            "status": "error",
            "command": "${CMD}",
            "exit_code": ${CMD_EXIT},
            "stdout": stdout[:8000],
            "stderr": stderr[:8000],
            "reason": "non-JSON output from roam --json",
        }, open("${RESULTS_DIR}/${CMD}.json", "w"), indent=2)
        EOF
          fi

          cat "${RESULTS_DIR}/${CMD}.json"
          if [ -s "${RESULTS_DIR}/${CMD}.stderr" ]; then
            echo "--- stderr ---"
            cat "${RESULTS_DIR}/${CMD}.stderr"
          fi
          echo ""
          echo "::endgroup::"

          if [ ${CMD_EXIT} -ne 0 ] && [ ${CMD_EXIT} -gt ${FINAL_EXIT} ]; then
            FINAL_EXIT=${CMD_EXIT}
          fi
        done

        # Extract health score if health command was run
        if [ -f "${RESULTS_DIR}/health.json" ]; then
          HEALTH_SCORE=$(python3 -c "
        import json, sys
        try:
            data = json.load(open('${RESULTS_DIR}/health.json'))
            score = data.get('summary', {}).get('health_score', data.get('health_score', ''))
            print(score)
        except Exception:
            print('')
        " 2>/dev/null || echo "")
          echo "health-score=${HEALTH_SCORE}" >> "${GITHUB_OUTPUT}"
        fi

        echo "exit-code=${FINAL_EXIT}" >> "${GITHUB_OUTPUT}"
        echo "results-dir=${RESULTS_DIR}" >> "${GITHUB_OUTPUT}"
        echo "changed-only=${CHANGED_ONLY}" >> "${GITHUB_OUTPUT}"
        echo "base-ref=${BASE_REF}" >> "${GITHUB_OUTPUT}"
        echo "affected-count=${AFFECTED_COUNT}" >> "${GITHUB_OUTPUT}"

    # ---- 7. Quality gate ----------------------------------------------------
    - name: Quality gate
      id: quality-gate
      if: inputs.gate != ''
      shell: bash
      run: |
        GATE_SCRIPT="${ACTION_PATH}/.github/scripts/gate_eval.py"
        if [ ! -f "${GATE_SCRIPT}" ]; then
          echo "::error::Missing gate evaluator script: ${GATE_SCRIPT}"
          exit 1
        fi

        GATE_RESULT=$(python3 "${GATE_SCRIPT}" \
          --expr "${GATE_EXPR}" \
          --results-dir "${RESULTS_DIR}")

        echo "gate-passed=${GATE_RESULT}" >> "${GITHUB_OUTPUT}"

        if [ "${GATE_RESULT}" = "false" ]; then
          echo "::error::Quality gate failed: ${GATE_EXPR}"
          exit 5
        fi
      env:
        RESULTS_DIR: ${{ steps.run-analysis.outputs.results-dir }}
        GATE_EXPR: ${{ inputs.gate }}
        ACTION_PATH: ${{ github.action_path }}

    # ---- 8. Generate SARIF --------------------------------------------------
    - name: Generate SARIF
      id: generate-sarif
      if: inputs.sarif == 'true'
      shell: bash
      run: |
        SARIF_DIR="${RUNNER_TEMP}/roam-sarif"
        SARIF_FILE="${RUNNER_TEMP}/roam-results.sarif"
        SARIF_SUMMARY="${RUNNER_TEMP}/roam-sarif-summary.json"
        mkdir -p "${SARIF_DIR}"

        REQUESTED_SARIF_COMMANDS="${{ inputs.sarif-commands }}"
        ANALYSIS_COMMANDS="${{ inputs.commands }}"

        # Build a non-colliding category baseline per job/runtime.
        UPLOAD_CATEGORY="${{ inputs.sarif-category }}"
        if [ -n "${GITHUB_JOB}" ]; then
          UPLOAD_CATEGORY="${UPLOAD_CATEGORY}/${GITHUB_JOB}"
        fi
        if [ -n "${{ inputs.python-version }}" ]; then
          UPLOAD_CATEGORY="${UPLOAD_CATEGORY}/py${{ inputs.python-version }}"
        fi
        echo "sarif-category=${UPLOAD_CATEGORY}" >> "${GITHUB_OUTPUT}"

        declare -a SARIF_COMMANDS=()
        declare -a SARIF_FILES=()
        declare -A _SEEN=()

        # Commands that currently emit SARIF via global --sarif flag.
        # _SUPPORTED_SARIF is intentionally a subset of cli.py::_SARIF_CONSUMERS
        # (37 total CLI SARIF emitters as of W1229; 29 auto-uploaded
        # here). The 8-entry gap (37 - 29) reflects the mature-stable gating
        # policy:
        # detectors auto-upload only after they have shipped, been dogfooded,
        # and proven low false-positive rates. The gap is policy, not lag.
        # Commands listed here auto-upload as SARIF via GitHub Code Scanning.
        # Excluded by design (mature-stable gating per W1158):
        #   py-types / py-modern (Python-tooling-specific, less universal),
        #   stale-refs / taint (advanced detectors, opt-in per project),
        #   audit-trail-conformance-check / check-rules (governance/policy,
        #     external SARIF pathway), supply-chain / vulns (third-party-data
        #     dependent, opt-in).
        # See W1158 audit + dev/SARIF-DISCLOSURE-PATTERN-MATURITY-2026-05-16.md.
        # W1165: impact added — universal blast-radius signal for CI.
        # W1160: affected-tests added — per-test SARIF projection
        # (DIRECT=error, TRANSITIVE=warning, COLOCATED=note).
        # W1159: partition added — per-partition conflict-risk + key-symbol
        # projection (HIGH=error, MEDIUM=warning, LOW=note).
        # W1171: smells added — per-finding severity projection
        # (critical=error, warning=warning, info=note), one rule per
        # registered smell-kind in roam.catalog.registry.
        # W1172: clones added — two-sided clone-pair / cluster projection
        # (similarity >= 0.95 -> warning, lower bands -> note; cluster
        # defaults to warning). PRIMARY anchor = file_a:line_a;
        # SECONDARY = file_b:line_b (pairs) or up to 10 additional
        # cluster members.
        # W1192: delete-check added — per-deletion deletion-safety
        # projection. BREAK-RISK -> error (gate-blocking), LIKELY-SAFE
        # -> warning (review-recommended), SAFE -> note (informational).
        # PRIMARY anchor = from_file:from_line (the deletion site);
        # SECONDARY = up to 10 survivors[] entries (each path:line).
        # W1195: auth-gaps added — per-finding PHP / Laravel auth-gap
        # projection. direct-unauthenticated-handler -> error
        # (deterministic static-analysis), helper-indirection -> warning
        # (graph-walked structural), name-based -> note (heuristic).
        # PRIMARY anchor = file:line (route definition line or
        # controller method declaration line).
        # W1203: test-impact added — per-test affected-test projection
        # (reach_count >= 20 -> warning, < 20 -> note). Informational
        # ranker (no error band — gating uses affected-tests instead).
        # PRIMARY anchor = file (test file path, file-level only).
        # W1208: n1 added — per-finding implicit N+1 projection.
        # n1/high-confidence -> error (model used in collection /
        # pagination context), n1/medium-confidence -> warning
        # (relationship lazy-load, no strong collection-context), and
        # n1/low-confidence -> note (heuristic match). PRIMARY anchor =
        # accessor_location (the line that fires per-item I/O).
        # W1218: orphan-imports added — per-import orphan-import
        # projection. orphan-imports/internal-typo -> error (Python
        # top-level package indexed but full dotted path is not —
        # deterministic typo), orphan-imports/missing-package ->
        # warning (Python not in index and not importable), and
        # orphan-imports/missing-local -> warning (JS/Go path-style
        # didn't resolve). PRIMARY anchor = file:line (the import
        # statement line).
        # W1217: missing-index added — per-finding unindexed-query
        # projection. missing-index/high-confidence -> error (WHERE
        # on unindexed column in a paginated query — guaranteed
        # table scan), missing-index/medium-confidence -> warning
        # (orderBy on non-indexed column, or paginated WHERE
        # without composite coverage), and missing-index/low-
        # confidence -> note (column has an individual index but
        # not the optimal composite). PRIMARY anchor =
        # query_location (the line that runs the unindexed query).
        # W1219: over-fetch added — per-finding Laravel/Eloquent
        # over-fetch projection. Single closed-enum rule
        # over-fetch/select-star-or-wide-query (defaultLevel
        # warning). Per-finding level: H severity / high confidence
        # -> warning (confirmed leak: BARE / UNGUARDED_RELATION
        # endpoint, or model with 30+ fillable fields & no
        # Resource); L severity / medium / low confidence -> note
        # (already partially guarded, or threshold-only model
        # signal). PRIMARY anchor = file:line — endpoint method
        # for endpoint findings, model_location (class declaration
        # line) for model findings.
        # W1215: bus-factor added — per-directory knowledge-loss
        # projection. Three closed-enum rules:
        # bus-factor/author-concentration -> warning (single
        # author owns >70% of churn), bus-factor/stale-ownership
        # -> warning (primary author inactive beyond stale-months
        # threshold), bus-factor/solo-author-summary -> note
        # (W164 collapse on solo-author repos). Per-result level
        # maps the HIGH/MEDIUM/LOW risk band onto warning/note
        # (HIGH -> warning; MEDIUM / LOW -> note). PRIMARY anchor
        # = directory path (no line — risk applies to the
        # directory as a whole, not a specific symbol).
        # W1216: laws added — per-violation mined-law projection.
        # Five closed-enum rules: laws/naming, laws/import-layering,
        # laws/test-coverage, laws/error-handling (stub),
        # laws/co-change (stub) — all defaultLevel note (mined laws
        # describe emergent conventions, not invariants, so the
        # advisory band is the safer default). Per-result level via
        # severity: blocker -> error, warning -> warning, advisory
        # / unknown -> note. PRIMARY anchor = file:line (the diff
        # hunk line that introduced the violation).
        # W1209: fan added — per-finding cross-file fan-in/out
        # architectural projection. Three closed-enum rules:
        # fan/hub -> note (high cross-file fan-in, absorbs change
        # pressure but does not propagate outward), fan/spreader
        # -> warning (high cross-file fan-out, changes propagate
        # outward — higher blast-radius risk), fan/high-risk -> error
        # (both directions over threshold — amplifies blast radius in
        # both directions, highest architectural-risk band). Per-result
        # level matches the rule defaultLevel (the flag IS the severity
        # band). Local-only flags (local-hub / local-spreader) are
        # skipped per the W150 audit (single-file by design — non-
        # architectural). PRIMARY anchor = file:line (symbol-mode) or
        # file (file-mode — no line since the metric applies to the
        # whole file).
        # W1213: duplicates added — per-cluster semantic-duplicate
        # projection. Single closed-enum rule duplicates/cluster
        # (defaultLevel note). Per-result level scales with the
        # cluster's avg similarity via _duplicates_cluster_level:
        # >= 0.95 -> warning (near-identical duplicate cluster),
        # < 0.95 -> note (structural-pattern match). NEVER escalates to
        # error — duplicates are refactor opportunities, not defects
        # (mirrors clones_to_sarif severity ceiling). PRIMARY anchor =
        # first member's file:line; SECONDARY = up to 10 additional
        # members so SARIF consumers can highlight the full cluster
        # footprint without inflating the document.
        # W1207: llm-smells added — per-occurrence LLM-API anti-pattern
        # projection. Ten closed-enum rules under the llm-smells/
        # namespace (no-model-version-pinning, missing-max-tokens,
        # direct-user-input-concatenation, no-structured-output-validation,
        # temperature-not-set, missing-timeout, missing-max-retries,
        # no-system-message, no-retry-on-rate-limit, call-in-loop).
        # Per-rule defaultLevel reflects the W415 / W415b severity
        # table: direct-user-input-concatenation -> error (OWASP
        # LLM01:2025 prompt-injection vector), temperature-not-set /
        # missing-max-retries -> note, the other seven -> warning.
        # Per-result level always overrides via the closed _to_level
        # mapping (critical -> error / warning -> warning / info ->
        # note). PRIMARY anchor = file:line for each LLM-API call site
        # or, for the file-level no-retry-on-rate-limit kind, the
        # file's first completion-call line.
        # W1210: hotspots added — per-symbol runtime-vs-static rank-
        # discrepancy projection (default mode only; --security and
        # --danger reject --sarif). Three closed-enum rules:
        # hotspots/confirmed -> error (static + runtime agree on
        # importance — genuinely hot in production), hotspots/upgrade
        # -> warning (runtime-critical but statically safe — hidden
        # hotspot static analysis missed), hotspots/downgrade -> note
        # (statically risky but low traffic — informational; was hot,
        # no longer). All three carry confidence tier ``runtime`` —
        # every emitted finding required ingested ``runtime_stats``
        # rows from ``roam ingest-trace``. PRIMARY anchor = file_path
        # (no line — compute_hotspots returns symbol_name + file_path,
        # no specific line; risk applies at symbol granularity).
        # Findings without an indexed symbol_id are skipped silently
        # (trace span didn't resolve to a known symbol — no stable
        # subject to attach to).
        # W1226: flag-dead added — per-flag feature-flag staleness
        # projection. Three closed-enum rules under the flag-* namespace:
        # flag-staleness -> warning (known-stale: flag listed in
        # --config file, operator-confirmed for removal),
        # flag-single-reference -> note (flag has a single call site
        # — likely leftover code, advisory band), flag-suspect
        # -> warning (suspect: same constant default at every call
        # site OR all references concentrate in a single file).
        # Per-result level via :func:`_flag_dead_staleness_level`:
        # stale + suspect -> warning; likely_stale -> note. NEVER
        # escalates to error — detector is heuristic (regex-based
        # call-site scan, no dashboard cross-check) so even the
        # strongest signal stays in the warning band (mirrors
        # duplicates_to_sarif severity ceiling). PRIMARY anchor =
        # first call site's file:line; SECONDARY = up to 10 additional
        # call sites so consumers can highlight the full call-site
        # footprint without inflating the document. The ``ok`` bucket
        # (no staleness indicators) is filtered upstream so SARIF
        # consumers never see non-actionable rows.
        # W1227: orphan-routes added — per-route Laravel dead-endpoint
        # projection. Single closed-enum rule orphan-route
        # (defaultLevel warning — dead endpoints are real bugs:
        # operational cost + attack surface, not just hygiene).
        # Per-result level via :func:`_orphan_routes_confidence_level`:
        # high + medium -> warning; low -> note. NEVER escalates to
        # error — detector is heuristic (path-segment grep + Laravel-
        # route regex parse, no full PHP AST analysis) so even the
        # strongest signal stays in the warning band (mirrors W1226
        # flag-dead + W1213 duplicates severity ceilings). PRIMARY
        # anchor = file:line (the route definition line). The ``used``
        # bucket (has a frontend consumer — not an orphan) is filtered
        # upstream so SARIF consumers never see non-actionable rows.
        # W1229: verify-imports added — per-import hallucination-
        # firewall projection. Two closed-enum rules:
        # invalid-import (defaultLevel warning — unresolved with FTS5
        # fuzzy-match candidates, likely typo / rename) and
        # hallucination-import (defaultLevel error — unresolved with
        # no candidates, the imported name genuinely doesn't exist in
        # the indexed symbol table, the canonical LLM-hallucination
        # signal). The error band is deliberate — verify-imports is
        # the only one of the W12xx dead-code detectors that escalates
        # to error because a hallucinated import is unrecoverable
        # (no remediation path through fuzzy match) and gates CI
        # against LLM-generated import drift. PRIMARY anchor =
        # file:line (the import statement site). ``resolved`` rows
        # are filtered upstream so SARIF consumers never see
        # non-actionable rows.
        _SUPPORTED_SARIF="health dead complexity rules secrets algo critique impact affected-tests partition smells clones delete-check auth-gaps test-impact n1 orphan-imports missing-index over-fetch bus-factor laws fan duplicates llm-smells dark-matter hotspots flag-dead orphan-routes verify-imports"

        if [ "${REQUESTED_SARIF_COMMANDS}" = "auto" ] || [ -z "${REQUESTED_SARIF_COMMANDS}" ]; then
          for CMD in ${ANALYSIS_COMMANDS}; do
            case " ${_SUPPORTED_SARIF} " in
              *" ${CMD} "*) ;;
              *) continue ;;
            esac
            if [ -z "${_SEEN["${CMD}"]+x}" ]; then
              SARIF_COMMANDS+=("${CMD}")
              _SEEN["${CMD}"]=1
            fi
          done
          if [ ${#SARIF_COMMANDS[@]} -eq 0 ]; then
            SARIF_COMMANDS=("health")
          fi
        else
          for CMD in ${REQUESTED_SARIF_COMMANDS}; do
            if [ -z "${_SEEN["${CMD}"]+x}" ]; then
              SARIF_COMMANDS+=("${CMD}")
              _SEEN["${CMD}"]=1
            fi
          done
        fi

        for CMD in "${SARIF_COMMANDS[@]}"; do
          OUT_FILE="${SARIF_DIR}/${CMD}.sarif"
          set +e
          roam --sarif "${CMD}" > "${OUT_FILE}" 2>/dev/null
          CMD_EXIT=$?
          set -e

          if [ ${CMD_EXIT} -ne 0 ] || [ ! -s "${OUT_FILE}" ]; then
            echo "::warning::SARIF generation failed or empty for command '${CMD}'"
            continue
          fi

          if python3 - "${OUT_FILE}" <<'PY'
        import json
        import sys
        p = sys.argv[1]
        try:
            data = json.load(open(p, encoding="utf-8"))
        except Exception:
            raise SystemExit(1)
        if not isinstance(data, dict):
            raise SystemExit(1)
        if data.get("version") != "2.1.0":
            raise SystemExit(1)
        runs = data.get("runs")
        if not isinstance(runs, list):
            raise SystemExit(1)
        raise SystemExit(0)
        PY
          then
            SARIF_FILES+=("${OUT_FILE}")
          else
            echo "::warning::Command '${CMD}' did not produce valid SARIF and will be skipped"
          fi
        done

        if [ ${#SARIF_FILES[@]} -eq 0 ]; then
          echo "::warning::No valid SARIF outputs generated from requested command set"
          exit 0
        fi

        set +e
        python3 "${ACTION_PATH}/.github/scripts/sarif_guard.py" \
          --output "${SARIF_FILE}" \
          --summary-out "${SARIF_SUMMARY}" \
          --max-runs "${{ inputs.sarif-max-runs }}" \
          --max-results "${{ inputs.sarif-max-results }}" \
          --max-bytes "${{ inputs.sarif-max-bytes }}" \
          "${SARIF_FILES[@]}"
        GUARD_EXIT=$?
        set -e

        if [ ${GUARD_EXIT} -ne 0 ]; then
          echo "::warning::SARIF guardrails failed (exit=${GUARD_EXIT}); skipping upload"
          exit 0
        fi

        if [ -s "${SARIF_FILE}" ]; then
          echo "sarif-file=${SARIF_FILE}" >> "${GITHUB_OUTPUT}"
        else
          echo "::warning::SARIF guardrails produced empty output"
          exit 0
        fi

        python3 - "${SARIF_SUMMARY}" "${GITHUB_OUTPUT}" <<'PY'
        import json
        import sys

        summary_path = sys.argv[1]
        output_path = sys.argv[2]

        try:
            summary = json.load(open(summary_path, encoding="utf-8"))
        except Exception:
            summary = {}

        truncated = bool(summary.get("truncated", False))
        results_after = int(summary.get("results_after", 0) or 0)
        dropped = int(summary.get("results_dropped_total", 0) or 0)
        dropped_runs = int(summary.get("dropped_runs", 0) or 0)

        with open(output_path, "a", encoding="utf-8") as fh:
            fh.write(f"sarif-truncated={'true' if truncated else 'false'}\n")
            fh.write(f"sarif-results={results_after}\n")

        if truncated:
            print(
                "::warning::SARIF truncated by guardrails "
                f"(dropped_results={dropped}, dropped_runs={dropped_runs}, "
                f"results_after={results_after})."
            )
        PY
      env:
        ACTION_PATH: ${{ github.action_path }}

    # ---- 9. Upload SARIF to GitHub Code Scanning ----------------------------
    - name: Upload SARIF
      if: inputs.sarif == 'true' && steps.generate-sarif.outputs.sarif-file != ''
      uses: github/codeql-action/upload-sarif@v3
      with:
        sarif_file: ${{ steps.generate-sarif.outputs.sarif-file }}
        category: ${{ steps.generate-sarif.outputs.sarif-category }}
      continue-on-error: true

    # ---- 10. Post PR comment ------------------------------------------------
    - name: Post PR comment
      if: inputs.comment == 'true' && github.event_name == 'pull_request'
      uses: actions/github-script@v7
      env:
        RESULTS_DIR: ${{ steps.run-analysis.outputs.results-dir }}
        HEALTH_SCORE: ${{ steps.run-analysis.outputs.health-score }}
        GATE_EXPR: ${{ inputs.gate }}
        GATE_PASSED: ${{ steps.quality-gate.outputs.gate-passed }}
        COMMANDS_RUN: ${{ inputs.commands }}
        CHANGED_ONLY: ${{ steps.run-analysis.outputs.changed-only }}
        BASE_REF: ${{ steps.run-analysis.outputs.base-ref }}
        AFFECTED_COUNT: ${{ steps.run-analysis.outputs.affected-count }}
        SARIF_CATEGORY: ${{ steps.generate-sarif.outputs.sarif-category }}
        SARIF_TRUNCATED: ${{ steps.generate-sarif.outputs.sarif-truncated }}
        SARIF_RESULTS: ${{ steps.generate-sarif.outputs.sarif-results }}
      with:
        script: |
          const fs = require('fs');
          const path = require('path');

          // ${{ github.action_path }} resolves to the action's root directory,
          // which works both for remote (uses: Cranot/roam-code@main) and
          // local (uses: ./) references.
          const scriptPath = path.join('${{ github.action_path }}', '.github', 'scripts', 'pr-comment.js');
          const script = require(scriptPath);
          await script({ github, context, core, fs, path });