fallow 3.35.0 → 3.37.0

package/types/output-contract.d.ts

@@ -164,6 +164,10 @@ export type AuditWorsened = ("warn" | "error" | "off")
  * is decided here.
  */
 export type GateStatus = ("pass" | "warn" | "fail" | "skipped")
+/**
+ * Why a file counts for the `parse-error` gate, other than a parser error.
+ */
+export type GateFileReason = "nesting-too-deep"
 /**
  * Analysis mode stored with baselines, snapshots, audit sides, and impact data.
  */
@@ -411,6 +415,7 @@ export type PolicyViolationSeverity = ("error" | "warn")
  * The origin of a stale suppression: inline comment or JSDoc tag.
  */
 export type SuppressionOrigin = ({
+type: "comment"
 /**
  * The issue kind token from the comment (e.g., "unused-exports"), or None for blanket.
  */
@@ -432,8 +437,8 @@ is_file_level: boolean
  * adopted the field stay byte-compatible. See issue #449.
  */
 kind_known?: boolean
-type: "comment"
 } | {
+type: "jsdoc_tag"
 /**
  * The name of the export that was tagged.
  */
@@ -442,7 +447,6 @@ export_name: string
  * Human-authored reason after `--`, when present.
  */
 reason?: (string | null)
-type: "jsdoc_tag"
 })
 /**
  * Where an override entry was declared. Serialized as the filename label
@@ -564,66 +568,67 @@ degrades_analysis?: boolean
 export type WorkspaceDiagnostic1 = ({
 kind: "undeclared-workspace"
 } | {
+kind: "malformed-package-json"
 /**
  * `serde_json` parse error text.
  */
 error: string
