fallow 2.76.0 → 2.78.0

package/types/output-contract.d.ts

@@ -164,7 +164,7 @@ export type IssueAction = (FixAction | SuppressLineAction | SuppressFileAction |
  * Discriminant string for [`FixAction`]. Kebab-case per the JSON output
  * contract.
  */
-export type FixActionType = ("remove-export" | "delete-file" | "remove-dependency" | "move-dependency" | "remove-enum-member" | "remove-class-member" | "resolve-import" | "install-dependency" | "remove-duplicate" | "move-to-dev" | "refactor-cycle" | "refactor-boundary" | "export-type" | "remove-catalog-entry" | "remove-empty-catalog-group" | "update-catalog-reference" | "add-catalog-entry" | "remove-catalog-reference" | "remove-dependency-override" | "fix-dependency-override")
+export type FixActionType = ("remove-export" | "delete-file" | "remove-dependency" | "move-dependency" | "remove-enum-member" | "remove-class-member" | "resolve-import" | "install-dependency" | "remove-duplicate" | "move-to-dev" | "refactor-cycle" | "refactor-re-export-cycle" | "refactor-boundary" | "export-type" | "remove-catalog-entry" | "remove-empty-catalog-group" | "update-catalog-reference" | "add-catalog-entry" | "remove-catalog-reference" | "remove-dependency-override" | "fix-dependency-override")
 /**
  * Singleton discriminant for [`SuppressLineAction`].
  */
@@ -233,6 +233,10 @@ export type DependencyLocation = ("dependencies" | "devDependencies" | "optional
  * ```
  */
 export type MemberKind = ("enum_member" | "class_method" | "class_property" | "namespace_member")
+/**
+ * Discriminator for [`ReExportCycle`]: which structural shape was detected.
+ */
+export type ReExportCycleKind = ("multi-node" | "self-loop")
 /**
  * The origin of a stale suppression: inline comment or JSDoc tag.
  */
@@ -245,6 +249,15 @@ issue_kind?: (string | null)
  * Whether this was a file-level suppression.
  */
 is_file_level: boolean
+/**
+ * Whether `issue_kind` parses to a known `IssueKind`. False when the
+ * token is a typo or refers to a kind that was renamed or removed in
+ * a newer fallow release. JSON consumers (CI annotations, MCP agents,
+ * VS Code) branch on this to choose the right next-step text.
+ * Omitted from the wire when `true` so producers that have not yet
+ * adopted the field stay byte-compatible. See issue #449.
+ */
+kind_known?: boolean
 type: "comment"
 } | {
 /**
@@ -273,6 +286,48 @@ export type RegressionStatus = ("pass" | "exceeded" | "skipped")
  * Interpretation of [`RegressionResult::tolerance`].
  */
 export type RegressionToleranceKind = ("absolute" | "percentage")
+/**
+ * A diagnostic about a workspace-discovery candidate.
+ *
+ * The `message` field is a human-readable rendering derived from `kind`. It
+ * always ends with a concrete next step ("fix the JSON syntax", "remove from
+ * `workspaces`", "add to `ignorePatterns`") so first-time users have a path
+ * forward.
+ */
+export type WorkspaceDiagnostic = ({
+/**
+ * Path to the directory or file that triggered the diagnostic.
+ */
+path: string
+/**
+ * Human-readable rendering derived from `kind` + `path`. Always ends
+ * with a next-step hint.
+ */
+message: string
+} & WorkspaceDiagnostic1)
+export type WorkspaceDiagnostic1 = ({
+kind: "undeclared-workspace"
+} | {
+/**
+ * `serde_json` parse error text.
+ */
+error: string
+kind: "malformed-package-json"
+} | {
+/**
+ * The glob pattern that matched the directory.
+ */
+pattern: string
+kind: "glob-matched-no-package-json"
+} | {
+/**
+ * JSONC parse error text.
+ */
+error: string
+kind: "malformed-tsconfig"
+} | {
+kind: "tsconfig-reference-dir-missing"
+})
 /**
  * Discriminant for [`CloneGroupAction::kind`]. Mirrors the action types
  * emitted by the legacy `build_clone_group_actions` walker.
@@ -495,7 +550,7 @@ export type GitLabReviewPositionType = "text"
 /**
  * Schema-version discriminator for the review envelope.
  */
-export type ReviewEnvelopeSchema = "fallow-review-envelope/v1"
+export type ReviewEnvelopeSchema = ("fallow-review-envelope/v1" | "fallow-review-envelope/v2")
 /**
  * Review-envelope provider tag.
  */
@@ -769,6 +824,15 @@ test_only_dependencies?: TestOnlyDependencyFinding[]
  * array natively.
  */
 circular_dependencies: CircularDependencyFinding[]
+/**
+ * Cycles or self-loops in the re-export edge subgraph (barrel files
+ * re-exporting from each other in a loop). Wrapped in
+ * [`ReExportCycleFinding`] so each entry carries a typed `actions`
+ * array natively (a `refactor-re-export-cycle` informational primary
+ * plus a `suppress-file` secondary; cycles are file-scoped so a single
+ * suppression breaks the cycle).
+ */
+re_export_cycles?: ReExportCycleFinding[]
 /**
  * Imports that cross architecture boundary rules. Wrapped in
  * [`BoundaryViolationFinding`] so each entry carries a typed `actions`
@@ -837,6 +901,16 @@ regression?: (RegressionResult | null)
  * is passed (always present in MCP responses).
  */
 _meta?: (Meta | null)
+/**
+ * Workspace-discovery diagnostics surfaced by
+ * `discover_workspaces_with_diagnostics` (issue #473): malformed
+ * declared-workspace `package.json`, glob matches with no `package.json`,
+ * malformed `tsconfig.json`, missing tsconfig reference paths. Omitted
+ * when empty so consumers on monorepos without discovery noise see no
+ * new field. Pairing of `#[serde(default, skip_serializing_if = ...)]`
+ * is required for schemars to mark the field non-required.
+ */
+workspace_diagnostics?: WorkspaceDiagnostic[]
 }
 /**
  * Entry-point detection summary embedded in `CheckOutput` and the combined
@@ -922,6 +996,11 @@ test_only_dependencies: number
  * Cycles detected in the import graph.
  */
 circular_dependencies: number
+/**
+ * Cycles or self-loops in the re-export edge subgraph (barrel files
+ * re-exporting from each other in a loop).
+ */
+re_export_cycles?: number
 /**
  * Imports that cross architecture boundary rules.
  */
@@ -1674,6 +1753,33 @@ actions: IssueAction[]
  */
 introduced?: (AuditIntroduced | null)
 }
