action.yml

name: DebtLens
description: Find maintainability debt in TypeScript, JavaScript, Python, Vue/Svelte SFC scripts, Kotlin, Swift, Ruby, Jetpack Compose, and framework codebases.
author: ColumbusLabs
branding:
  icon: search
  color: purple

inputs:
  target:
    description: Directory or file to scan.
    default: "."
  min-severity:
    description: Lowest severity to report (info, low, medium, high).
    default: low
  rules:
    description: Comma-separated rule ids to run. Empty runs all rules.
    default: ""
  fail-on:
    description: Exit with code 1 when any issue meets this severity (info, low, medium, high).
    default: ""
  fail-on-confidence:
    description: With fail-on, require at least this confidence (0-1) to exit with code 1.
    default: ""
  gate:
    description: Named quality-gate preset (advisory, new-code, strict-new-code, legacy-baseline).
    default: ""
  format:
    description: Output format (terminal, json, markdown, pr-comment, sarif, html, junit, gitlab-codequality).
    default: terminal
  output:
    description: Write the report to this file instead of stdout.
    default: ""
  changed:
    description: Scan only changed files. Use "true" for changes vs HEAD, or a base ref (e.g. origin/main).
    default: ""
  diff-base:
    description: Compare against a git ref and report only introduced findings.
    default: ""
  pack:
    description: Built-in rule pack preset (core, react, react-native, next, expo, node, python, python-web, vue, svelte, kotlin, swift, ruby, rails, compose, swiftui, ai-assisted-maintainer, oss-maintainer, ai-workflow-drift).
    default: ""
  package:
    description: Workspace package name to scan.
    default: ""
  profile:
    description: Collect per-rule timing profile in the JSON report.
    default: "false"
  cache:
    description: Reuse unchanged scan results from a content-hash cache.
    default: "false"
  cache-path:
    description: Path to the scan cache file when cache is enabled.
    default: ""
  parallel:
    description: Run detectors concurrently after source loading.
    default: "false"
  batch-size:
    description: Load source files in bounded batches.
    default: ""
  blame-age:
    description: Add introducedDaysAgo metadata to JSON issues using git blame.
    default: "false"
  hotspots:
    description: Enable optional git-derived hotspot prioritization.
    default: "false"
  churn-days:
    description: Hotspot mode - derive churn from commits in the last count days.
    default: ""
  churn-range:
    description: Hotspot mode - derive churn from a git revision range.
    default: ""
  ownership:
    description: Enable CODEOWNERS-based ownership and handoff summaries.
    default: "false"
  codeowners:
    description: Optional path to a CODEOWNERS file for ownership mode.
    default: ""
  audit-suppressions:
    description: Include used and unused inline suppression directives in scan output.
    default: "false"
  respect-gitignore:
    description: Skip files ignored by git in addition to configured excludes.
    default: "false"
  baseline:
    description: Report only issues absent from this baseline file.
    default: ""
  config:
    description: Path to debtlens.config.json.
    default: ""
  write-baseline:
    description: Write current issues to this baseline file and exit. Mutually exclusive with baseline.
    default: ""
  thresholds:
    description: Comma-separated key=value threshold overrides (e.g. large-component.maxLines=300).
    default: ""
  max-files:
    description: Maximum number of files to scan.
    default: ""
  working-directory:
    description: Directory to run the scan from.
    default: "."
  quiet:
    description: Terminal only - suppress per-finding detail.
    default: "false"
  group-by:
    description: Terminal grouping (severity, rule, file).
    default: severity
  sarif-compact:
    description: SARIF only - emit only rules referenced by findings.
    default: "false"
  sarif-category:
    description: SARIF only - set runs[].automationDetails.id for separated code scanning runs.
    default: ""
  junit-fail-on:
    description: JUnit only - severity threshold for failed testcases (info, low, medium, high). Defaults to all reported findings.
    default: ""
  markdown-heatmap:
    description: Markdown only - append a debt heatmap table. Use a positive integer limit or leave empty to disable.
    default: ""
  fail-on-regression:
    description: Exit with code 1 when counts increase versus baseline or diff-base.
    default: "false"
  json-output:
    description: Optional path to also write the canonical ScanResult JSON report.
    default: ""
  upload-json-artifact:
    description: Upload the canonical ScanResult JSON as an Actions artifact.
    default: "false"
  json-artifact-name:
    description: Name for the uploaded JSON artifact.
    default: debtlens-scan-result
  json-artifact-retention-days:
    description: Retention days for the uploaded JSON artifact.
    default: "14"
  previous-report:
    description: Optional previous ScanResult JSON path for step-summary trend comparison.
    default: ""
  comment-delta-only:
    description: PR comment only - label findings as baseline or diff-base deltas. Pair with baseline or diff-base so the scan contains only new findings.
    default: "false"
  step-summary:
    description: Append a compact Markdown summary to the GitHub Actions step summary.
    default: "false"
  comment:
    description: Post or update a pull request comment with the scan report.
    default: "false"
  comment-max-findings:
    description: PR comment only - maximum detailed findings before omitted findings are summarized. Leave empty to rely on the byte cap.
    default: ""
  comment-max-bytes:
    description: PR comment only - maximum rendered comment size in bytes.
    default: "60000"
  comment-full-report-url:
    description: PR comment only - optional URL for the full report artifact when findings are omitted.
    default: ""
  comment-fail-on-error:
    description: Fail the Action when PR comment posting fails. Defaults to warn-only for fork and permission-limited PRs.
    default: "false"
  annotations:
    description: Emit capped GitHub workflow command annotations without requiring SARIF/code scanning.
    default: "false"
  annotations-max-count:
    description: Maximum workflow command annotations to emit when annotations are enabled.
    default: "50"