-kind: "malformed-package-json"
 } | {
+kind: "glob-matched-no-package-json"
 /**
  * The glob pattern that matched the directory.
  */
 pattern: string
-kind: "glob-matched-no-package-json"
 } | {
+kind: "workspace-glob-outside-root"
 /**
  * The workspace entry, as written in the file.
  */
 pattern: string
-kind: "workspace-glob-outside-root"
 } | {
+kind: "workspace-pattern-dir-missing"
 /**
  * The workspace pattern, as written in the file.
  */
 pattern: string
-kind: "workspace-pattern-dir-missing"
 } | {
 kind: "nested-project-root"
 } | {
+kind: "malformed-tsconfig"
 /**
  * JSONC parse error text.
  */
 error: string
-kind: "malformed-tsconfig"
 } | {
 kind: "tsconfig-reference-dir-missing"
 } | {
+kind: "malformed-pnpm-workspace-yaml"
 /**
  * YAML parse error text.
  */
 error: string
-kind: "malformed-pnpm-workspace-yaml"
 } | {
+kind: "skipped-large-file"
 /**
  * On-disk size of the skipped file in bytes.
  */
 size_bytes: number
-kind: "skipped-large-file"
 } | {
+kind: "skipped-minified-file"
 /**
  * On-disk size of the skipped file in bytes.
  */
 size_bytes: number
-kind: "skipped-minified-file"
 } | {
 kind: "skipped-source-dotdir"
 } | {
+kind: "source-read-failure"
 /**
  * Filesystem or UTF-8 decoding error from `read_to_string`.
  */
 error: string
-kind: "source-read-failure"
 } | {
+kind: "source-parse-degraded"
 /**
  * Number of parser diagnostics reported for the file.
  */
@@ -633,7 +638,12 @@ error_count: number
  * the extracted module is a fragment at best.
  */
 panicked: boolean
-kind: "source-parse-degraded"
+} | {
+kind: "source-nesting-too-deep"
+/**
+ * The bracket nesting cap of the pre-parse scan.
+ */
+limit: number
 } | {
 kind: "bun-lockb-override-resolution-skipped"
 } | {
@@ -645,8 +655,8 @@ kind: "npm-lock-override-resolution-skipped"
 } | {
 kind: "bun-resolutions-shadowed-by-overrides"
 } | {
-cause: PnpmWorkspaceOverridesIgnoredCause
 kind: "pnpm-workspace-overrides-ignored"
+cause: PnpmWorkspaceOverridesIgnoredCause
 } | {
 kind: "node-modules-missing"
 } | {
@@ -654,6 +664,7 @@ kind: "boundaries-not-configured"
 } | {
 kind: "rule-packs-not-configured"
 } | {
+kind: "excluded-by-default-ignore"
 /**
  * The built-in glob that matched, verbatim (for example
  * `** /build/**`).
@@ -677,22 +688,22 @@ file_count: number
  * one matched location out of several.
  */
 directory_count: number
-kind: "excluded-by-default-ignore"
 } | {
+kind: "no-source-files-analyzed"
 /**
  * Candidate source files the built-in ignore patterns removed from
  * this walk, summed across every pattern. `0` when the walk found no
  * candidate to exclude in the first place.
  */
 excluded_file_count: number
-kind: "no-source-files-analyzed"
 } | {
+kind: "file-scores-unavailable"
 /**
  * Scoring error text.
  */
 error: string
-kind: "file-scores-unavailable"
 } | {
+kind: "hotspots-skipped"
 /**
  * Which input stopped it, as a kebab-case token: `not-a-repository`,
  * `no-commits`, `invalid-since` or `churn-file-unreadable`. The set is
@@ -706,25 +717,25 @@ kind: "file-scores-unavailable"
  * remedy for all four.
  */
 cause: string
-kind: "hotspots-skipped"
 } | {
+kind: "change-coupling-skipped"
 /**
  * Kebab-case token: `shallow-clone` (the fetched history is
  * incomplete) or `too-few-commits` (fewer analyzed commits than the
  * minimum revisions of one file). The set is open.
  */
 cause: string
-kind: "change-coupling-skipped"
 } | {
+kind: "shallow-clone"
 /**
  * `true` when the run also asked for ownership attribution, which a
  * shallow clone skews further by inflating single-author dominance.
  */
 ownership_requested: boolean
-kind: "shallow-clone"
 } | {
 kind: "unpinned-clock"
 } | {
+kind: "ownership-unavailable"
 /**
  * Which input failed, as a kebab-case token: `invalid-bot-pattern` or
  * `codeowners-parse-failed`. The set is open.
@@ -734,21 +745,21 @@ cause: string
  * Underlying error text.
  */
 error: string
-kind: "ownership-unavailable"
 } | {
+kind: "trend-snapshot-unreadable"
 /**
  * Filesystem or JSON error text.
  */
 error: string
-kind: "trend-snapshot-unreadable"
 } | {
+kind: "trend-group-baseline-unavailable"
 /**
  * Why the groups have no baseline, as a kebab-case token:
  * `snapshot-has-no-groups` or `grouped-by-mismatch`. The set is open.
  */
 cause: string
-kind: "trend-group-baseline-unavailable"
 } | {
+kind: "plugin-config-unreadable"
 /**
  * The plugin that read the config, as it labels itself:
  * `module-federation` for a standalone `module-federation.config.*`,
@@ -775,8 +786,8 @@ key: string
  * option the message points at.
  */
 reason: string
-kind: "plugin-config-unreadable"
 } | {
+kind: "plugin-effect-not-modeled"
 /**
  * The plugin that read the config, as it labels itself (`nuxt`).
  */
@@ -795,34 +806,51 @@ key: string
  * be classified at all. The set is open.
  */
 reason: string
-kind: "plugin-effect-not-modeled"
 } | {
 kind: "coverage-auto-detected"
 } | {
 kind: "flag-age-shallow-clone"
 } | {
+kind: "flag-age-unavailable"
 /**
  * Why no history is available, as a kebab-case token:
  * `not-a-repository` or `no-commits`. The set is open.
  */
 cause: string
-kind: "flag-age-unavailable"
 } | {
+kind: "ignore-dependencies-glob-unmatched"
 /**
  * The `ignoreDependencies` entry, as written in the config.
  */
 pattern: string
-kind: "ignore-dependencies-glob-unmatched"
 } | {
+kind: "ignore-findings-pattern-unmatched"
 /**
  * The `ignoreFindings` entry, as written in the config.
  */
 pattern: string
-kind: "ignore-findings-pattern-unmatched"
 } | {
+kind: "entry-pattern-redundant"
+/**
+ * The `entry` pattern, as written in the config.
+ */
+pattern: string
+} | {
+kind: "ignore-dependencies-entry-redundant"
+/**
+ * The `ignoreDependencies` entry, as written in the config.
+ */
+pattern: string
+} | {
+kind: "ignore-patterns-entry-redundant"
+/**
+ * The `ignorePatterns` glob, as written in the config.
+ */
+pattern: string
+} | {
+kind: "baseline-install-state-mismatch"
 baseline_node_modules: NodeModulesState
 run_node_modules: NodeModulesState
-kind: "baseline-install-state-mismatch"
 })
 /**
  * Why the declared pnpm version ignores the `overrides` section of
@@ -922,6 +950,15 @@ export type WorsenedMetricKind = ("cyclomatic" | "cognitive" | "crap" | "line_co
  * Audit-mode reason why a complexity finding does not gate the verdict.
  */
 export type AuditGateExemption = "test-file"
