feat: add interactive visualization command (fallow viz)

.claude/rules/cli-crate.md

@@ -26,6 +26,7 @@ Key modules:
 - `migrate/` , Config migration from knip/jscpd/stylelint
 - `init.rs` , Generate config files (`.fallowrc.json` or `fallow.toml`), scaffold starter agent guides (`--agents`), scaffold pre-commit git hooks (`--hooks`), record a deliberate stay-unconfigured decision (`--decline`, conflicts with the scaffolding flags; persists `onboarding_declined` in the impact store via `impact::decline_onboarding`, writes NO config file, suppresses the first-contact `setup` next-step + human `Setup:` hint)
 - `list.rs` , Show active plugins, entry points, files, boundary zones/rules (`--boundaries`)
+- `viz.rs` , `viz` command: one engine-owned project analysis (`AnalysisSession::analyze_project_with_artifacts`, complexity + graph retained) handed to `fallow_engine::viz::build_viz_data`, then emitted as a self-contained interactive HTML map (treemap + force graph with dead-code / duplication / boundaries / complexity lenses) or `--viz-format dot`/`mermaid` text. The HTML embeds the built TS frontend from `viz-frontend/` (rolldown bundle at `crates/cli/viz-assets/viz.js` + `viz.css`, `include_str!`'d; rebuild via `cd viz-frontend && npm ci && npm run build`). Read-only, telemetry `Workflow::ProjectInventory`.
 - `plugin_check.rs` , `fallow plugin-check` read-only dry-run for external-plugin (manifestEntries) authoring. Loads config via `fallow_engine::project_config::config_for_project`, computes activation per plugin (`is_external_plugin_active`, empty discovered set + FS-fallback, no source walk), and for active plugins emits the shared `RuleReport` (`fallow_engine::plugins::check_manifest_entries`) as bespoke JSON with per-seed `path_exists` + typed `warnings[]`. Exit 0 always. See `.claude/rules/plugins.md` for the full loop.
 - `schema.rs` , `schema`, `config-schema`, `plugin-schema`, `rule-pack-schema` commands (the schema printers live in `init.rs`; `rule-pack-schema` prints `RulePackDef::json_schema()`). `fallow schema` is the agent capability manifest: `manifest_version` "1", clap-derived commands/global_flags, `issue_types` derived from the explain rule slices (one row per rule, all analyses; per-id metadata table for filter_flag/fixable/suppress_comment/note/license; drift tests pin completeness vs the rule slices, IssueKind coverage, suppress-token round-trip through `IssueKind::parse`, and filter-flag existence on live clap), an `mcp_tools` block from `fallow_types::mcp_manifest`, a live-derived `plugins` block, a `task_matrix` block (the agent task-to-command cheat sheet from `crate::task_matrix::TASK_MATRIX`, the same rows as `init --agents`, the `hooks install --target agent` managed block, root `--help`, and the generated SKILL.md section; drift tests parse every row's probe through live clap and pin the no-mutating-commands contract), and user-facing-only env vars (internal plumbing excluded via a guard test). Always JSON; ignores `--format`.
 - `security.rs` - opt-in `fallow security` command surfacing local security CANDIDATES (not verified vulnerabilities). MVP rule `client-server-leak` (detector in `crates/core/src/analyze/security/mod.rs`). `run()` loads config via `load_config_for_analysis`, forces `rules.security_client_server_leak` from `off` to `warn` (respecting an explicit user `error`), runs `fallow_core::analyze`, reads `results.security_findings` + `results.security_unresolved_edge_files` + unresolved-callee diagnostics, applies `--workspace` / `--changed-since` / `--file` retains, relativizes finding + trace paths, and renders `SecurityOutput` (human / JSON / SARIF). `--file` still builds the full project graph, then scopes candidates to matching finding anchors or trace hops and scopes unresolved-callee diagnostics by path. SARIF is hand-built at `level: note` with `partialFingerprints` (FNV) and no CWE; trace hops become `relatedLocations`. Exits 0 unless the user set the rule to `error` AND findings exist. `SecurityOutput`/`SecuritySchemaVersion` are a `FallowOutput::Security` variant registered in `schema_emit.rs`; `--format json` is in the published schema + TS contracts. Findings and unresolved-callee diagnostics are `#[serde(skip)]` on `AnalysisResults`, so they never appear under bare `fallow` or `audit`. **Agent-actionable candidate record (issue #900):** every `SecurityFinding` carries `candidate { source_kind, sink, boundary }` plus optional `taint_flow { source, sink, path }` and a top-level `finding_id`. Slot 1 `source_kind` is the stable catalogue source id, threaded through from `tainted_sink::sink_source` (it returns `(id, title)` now; the id was previously discarded after setting `source_backed`). The `sink` slot is self-contained (path/line/col/category/cwe/callee) and set by the detectors; the `boundary` slot (`client_server` from a `ClientBoundary` trace hop, `cross_module` from the reachability hop count, `architecture_zone` from the run's boundary-violation zone names) and `taint_flow` are filled by `rank::enrich_candidate`. `rank_security_findings` now takes a `boundary_crossings: FxHashMap<PathBuf, (from_zone, to_zone)>` map (built in `analyze/mod.rs`) instead of the old path set, so it can populate both `crosses_boundary` AND the zone slot. `taint_flow.path` is the compact `{ intra_module, cross_module_hops }` shape; the full ordered hops stay on `reachability.untrusted_source_trace`, never duplicated. There is deliberately NO `impact` wire field (agent-owned, documented in the schema doc comment). `finding_id` is the SARIF FNV fingerprint extracted to the shared `security_finding_id` helper, stamped in `run()` after relativization so it equals the SARIF `partialFingerprints` value; `relativize_finding` also relativizes the candidate/taint_flow paths. `export_visibility` and a package boundary are reserved follow-ups (absent, not always-false). The current security schema version is V4 after metadata V3 and unresolved-callee diagnostic samples in issue #1134. **`secret-to-network` exfil category (issue #890):** an INCLUDE-REQUIRED catalogue category (CWE-201) admitted only via `security.categories.include` (gated by `tainted_sink::is_include_required_category` calling `CategoryFilter::explicitly_admits`, like `hardcoded-secret`). A non-public `process.env` / `import.meta.env` secret reaching a network sink's body/options arg via same-identifier source-backing. Three load-bearing pieces: (1) the new `requires_source_kinds: Vec<String>` matcher field narrows `requires_source` to specific source ids; `matcher_admits_sink` now takes the matched source as `(id, title)` (the call site stopped discarding the id) and gates on `requires_source_kinds` containing the id. (2) The shared `is_public_env_var` / `is_public_env_path` predicate moved to `fallow_types::extract`; the extract layer skips public env vars in `tainted_source_path` AND `collect_source_paths_into` (the latter must return BEFORE recursing into the bare `process.env` object, or the object prefix re-introduces the source, the bug that broke the #876 public-env regression). `flatten_member_path` gained a `MetaProperty` arm so `import.meta.env.X` is modeled as a source. (3) `SinkSite.url_arg_literal` captures the network call's arg-0 URL literal (`call_url_arg_literal`); for `secret-to-network` findings, `tainted_sink` builds `candidate.network: SecurityNetworkContext { destination }` (the literal host, or `None` for a dynamic destination, the suspicious case). `CACHE_VERSION` 135 -> 136. Hardcoded-secret-as-source and a provider-match heuristic are reserved follow-ups. **`--gate <mode>` (issue #886, valued flag, `new` and `newly-reachable`; no `all` mode by design):** an opt-in regression gate that reports ONLY candidates introduced on a CHANGED LINE and exits **8** if any exist, so a PR gates on new exposure without gating on the backlog. Requires a diff source (`--changed-since`, `--diff-file`, or `--diff-stdin`); a diff it cannot compute is a LOUD exit 2 (via `changed_files::try_get_changed_diff`, which returns `Err` on git failure rather than `get_changed_files`' silent `None`), NEVER a green gate. The gate filter is the STRICT `check::filtering::retain_gate_new` (a SEPARATE pass from the advisory `filter_results_by_diff`, leaving advisory display untouched): keep a new sink anchor on an added line OR a `UntrustedSource`/`Sink` trace hop on an added line; DROP the `SecretSource && touches_file` file-level exception and `Intermediate`/`ClientBoundary` pass-through hops (so editing a secret-reading file does not trip the gate). `--changed-since` for the gate builds a LINE-level diff (`git diff --relative --unified=0 ref...HEAD`); the existing `--changed-since` file-level filter is unrelated. Exit contract: **8** = new candidate (PURE: never "could not run"), and the gate SUPERSEDES the advisory `--fail-on-issues` exit-1 path in gate mode (composing would re-gate the backlog). The `gate` block on `SecurityOutput` (`mode`/`verdict`/`new_count`, snake_case, emitted on pass too so consumers distinguish "gate ran and passed" from "gate did not run") is additive on `SecuritySchemaVersion` V2; human prose says "REVIEW REQUIRED" (not FAIL) with the unverified disclaimer; SARIF keeps `level: note` and rides the gate as a `run.properties.fallowGate` property. Canonical pre-commit recipe: `git diff --cached --unified=0 | fallow security --gate new --diff-stdin` (staged content; `--changed-since` checks committed HEAD). `--gate newly-reachable` requires `--changed-since <ref>`, materializes the base tree through the shared base worktree module, and compares reachable keys (`security-reach:<rel_path>:<kind>:<category>`) for findings with `reachability.reachable_from_entry == true`. It runs before changed-file advisory narrowing so unchanged sink anchors that became reachable through changed imports are not hidden. Diff-only inputs (`--diff-file` or `--diff-stdin` without `--changed-since`) exit 2 because this mode needs the base tree, not just added lines. Base reachable snapshots are cached under `.fallow/cache/security-base-v<N>/` unless `--no-cache` is set.

.github/workflows/ci.yml

@@ -39,6 +39,7 @@ jobs:
       self-analyze: ${{ steps.filter.outputs.self-analyze }}
       skills: ${{ steps.filter.outputs.skills }}
       action-current: ${{ steps.filter.outputs.action-current }}
+      viz: ${{ steps.filter.outputs.viz }}
     steps:
       - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
       - uses: dorny/paths-filter@7b450fff21473bca461d4b92ce414b9d0420d706 # v4.0.2
@@ -169,6 +170,9 @@ jobs:
               - '.github/actions/setup-rust/**'
               - '.github/workflows/ci.yml'
               - 'scripts/workflow-policy.test.mjs'
+            viz:
+              - 'viz-frontend/**'
+              - 'crates/cli/viz-assets/**'
 
   docker:
     name: Docker
@@ -848,10 +852,34 @@ jobs:
           cargo +"$MIRI_TOOLCHAIN" miri test -p fallow-extract --lib --tests suppress::
           cargo +"$MIRI_TOOLCHAIN" miri test -p fallow-extract --lib --tests visitor::helpers::
 
+  viz-frontend:
+    name: Viz frontend
+    runs-on: ubuntu-latest
+    needs: changes
+    if: needs.changes.outputs.viz == 'true'
+    timeout-minutes: 10
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        with:
+          node-version: '22'
+      - run: npm ci
+        working-directory: viz-frontend
+      - run: npm run lint
+        working-directory: viz-frontend
+      - run: npm run test
+        working-directory: viz-frontend
+      - run: npm run build
+        working-directory: viz-frontend
+      - name: Bundle drift
+        run: git diff --exit-code crates/cli/viz-assets
+
   ci-ok:
     name: CI
     if: always()
-    needs: [check, windows-rust, doc, typos, js-lint, npm-package, action-current, fallow-self-analyze, vscode, test-gitlab-ci, audit, deny, shear, zizmor, msrv, miri, skills-vendor]
+    needs: [check, windows-rust, doc, typos, js-lint, npm-package, action-current, fallow-self-analyze, vscode, test-gitlab-ci, audit, deny, shear, zizmor, msrv, miri, skills-vendor, viz-frontend]
     runs-on: ubuntu-latest
     timeout-minutes: 5
     permissions: {}

.oxlintrc.json

@@ -83,6 +83,12 @@
       "rules": {
         "unicorn/prefer-node-protocol": "off"
       }
+    },
+    {
+      "files": ["viz-frontend/**/*.ts"],
+      "rules": {
+        "unicorn/no-new-array": "off"
+      }
     }
   ]
 }