+/**
+ * Wire-shape envelope for a [`ReExportCycle`] finding. Mirrors
+ * [`CircularDependencyFinding`]: flattens the bare finding and carries a
+ * typed `actions` array (`refactor-re-export-cycle` informational primary
+ * plus `suppress-file` secondary; cycles are file-scoped so a single
+ * file-level suppression on the alphabetically-first member breaks the
+ * cycle, and no `// fallow-ignore-next-line` form makes sense because the
+ * diagnostic is anchored at line 1 col 0 of each member).
+ */
+export interface ReExportCycleFinding {
+/**
+ * Files participating in the cycle, sorted lexicographically. For a
+ * self-loop, exactly one entry.
+ */
+files: string[]
+kind: ReExportCycleKind
+/**
+ * Suggested next steps. Always emitted (possibly empty for
+ * forward-compat).
+ */
+actions: IssueAction[]
+/**
+ * Set by the audit pass when this finding is introduced relative to
+ * the merge-base.
+ */
+introduced?: (AuditIntroduced | null)
+}
 /**
  * Wire-shape envelope for a [`BoundaryViolation`] finding. Mirrors
  * [`UnusedFileFinding`]: flattens the bare finding and carries a typed
@@ -2063,6 +2169,12 @@ export interface Meta {
  * URL to the documentation page for this command.
  */
 docs?: (string | null)
+/**
+ * Per-field definitions for envelope fields and action payload fields.
+ */
+field_definitions?: {
+[k: string]: string
+}
 /**
  * Per-metric definitions: name, description, range, interpretation.
  */
@@ -3927,15 +4039,15 @@ export interface TargetEvidence {
 /**
  * Names of unused exports (populated for `RemoveDeadCode` targets).
  */
-unused_exports: string[]
+unused_exports?: string[]
 /**
  * Complex functions with line numbers and cognitive scores (populated for `ExtractComplexFunctions`).
  */
-complex_functions: EvidenceFunction[]
+complex_functions?: EvidenceFunction[]
 /**
  * Files forming the import cycle (populated for `BreakCircularDependency` targets).
  */
-cycle_path: string[]
+cycle_path?: string[]
 }
 /**
  * A function referenced in target evidence.
@@ -4199,16 +4311,75 @@ export interface ReviewEnvelopeOutput {
  */
 event?: (ReviewEnvelopeEvent | null)
 /**
- * Review summary body (rendered above per-line comments).
+ * Review summary body (rendered above per-line comments). Deprecated in
+ * v2 envelopes: prefer [`summary.body`](`ReviewEnvelopeSummary::body`),
+ * which is byte-identical to this field but carries a stable
+ * fingerprint for reconciliation. Kept on v2 emit so v1 consumers that
+ * only look at `body` keep working.
  */
 body: string
