fallow 3.5.1 → 3.6.0

package/capabilities.json

@@ -1,6 +1,6 @@
 {
   "name": "fallow",
-  "version": "3.5.1",
+  "version": "3.6.0",
   "manifest_version": "1",
   "description": "Codebase analyzer for TypeScript/JavaScript: unused code, circular dependencies, code duplication, complexity hotspots, and architecture boundary violations",
   "global_flags": [
@@ -51,6 +51,16 @@
         "github-summary"
       ]
     },
+    {
+      "name": "--pretty",
+      "type": "bool",
+      "required": false,
+      "description": "Indent JSON output for manual inspection. Requires the final output format to be JSON",
+      "possible_values": [
+        "true",
+        "false"
+      ]
+    },
     {
       "name": "--quiet",
       "type": "bool",
@@ -1700,6 +1710,11 @@
         }
       ]
     },
+    {
+      "name": "audit-cache",
+      "description": "Maintain reusable audit base-snapshot caches",
+      "flags": []
+    },
     {
       "name": "decision-surface",
       "description": "Surface the consequential structural DECISIONS a change embeds (the apex of the review brief), each framed as a judgment question with the routed expert to ask",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fallow",
-  "version": "3.5.1",
+  "version": "3.6.0",
   "description": "Codebase intelligence for TypeScript and JavaScript. Free static analysis of code and styles, optional paid runtime intelligence (Fallow Runtime). Quality, risk, architecture, dependencies, duplication, and design-system drift for humans, CI, and the agents writing your code. Zero-config framework support.",
   "license": "MIT",
   "repository": {
@@ -87,13 +87,13 @@
     "@tanstack/intent": "0.3.5"
   },
   "optionalDependencies": {
-    "@fallow-cli/darwin-arm64": "3.5.1",
-    "@fallow-cli/darwin-x64": "3.5.1",
-    "@fallow-cli/linux-x64-gnu": "3.5.1",
-    "@fallow-cli/linux-arm64-gnu": "3.5.1",
-    "@fallow-cli/linux-x64-musl": "3.5.1",
-    "@fallow-cli/linux-arm64-musl": "3.5.1",
-    "@fallow-cli/win32-arm64-msvc": "3.5.1",
-    "@fallow-cli/win32-x64-msvc": "3.5.1"
+    "@fallow-cli/darwin-arm64": "3.6.0",
+    "@fallow-cli/darwin-x64": "3.6.0",
+    "@fallow-cli/linux-x64-gnu": "3.6.0",
+    "@fallow-cli/linux-arm64-gnu": "3.6.0",
+    "@fallow-cli/linux-x64-musl": "3.6.0",
+    "@fallow-cli/linux-arm64-musl": "3.6.0",
+    "@fallow-cli/win32-arm64-msvc": "3.6.0",
+    "@fallow-cli/win32-x64-msvc": "3.6.0"
   }
 }

package/skills/fallow/SKILL.md

@@ -45,7 +45,7 @@ cargo install fallow-cli   # build from source
 
 ## Agent Rules
 
-1. **Always use `--format json --quiet 2>/dev/null`** for machine-readable output. The `2>/dev/null` discards stderr so progress messages and threshold warnings don't corrupt the JSON on stdout. Never use `2>&1`
+1. **Always use `--format json --quiet 2>/dev/null`** for machine-readable output and parse it as JSON. Compact JSON is the default; never depend on whitespace or add `--pretty` in agent pipelines. The `2>/dev/null` discards stderr so progress messages and threshold warnings don't corrupt the JSON on stdout. Never use `2>&1`
 2. **Always append `|| true`** to every fallow command. Exit code 1 means "issues found" (normal), not a runtime error. Without `|| true`, the Bash tool treats exit 1 as failure and cancels parallel commands. Only exit code 2 is a real error (invalid config, parse failure)
 3. **Use `--explain`** to include a `_meta` object in JSON output with metric definitions, ranges, and interpretation hints. In human format, `--explain` prints a `Description:` line under each section header.
 4. **Use the root `kind` field** to identify typed JSON envelopes (`dead-code`, `dead-code-grouped`, `health`, `dupes`, `combined`, `audit`, etc.).
@@ -109,6 +109,7 @@ Route by intent before reaching for the big analysis commands. Same matrix as `f
 | `suppressions` | List active fallow-ignore suppression markers (read-only inventory) | `--file` |
 | `explain` | Explain one issue type without running analysis | `<issue-type>`, `--format json` |
 | `audit` | Combined dead-code + complexity + duplication + styling for changed files, returns a verdict; `fallow review` is an alias for `fallow audit --brief` (advisory orientation brief, always exits 0) | `--base`, `--gate`, `--brief`, `--max-decisions`, `--walkthrough-guide`, `--walkthrough-file`, `--show-deprioritized`, `--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`, `--no-css`, `--css-deep`, `--no-css-deep`, `--include-entry-exports` |
+| `audit-cache` | Maintain reusable audit base-snapshot caches |  |
 | `decision-surface` | Surface the consequential structural DECISIONS a change embeds (the apex of the review brief), each framed as a judgment question with the routed expert to ask | `--max-decisions` |
 | `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 | `--all`, `--sort`, `--limit` |
 | `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` |

package/skills/fallow/references/cli-reference.md