CHANGELOG.md

@@ -38,6 +38,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- **`fallow viz` renders your codebase as an interactive map.** A new command that runs one project analysis and writes a single self-contained HTML file (no server, no external assets) styled like the rest of fallow: a nested treemap of files sized by bytes, plus a force-directed import graph with directory and import-community clustering. Both views share four lenses that recolor the same map: dead code (unused files, unused exports, entry points), duplication (share of duplicated lines per file, with clone previews), boundaries (architecture zones from your `boundaries` config, with violating imports drawn in red), and complexity hotspots (per-function cyclomatic and cognitive scores, including React context such as hook counts and JSX depth). Clicking any file opens a detail panel with the evidence: unused export names, clone groups and their other locations, boundary crossings, cycle membership, importers and imports as click-through navigation, and a runnable `fallow ... --trace` command to verify each finding. Search, breadcrumb drill-down, keyboard shortcuts, shareable URL deep links, and dark/light themes are built in; findings carry a hatch texture and `[E]`/`[W]` prefixes so color is never the only signal, and all motion honors `prefers-reduced-motion`. The HTML opens in your browser by default (`--no-open` to skip, `--out <path>` to choose the file); `--viz-format dot` and `--viz-format mermaid` emit the import graph as text for piping into other tools. Read-only, and respects `--production`, `--config`, and `--no-cache` like the analysis commands.
+
 - **VS Code can set a changed-code baseline at HEAD in one command.** The new
   `Fallow: Set Baseline at HEAD` palette command creates the local lightweight
   `fallow-baseline` tag, writes `fallow.changedSince` to a single-folder