+summary?: ReviewEnvelopeSummary
 /**
  * Per-line comments. Each is either a [`GitHubReviewComment`] or a
  * [`GitLabReviewComment`] depending on `meta.provider`.
  */
 comments: ReviewComment[]
+/**
+ * Regex consumers run against every existing PR/MR comment body to
+ * extract a fallow-emitted fingerprint marker. Capture group 1 is the
+ * fingerprint string (a bare 16-char hex hash for single-finding
+ * comments, or `<kind>:<16-char-hex>` for compositions such as
+ * `merged:` for same-line collapsed comments).
+ *
+ * The pattern is anchored with `^` / `$` and relies on multiline
+ * matching to anchor at line boundaries inside a multi-line comment
+ * body. Multiline is NOT baked into the pattern via `(?m)` (which
+ * JavaScript RegExp rejects as `Invalid group`); instead the consumer
+ * passes [`Self::marker_regex_flags`] as the flags argument to its
+ * regex engine. JavaScript: `new RegExp(env.marker_regex,
+ * env.marker_regex_flags)`. Rust: `regex::RegexBuilder::new(pat)
+ * .multi_line(flags.contains('m')).build()` (or any equivalent).
+ */
+marker_regex?: string
+/**
+ * Flags consumers pass alongside [`Self::marker_regex`] when
+ * constructing their regex engine. Currently always `"m"` (multiline
+ * so the anchored `^` / `$` match at every line boundary within a
+ * comment body). Emitting flags as a separate field instead of
+ * baking `(?m)` into the pattern keeps the wire compatible with
+ * JavaScript RegExp, which rejects inline flag groups outside a
+ * `(?flags:X)` grouping.
+ */
+marker_regex_flags?: string
 meta: ReviewEnvelopeMeta
 }
+/**
+ * Summary block on [`ReviewEnvelopeOutput`]. Always present on v2 emit;
+ * `serde(default)` keeps schemars from marking it required so a future
+ * Deserialize derivation against v1 historical input synthesizes an empty
+ * value rather than erroring.
+ */
+export interface ReviewEnvelopeSummary {
+/**
+ * Markdown body of the summary. Byte-identical to the legacy top-level
+ * [`ReviewEnvelopeOutput::body`] field; the duplication is intentional
+ * so v1 consumers see no behavior change.
+ */
+body: string
+/**
+ * FNV-1a 64-bit hash (16 lowercase hex chars) of the summary body
+ * BEFORE the trailing fallow-fingerprint marker line is appended.
+ * (Computing the hash from the post-marker body would be circular:
+ * the marker contains the fingerprint, so the fingerprint cannot
+ * depend on the marker.) To reproduce from [`Self::body`], strip the
+ * line matching [`ReviewEnvelopeOutput::marker_regex`] together with
+ * its leading separator newlines and hash the remainder. Stable
+ * across runs that produce the same summary content; consumers
+ * upsert the sticky summary comment by matching this fingerprint
+ * against the marker_regex extraction of every existing comment body.
+ */
+fingerprint: string
+}
 /**
  * GitHub pull-request review comment.
  */
@@ -4229,8 +4400,30 @@ body: string
 /**
  * Stable fingerprint for the comment, used by `fallow ci
  * reconcile-review` to detect carryover comments across PR revisions.
+ * For single-finding comments the value is a bare 16-char hex FNV-1a
+ * hash. For merged comments (multiple findings on the same path:line)
+ * the value is `merged:<16-char hex>` over the sorted constituent
+ * fingerprints, so the identity shifts whenever constituent findings
+ * change membership. Bundled wrappers and `fallow ci reconcile-review`
+ * dedupe on this primary fingerprint only; consumers wanting
+ * update-in-place reconciliation (preserving reviewer reply threads
+ * across content changes) implement their own identity tracking via
+ * `marker_regex`.
  */
 fingerprint: string
+/**
+ * True when [`Self::body`] was truncated to fit a downstream provider's
+ * note-size budget (today: 65,536 bytes). The body retains the closing
+ * fallow-fingerprint marker so reconciliation continues to work after
+ * truncation.
+ *
+ * Co-presence invariant: `truncated == true` always implies the body
+ * contains an inline `<!-- fallow-truncated -->` HTML marker and the
+ * `> Body truncated by fallow.` blockquote breadcrumb, and vice versa.
+ * All three signals are emitted together; consumers may use any one
+ * (the typed boolean is the authoritative machine-readable signal).
+ */
+truncated?: boolean
 }
 /**
  * GitLab merge-request discussion comment.
@@ -4242,9 +4435,18 @@ export interface GitLabReviewComment {
 body: string
 position: GitLabReviewPosition
 /**
- * Stable fingerprint for the comment.
+ * Stable fingerprint for the comment. See
+ * [`GitHubReviewComment::fingerprint`] for the single vs `merged:`
+ * shape contract; semantics are identical across providers.
  */
 fingerprint: string
