[FEAT] --diff-base flag: scope all analysis commands to changed files only

[Wolfvin]

Background

CodeLens currently scans the full repo on every invocation. In CI environments (PR checks, pre-merge gates), this means re-analyzing hundreds of unchanged files on every commit — wasting time and producing noise from pre-existing findings that are irrelevant to the current change.

Strix (a dynamic pentest agent) solves this with a --scope-mode diff + --diff-base pattern that limits analysis to changed files only. The same approach applies cleanly to CodeLens's static model.

Goal

Add a --diff-base <ref> global flag (and optionally --diff-base HEAD~1 as a shortcut) that pre-filters the file list for any analysis command to only files changed relative to the given ref.

# Only scan files changed vs main
codelens check . --diff-base main
codelens taint . --diff-base main
codelens vuln-scan . --diff-base origin/HEAD
codelens scan . --diff-base HEAD~1

Implementation

This is a pre-filter layer, not new analysis logic:

1. When --diff-base <ref> is provided, run:

   subprocess.run(['git', 'diff', '--name-only', ref, 'HEAD'], capture_output=True)

2. Parse the output into a set of changed file paths
3. Pass this set as an allowlist to the existing file discovery layer — unchanged files are skipped before any parsing/analysis begins
4. If the diff is empty (no changed files), exit early with a clear message

The filter should live in a shared DiffScope utility class used by all commands, so it's a single implementation point rather than per-command.

Definition of Done

• --diff-base <ref> flag accepted by all analysis commands (check, scan, taint, vuln-scan, dead-code, secrets, complexity, circular)
• git diff --name-only output used as file allowlist before file discovery
• Empty diff → early exit with message No changed files relative to <ref>
• Invalid ref → clear error, non-zero exit
• --diff-base documented in --help output for each affected command
• SKILL.md updated: CI usage example with --diff-base
• sync_command_count.py --apply run (count unchanged — this is a flag, not a new command)

Source of Truth

• Existing file discovery logic: scripts/codelens.py + individual command files in scripts/commands/
• DiffScope utility: new module, scripts/utils/diff_scope.py (suggested location)
• Strix reference: strix/core/scope.py in https://github.com/usestrix/strix (public repo — read for inspiration, do not copy)

CI use case

- name: CodeLens diff check
  run: python scripts/codelens.py check . --diff-base origin/main --format sarif > codelens.sarif

This replaces a full-repo scan on every PR with a targeted scan of only what changed — the primary use case this flag enables.

[Wolfvin]

🔄 Taking this issue

Mengerjakan issue ini -- 2026-07-02T17:49:59Z

Scope: full issue — --diff-base <ref> global flag for all analysis commands. New scripts/diff_scope.py utility class wrapping git diff --name-only, wired into scripts/codelens.py so the changed-files allowlist is passed to every command's file discovery. Empty diff → early exit, invalid ref → clear error. Docs update in SKILL.md + SKILL-QUICK.md with CI usage example. No command count change (flag, not new command).

[Wolfvin]

PR siap review

PR: #161 — feat(diff): --diff-base flag scopes analysis to git-changed files (closes #157)
Branch: feat/issue-157-diff-base-flag
Summary: Implements issue #157 — adds global --diff-base <ref> flag that restricts any analysis command to only report findings from files changed relative to a git ref. New scripts/diff_scope.py DiffScope utility class (validates ref, computes changed-file set via git_aware, filters findings by file path). Wired into codelens.py as a post-filter layer (commands scan full workspace, findings from unchanged files removed before output). Empty diff → early exit, invalid ref → exit 1. Works on all 20+ analysis commands; graph commands (scan/trace/impact/circular) excluded (filtering would corrupt graph structure). DiffScope is reusable — PR #141 could adopt it to replace its per-command --diff-vs flag.
Tests: 44 passed (new test_diff_scope.py — construction, allows(), filter_findings() with all key variants, from_ref() against real temp git repos, error cases, CLI integration via subprocess), 129 passed regression check (test_formatters + test_cli + test_command_count + test_command_registry + test_git_aware — no regressions), 0 failed. Command count unchanged at 70 (flag, not new command).
Findings: PR #141 (issue #57, open) implements similar functionality for check command only. This PR is global (all analysis commands). No file collision. Complementary — both can merge.