@@ -510,7 +510,7 @@ fallow health --format json --quiet --trend
 {
   "kind": "health",
   "schema_version": 7,
-  "version": "3.5.1",
+  "version": "3.6.0",
   "elapsed_ms": 32,
   "summary": {
     "files_analyzed": 482,
@@ -908,7 +908,7 @@ fallow audit \
 {
   "kind": "audit",
   "schema_version": 7,
-  "version": "3.5.1",
+  "version": "3.6.0",
   "command": "audit",
   "verdict": "fail",
   "changed_files_count": 12,
@@ -983,7 +983,7 @@ fallow flags --format json --quiet --workspace my-package
 ```json
 {
   "schema_version": 7,
-  "version": "3.5.1",
+  "version": "3.6.0",
   "elapsed_ms": 116,
   "feature_flags": [],
   "total_flags": 0
@@ -1084,7 +1084,7 @@ fallow security --gate newly-reachable --changed-since origin/main
 {
   "kind": "security",
   "schema_version": "4",
-  "version": "3.5.1",
+  "version": "3.6.0",
   "elapsed_ms": 42,
   "config": {
     "rules": {
@@ -1113,7 +1113,7 @@ fallow security --gate newly-reachable --changed-since origin/main
 {
   "kind": "security",
   "schema_version": "4",
-  "version": "3.5.1",
+  "version": "3.6.0",
   "elapsed_ms": 42,
   "config": {
     "rules": {
@@ -1638,6 +1638,7 @@ Available on all commands:
 | `-c, --config` | `string` | - | Config file path |
 | `--allow-remote-extends` | `bool` | `false` | Allow trusted config files to extend HTTPS URLs |
 | `-f, --format` | `human\|json\|sarif\|compact\|markdown\|codeclimate\|pr-comment-github\|pr-comment-gitlab\|review-github\|review-gitlab\|badge\|github-annotations\|github-summary` | `human` | Output format (alias: --output) |
+| `--pretty` | `bool` | `false` | Indent JSON output for manual inspection. Requires the final output format to be JSON |
 | `-q, --quiet` | `bool` | `false` | Suppress progress output |
 | `--no-cache` | `bool` | `false` | Disable incremental caching |
 | `--threads` | `string` | - | Number of parser threads |
@@ -1767,7 +1768,7 @@ Set `FALLOW_FORMAT=json` and `FALLOW_QUIET=1` in your agent environment to avoid
 | Format | Description | Use Case |
 |--------|-------------|----------|
 | `human` | Colored terminal output | Interactive use |
-| `json` | Machine-readable JSON | Agent integration, CI pipelines |
+| `json` | Compact machine-readable JSON by default; add `--pretty` for indented manual inspection | Agent integration, CI pipelines |
 | `sarif` | Static Analysis Results Interchange Format | GitHub Code Scanning, SARIF-compatible tools |
 | `compact` | Grep-friendly: one issue per line. Dupes lines include `code-duplication:path:start-end:fingerprint=dup:<id>,...` | Quick filtering |
 | `markdown` | Markdown tables | Documentation, PR comments |
@@ -1837,7 +1838,7 @@ The HTTP layer mirrors the bash `gh_api_retry` / `curl_retry` helpers: `FALLOW_A
 {
   "kind": "dead-code",
   "schema_version": 7,
-  "version": "3.5.1",
+  "version": "3.6.0",
   "elapsed_ms": 45,
   "total_issues": 12,
   "entry_points": {
@@ -1997,7 +1998,7 @@ When `--baseline` is used in combined output, the JSON includes a `baseline_delt
 {
   "kind": "dupes",
   "schema_version": 7,
-  "version": "3.5.1",
+  "version": "3.6.0",
   "elapsed_ms": 82,
   "total_clones": 15,
   "total_lines_duplicated": 230,
@@ -2041,11 +2042,11 @@ When running `fallow` with no subcommand (all analyses), the JSON output combine
 {
   "kind": "combined",
   "schema_version": 7,
-  "version": "3.5.1",
+  "version": "3.6.0",
   "elapsed_ms": 159,
   "check": {
     "schema_version": 7,
-    "version": "3.5.1",
+    "version": "3.6.0",
     "elapsed_ms": 45,
     "total_issues": 12,
     "unused_files": [],

package/types/output-contract.d.ts

@@ -10466,12 +10466,10 @@ export type RefactoringTarget = Omit<RefactoringTargetFinding, "actions">;
 // import the bare names from `fallow/types` would break at upgrade time
 // otherwise.
 //
-// Stability commitment: these aliases ship as part of fallow's v2.x stable
-// surface. They are scheduled for removal alongside the kind-tagged
-// `FallowOutput` major bump (see https://github.com/fallow-rs/fallow/issues/413),
-// with a one-minor-cycle deprecation window (`@deprecated` JSDoc +
-// CHANGELOG headline) preceding the removal. New code should prefer the
-// `*Finding` wrapper names. Full public-consumer policy:
+// Stability commitment: legacy output aliases remain supported throughout v3.
+// Removing them requires an explicit deprecation period and a future major
+// release. New code should prefer the `*Finding` wrapper names. Full
+// public-consumer policy:
 // https://github.com/fallow-rs/fallow/blob/main/docs/backwards-compatibility.md
 //