outputs:
  scan-status:
    description: Raw DebtLens scan exit status before the Action replays it.
    value: ${{ steps.scan.outputs['scan-status'] }}
  gate-status:
    description: passed when scan-status is 0, otherwise failed.
    value: ${{ steps.scan.outputs['gate-status'] }}
  total-issues:
    description: Total reported issue count.
    value: ${{ steps.scan.outputs['total-issues'] }}
  high-issues:
    description: High-severity reported issue count.
    value: ${{ steps.scan.outputs['high-issues'] }}
  medium-issues:
    description: Medium-severity reported issue count.
    value: ${{ steps.scan.outputs['medium-issues'] }}
  low-issues:
    description: Low-severity reported issue count.
    value: ${{ steps.scan.outputs['low-issues'] }}
  info-issues:
    description: Info-severity reported issue count.
    value: ${{ steps.scan.outputs['info-issues'] }}
  top-rule:
    description: Rule id with the most findings.
    value: ${{ steps.scan.outputs['top-rule'] }}
  top-rule-count:
    description: Finding count for top-rule.
    value: ${{ steps.scan.outputs['top-rule-count'] }}
  json-path:
    description: Canonical ScanResult JSON path, either json-output or the internal runner temp path.
    value: ${{ steps.scan.outputs['json-path'] }}
  json-artifact-name:
    description: Uploaded JSON artifact name when upload-json-artifact is enabled.
    value: ${{ steps.scan.outputs['json-artifact-name'] }}
  report-path:
    description: Rendered report output path when output is configured.
    value: ${{ steps.scan.outputs['report-path'] }}
  report-format:
    description: Rendered report format requested by the Action.
    value: ${{ steps.scan.outputs['report-format'] }}