+/**
+ * True when [`Self::body`] was truncated to fit GitLab's note-size
+ * budget. See [`GitHubReviewComment::truncated`] for the full
+ * co-presence invariant with the inline HTML marker and human
+ * blockquote breadcrumb.
+ */
+truncated?: boolean
 }
 /**
  * `position` block inside [`GitLabReviewComment`]. Mirrors the GitLab
@@ -4796,6 +4998,13 @@ groups?: (HealthGroup[] | null)
  * is passed (always present in MCP responses).
  */
 _meta?: (Meta | null)
+/**
+ * Workspace-discovery diagnostics surfaced during config load
+ * (issue #473). Mirror of [`CheckOutput::workspace_diagnostics`] so
+ * stand-alone `fallow health --format json` consumers see the same
+ * signal.
+ */
+workspace_diagnostics?: WorkspaceDiagnostic[]
 }
 /**
  * A health report scoped to a single group.
@@ -4950,6 +5159,14 @@ groups?: (DuplicationGroup[] | null)
  * is passed (always present in MCP responses).
  */
 _meta?: (Meta | null)
+/**
+ * Workspace-discovery diagnostics surfaced during config load
+ * (issue #473). See [`CheckOutput::workspace_diagnostics`] for the full
+ * contract; the same list is repeated on each top-level command's
+ * envelope so single-command consumers see it without having to look at
+ * a separate top-level field.
+ */
+workspace_diagnostics?: WorkspaceDiagnostic[]
 }
 /**
  * A single grouped duplication bucket. Per-group `stats` are dedup-aware and
@@ -5187,6 +5404,15 @@ test_only_dependencies?: TestOnlyDependencyFinding[]
  * array natively.
  */
 circular_dependencies: CircularDependencyFinding[]
+/**
+ * Cycles or self-loops in the re-export edge subgraph (barrel files
+ * re-exporting from each other in a loop). Wrapped in
+ * [`ReExportCycleFinding`] so each entry carries a typed `actions`
+ * array natively (a `refactor-re-export-cycle` informational primary
+ * plus a `suppress-file` secondary; cycles are file-scoped so a single
+ * suppression breaks the cycle).
+ */
+re_export_cycles?: ReExportCycleFinding[]
 /**
  * Imports that cross architecture boundary rules. Wrapped in
  * [`BoundaryViolationFinding`] so each entry carries a typed `actions`
@@ -5259,6 +5485,12 @@ export interface CombinedOutput {
 schema_version: SchemaVersion
 version: ToolVersion
 elapsed_ms: ElapsedMs
+/**
+ * Sectioned `_meta` block emitted only when `--explain` is passed.
+ * Contains `check`, `dupes`, and/or `health` keys matching the analyses
+ * enabled for the combined run.
+ */
+_meta?: (CombinedMeta | null)
 /**
  * Dead-code analysis sub-envelope. Absent when `--skip check`.
  */
@@ -5276,6 +5508,23 @@ dupes?: (DupesReportPayload | null)
  */
 health?: (HealthReport | null)
 }
+/**
+ * Sectioned `_meta` block for the bare combined JSON envelope.
+ */
+export interface CombinedMeta {
+/**
+ * Dead-code metadata from `crate::explain::check_meta()`.
+ */
+check?: (Meta | null)
+/**
+ * Duplication metadata from `crate::explain::dupes_meta()`.
+ */
+dupes?: (Meta | null)
+/**
+ * Health metadata from `crate::explain::health_meta()`.
+ */
+health?: (Meta | null)
+}
 /**
  * Single CodeClimate-compatible issue inside [`CodeClimateOutput`].
  */
@@ -5496,6 +5745,16 @@ export type MisconfiguredDependencyOverride = MisconfiguredDependencyOverrideFin
  */
 export type PrivateTypeLeak = PrivateTypeLeakFinding;
 
+/**
+ * Backwards-compat alias for the pre-#384 bare `ReExportCycle` name.
+ * The wire shape is byte-identical: `ReExportCycleFinding` flattens the bare
+ * finding's fields via `#[serde(flatten)]` and adds `actions[]` plus
+ * the optional audit-mode `introduced` flag. Consumers that imported
+ * `ReExportCycle` from `fallow/types` pre-migration continue to work via
+ * this alias; new code should prefer `ReExportCycleFinding`.
+ */
+export type ReExportCycle = ReExportCycleFinding;
+
 /**
  * Backwards-compat alias for the pre-#384 bare `TestOnlyDependency` name.
  * The wire shape is byte-identical: `TestOnlyDependencyFinding` flattens the bare