+/**
+ * How `fallow health` counts cyclomatic complexity for its gates.
+ *
+ * The policy changes the cyclomatic value that the `maxCyclomatic` gate reads
+ * and the cyclomatic value in every CRAP score. It does not change the health
+ * score, the complexity density, or the hotspot ranking: those keep the
+ * standard count so that grades stay comparable across projects.
+ */
+export type CyclomaticPolicy = ("standard" | "literal-membership")
 /**
  * Coverage model used for CRAP score computation.
  */
@@ -1189,12 +1226,13 @@ export type DiffRiskActionType = ("suppress-line" | "suppress-file" | "suppress-
  * `target` block of [`InspectOutput`], tagged by `type`.
  */
 export type InspectTargetDescriptor = ({
+type: "file"
 /**
  * File path relative to the analysed root.
  */
 file: string
-type: "file"
 } | {
+type: "symbol"
 /**
  * File path relative to the analysed root.
  */
@@ -1203,7 +1241,6 @@ file: string
  * Name of the inspected export.
  */
 export_name: string
-type: "symbol"
 })
 /**
  * `identity` block of [`InspectOutput`]; shape follows the target type.
@@ -2031,7 +2068,8 @@ files?: GateFile[]
  *
  * Today only `parse-error` emits it. The item carries the same facts as the
  * `source-parse-degraded` entry in `workspace_diagnostics[]` for that file,
- * so a consumer can act on the gate without a join.
+ * so a consumer can act on the gate without a join. With `reason` set, the
+ * count and the parser outcome are placeholders.
  */
 export interface GateFile {
 /**
@@ -2039,14 +2077,19 @@ export interface GateFile {
  */
 path: string
 /**
- * The number of parser errors for the file.
+ * The number of parser errors for the file. `1` when `reason` is set.
  */
 error_count: number
 /**
  * True when the parser stopped in the file instead of recovering, so the
- * analysis saw only the part before the error.
+ * analysis saw only the part before the error. `true` when `reason` is set.
  */
 panicked: boolean
+/**
+ * Why the file counts when it is not a parser error. Absent for a parser
+ * error, the only reason before this field existed.
+ */
+reason?: (GateFileReason | null)
 }
 /**
  * Metric and rule definitions emitted under `_meta` when `--explain` is
@@ -3431,7 +3474,7 @@ _meta?: (Meta | null)
  * - source discovery, during the file walk: `skipped-large-file`,
  *   `skipped-minified-file`, `skipped-source-dotdir`,
  *   `excluded-by-default-ignore`, `source-read-failure`,
- *   `source-parse-degraded`;
+ *   `source-parse-degraded`, `source-nesting-too-deep`;
  * - dead-code analysis, from the dependency-catalog and override
  *   detectors: `malformed-pnpm-workspace-yaml`,
  *   `bun-lockb-override-resolution-skipped`;
@@ -3450,10 +3493,11 @@ _meta?: (Meta | null)
  *
  * A diagnostic here is advisory and never withholds a finding. Where an
  * entry reports a source file this run never fully analyzed
- * (`source-parse-degraded`, `source-read-failure`, `skipped-large-file`,
- * `skipped-minified-file`, `skipped-source-dotdir`) it can distort a
- * verdict, so the affected `unused_files[]`, `unused_exports[]`, and
- * dependency entries additionally carry the caveat themselves in their own
+ * (`source-parse-degraded`, `source-nesting-too-deep`,
+ * `source-read-failure`, `skipped-large-file`, `skipped-minified-file`,
+ * `skipped-source-dotdir`) it can distort a verdict, so the affected
+ * `unused_files[]`, `unused_exports[]`, and dependency entries
+ * additionally carry the caveat themselves in their own
  * optional `reachability_caveats[]` array, and a reader who never scrolls
  * back up to this list still sees it. `fallow fix` reads the same array
  * and withholds the removal while a caveat stands.
@@ -3513,6 +3557,14 @@ total_issues: number
  * Prop chains whose saved effective severity explicitly enforces error policy.
  */
 prop_drilling_chains?: number
+/**
+ * Thin wrappers whose saved effective severity explicitly enforces error policy.
+ */
+thin_wrappers?: number
+/**
+ * Duplicate prop shapes whose saved effective severity explicitly enforces error policy.
+ */
+duplicate_prop_shapes?: number
 /**
  * Unused source files.
  */
@@ -6904,11 +6956,11 @@ actions: IssueAction[]
  */
 introduced?: (AuditIntroduced | null)
 /**
- * Rule severity of this finding. This type never gates the run, so the
- * value does not change the exit code. `fallow report --from` reads it
- * for the SARIF level, so the level does not depend on the config at
- * render time. Absent in output from older versions. Not part of the
- * finding identity, baseline keys or fingerprints.
+ * Rule severity of this finding. Explicit errors enforce analysis gates;
+ * warnings stay advisory, including under strict flags. Saved reports
+ * retain this value for CI levels without the original config. Absent
+ * in output from older versions. Not part of finding identity, baseline
+ * keys or fingerprints.
  */
 effective_severity?: (EffectiveSeverity | null)
 }
