fallow 2.92.1 → 2.93.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "fallow",
|
|
3
|
-
"version": "2.
|
|
3
|
+
"version": "2.93.0",
|
|
4
4
|
"description": "Deterministic codebase intelligence for TypeScript and JavaScript. Quality, risk, architecture, dependencies, duplication, and safe cleanup evidence for humans, CI, and agents. Optional runtime intelligence layer (Fallow Runtime) adds production execution evidence. Rust-native, sub-second, zero-config framework support.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"repository": {
|
|
@@ -83,13 +83,13 @@
|
|
|
83
83
|
"@tanstack/intent": "0.0.41"
|
|
84
84
|
},
|
|
85
85
|
"optionalDependencies": {
|
|
86
|
-
"@fallow-cli/darwin-arm64": "2.
|
|
87
|
-
"@fallow-cli/darwin-x64": "2.
|
|
88
|
-
"@fallow-cli/linux-x64-gnu": "2.
|
|
89
|
-
"@fallow-cli/linux-arm64-gnu": "2.
|
|
90
|
-
"@fallow-cli/linux-x64-musl": "2.
|
|
91
|
-
"@fallow-cli/linux-arm64-musl": "2.
|
|
92
|
-
"@fallow-cli/win32-arm64-msvc": "2.
|
|
93
|
-
"@fallow-cli/win32-x64-msvc": "2.
|
|
86
|
+
"@fallow-cli/darwin-arm64": "2.93.0",
|
|
87
|
+
"@fallow-cli/darwin-x64": "2.93.0",
|
|
88
|
+
"@fallow-cli/linux-x64-gnu": "2.93.0",
|
|
89
|
+
"@fallow-cli/linux-arm64-gnu": "2.93.0",
|
|
90
|
+
"@fallow-cli/linux-x64-musl": "2.93.0",
|
|
91
|
+
"@fallow-cli/linux-arm64-musl": "2.93.0",
|
|
92
|
+
"@fallow-cli/win32-arm64-msvc": "2.93.0",
|
|
93
|
+
"@fallow-cli/win32-x64-msvc": "2.93.0"
|
|
94
94
|
}
|
|
95
95
|
}
|
package/skills/fallow/SKILL.md
CHANGED
|
@@ -22,8 +22,14 @@ Codebase intelligence for JavaScript and TypeScript. The free static layer repor
|
|
|
22
22
|
- Auditing a project for structural issues
|
|
23
23
|
- Setting up CI quality gates or duplication thresholds
|
|
24
24
|
- Auto-fixing unused exports and dependencies
|
|
25
|
-
- Detecting feature flag patterns (environment gates, SDK calls, config objects)
|
|
25
|
+
- Detecting feature flag patterns (environment gates, SDK calls, config objects) with `fallow flags`
|
|
26
26
|
- Investigating why a specific export or file appears unused
|
|
27
|
+
- Surfacing local security candidates for an agent to verify (`fallow security`)
|
|
28
|
+
- Finding untested but runtime-reachable code (`fallow health --coverage-gaps`)
|
|
29
|
+
- Ranking complexity hotspots, code owners, and refactoring targets (`fallow health --hotspots --ownership --targets`)
|
|
30
|
+
- Gating CI on regressions with baselines (`--save-baseline` / `--save-regression-baseline`)
|
|
31
|
+
- Explaining an issue type or why a function scored high (`fallow explain`, `fallow health --complexity-breakdown`)
|
|
32
|
+
- Reviewing what fallow has surfaced over time (`fallow impact`)
|
|
27
33
|
|
|
28
34
|
## When NOT to Use
|
|
29
35
|
|
|
@@ -60,87 +66,143 @@ cargo install fallow-cli # build from source
|
|
|
60
66
|
10. **Type the JSON in TypeScript**. When a project has `fallow` installed as a dev-dependency and the agent is consuming `--format json` output from TypeScript code, `import type { CheckOutput, HealthOutput, DupesOutput, AuditOutput, FallowJsonOutput } from "fallow/types"` exposes the full output contract. `SchemaVersion` is pinned to a literal at codegen time, so a major schema bump fails to compile at call sites that gate on the version.
|
|
61
67
|
11. **Never enable telemetry on the user's behalf**. Fallow's product telemetry is opt-in and off by default; only the user may run `fallow telemetry enable`. You MAY set `FALLOW_AGENT_SOURCE=<allowlisted-value>` (for example `claude_code`, `codex`, `cursor`, `windsurf`, `gemini`, `cline`) so that, IF the user has already enabled telemetry, your integration is correctly attributed. Setting `FALLOW_AGENT_SOURCE` never enables telemetry by itself and uploads no codebase content.
|
|
62
68
|
|
|
69
|
+
## Task Cheat Sheet
|
|
70
|
+
|
|
71
|
+
Route by intent before reaching for the big analysis commands. Same matrix as `fallow schema` (`task_matrix`) and the generated AGENTS.md section.
|
|
72
|
+
|
|
73
|
+
<!-- generated:task-matrix:start -->
|
|
74
|
+
| When the agent is about to... | Run |
|
|
75
|
+
|---|---|
|
|
76
|
+
| delete an "unused" export or file | `fallow dead-code --trace <file>:<export>` |
|
|
77
|
+
| delete an "unused" dependency | `fallow dead-code --trace-dependency <name>` |
|
|
78
|
+
| commit or open a PR | `fallow audit --base <ref>` |
|
|
79
|
+
| prioritize refactoring | `fallow health --hotspots --targets` |
|
|
80
|
+
| ask who owns code | `fallow health --ownership` |
|
|
81
|
+
| check untested-but-reachable code | `fallow health --coverage-gaps` |
|
|
82
|
+
| consolidate duplication | `fallow dupes --trace dup:<fingerprint>` |
|
|
83
|
+
| find feature flags | `fallow flags` |
|
|
84
|
+
| surface security candidates | `fallow security` |
|
|
85
|
+
| understand a finding | `fallow explain <issue-type>` |
|
|
86
|
+
| scope a monorepo | `--workspace <glob> / --changed-workspaces <ref>`; global flags, prefix any command |
|
|
87
|
+
<!-- generated:task-matrix:end -->
|
|
88
|
+
|
|
63
89
|
## Commands
|
|
64
90
|
|
|
91
|
+
<!-- generated:commands:start -->
|
|
65
92
|
| Command | Purpose | Key Flags |
|
|
66
|
-
|
|
93
|
+
|---|---|---|
|
|
67
94
|
| `fallow` | Run full codebase analysis: cleanup + duplication + health (default) | `--only`, `--skip`, `--production`, `--production-dead-code`, `--production-health`, `--production-dupes`, `--ci`, `--fail-on-issues`, `--group-by`, `--summary`, `--fail-on-regression`, `--tolerance`, `--regression-baseline`, `--save-regression-baseline`, `--score`, `--trend`, `--save-snapshot`, `--include-entry-exports` |
|
|
68
95
|
| `dead-code` | Dead code analysis (`check` is an alias) | `--unused-exports`, `--changed-since`, `--changed-workspaces`, `--production`, `--file`, `--include-entry-exports`, `--stale-suppressions`, `--ci`, `--group-by`, `--summary`, `--fail-on-regression`, `--tolerance`, `--regression-baseline`, `--save-regression-baseline` |
|
|
69
|
-
| `
|
|
96
|
+
| `watch` | Watch for changes and re-run analysis | `--no-clear` |
|
|
70
97
|
| `fix` | Auto-remove unused exports/deps | `--dry-run`, `--yes` (required in non-TTY) |
|
|
71
98
|
| `init` | Generate config file, AGENTS.md agent guide, or pre-commit hook | `--toml`, `--agents`, `--hooks`, `--branch` |
|
|
72
|
-
| `
|
|
99
|
+
| `hooks` | Install or remove fallow-managed Git and agent hooks | |
|
|
100
|
+
| `ci` | CI helpers for PR/MR feedback envelopes | |
|
|
101
|
+
| `ci reconcile-review` | Resolve stale review threads on a PR/MR by joining a typed review envelope (`--format review-github` / `review-gitlab`) against the provider's existing comments + threads. Posts an idempotent "Resolved in `<sha>`" follow-up per stale fingerprint, marker keyed on (fingerprint, short-sha) so re-runs on the same commit don't duplicate. Provider mutations are fail-fast; JSON can include `apply_hint`, `failed_fingerprints`, and `unapplied_fingerprints` when `apply_errors` is non-empty. | `--provider`, `--pr` (GH) / `--mr` (GL), `--repo` / `--project-id`, `--api-url`, `--envelope`, `--dry-run` |
|
|
102
|
+
| `config-schema` | Print the JSON Schema for fallow configuration files | |
|
|
103
|
+
| `plugin-schema` | Print the JSON Schema for external plugin files | |
|
|
104
|
+
| `rule-pack-schema` | Print the JSON Schema for rule pack files | |
|
|
105
|
+
| `config` | Show the loaded config path and resolved config (verifies which `.fallowrc.json` is in effect) | `--path` |
|
|
73
106
|
| `list` | Inspect project structure | `--files`, `--entry-points`, `--plugins`, `--boundaries`, `--workspaces` |
|
|
74
107
|
| `workspaces` | Inspect monorepo workspaces + discovery diagnostics (shorthand for `list --workspaces`) | (no flags) |
|
|
108
|
+
| `dupes` | Code duplication detection | `--mode`, `--threshold`, `--top`, `--changed-since`, `--workspace`, `--changed-workspaces`, `--skip-local`, `--cross-language`, `--ignore-imports`, `--explain-skipped`, `--fail-on-regression`, `--tolerance`, `--regression-baseline`, `--save-regression-baseline` |
|
|
75
109
|
| `health` | Function complexity analysis (also covers Angular templates as synthetic `<template>` findings: external `.html` files via `templateUrl` AND inline `@Component({ template: \`...\` })` literals; suppress external with `<!-- fallow-ignore-file complexity -->` at the top of the `.html` file, suppress inline with `// fallow-ignore-next-line complexity` directly above the `@Component` decorator) | `--complexity`, `--max-cyclomatic`, `--max-cognitive`, `--max-crap`, `--top`, `--sort`, `--file-scores`, `--hotspots`, `--ownership`, `--ownership-emails`, `--targets`, `--effort`, `--score`, `--min-score`, `--since`, `--min-commits`, `--save-snapshot`, `--trend`, `--coverage-gaps`, `--coverage`, `--coverage-root`, `--runtime-coverage`, `--min-invocations-hot`, `--min-observation-volume`, `--low-traffic-threshold`, `--workspace`, `--changed-workspaces`, `--baseline`, `--save-baseline` |
|
|
76
|
-
| `audit` | Combined dead-code + complexity + duplication for changed files | `--base`, `--gate`, `--production`, `--production-dead-code`, `--production-health`, `--production-dupes`, `--workspace`, `--changed-workspaces`, `--ci`, `--fail-on-issues`, `--explain`, `--explain-skipped`, `--dead-code-baseline`, `--health-baseline`, `--dupes-baseline`, `--max-crap`, `--coverage`, `--coverage-root`, `--include-entry-exports` |
|
|
77
110
|
| `flags` | Detect feature flag patterns (env vars, SDK calls, config objects) | `--top` |
|
|
78
|
-
| `security` | Surface opt-in local security candidates for agent verification (not confirmed vulnerabilities). Rule families include the graph rule `client-server-leak`, a data-driven `tainted-sink` catalogue, and the include-required `hardcoded-secret` category for provider-prefix credentials and high-entropy literals assigned to secret-shaped identifiers. Most catalogue rows require non-literal input; narrowly literal-aware rows flag deterministic unsafe literals. Rules default off; suppress a file with `// fallow-ignore-file security-sink`; scope categories with `security.categories`. Add project-local request object names with `security.requestReceivers`; it extends the built-in `req` / `request` / `ctx` / `context` / `event` allowlist for HTTP `query`, `params`, and `body` reads. `hardcoded-secret` runs only when listed in `security.categories.include`. | `--format human|json|sarif`, `--changed-since`, `--file`, `--diff-file`, `--workspace`, `--changed-workspaces`, `--surface`, `--ci`, `--fail-on-issues`, `--sarif-file`, `--summary` |
|
|
79
111
|
| `explain` | Explain one issue type without running analysis | `<issue-type>`, `--format json` |
|
|
112
|
+
| `audit` | Combined dead-code + complexity + duplication for changed files | `--base`, `--gate`, `--production`, `--production-dead-code`, `--production-health`, `--production-dupes`, `--workspace`, `--changed-workspaces`, `--ci`, `--fail-on-issues`, `--explain`, `--explain-skipped`, `--dead-code-baseline`, `--health-baseline`, `--dupes-baseline`, `--max-crap`, `--coverage`, `--coverage-root`, `--include-entry-exports` |
|
|
113
|
+
| `impact` | Show what fallow has done for you: how many issues it is surfacing, the trend since the last recorded run, and how many commits it contained at the pre-commit gate | |
|
|
114
|
+
| `security` | Surface opt-in local security candidates for agent verification (not confirmed vulnerabilities). Rule families include the graph rule `client-server-leak`, a data-driven `tainted-sink` catalogue, and the include-required `hardcoded-secret` category for provider-prefix credentials and high-entropy literals assigned to secret-shaped identifiers. Most catalogue rows require non-literal input; narrowly literal-aware rows flag deterministic unsafe literals. Rules default off; suppress a file with `// fallow-ignore-file security-sink`; scope categories with `security.categories`. Add project-local request object names with `security.requestReceivers`; it extends the built-in `req` / `request` / `ctx` / `context` / `event` allowlist for HTTP `query`, `params`, and `body` reads. `hardcoded-secret` runs only when listed in `security.categories.include`. | `--format human\|json\|sarif`, `--changed-since`, `--file`, `--diff-file`, `--workspace`, `--changed-workspaces`, `--surface`, `--ci`, `--fail-on-issues`, `--sarif-file`, `--summary` |
|
|
115
|
+
| `schema` | Dump CLI definition as JSON | |
|
|
116
|
+
| `ci-template` | Print or vendor CI integration templates | |
|
|
117
|
+
| `migrate` | Convert knip/jscpd config | `--dry-run`, `--from PATH` |
|
|
80
118
|
| `license` | Manage the local license JWT for continuous/cloud runtime monitoring (activate, status, refresh, deactivate) | `activate --trial --email <addr>`, `activate --from-file`, `activate --stdin`, `status`, `refresh`, `deactivate` |
|
|
81
119
|
| `telemetry` | Manage opt-in, off-by-default product telemetry (never collects code, paths, or names). Agents must not enable it; only the user may | `status`, `enable`, `disable`, `inspect --example` |
|
|
82
120
|
| `coverage` | Runtime coverage setup, focused analysis, and cloud inventory workflow helper | `setup`, `setup --yes`, `setup --non-interactive`, `analyze --runtime-coverage <path>`, `analyze --cloud --repo owner/repo`, `upload-inventory` |
|
|
83
121
|
| `coverage upload-source-maps` | Upload build source maps from CI so bundled runtime coverage resolves to original source paths. Retries 429 `Retry-After` and transient gateway failures. Use `FALLOW_CA_BUNDLE` for complete custom PEM trust bundles. | `--dir dist`, `--git-sha <sha>`, `--repo <name>`, `--strip-path=false`, `--dry-run` |
|
|
84
|
-
| `
|
|
85
|
-
|
|
86
|
-
|
|
122
|
+
| `setup-hooks` | Install or remove a Claude Code PreToolUse hook that gates `git commit` / `git push` on `fallow audit`, so the agent cleans findings before the command runs | `--agent`, `--dry-run`, `--force`, `--user`, `--gitignore-claude`, `--uninstall` |
|
|
123
|
+
|
|
124
|
+
Run `fallow <command> --help` for the full flag list per command (see also references/cli-reference.md).
|
|
125
|
+
<!-- generated:commands:end -->
|
|
87
126
|
|
|
88
127
|
## Issue Types
|
|
89
128
|
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
|
94
|
-
|
|
|
95
|
-
|
|
|
96
|
-
|
|
|
97
|
-
|
|
|
98
|
-
|
|
|
99
|
-
|
|
|
100
|
-
|
|
|
101
|
-
|
|
|
102
|
-
|
|
|
103
|
-
|
|
|
104
|
-
|
|
|
105
|
-
|
|
|
106
|
-
|
|
|
107
|
-
|
|
|
108
|
-
|
|
|
109
|
-
|
|
|
110
|
-
|
|
|
111
|
-
|
|
|
112
|
-
|
|
|
129
|
+
<!-- generated:issue-types:start -->
|
|
130
|
+
| Type | Filter flag | Fixable | Suppress comment | Description |
|
|
131
|
+
|---|---|---|---|---|
|
|
132
|
+
| `unused-file` | `--unused-files` | - | `// fallow-ignore-file unused-file` | Files unreachable from entry points |
|
|
133
|
+
| `unused-export` | `--unused-exports` | yes | `// fallow-ignore-next-line unused-export` | Symbols never imported elsewhere |
|
|
134
|
+
| `unused-type` | `--unused-types` | - | `// fallow-ignore-next-line unused-type` | Type aliases and interfaces |
|
|
135
|
+
| `private-type-leak` | `--private-type-leaks` | - | `// fallow-ignore-next-line private-type-leak` | Opt-in API hygiene check (default `off`) for exported signatures whose type references a same-file private type |
|
|
136
|
+
| `unused-dependency` | `--unused-deps` | yes | - | Packages in `dependencies` never imported. In monorepos, internal workspace package names (e.g., `@repo/ui`) declared in another workspace's `package.json` but never imported are reported here too. `--unused-deps` also covers the dev/optional/type-only/test-only sibling rows below. |
|
|
137
|
+
| `unused-dev-dependency` | `--unused-deps` | yes | - | Packages in `devDependencies` never imported by test files, config files, or scripts |
|
|
138
|
+
| `unused-optional-dependency` | `--unused-deps` | yes | - | Packages in `optionalDependencies` never imported (often platform-specific; verify before removing) |
|
|
139
|
+
| `type-only-dependency` | `--unused-deps` | - | - | Production dependency only used via type-only imports; Only reported in --production mode; --unused-deps scopes it together with the other dependency kinds |
|
|
140
|
+
| `test-only-dependency` | `--unused-deps` | - | - | Production deps only imported from test files (should be devDependencies) |
|
|
141
|
+
| `unused-enum-member` | `--unused-enum-members` | yes | `// fallow-ignore-next-line unused-enum-member` | Enum values never referenced |
|
|
142
|
+
| `unused-class-member` | `--unused-class-members` | - | `// fallow-ignore-next-line unused-class-member` | Methods and properties |
|
|
143
|
+
| `unresolved-import` | `--unresolved-imports` | - | `// fallow-ignore-next-line unresolved-import` | Imports that can't be resolved |
|
|
144
|
+
| `unlisted-dependency` | `--unlisted-deps` | - | - | Used packages missing from package.json. In monorepos, importing a workspace package from a workspace whose own `package.json` does not list it is reported here too; self-references stay allowed without requiring a package to depend on itself. |
|
|
145
|
+
| `duplicate-export` | `--duplicate-exports` | - | `// fallow-ignore-file duplicate-export` | Same symbol exported from multiple modules |
|
|
146
|
+
| `circular-dependency` | `--circular-deps` | - | `// fallow-ignore-next-line circular-dependency` | Import cycles in the module graph |
|
|
147
|
+
| `re-export-cycle` | `--re-export-cycles` | - | `// fallow-ignore-file re-export-cycle` | Barrel files re-exporting from each other in a loop (`kind: "multi-node"`) or a barrel re-exporting from itself (`kind: "self-loop"`). Chain propagation through the loop is a structural no-op so imports through any member may silently come up empty. Default `warn`. Distinct from `circular-dependencies` (runtime cycles, sometimes intentional). File-scoped suppression only: `// fallow-ignore-file re-export-cycle` on any member breaks the cycle. |
|
|
148
|
+
| `boundary-violation` | `--boundary-violations` | - | `// fallow-ignore-next-line boundary-violation` | Imports crossing architecture zone boundaries. Presets: `layered`, `hexagonal`, `feature-sliced`, `bulletproof`; `autoDiscover` can create one zone per feature directory; per-rule `allowTypeOnly: [zones]` admits `import type` / `export type` crossings while still blocking value imports. Optional sections: `boundaries.coverage.requireAllFiles` reports unzoned source files (`allowUnmatched` globs exempt intentional ones), and `boundaries.calls.forbidden` bans callee patterns per zone (segment-aware and import-resolved, so `child_process.*` covers `node:child_process` named/namespace/default imports; direct callees only, zoned files only). The whole family shares the `boundary-violation` rule and suppression token (`boundary-call-violation` and `boundary-call-violations` accepted as aliases); start the rule at `warn` for a staged rollout |
|
|
149
|
+
| `boundary-coverage` | - | - | `// fallow-ignore-file boundary-violation` | Source file matches no configured architecture boundary zone; Requires boundaries.coverage.requireAllFiles |
|
|
150
|
+
| `boundary-call-violation` | - | - | `// fallow-ignore-next-line boundary-call-violation` | Zoned file calls a callee its zone forbids; Requires boundaries.calls.forbidden patterns |
|
|
151
|
+
| `policy-violation` | `--policy-violations` | - | `// fallow-ignore-next-line policy-violation` | Calls or imports banned by a declarative rule pack (`rulePacks` config key lists standalone JSON/JSONC files of `banned-call` / `banned-import` rules; pure data, no project code executes). Findings identified as `<pack>/<rule-id>`. Default `warn` master; per-rule `severity` overrides per finding and the exit gate reads the effective severity. Invalid or missing packs fail config load with exit 2. `fallow rule-pack-schema` prints the pack JSON Schema. Suppress with `// fallow-ignore-next-line policy-violation` (one token covers every pack rule on the line). |
|
|
152
|
+
| `stale-suppression` | `--stale-suppressions` | - | - | `fallow-ignore` comments or `@expected-unused` JSDoc tags that no longer match any issue |
|
|
153
|
+
| `unused-catalog-entry` | `--unused-catalog-entries` | yes | - | `pnpm-workspace.yaml` entries no workspace package.json references via `catalog:` (default `warn`) |
|
|
154
|
+
| `empty-catalog-group` | `--empty-catalog-groups` | - | - | Named `catalogs.<name>:` groups in `pnpm-workspace.yaml` with no entries. Top-level `catalog:` placeholders are ignored. Default `warn`. |
|
|
155
|
+
| `unresolved-catalog-reference` | `--unresolved-catalog-references` | - | - | `package.json` references to `catalog:` / `catalog:<name>` whose catalog does not declare the package; `pnpm install` would fail. Default `error`. Suppress via `ignoreCatalogReferences: [{ package, catalog?, consumer? }]` in fallow config (package.json has no comment syntax). |
|
|
156
|
+
| `unused-dependency-override` | `--unused-dependency-overrides` | - | - | `pnpm-workspace.yaml#overrides` / `package.json#pnpm.overrides` entries whose target package is not declared by any workspace `package.json` and is not present in `pnpm-lock.yaml`. Default `warn`. When the lockfile is missing or unreadable the check degrades to a manifest-only fallback and every finding carries a `hint` reminding consumers to verify before removal. Suppress via `ignoreDependencyOverrides: [{ package, source? }]` in fallow config. |
|
|
157
|
+
| `misconfigured-dependency-override` | `--misconfigured-dependency-overrides` | - | - | `pnpm.overrides` entries whose key is unparsable (empty, dangling separators, malformed selectors) or value is missing/empty. `pnpm install` would fail. Default `error`. Suppression: same `ignoreDependencyOverrides` config rule. |
|
|
158
|
+
| `high-cyclomatic-complexity` | `--complexity` | - | `// fallow-ignore-next-line complexity` | Function has high cyclomatic complexity |
|
|
159
|
+
| `high-cognitive-complexity` | `--complexity` | - | `// fallow-ignore-next-line complexity` | Function has high cognitive complexity |
|
|
160
|
+
| `high-complexity` | `--complexity` | - | `// fallow-ignore-next-line complexity` | Function exceeds both complexity thresholds |
|
|
161
|
+
| `high-crap-score` | `--complexity` | - | `// fallow-ignore-next-line complexity` | Function has a high CRAP score (complexity combined with low coverage) |
|
|
162
|
+
| `refactoring-target` | `--targets` | - | - | File identified as a high-priority refactoring candidate |
|
|
163
|
+
| `untested-file` | `--coverage-gaps` | - | `// fallow-ignore-file coverage-gaps` | Runtime-reachable file has no test dependency path |
|
|
164
|
+
| `untested-export` | `--coverage-gaps` | - | `// fallow-ignore-file coverage-gaps` | Runtime-reachable export has no test dependency path |
|
|
165
|
+
| `code-duplication` | - | - | `// fallow-ignore-next-line code-duplication` | Duplicated code block; Reported by fallow dupes (and bare fallow / fallow audit) |
|
|
166
|
+
| `feature-flag` | - | - | `// fallow-ignore-next-line feature-flag` | Detected feature flag pattern; Reported by fallow flags |
|
|
167
|
+
| `tainted-sink` | - | - | `// fallow-ignore-next-line security-sink` | Syntactic security sink candidates require verification |
|
|
168
|
+
| `client-server-leak` | - | - | `// fallow-ignore-file security-client-server-leak` | Client-bound code reaches a non-public env read |
|
|
169
|
+
| `hardcoded-secret` | - | - | `// fallow-ignore-next-line security-sink` | Provider-prefixed or contextual secret literals require verification; Include-required category: enable via security.categories.include |
|
|
170
|
+
|
|
171
|
+
Runtime-coverage verdicts and the full security sink catalogue are listed by `fallow schema` (`issue_types`).
|
|
172
|
+
<!-- generated:issue-types:end -->
|
|
113
173
|
|
|
114
174
|
## MCP Tools
|
|
115
175
|
|
|
116
176
|
When using fallow via MCP (`fallow-mcp`), the following tools are available:
|
|
117
177
|
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
| `
|
|
122
|
-
| `
|
|
123
|
-
| `
|
|
124
|
-
| `
|
|
125
|
-
| `
|
|
126
|
-
| `
|
|
127
|
-
| `
|
|
128
|
-
| `
|
|
129
|
-
| `
|
|
130
|
-
| `
|
|
131
|
-
| `
|
|
132
|
-
| `
|
|
133
|
-
| `
|
|
134
|
-
| `
|
|
135
|
-
| `
|
|
136
|
-
| `
|
|
137
|
-
| `
|
|
138
|
-
| `
|
|
139
|
-
| `
|
|
140
|
-
| `
|
|
141
|
-
| `
|
|
142
|
-
| `
|
|
143
|
-
| `
|
|
178
|
+
<!-- generated:mcp-tools:start -->
|
|
179
|
+
| Tool | Kind | License | Key params | Description |
|
|
180
|
+
|---|---|---|---|---|
|
|
181
|
+
| `code_execute` | composition | free | `code`, `timeout_ms`, `max_output_bytes` | Bounded read-only Code Mode for composing multiple fallow analysis calls in one JavaScript snippet. The snippet receives `{ fallow, root }`, returns JSON-serializable data, and can call read-only helpers such as `fallow.projectInfo`, `fallow.audit`, `fallow.checkHealth`, and `fallow.run(tool, params)` for the same allowlist. Mutating fix tools are not exposed. The sandbox has no filesystem, network, imports, `eval`, `Function`, `process`, `require`, `Deno`, `Bun`, or shell access. Params: `code`, optional `root`, `timeout_ms` (capped at 30000), and `max_output_bytes` (capped at 4000000). |
|
|
182
|
+
| `analyze` | analysis | free | `issue_types`, `production`, `workspace`, `baseline`, `group_by`, `file` | Full dead code analysis (unused files/exports/types/dependencies/members + circular dependencies + re-export cycles (barrel files that form a structural loop, silently breaking re-exports) + boundary violations + rule-pack policy violations (banned calls and banned imports declared via the `rulePacks` config key) + stale suppressions). Private type leaks are an opt-in API hygiene check via `issue_types: ["private-type-leaks"]`. Set `boundary_violations: true` as a convenience alias for `issue_types: ["boundary-violations"]`. Set `group_by` to `"owner"`, `"directory"`, `"package"`, or `"section"` to partition results. The `section` mode reads GitLab CODEOWNERS `[Section]` headers and emits `owners` metadata per group |
|
|
183
|
+
| `check_changed` | analysis | free | `since`, `baseline`, `fail_on_regression` | Incremental analysis of files changed since a git ref |
|
|
184
|
+
| `security_candidates` | analysis | free | `gate`, `surface`, `changed_since`, `paths` | Unverified local security candidates, not confirmed vulnerabilities (`fallow security --format json`). Read `security_findings[]` for category, CWE, severity, evidence, trace, optional `reachability`, blind-spot counters, and optional `unresolved_callee_diagnostics` samples for dynamic callee follow-up. `severity` is a review-priority tier, not a verified vulnerability verdict. Each finding also carries an agent-actionable `candidate` (`source_kind`/`sink`/`boundary`), where URL-category sinks may include `url_shape` (`fixed-origin-dynamic-path` or `dynamic-origin`), an optional `taint_flow` source-to-sink triple, and a stable `finding_id` (equal to the SARIF fingerprint) for cross-run correlation; there is no `impact` field (deciding exploitability is the agent's job). Set `surface: true` to include top-level `attack_surface[]` entries with defensive-boundary prompts for a verifier. Set `gate` to `new` for changed-line candidates or `newly-reachable` for candidates that became reachable from entry points; `newly-reachable` requires `changed_since`. `reachability.untrusted_source_trace` is module-level import context only and does not prove value flow; `reachability.taint_confidence` tiers each reachable candidate as `arg-level` (sink argument traces to a same-module source read, strong) or `module-level` (only the module is import-reachable from a source, weak), so tier from this field instead of the evidence text. Verify trace, reachability context, severity, and evidence before editing code. Supports `root`, `config`, `workspace`, `paths`, `changed_since`, `changed_workspaces`, `surface`, `gate`, `no_cache`, and `threads`; `paths` forwards repeated `fallow security --file` filters for finding anchors, trace hops, untrusted-source reachability trace hops, and unresolved-callee diagnostics. See <https://docs.fallow.tools/cli/security-agent-verification> for the verifier packet and verdict recipe. Inherits `FALLOW_DIFF_FILE` from the server environment for line-level diff scoping; raise `FALLOW_TIMEOUT_SECS` for large repos. |
|
|
185
|
+
| `inspect_target` | analysis | free | `target`, `production` | Compose one evidence bundle for a file or exported symbol. File targets use `target: { type: "file", file }`; symbol targets use `target: { type: "symbol", file, export_name }`. Returns `kind: "inspect_target"`, normalized target identity, `trace_file`, optional `trace_export`, file-scoped dead-code actions, duplication groups filtered to the file, complexity findings filtered to the file, and security candidates scoped to the file. Evidence sections carry `status` and `scope`; symbol targets warn when supporting evidence is file-scoped. Supports `root`, `config`, `production`, `workspace`, `no_cache`, and `threads`; `production` applies to trace, dead-code, and health evidence only. Raise `FALLOW_TIMEOUT_SECS` for large repos. |
|
|
186
|
+
| `find_dupes` | analysis | free | `mode`, `min_tokens`, `min_occurrences`, `top`, `threshold` | Code duplication detection. Set `changed_since` to scope to changed files since a git ref. Set `min_occurrences` (≥ 2, default 2) to hide pair-only clones and focus on widespread copy-paste; JSON gains `stats.clone_groups_below_min_occurrences` when the filter hides anything. Each `clone_groups[]` entry carries a stable `fingerprint`, usually `dup:<8hex>` and widened only on rare report collisions; pass it to `trace_clone` to deep-dive that group |
|
|
187
|
+
| `check_health` | analysis | free | `score`, `file_scores`, `hotspots`, `targets`, `coverage`, `runtime_coverage`, `max_crap`, `group_by` | Complexity metrics, health scores, hotspots, and refactoring targets. Set `complexity_breakdown: true` to add a per-decision-point `contributions[]` array to each complexity finding (each `else-if`, nested `if`, boolean operator, loop, `case`, etc. with its source line and cyclomatic/cognitive weight) so you can explain WHY a function scored high and pinpoint refactor targets. Optional `runtime_coverage` merges a V8 or Istanbul dump; tune it with `min_invocations_hot` (default 100), `min_observation_volume` (default 5000), and `low_traffic_threshold` (default 0.001). When runtime evidence combines with static usage, test coverage, CRAP/complexity, ownership, or change scope, read `coverage_intelligence` for stable `fallow:coverage-intel:<hash>` recommendations. Set `group_by` to `owner`, `directory`, `package`, or `section` for per-group `vital_signs` / `health_score`; SARIF results gain `properties.group`, CodeClimate issues gain a top-level `group` field |
|
|
188
|
+
| `check_runtime_coverage` | runtime-coverage | freemium | `coverage`, `min_invocations_hot`, `min_observation_volume`, `low_traffic_threshold`, `group_by` | Merge V8 or Istanbul runtime-coverage data into the health report. One local capture is free; continuous/cloud or multi-capture runtime monitoring is paid. Required `coverage` param (V8 dir, V8 JSON, or Istanbul `coverage-final.json`). Tuning knobs: `min_invocations_hot` (default 100), `min_observation_volume` (default 5000), `low_traffic_threshold` (default 0.001), `max_crap` (default 30.0), `top`, `group_by`. Cloud runtime rows can expose `resolutionStatus` / `mappingQuality` on function-list JSON and `resolution_status` / `mapping_quality` in runtime-context JSON. Use `coverage_intelligence` and the confidence table below before acting on file-level runtime signals. Long dumps may exceed the 120s MCP timeout; raise `FALLOW_TIMEOUT_SECS`. Pick this over `check_health` when you have a coverage dump. |
|
|
189
|
+
| `get_hot_paths` | runtime-coverage | freemium | `coverage`, `top`, `min_invocations_hot` | Runtime-context slice over the same runtime coverage pipeline. Same params as `check_runtime_coverage`; read `runtime_coverage.hot_paths` for production hot paths. |
|
|
190
|
+
| `get_blast_radius` | runtime-coverage | freemium | `coverage`, `group_by` | Runtime-context slice for blast-radius review. Same params as `check_runtime_coverage`; read `runtime_coverage.blast_radius` for stable `fallow:blast:<hash>` IDs, caller counts, traffic-weighted caller reach, optional cloud deploy touch counts, and low/medium/high risk bands. |
|
|
191
|
+
| `get_importance` | runtime-coverage | freemium | `coverage`, `group_by` | Runtime-context slice for production-importance review. Same params as `check_runtime_coverage`; read `runtime_coverage.importance` for stable `fallow:importance:<hash>` IDs, invocations, cyclomatic complexity, owner count, 0-100 score, and templated reason. |
|
|
192
|
+
| `get_cleanup_candidates` | runtime-coverage | freemium | `coverage`, `group_by` | Runtime-context slice for cleanup review. Same params as `check_runtime_coverage`; read `runtime_coverage.findings` for `safe_to_delete`, `review_required`, `low_traffic`, and `coverage_unavailable`. |
|
|
193
|
+
| `audit` | analysis | free | `gate`, `base`, `max_crap`, `coverage`, `runtime_coverage` | Combined dead-code + complexity + duplication for changed files, returns verdict. Set `gate` to `"new-only"` or `"all"`. Optional `runtime_coverage` (V8 dir / V8 JSON / Istanbul JSON) folds runtime findings into the same call; `min_invocations_hot` tunes the hot-path threshold (default 100). Runtime evidence appears under the audit `complexity` sub-result, including `coverage_intelligence` when combined evidence yields actionable recommendations. |
|
|
194
|
+
| `fallow_explain` | introspection | free | `issue_type` | Explain one issue type without running analysis. Required `issue_type`; returns rationale, examples, fix guidance, and docs URL |
|
|
195
|
+
| `fix_preview` | fix | free | `no_create_config` | Dry-run auto-fix preview |
|
|
196
|
+
| `fix_apply` | fix | free | `no_create_config` | Apply auto-fixes (destructive) |
|
|
197
|
+
| `project_info` | introspection | free | `entry_points`, `files`, `plugins`, `boundaries` | Project metadata. Set `entry_points`, `files`, `plugins`, or `boundaries` to `true` to request specific sections |
|
|
198
|
+
| `list_boundaries` | introspection | free | - | Architecture boundary zones, access rules, and pre-expansion `autoDiscover` `logical_groups[]` (user-authored parent name, verbatim paths, discovered children, `status` enum, summed `file_count`). Returns `{"configured": false}` if no boundaries configured |
|
|
199
|
+
| `feature_flags` | analysis | free | `workspace`, `production` | Detect feature flag patterns (env vars, SDK calls, config objects). Set `top` to limit results |
|
|
200
|
+
| `impact` | introspection | free | `root` | Read the local, opt-in Fallow Impact value report (`fallow impact --format json`). Runs no analysis: current surfacing counts, trend since the last recorded run, pre-commit gate containment, and (on impact v1.5+) resolved/suppressed attribution. Read-only and `root`-only; the mutating `enable` / `disable` lifecycle is not exposed. A never-enabled project returns a populated `{"enabled": false, ...}` report (never `{}`); branch on `enabled` then `record_count` and recommend the user run `fallow impact enable` rather than toggling it. Local-developer signal: empty in ephemeral CI runners, so not a CI metric |
|
|
201
|
+
| `trace_export` | trace | free | `file`, `export_name` | Trace why an export is used or unused (`fallow dead-code --trace FILE:EXPORT_NAME --format json`). Required `file` and `export_name`. Returns file reachability, entry-point status, direct references, re-export chains, and a reason string. Use before deleting a supposedly-unused export |
|
|
202
|
+
| `trace_file` | trace | free | `file` | Trace all graph edges for a file (`fallow dead-code --trace-file PATH --format json`). Required `file`. Returns reachability, exports, imports-from, imported-by, and re-exports. Use to decide whether a file is isolated, barrel-only, or imported by live entry points |
|
|
203
|
+
| `trace_dependency` | trace | free | `package_name` | Trace where a dependency is imported (`fallow dead-code --trace-dependency PACKAGE --format json`). Required `package_name`. Returns importing files, type-only importers, total import count, `used_in_scripts` (true when invoked from package.json scripts or CI configs), and `is_used` (combined import + script signal; mirrors the unused-deps detector so build tools like `microbundle` or `vitest` are not falsely flagged as unused). Use before removing a dependency or moving between `dependencies` and `devDependencies` |
|
|
204
|
+
| `trace_clone` | trace | free | `file`, `line`, `fingerprint` | Deep-dive a duplicate-code clone group (`fallow dupes --trace <spec> --format json`). Address by exactly one of: `file` + `line` (a source location), or `fingerprint` (a `dup:<id>` from a prior `find_dupes` `clone_groups[].fingerprint`, usually `dup:<8hex>` and widened only on rare report collisions). Returns the matched clone instance plus every clone group containing it; each traced group carries its `fingerprint`, an extract-function `suggestion` with estimated savings, and a best-effort `suggested_name` (omitted when no confident name). Supports `mode`, `min_tokens`, `min_lines`, `threshold`, `skip_local`, `cross_language`, `ignore_imports`. Use to consolidate duplication when you need exact sibling locations and a refactor target |
|
|
205
|
+
<!-- generated:mcp-tools:end -->
|
|
144
206
|
|
|
145
207
|
Runtime source-map confidence for cloud runtime tools:
|
|
146
208
|
|
|
@@ -155,6 +217,8 @@ Most tools accept `root`, `config`, `no_cache`, and `threads` params. Exceptions
|
|
|
155
217
|
|
|
156
218
|
All JSON responses include structured `actions` arrays on every finding (dead code, health, duplication), enabling programmatic fix application or suppression.
|
|
157
219
|
|
|
220
|
+
`dead-code`, `health`, `dupes`, bare `fallow`, and `audit` JSON output also carry a top-level `next_steps` array of read-only follow-up commands computed from the run's findings: each entry is `{ id, command, reason }`. The `command` is runnable as-is (never a placeholder, never `fix` or any other mutating command); the stable kebab-case `id` (`trace-unused-export`, `trace-clone`, `complexity-breakdown`, `scope-workspaces`, `audit-changed`) maps to a verification step you should run BEFORE acting, for example tracing an export before deleting it. When running via MCP, dispatch on the `id` to the matching tool / `code_execute` host call (`trace_export`, `trace_clone`, `check_health` with `complexity_breakdown: true`, `audit`) rather than shelling out the CLI string. The array is deduplicated, capped at three, and omitted when empty; set `FALLOW_SUGGESTIONS=off` to suppress it.
|
|
221
|
+
|
|
158
222
|
## Node.js Bindings
|
|
159
223
|
|
|
160
224
|
When embedding fallow inside a Node.js process (editor extensions, long-running servers, custom tooling), prefer the NAPI bindings over spawning the CLI. Same analysis engine, same JSON envelopes, no subprocess or JSON parsing overhead.
|
|
@@ -288,6 +352,91 @@ fallow dead-code --format json --quiet --include-entry-exports
|
|
|
288
352
|
|
|
289
353
|
Reports unused exports in entry files (package.json `main`/`exports`, framework pages). By default, exports in entry files are assumed externally consumed. This flag catches typos like `meatdata` instead of `metadata`.
|
|
290
354
|
|
|
355
|
+
### Detect feature flag patterns
|
|
356
|
+
|
|
357
|
+
```bash
|
|
358
|
+
fallow flags --format json --quiet
|
|
359
|
+
fallow flags --format json --quiet --top 20
|
|
360
|
+
```
|
|
361
|
+
|
|
362
|
+
Reports environment-variable gates (`process.env.FEATURE_*`), SDK calls from common flag providers, and config-object patterns, with flag locations, detection confidence, and a cross-reference against dead code. Only `--top N` is command-specific.
|
|
363
|
+
|
|
364
|
+
### Surface security candidates for verification
|
|
365
|
+
|
|
366
|
+
```bash
|
|
367
|
+
fallow security --format json --quiet
|
|
368
|
+
fallow security --format json --quiet --surface
|
|
369
|
+
# Pre-commit gate: review-required (exit 8) only on NEW candidates in changed lines
|
|
370
|
+
git diff --cached --unified=0 | fallow security --gate new --diff-stdin --format json --quiet
|
|
371
|
+
```
|
|
372
|
+
|
|
373
|
+
These are unverified candidates, not confirmed vulnerabilities; an agent must verify trace, reachability, and evidence before editing. `--surface` adds a top-level `attack_surface[]` inventory for a verifier. The gate modes are `new` (candidates introduced on changed lines) and `newly-reachable` (candidates that became reachable from entry points, which needs `--changed-since <ref>`); there is no `all` mode by design. The gate fails with exit 8, distinct from the standard exit ladder.
|
|
374
|
+
|
|
375
|
+
### Find untested runtime-reachable code (coverage gaps)
|
|
376
|
+
|
|
377
|
+
```bash
|
|
378
|
+
fallow health --format json --quiet --coverage-gaps
|
|
379
|
+
```
|
|
380
|
+
|
|
381
|
+
Reports `untested-file` and `untested-export` findings: runtime-reachable code with no dependency path from any discovered test root. Opt-in and requires the full analysis pipeline.
|
|
382
|
+
|
|
383
|
+
### Find complexity hotspots, owners, and refactoring targets
|
|
384
|
+
|
|
385
|
+
```bash
|
|
386
|
+
# Files that are both complex and frequently changing (needs a git repo)
|
|
387
|
+
fallow health --format json --quiet --hotspots
|
|
388
|
+
# Add ownership signals (bus factor, declared CODEOWNERS owner, drift)
|
|
389
|
+
fallow health --format json --quiet --hotspots --ownership
|
|
390
|
+
# Ranked refactoring targets (complexity + coupling + churn + dead code)
|
|
391
|
+
fallow health --format json --quiet --targets
|
|
392
|
+
# Partition the report per team or package
|
|
393
|
+
fallow health --format json --quiet --hotspots --group-by owner
|
|
394
|
+
```
|
|
395
|
+
|
|
396
|
+
`--ownership` implies `--hotspots` and `--effort` implies `--targets`. The global `--group-by` accepts `owner`, `directory`, `package`, or `section` (the `section` mode reads GitLab CODEOWNERS `[Section]` headers). Hotspots and ownership require a git repository.
|
|
397
|
+
|
|
398
|
+
### Explain why a complex function scored high
|
|
399
|
+
|
|
400
|
+
```bash
|
|
401
|
+
fallow health --format json --quiet --complexity --complexity-breakdown
|
|
402
|
+
```
|
|
403
|
+
|
|
404
|
+
Adds a per-decision-point `contributions[]` array to every complexity finding (each `if`, `else-if`, loop, boolean operator, and `case` with its source line and cyclomatic/cognitive weight), so you can pinpoint the exact refactor target.
|
|
405
|
+
|
|
406
|
+
### Gate CI on regressions (baselines)
|
|
407
|
+
|
|
408
|
+
```bash
|
|
409
|
+
# 1. Save the current issue counts as a regression baseline
|
|
410
|
+
fallow dead-code --format json --quiet --save-regression-baseline .fallow/baseline.json
|
|
411
|
+
# 2. In CI: fail only if issues increase beyond tolerance
|
|
412
|
+
fallow dead-code --format json --quiet --regression-baseline .fallow/baseline.json --fail-on-regression --tolerance 0
|
|
413
|
+
# Identity-based baseline (fail only on NEW findings, not raw counts)
|
|
414
|
+
fallow dead-code --format json --quiet --save-baseline .fallow/snapshot.json
|
|
415
|
+
fallow dead-code --format json --quiet --baseline .fallow/snapshot.json
|
|
416
|
+
```
|
|
417
|
+
|
|
418
|
+
`--save-regression-baseline` / `--regression-baseline` / `--fail-on-regression` / `--tolerance` are count-based gates; `--save-baseline` / `--baseline` are identity-based (track finding identity, fail on new). All six are global flags, so they also work on `health` and `dupes`. `audit` rejects the global baseline flags and uses `--dead-code-baseline` / `--health-baseline` / `--dupes-baseline` instead.
|
|
419
|
+
|
|
420
|
+
### Explain an issue type without running analysis
|
|
421
|
+
|
|
422
|
+
```bash
|
|
423
|
+
fallow explain unused-export --format json
|
|
424
|
+
fallow explain code-duplication
|
|
425
|
+
```
|
|
426
|
+
|
|
427
|
+
The issue type is a positional argument and accepts forms like `unused-export`, `fallow/unused-export`, `unused exports`, or `code duplication`. It runs no analysis and returns the rule rationale, a worked example, fix guidance, and the docs URL.
|
|
428
|
+
|
|
429
|
+
### Show what fallow has surfaced over time (Impact)
|
|
430
|
+
|
|
431
|
+
```bash
|
|
432
|
+
# Enable once (local-only, opt-in, never uploads, never affects exit codes)
|
|
433
|
+
fallow impact enable
|
|
434
|
+
# Read the value report: surfacing count, trend, pre-commit containment
|
|
435
|
+
fallow impact --format json --quiet
|
|
436
|
+
```
|
|
437
|
+
|
|
438
|
+
`fallow impact enable` is a one-time, user-owned local action; the agent-facing line is the read step. The store lives at `.fallow/impact.json` (gitignored), the report is read-only, and it is empty in ephemeral CI runners.
|
|
439
|
+
|
|
291
440
|
### Debug why something is flagged
|
|
292
441
|
|
|
293
442
|
```bash
|
|
@@ -502,7 +502,7 @@ fallow health --format json --quiet --trend
|
|
|
502
502
|
{
|
|
503
503
|
"kind": "health",
|
|
504
504
|
"schema_version": 7,
|
|
505
|
-
"version": "2.
|
|
505
|
+
"version": "2.93.0",
|
|
506
506
|
"elapsed_ms": 32,
|
|
507
507
|
"summary": {
|
|
508
508
|
"files_analyzed": 482,
|
|
@@ -893,7 +893,7 @@ fallow audit \
|
|
|
893
893
|
{
|
|
894
894
|
"kind": "audit",
|
|
895
895
|
"schema_version": 7,
|
|
896
|
-
"version": "2.
|
|
896
|
+
"version": "2.93.0",
|
|
897
897
|
"command": "audit",
|
|
898
898
|
"verdict": "fail",
|
|
899
899
|
"changed_files_count": 12,
|
|
@@ -967,7 +967,7 @@ fallow flags --format json --quiet --workspace my-package
|
|
|
967
967
|
```json
|
|
968
968
|
{
|
|
969
969
|
"schema_version": 7,
|
|
970
|
-
"version": "2.
|
|
970
|
+
"version": "2.93.0",
|
|
971
971
|
"elapsed_ms": 116,
|
|
972
972
|
"feature_flags": [],
|
|
973
973
|
"total_flags": 0
|
|
@@ -1073,7 +1073,7 @@ fallow security --gate newly-reachable --changed-since origin/main
|
|
|
1073
1073
|
{
|
|
1074
1074
|
"kind": "security",
|
|
1075
1075
|
"schema_version": "4",
|
|
1076
|
-
"version": "2.
|
|
1076
|
+
"version": "2.93.0",
|
|
1077
1077
|
"elapsed_ms": 42,
|
|
1078
1078
|
"config": {
|
|
1079
1079
|
"rules": {
|
|
@@ -1102,7 +1102,7 @@ fallow security --gate newly-reachable --changed-since origin/main
|
|
|
1102
1102
|
{
|
|
1103
1103
|
"kind": "security",
|
|
1104
1104
|
"schema_version": "4",
|
|
1105
|
-
"version": "2.
|
|
1105
|
+
"version": "2.93.0",
|
|
1106
1106
|
"elapsed_ms": 42,
|
|
1107
1107
|
"config": {
|
|
1108
1108
|
"rules": {
|
|
@@ -1201,14 +1201,24 @@ MCP equivalent: `fallow_explain` with required `issue_type`.
|
|
|
1201
1201
|
|
|
1202
1202
|
---
|
|
1203
1203
|
|
|
1204
|
-
## `schema`:
|
|
1204
|
+
## `schema`: Capability Manifest
|
|
1205
1205
|
|
|
1206
|
-
Dumps
|
|
1206
|
+
Dumps fallow's complete capability manifest as machine-readable JSON (always JSON, regardless of `--format`). The single source of truth for agent introspection.
|
|
1207
1207
|
|
|
1208
1208
|
```bash
|
|
1209
1209
|
fallow schema
|
|
1210
1210
|
```
|
|
1211
1211
|
|
|
1212
|
+
Top-level blocks:
|
|
1213
|
+
|
|
1214
|
+
- `manifest_version`: manifest shape discriminator (currently `"1"`).
|
|
1215
|
+
- `commands` + `global_flags`: every CLI command and flag, derived live from the CLI definition.
|
|
1216
|
+
- `issue_types`: one row per reportable issue type across ALL analyses (dead-code, health, dupes, flags, security). Each row carries `id` (the bare rule id; several rows share one suppression token, e.g. all complexity rules suppress via `complexity`), `rule_id` (SARIF id), `command`, `category`, `filter_flag` (null when none), `fixable`, `suppressible`, `suppress_comment` (copy-pasteable, null when not suppressible), `note`, `license` (`free` | `freemium`), and `docs_url`. Nullable fields are always present (null, never absent).
|
|
1217
|
+
- `mcp_tools`: all MCP server tools with `kind` grouping (analysis/trace/fix/introspection/runtime-coverage/composition), one-line description, `key_params` (curated subset; live MCP `list_tools` schemas are authoritative), `license` + `license_note` (the 5 runtime-coverage tools are `freemium`: a single local capture is free, continuous monitoring is paid), and `read_only`.
|
|
1218
|
+
- `plugins`: built-in framework plugin count + names, derived live from the registry.
|
|
1219
|
+
- `environment_variables`: every user-facing `FALLOW_*` variable (internal plumbing excluded).
|
|
1220
|
+
- `output_formats`, `exit_codes`, `severity_levels`, `suppression_comments`.
|
|
1221
|
+
|
|
1212
1222
|
---
|
|
1213
1223
|
|
|
1214
1224
|
## `config-schema`: Config JSON Schema
|
|
@@ -1551,6 +1561,7 @@ Available on all commands:
|
|
|
1551
1561
|
| `FALLOW_AUDIT_BASE` | Pin the `fallow audit` comparison base when `--base` / `--changed-since` is unset (precedence: flag > env > auto-detect). Escape hatch for the agent gate and forks, e.g. `FALLOW_AUDIT_BASE=upstream/main`. When unset, audit auto-detects the `git merge-base` against the branch's upstream or the remote default. A malformed value exits 2. |
|
|
1552
1562
|
| `FALLOW_AUDIT_CACHE_MAX_AGE_DAYS` | Max age (in days since last reuse or fresh create) of a persistent reusable `fallow audit` base-snapshot worktree cache. Older entries are reclaimed at the top of the next `fallow audit` invocation (default: `30`). Wins over `audit.cacheMaxAgeDays` config field. `0` disables the GC; invalid values silently fall back to config / default. |
|
|
1553
1563
|
| `FALLOW_UPDATE_CHECK` | Set to `off`, `0`, `false`, `disabled`, or `no` to disable the human-TTY upgrade nudge and its background latest-version check. `DO_NOT_TRACK`, `FALLOW_TELEMETRY_DISABLED`, and CI also suppress it. |
|
|
1564
|
+
| `FALLOW_SUGGESTIONS` | Set to `off`, `0`, `false`, `no`, or `disabled` to suppress the top-level `next_steps[]` array of read-only follow-up commands in JSON output (and the human `Next:` line on bare `fallow`). Default on. Inherited by the MCP-spawned CLI, so it disables `next_steps` on MCP responses too. Useful for CI consumers that snapshot-diff raw `--format json`. |
|
|
1554
1565
|
| `FALLOW_COMMAND` | GitLab CI: command to run (default: `dead-code`). |
|
|
1555
1566
|
| `FALLOW_FAIL_ON_ISSUES` | GitLab CI: set to `true` to exit 1 if issues found. |
|
|
1556
1567
|
| `FALLOW_CHANGED_SINCE` | GitLab CI: git ref for incremental analysis. Auto-detected in MR pipelines. |
|
|
@@ -1650,7 +1661,7 @@ The HTTP layer mirrors the bash `gh_api_retry` / `curl_retry` helpers: `FALLOW_A
|
|
|
1650
1661
|
{
|
|
1651
1662
|
"kind": "dead-code",
|
|
1652
1663
|
"schema_version": 7,
|
|
1653
|
-
"version": "2.
|
|
1664
|
+
"version": "2.93.0",
|
|
1654
1665
|
"elapsed_ms": 45,
|
|
1655
1666
|
"total_issues": 12,
|
|
1656
1667
|
"entry_points": {
|
|
@@ -1810,7 +1821,7 @@ When `--baseline` is used in combined output, the JSON includes a `baseline_delt
|
|
|
1810
1821
|
{
|
|
1811
1822
|
"kind": "dupes",
|
|
1812
1823
|
"schema_version": 7,
|
|
1813
|
-
"version": "2.
|
|
1824
|
+
"version": "2.93.0",
|
|
1814
1825
|
"elapsed_ms": 82,
|
|
1815
1826
|
"total_clones": 15,
|
|
1816
1827
|
"total_lines_duplicated": 230,
|
|
@@ -1854,11 +1865,11 @@ When running `fallow` with no subcommand (all analyses), the JSON output combine
|
|
|
1854
1865
|
{
|
|
1855
1866
|
"kind": "combined",
|
|
1856
1867
|
"schema_version": 7,
|
|
1857
|
-
"version": "2.
|
|
1868
|
+
"version": "2.93.0",
|
|
1858
1869
|
"elapsed_ms": 159,
|
|
1859
1870
|
"check": {
|
|
1860
1871
|
"schema_version": 7,
|
|
1861
|
-
"version": "2.
|
|
1872
|
+
"version": "2.93.0",
|
|
1862
1873
|
"elapsed_ms": 45,
|
|
1863
1874
|
"total_issues": 12,
|
|
1864
1875
|
"unused_files": [],
|
|
@@ -732,6 +732,11 @@ _meta?: (Meta | null)
|
|
|
732
732
|
dead_code?: (CheckOutput | null)
|
|
733
733
|
duplication?: (DupesReportPayload | null)
|
|
734
734
|
complexity?: (HealthReport | null)
|
|
735
|
+
/**
|
|
736
|
+
* Read-only follow-up commands computed from this run's findings. See
|
|
737
|
+
* [`CheckOutput::next_steps`] for the contract.
|
|
738
|
+
*/
|
|
739
|
+
next_steps?: NextStep[]
|
|
735
740
|
}
|
|
736
741
|
/**
|
|
737
742
|
* Per-category summary counts for the audit result.
|
|
@@ -1031,6 +1036,15 @@ baseline?: (BaselineMatch | null)
|
|
|
1031
1036
|
regression?: (RegressionResult | null)
|
|
1032
1037
|
_meta?: (Meta | null)
|
|
1033
1038
|
workspace_diagnostics?: WorkspaceDiagnostic[]
|
|
1039
|
+
/**
|
|
1040
|
+
* Read-only follow-up commands computed from this run's findings, emitted
|
|
1041
|
+
* at the JSON root so an agent acting on the output is pointed at fallow's
|
|
1042
|
+
* adjacent verification capabilities (trace, complexity breakdown, audit,
|
|
1043
|
+
* workspace scoping). Each command is runnable as-is and never mutating;
|
|
1044
|
+
* see [`NextStep`] for both contracts. Omitted when empty or when
|
|
1045
|
+
* `FALLOW_SUGGESTIONS=off`; does NOT contribute to `total_issues`.
|
|
1046
|
+
*/
|
|
1047
|
+
next_steps?: NextStep[]
|
|
1034
1048
|
}
|
|
1035
1049
|
/**
|
|
1036
1050
|
* Entry-point detection summary embedded in `CheckOutput` and the combined
|
|
@@ -2446,6 +2460,53 @@ exceeded: boolean
|
|
|
2446
2460
|
*/
|
|
2447
2461
|
reason?: (string | null)
|
|
2448
2462
|
}
|
|
2463
|
+
/**
|
|
2464
|
+
* A read-only follow-up command fallow surfaces from the current findings,
|
|
2465
|
+
* emitted as the top-level `next_steps` array on each command's JSON envelope.
|
|
2466
|
+
*
|
|
2467
|
+
* `next_steps` exists to point agents and humans sideways to fallow's adjacent
|
|
2468
|
+
* verification capabilities (trace, complexity breakdown, audit, workspace
|
|
2469
|
+
* scoping) that telemetry shows agents rarely discover, because they act on the
|
|
2470
|
+
* output in front of them rather than on reference docs.
|
|
2471
|
+
*
|
|
2472
|
+
* ## Two hard contracts
|
|
2473
|
+
*
|
|
2474
|
+
* 1. **Read-only.** A `next_step` NEVER suggests `fallow fix` or any mutating
|
|
2475
|
+
* command. Fallow surfaces evidence and verification paths; deciding and
|
|
2476
|
+
* applying the remediation is the agent's job.
|
|
2477
|
+
* 2. **Runnable, placeholder-free.** `command` is always runnable as-is. It
|
|
2478
|
+
* never contains an angle-bracket placeholder (`<...>`); finding-derived
|
|
2479
|
+
* values are filled in from a real, deterministically-selected finding, and
|
|
2480
|
+
* any environment- or user-specific value that cannot be made concrete lives
|
|
2481
|
+
* in `reason` instead. An agent can copy `command` and run it without edits.
|
|
2482
|
+
*
|
|
2483
|
+
* Both contracts are enforced by unit tests in
|
|
2484
|
+
* `crates/cli/src/report/suggestions.rs`.
|
|
2485
|
+
*
|
|
2486
|
+
* Note: a SEPARATE, unrelated `next_steps` field exists on the
|
|
2487
|
+
* `coverage setup` envelope (`CoverageSetupOutput.next_steps`) as a plain
|
|
2488
|
+
* `Vec<String>` of human onboarding steps. Consumers that read multiple
|
|
2489
|
+
* envelope kinds must route on the envelope's `kind` before interpreting a
|
|
2490
|
+
* `next_steps` field: on analysis envelopes it is `Vec<NextStep>` objects, on
|
|
2491
|
+
* `coverage setup` it is `Vec<String>`.
|
|
2492
|
+
*/
|
|
2493
|
+
export interface NextStep {
|
|
2494
|
+
/**
|
|
2495
|
+
* Stable kebab-case key for machine dispatch and de-duplication
|
|
2496
|
+
* (for example `"trace-unused-export"`). Identity is stable across runs;
|
|
2497
|
+
* the `command` and `reason` strings may vary with the findings.
|
|
2498
|
+
*/
|
|
2499
|
+
id: string
|
|
2500
|
+
/**
|
|
2501
|
+
* A runnable, read-only command string. Placeholder-free by contract.
|
|
2502
|
+
*/
|
|
2503
|
+
command: string
|
|
2504
|
+
/**
|
|
2505
|
+
* One short phrase explaining why this helps. Carries any value that
|
|
2506
|
+
* cannot be made concrete in `command`.
|
|
2507
|
+
*/
|
|
2508
|
+
reason: string
|
|
2509
|
+
}
|
|
2449
2510
|
/**
|
|
2450
2511
|
* Wire-shape payload for `fallow dupes --format json` (the body that
|
|
2451
2512
|
* flattens into [`crate::output_envelope::DupesOutput`] and is also
|
|
@@ -4623,6 +4684,11 @@ grouped_by?: (GroupByMode | null)
|
|
|
4623
4684
|
groups?: (HealthGroup[] | null)
|
|
4624
4685
|
_meta?: (Meta | null)
|
|
4625
4686
|
workspace_diagnostics?: WorkspaceDiagnostic[]
|
|
4687
|
+
/**
|
|
4688
|
+
* Read-only follow-up commands computed from this run's findings. See
|
|
4689
|
+
* [`CheckOutput::next_steps`] for the contract.
|
|
4690
|
+
*/
|
|
4691
|
+
next_steps?: NextStep[]
|
|
4626
4692
|
}
|
|
4627
4693
|
/**
|
|
4628
4694
|
* A health report scoped to a single group.
|
|
@@ -4766,6 +4832,11 @@ _meta?: (Meta | null)
|
|
|
4766
4832
|
* a separate top-level field.
|
|
4767
4833
|
*/
|
|
4768
4834
|
workspace_diagnostics?: WorkspaceDiagnostic[]
|
|
4835
|
+
/**
|
|
4836
|
+
* Read-only follow-up commands computed from this run's findings. See
|
|
4837
|
+
* [`CheckOutput::next_steps`] for the contract.
|
|
4838
|
+
*/
|
|
4839
|
+
next_steps?: NextStep[]
|
|
4769
4840
|
}
|
|
4770
4841
|
/**
|
|
4771
4842
|
* A single grouped duplication bucket. Per-group `stats` are dedup-aware and
|
|
@@ -4880,6 +4951,11 @@ grouped_by: GroupByMode
|
|
|
4880
4951
|
total_issues: number
|
|
4881
4952
|
groups: CheckGroupedEntry[]
|
|
4882
4953
|
_meta?: (Meta | null)
|
|
4954
|
+
/**
|
|
4955
|
+
* Read-only follow-up commands computed from the full (ungrouped) findings.
|
|
4956
|
+
* See [`CheckOutput::next_steps`] for the contract.
|
|
4957
|
+
*/
|
|
4958
|
+
next_steps?: NextStep[]
|
|
4883
4959
|
}
|
|
4884
4960
|
/**
|
|
4885
4961
|
* Single resolver bucket inside `CheckGroupedOutput`. Carries the group's
|
|
@@ -5866,6 +5942,11 @@ _meta?: (CombinedMeta | null)
|
|
|
5866
5942
|
check?: (CheckOutput | null)
|
|
5867
5943
|
dupes?: (DupesReportPayload | null)
|
|
5868
5944
|
health?: (HealthReport | null)
|
|
5945
|
+
/**
|
|
5946
|
+
* Read-only follow-up commands aggregated across the combined run's
|
|
5947
|
+
* findings. See [`CheckOutput::next_steps`] for the contract.
|
|
5948
|
+
*/
|
|
5949
|
+
next_steps?: NextStep[]
|
|
5869
5950
|
}
|
|
5870
5951
|
export interface CombinedMeta {
|
|
5871
5952
|
check?: (Meta | null)
|