CLAUDE.md

@@ -24,7 +24,7 @@ crates/
   api/      -- Programmatic API boundary for JS/native callers
   napi/     -- napi-rs native Node addon (cdylib, #[napi] bindings) behind the @fallow/node package
   cli/      -- CLI binary, split into per-command modules
-    audit.rs, check/, dupes.rs, health/, watch.rs, fix/, init.rs, list.rs, schema.rs, regression/, impact.rs, security.rs
+    audit.rs, check/, dupes.rs, health/, watch.rs, fix/, init.rs, list.rs, schema.rs, regression/, impact.rs, security.rs, viz.rs
     license/    -- `fallow license {activate, status, refresh, deactivate}` with offline JWT verify plus live trial / refresh flows
     coverage/   -- `fallow coverage setup` resumable first-run state machine for runtime coverage
     report/     -- Output formatting (mod.rs dispatch, human/, json.rs, sarif.rs, compact.rs, markdown.rs)
@@ -35,6 +35,7 @@ crates/
   multicall/ -- Packaged `fallow` binary bundling the CLI, LSP, and MCP servers into one engine (renamed to `fallow` at packaging time for npm platform packages and VS Code); publish = false, so `cargo install fallow-cli` stays the pure CLI
 editors/
   vscode/   -- VS Code extension (LSP client, tree views, status bar, auto-download)
+viz-frontend/ -- TS source (rolldown) for the `fallow viz` interactive HTML; bundles to crates/cli/viz-assets/
 npm/
   fallow/   -- npm wrapper package with optionalDependencies pattern
 action/       -- GitHub Action (composite)

Cargo.toml

@@ -103,6 +103,9 @@ tokio = { version = "1", features = ["rt-multi-thread", "macros", "sync", "io-st
 # File watching
 notify = "8"
 
+# Browser
+open = "5"
+
 # Testing
 criterion2 = { version = "3.0.3", default-features = false }
 dhat = "0.3"

README.md

@@ -116,6 +116,7 @@ Adopting on an existing codebase? `fallow audit` fails only on findings a change
 | [`npx fallow recommend`](https://docs.fallow.tools/cli/recommend) | Detect the stack and propose a config; subjective choices stay open questions |
 | [`npx fallow init`](https://docs.fallow.tools/cli/init) | Scaffold config; `--agents` scaffolds an AGENTS.md |
 | `npx fallow migrate` | Migrate from knip, jscpd, or stylelint config |
+| `npx fallow viz` | Interactive HTML map of the codebase: treemap + import graph with dead-code, duplication, boundaries, and hotspot lenses |
 | `npx fallow schema` | Machine-readable capability manifest (always JSON) |
 
 <details>