@@ -6970,11 +7022,11 @@ actions: IssueAction[]
  */
 introduced?: (AuditIntroduced | null)
 /**
- * Rule severity of this finding. This type never gates the run, so the
- * value does not change the exit code. `fallow report --from` reads it
- * for the SARIF level, so the level does not depend on the config at
- * render time. Absent in output from older versions. Not part of the
- * finding identity, baseline keys or fingerprints.
+ * Rule severity of this finding. Explicit errors enforce analysis gates;
+ * warnings stay advisory, including under strict flags. Saved reports
+ * retain this value for CI levels without the original config. Absent
+ * in output from older versions. Not part of finding identity, baseline
+ * keys or fingerprints.
  */
 effective_severity?: (EffectiveSeverity | null)
 }
@@ -7987,9 +8039,17 @@ line: number
  */
 col: number
 /**
- * Cyclomatic complexity of the function.
+ * Cyclomatic complexity of the function, as the cyclomatic gate and the
+ * CRAP score read it. Under the `literal-membership` value of
+ * `health.cyclomaticPolicy`, this is the value after literal membership
+ * chains count as one predicate.
  */
 cyclomatic: number
+/**
+ * Standard `McCabe` cyclomatic complexity, present only when the
+ * `health.cyclomaticPolicy` value gave `cyclomatic` a different value.
+ */
+standard_cyclomatic?: (number | null)
 /**
  * Cognitive complexity of the function.
  */
@@ -8305,6 +8365,15 @@ weight: number
  * consumer explain a cognitive `+3` as "+1 base, +2 nesting".
  */
 nesting: number
+/**
+ * This cyclomatic `||` increment is part of a literal membership chain:
+ * strict equality checks of one identifier against primitive literals
+ * (`kind === "a" || kind === "b"`). The `literal-membership` value of
+ * `health.cyclomaticPolicy` removes these increments from the effective
+ * cyclomatic value. Omitted when `false`, and always `false` under the
+ * default `standard` policy.
+ */
+literal_membership?: boolean
 }
 /**
  * Resolved thresholds used to evaluate a health finding.
@@ -8435,6 +8504,11 @@ functions_above_threshold: number
  * Global cyclomatic-complexity ceiling for this run.
  */
 max_cyclomatic_threshold: number
+/**
+ * Cyclomatic policy of the gates (`health.cyclomaticPolicy`). Absent
+ * under the default `standard` policy.
+ */
+cyclomatic_policy?: (CyclomaticPolicy | null)
 /**
  * Global cognitive-complexity ceiling for this run.
  */
@@ -16769,7 +16843,7 @@ _meta?: (Meta | null)
  * - source discovery, during the file walk: `skipped-large-file`,
  *   `skipped-minified-file`, `skipped-source-dotdir`,
  *   `excluded-by-default-ignore`, `source-read-failure`,
- *   `source-parse-degraded`;
+ *   `source-parse-degraded`, `source-nesting-too-deep`;
  * - dead-code analysis, from the dependency-catalog and override
  *   detectors: `malformed-pnpm-workspace-yaml`,
  *   `bun-lockb-override-resolution-skipped`;
@@ -16788,10 +16862,11 @@ _meta?: (Meta | null)
  *
  * A diagnostic here is advisory and never withholds a finding. Where an
  * entry reports a source file this run never fully analyzed