runs:
  using: composite
  steps:
    - uses: actions/setup-node@v4
      with:
        node-version: "20"
    - name: Prepare DebtLens runtime
      shell: bash
      working-directory: ${{ github.action_path }}
      env:
        DL_ACTION_REF: ${{ github.action_ref }}
        DL_ACTION_REPOSITORY: ${{ github.action_repository }}
      run: bash "$GITHUB_ACTION_PATH/scripts/prepare-action-runtime.sh"
    - name: Run DebtLens scan
      id: scan
      shell: bash
      working-directory: ${{ inputs.working-directory }}
      env:
        DL_TARGET: ${{ inputs.target }}
        DL_MIN_SEVERITY: ${{ inputs.min-severity }}
        DL_RULES: ${{ inputs.rules }}
        DL_FAIL_ON: ${{ inputs.fail-on }}
        DL_FAIL_ON_CONFIDENCE: ${{ inputs.fail-on-confidence }}
        DL_GATE: ${{ inputs.gate }}
        DL_FORMAT: ${{ inputs.format }}
        DL_OUTPUT: ${{ inputs.output }}
        DL_CHANGED: ${{ inputs.changed }}
        DL_DIFF_BASE: ${{ inputs.diff-base }}
        DL_PACK: ${{ inputs.pack }}
        DL_PACKAGE: ${{ inputs.package }}
        DL_PROFILE: ${{ inputs.profile }}
        DL_CACHE: ${{ inputs.cache }}
        DL_CACHE_PATH: ${{ inputs.cache-path }}
        DL_PARALLEL: ${{ inputs.parallel }}
        DL_BATCH_SIZE: ${{ inputs.batch-size }}
        DL_BLAME_AGE: ${{ inputs.blame-age }}
        DL_HOTSPOTS: ${{ inputs.hotspots }}
        DL_CHURN_DAYS: ${{ inputs.churn-days }}
        DL_CHURN_RANGE: ${{ inputs.churn-range }}
        DL_OWNERSHIP: ${{ inputs.ownership }}
        DL_CODEOWNERS: ${{ inputs.codeowners }}
        DL_AUDIT_SUPPRESSIONS: ${{ inputs.audit-suppressions }}
        DL_RESPECT_GITIGNORE: ${{ inputs.respect-gitignore }}
        DL_BASELINE: ${{ inputs.baseline }}
        DL_CONFIG: ${{ inputs.config }}
        DL_WRITE_BASELINE: ${{ inputs.write-baseline }}
        DL_THRESHOLDS: ${{ inputs.thresholds }}
        DL_MAX_FILES: ${{ inputs.max-files }}
        DL_QUIET: ${{ inputs.quiet }}
        DL_GROUP_BY: ${{ inputs.group-by }}
        DL_SARIF_COMPACT: ${{ inputs.sarif-compact }}
        DL_SARIF_CATEGORY: ${{ inputs.sarif-category }}
        DL_JUNIT_FAIL_ON: ${{ inputs.junit-fail-on }}
        DL_MARKDOWN_HEATMAP: ${{ inputs.markdown-heatmap }}
        DL_FAIL_ON_REGRESSION: ${{ inputs.fail-on-regression }}
        DL_JSON_OUTPUT: ${{ inputs.json-output }}
        DL_STEP_SUMMARY: ${{ inputs.step-summary }}
        DL_COMMENT: ${{ inputs.comment }}
        DL_PREVIOUS_REPORT: ${{ inputs.previous-report }}
        DL_COMMENT_DELTA_ONLY: ${{ inputs.comment-delta-only }}
        DL_COMMENT_MAX_FINDINGS: ${{ inputs.comment-max-findings }}
        DL_COMMENT_MAX_BYTES: ${{ inputs.comment-max-bytes }}
        DL_COMMENT_FULL_REPORT_URL: ${{ inputs.comment-full-report-url }}
        DL_COMMENT_FAIL_ON_ERROR: ${{ inputs.comment-fail-on-error }}
        DL_UPLOAD_JSON_ARTIFACT: ${{ inputs.upload-json-artifact }}
        DL_JSON_ARTIFACT_NAME: ${{ inputs.json-artifact-name }}
        DL_ANNOTATIONS: ${{ inputs.annotations }}
        DL_ANNOTATIONS_MAX_COUNT: ${{ inputs.annotations-max-count }}
        GITHUB_TOKEN: ${{ github.token }}
      run: |
        set -euo pipefail
        if [ -n "$DL_WRITE_BASELINE" ]; then
          args=(scan "$DL_TARGET" --min-severity "$DL_MIN_SEVERITY" --write-baseline "$DL_WRITE_BASELINE")
          [ -n "$DL_RULES" ] && args+=(--rules "$DL_RULES")
          [ -n "$DL_PACK" ] && args+=(--pack "$DL_PACK")
          [ -n "$DL_CONFIG" ] && args+=(--config "$DL_CONFIG")
          [ -n "$DL_THRESHOLDS" ] && args+=(--threshold "$DL_THRESHOLDS")
          [ -n "$DL_MAX_FILES" ] && args+=(--max-files "$DL_MAX_FILES")
          if [ "$DL_CACHE" = "true" ]; then
            if [ -n "$DL_CACHE_PATH" ]; then
              args+=(--cache "$DL_CACHE_PATH")
            else
              args+=(--cache)
            fi
          fi
          [ "$DL_PARALLEL" = "true" ] && args+=(--parallel)
          [ -n "$DL_BATCH_SIZE" ] && args+=(--batch-size "$DL_BATCH_SIZE")
          [ -n "$DL_PACKAGE" ] && args+=(--package "$DL_PACKAGE")
          [ "$DL_RESPECT_GITIGNORE" = "true" ] && args+=(--respect-gitignore)
          node "$GITHUB_ACTION_PATH/dist/cli/index.js" "${args[@]}"
          exit $?
        fi

        internal_json="$RUNNER_TEMP/debtlens-report.json"
        args=(scan "$DL_TARGET" --min-severity "$DL_MIN_SEVERITY" --format json --output "$internal_json")
        [ -n "$DL_RULES" ] && args+=(--rules "$DL_RULES")
        [ -n "$DL_PACK" ] && args+=(--pack "$DL_PACK")
        [ -n "$DL_FAIL_ON" ] && args+=(--fail-on "$DL_FAIL_ON")
        [ -n "$DL_FAIL_ON_CONFIDENCE" ] && args+=(--fail-on-confidence "$DL_FAIL_ON_CONFIDENCE")
        [ -n "$DL_GATE" ] && args+=(--gate "$DL_GATE")
        [ -n "$DL_BASELINE" ] && args+=(--baseline "$DL_BASELINE")
        [ -n "$DL_DIFF_BASE" ] && args+=(--diff-base "$DL_DIFF_BASE")
        [ -n "$DL_CONFIG" ] && args+=(--config "$DL_CONFIG")
        if [ "$DL_CHANGED" = "true" ]; then
          args+=(--changed)
        elif [ -n "$DL_CHANGED" ]; then
          args+=(--changed "$DL_CHANGED")
        fi
        [ "$DL_RESPECT_GITIGNORE" = "true" ] && args+=(--respect-gitignore)
        [ -n "$DL_THRESHOLDS" ] && args+=(--threshold "$DL_THRESHOLDS")
        [ -n "$DL_MAX_FILES" ] && args+=(--max-files "$DL_MAX_FILES")
        if [ "$DL_CACHE" = "true" ]; then
          if [ -n "$DL_CACHE_PATH" ]; then
            args+=(--cache "$DL_CACHE_PATH")
          else
            args+=(--cache)
          fi
        fi
        [ "$DL_PARALLEL" = "true" ] && args+=(--parallel)
        [ -n "$DL_BATCH_SIZE" ] && args+=(--batch-size "$DL_BATCH_SIZE")
        [ "$DL_BLAME_AGE" = "true" ] && args+=(--blame-age)
        [ "$DL_HOTSPOTS" = "true" ] && args+=(--hotspots)
        [ -n "$DL_CHURN_DAYS" ] && args+=(--churn-days "$DL_CHURN_DAYS")
        [ -n "$DL_CHURN_RANGE" ] && args+=(--churn-range "$DL_CHURN_RANGE")
        [ "$DL_OWNERSHIP" = "true" ] && args+=(--ownership)
        [ -n "$DL_CODEOWNERS" ] && args+=(--codeowners "$DL_CODEOWNERS")
        [ "$DL_AUDIT_SUPPRESSIONS" = "true" ] && args+=(--audit-suppressions)
        [ -n "$DL_PACKAGE" ] && args+=(--package "$DL_PACKAGE")
        [ "$DL_PROFILE" = "true" ] && args+=(--profile)
        [ "$DL_FAIL_ON_REGRESSION" = "true" ] && args+=(--fail-on-regression)
        summary_fail_on="$DL_FAIL_ON"
        summary_fail_on_confidence="$DL_FAIL_ON_CONFIDENCE"
        summary_fail_on_regression="$DL_FAIL_ON_REGRESSION"
        case "$DL_GATE" in
          new-code)
            [ -z "$summary_fail_on" ] && summary_fail_on="high"
            ;;
          strict-new-code)
            [ -z "$summary_fail_on" ] && summary_fail_on="medium"
            [ -z "$summary_fail_on_confidence" ] && summary_fail_on_confidence="0.8"
            summary_fail_on_regression="true"
            ;;
          legacy-baseline)
            [ -z "$summary_fail_on" ] && summary_fail_on="high"
            summary_fail_on_regression="true"
            ;;
        esac
        set +e
        node "$GITHUB_ACTION_PATH/dist/cli/index.js" "${args[@]}"
        scan_status=$?
        set -e

        DEBTLENS_SCAN_STATUS="$scan_status" \
          DEBTLENS_JSON_PATH="$internal_json" \
          DEBTLENS_JSON_OUTPUT="$DL_JSON_OUTPUT" \
          DEBTLENS_UPLOAD_JSON_ARTIFACT="$DL_UPLOAD_JSON_ARTIFACT" \
          DEBTLENS_JSON_ARTIFACT_NAME="$DL_JSON_ARTIFACT_NAME" \
          DEBTLENS_REPORT_OUTPUT="$DL_OUTPUT" \
          DEBTLENS_REPORT_FORMAT="$DL_FORMAT" \
          node "$GITHUB_ACTION_PATH/scripts/export-action-outputs.mjs" "$internal_json"

        if [ -n "$DL_JSON_OUTPUT" ]; then
          mkdir -p "$(dirname "$DL_JSON_OUTPUT")"
          cp "$internal_json" "$DL_JSON_OUTPUT"
        fi

        export DEBTLENS_QUIET="$DL_QUIET"
        export DEBTLENS_GROUP_BY="$DL_GROUP_BY"
        export DEBTLENS_SARIF_COMPACT="$DL_SARIF_COMPACT"
        export DEBTLENS_SARIF_CATEGORY="$DL_SARIF_CATEGORY"
        export DEBTLENS_JUNIT_FAIL_ON="$DL_JUNIT_FAIL_ON"
        export DEBTLENS_MARKDOWN_HEATMAP="$DL_MARKDOWN_HEATMAP"
        export DEBTLENS_PR_COMMENT_DELTA_ONLY="$DL_COMMENT_DELTA_ONLY"
        export DEBTLENS_PR_COMMENT_MAX_FINDINGS="$DL_COMMENT_MAX_FINDINGS"
        export DEBTLENS_PR_COMMENT_MAX_BYTES="$DL_COMMENT_MAX_BYTES"
        export DEBTLENS_PR_COMMENT_FULL_REPORT_URL="$DL_COMMENT_FULL_REPORT_URL"

        if [ "$DL_FORMAT" = "json" ]; then
          if [ -n "$DL_OUTPUT" ]; then
            mkdir -p "$(dirname "$DL_OUTPUT")"
            cp "$internal_json" "$DL_OUTPUT"
          else
            cat "$internal_json"
          fi
        else
          node "$GITHUB_ACTION_PATH/scripts/render-scan-result.mjs" "$internal_json" "$DL_FORMAT" "$DL_OUTPUT"
        fi

        if [ "$DL_STEP_SUMMARY" = "true" ] && [ -n "$GITHUB_STEP_SUMMARY" ]; then
          DEBTLENS_SCAN_STATUS="$scan_status" \
            DEBTLENS_FAIL_ON="$summary_fail_on" \
            DEBTLENS_FAIL_ON_CONFIDENCE="$summary_fail_on_confidence" \
            DEBTLENS_FAIL_ON_REGRESSION="$summary_fail_on_regression" \
            DEBTLENS_JSON_PATH="$internal_json" \
            DEBTLENS_JSON_OUTPUT="$DL_JSON_OUTPUT" \
            DEBTLENS_UPLOAD_JSON_ARTIFACT="$DL_UPLOAD_JSON_ARTIFACT" \
            DEBTLENS_JSON_ARTIFACT_NAME="$DL_JSON_ARTIFACT_NAME" \
            DEBTLENS_REPORT_OUTPUT="$DL_OUTPUT" \
            DEBTLENS_REPORT_FORMAT="$DL_FORMAT" \
            node "$GITHUB_ACTION_PATH/scripts/append-step-summary.mjs" "$internal_json" "$DL_PREVIOUS_REPORT"
        fi

        if [ "$DL_ANNOTATIONS" = "true" ]; then
          DEBTLENS_ANNOTATIONS_MAX_COUNT="$DL_ANNOTATIONS_MAX_COUNT" node "$GITHUB_ACTION_PATH/scripts/emit-github-annotations.mjs" "$internal_json"
        fi

        if [ "$DL_COMMENT" = "true" ]; then
          comment_output="$RUNNER_TEMP/debtlens-pr-comment.md"
          node "$GITHUB_ACTION_PATH/scripts/render-scan-result.mjs" "$internal_json" pr-comment "$comment_output"
          DEBTLENS_COMMENT_FAIL_ON_ERROR="$DL_COMMENT_FAIL_ON_ERROR" node "$GITHUB_ACTION_PATH/scripts/post-pr-comment.mjs" "$comment_output"
        fi

    - uses: actions/upload-artifact@v4
      if: ${{ inputs.upload-json-artifact == 'true' && inputs.write-baseline == '' }}
      with:
        name: ${{ inputs.json-artifact-name }}
        path: ${{ runner.temp }}/debtlens-report.json
        retention-days: ${{ inputs.json-artifact-retention-days }}
    - name: Complete DebtLens scan
      if: ${{ always() && inputs.write-baseline == '' }}
      shell: bash
      run: |
        if [ "${{ steps.scan.outcome }}" != "success" ]; then
          exit 1
        fi
        exit "${{ steps.scan.outputs['scan-status'] || 0 }}"