- * (`source-parse-degraded`, `source-read-failure`, `skipped-large-file`,
- * `skipped-minified-file`, `skipped-source-dotdir`) it can distort a
- * verdict, so the affected `unused_files[]`, `unused_exports[]`, and
- * dependency entries additionally carry the caveat themselves in their own
+ * (`source-parse-degraded`, `source-nesting-too-deep`,
+ * `source-read-failure`, `skipped-large-file`, `skipped-minified-file`,
+ * `skipped-source-dotdir`) it can distort a verdict, so the affected
+ * `unused_files[]`, `unused_exports[]`, and dependency entries
+ * additionally carry the caveat themselves in their own
  * optional `reachability_caveats[]` array, and a reader who never scrolls
  * back up to this list still sees it. `fallow fix` reads the same array
  * and withholds the removal while a caveat stands.
@@ -16829,10 +16904,12 @@ elapsed_ms: ElapsedMs
 /**
  * The verdict of every gate this run evaluated, keyed by name. The CLI
  * always emits it, with the default exit rule of each section that ran
- * (`error-severity-findings`, `health-findings`). Without
+ * (`error-severity-findings`, `health-findings`). A `coverage-gaps` rule
+ * at `error` adds `health-coverage-gaps`. Without
  * `--fail-on-issues` or `--ci`, the machine formats of the combined run
  * exit 0 for findings, so most entries have `enforced: false`. With one of
- * these flags, the findings rules and `duplication-threshold` are
+ * these flags, the findings rules, `health-coverage-gaps` and
+ * `duplication-threshold` are
  * `enforced`, the dupes section adds an enforced `duplication-findings`
  * entry, and every format exits 1 when one fails. For the default
  * exit rules (`error-severity-findings`,
@@ -16984,8 +17061,8 @@ total_flags: number
  * A flags run walks and parses the project like every other analysis, so
  * it records the same discovery kinds: a `skipped-large-file`,
  * `skipped-minified-file`, or `source-read-failure` file was never
- * scanned for flags, and a `source-parse-degraded` file was scanned from
- * a partial module. Each is a reason a flag can be missing from
+ * scanned for flags, a `source-parse-degraded` file was scanned from a
+ * partial module, and a `source-nesting-too-deep` file was not scanned. Each is a reason a flag can be missing from
  * `feature_flags[]`, which is exactly what a consumer reading a
  * zero-result run needs to know. The analysis-stage kinds appear here
  * too: the scan correlates flags with dead exports, so it runs the
@@ -19845,6 +19922,10 @@ runner?: (MutationRunnerOutput | null)
  * started.
  */
 cache?: (MutationCacheOutput | null)
+/**
+ * The resume facts. Absent without `--resume`.
+ */
+resume?: (MutationResumeOutput | null)
 summary: MutationSummary
 /**
  * Each mutant, ranked mutants first.
@@ -19979,6 +20060,36 @@ stored: number
  */
 not_keyed: string[]
 }
+/**
+ * The resume facts of a `--resume` run.
+ */
+export interface MutationResumeOutput {
+/**
+ * The path of the outcome journal, relative to the project root. When
+ * the cache directory is outside the root, the path is absolute: the
+ * report has no other cache path, so no other rule applies. The file
+ * stays only when the run did not complete. A run with
+ * `completion.status: complete` removes it.
+ */
+journal: string
+/**
+ * The mutants whose status came from the journal. They did not run.
+ */
+reused: number
+/**
+ * The journal results whose key does not match this run, because an
+ * input of the mutant changed. These results were not reused from the
+ * journal. The mutant ran again, or its status came from the result
+ * cache.
+ */
+rejected: number
+/**
+ * Why the run did not read a journal and started from the beginning,
+ * for example because no journal exists. Absent when the run read the
+ * journal.
+ */
+note?: (string | null)
+}
 /**
  * The totals of a run.
  */
@@ -20104,6 +20215,11 @@ attempts?: MutantAttempt[]
  * The mutant did not run in this run. `--no-cache` runs each mutant.
  */
 cached?: boolean
+/**
+ * True when the status comes from the journal of an interrupted run
+ * (`--resume`). The mutant did not run in this run.
+ */
+resumed?: boolean
 /**
  * The TypeScript diagnostic codes of the new errors of a
  * `compile_error` mutant, sorted, at most 8.
@@ -20286,7 +20402,8 @@ changed_paths: string[]
  */
 export interface MutationRunIssue {
 /**
- * A stable kebab-case code: `runtime-error`, `static-map-miss`,
+ * A stable kebab-case code: `cache-write-failed`,
+ * `journal-write-failed`, `runtime-error`, `static-map-miss`,
  * `test-files-not-discovered`, `typecheck-failed`, `worktree-changed`
  * or `worktree-check-failed`.
  */