tend-cli 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,1274 @@
+import { Command } from "commander";
+import { z } from "zod";
+import { SimpleGit } from "simple-git";
+
+//#region src/findings/finding.d.ts
+declare const TOOLS: readonly ["sonarjs", "knip", "jscpd", "semgrep", "osv", "gitleaks"];
+declare const FindingSchema: z.ZodObject<{
+  id: z.ZodString;
+  retryId: z.ZodOptional<z.ZodString>;
+  tool: z.ZodEnum<["sonarjs", "knip", "jscpd", "semgrep", "osv", "gitleaks"]>;
+  rule: z.ZodString;
+  category: z.ZodEnum<["bug", "smell", "dead-code", "duplication", "security", "secret", "vuln-dep"]>;
+  severity: z.ZodEnum<["error", "warning", "info"]>;
+  file: z.ZodString;
+  range: z.ZodObject<{
+    startLine: z.ZodNumber;
+    startCol: z.ZodNumber;
+    endLine: z.ZodNumber;
+    endCol: z.ZodNumber;
+  }, "strip", z.ZodTypeAny, {
+    startLine: number;
+    startCol: number;
+    endLine: number;
+    endCol: number;
+  }, {
+    startLine: number;
+    startCol: number;
+    endLine: number;
+    endCol: number;
+  }>;
+  message: z.ZodString;
+  helpUri: z.ZodOptional<z.ZodString>;
+  flowPath: z.ZodOptional<z.ZodArray<z.ZodObject<{
+    file: z.ZodString;
+    line: z.ZodNumber;
+  }, "strip", z.ZodTypeAny, {
+    file: string;
+    line: number;
+  }, {
+    file: string;
+    line: number;
+  }>, "many">>;
+  remediation: z.ZodOptional<z.ZodString>;
+  track: z.ZodEnum<["ai-fix", "deterministic", "report-only"]>;
+  status: z.ZodEnum<["pending", "fixing", "fixed", "reverted", "unfixable", "skipped"]>;
+  attempts: z.ZodNumber;
+  revertReason: z.ZodOptional<z.ZodEnum<["broke-test", "suppression", "regression", "typecheck", "session-error"]>>;
+  firstSeenLoop: z.ZodNumber;
+  lastSeenLoop: z.ZodNumber;
+  inScope: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+  id: string;
+  tool: "sonarjs" | "knip" | "jscpd" | "semgrep" | "osv" | "gitleaks";
+  status: "pending" | "fixing" | "fixed" | "reverted" | "unfixable" | "skipped";
+  message: string;
+  rule: string;
+  category: "bug" | "smell" | "dead-code" | "duplication" | "security" | "secret" | "vuln-dep";
+  severity: "error" | "warning" | "info";
+  file: string;
+  range: {
+    startLine: number;
+    startCol: number;
+    endLine: number;
+    endCol: number;
+  };
+  track: "ai-fix" | "deterministic" | "report-only";
+  attempts: number;
+  firstSeenLoop: number;
+  lastSeenLoop: number;
+  retryId?: string | undefined;
+  helpUri?: string | undefined;
+  flowPath?: {
+    file: string;
+    line: number;
+  }[] | undefined;
+  remediation?: string | undefined;
+  revertReason?: "broke-test" | "suppression" | "regression" | "typecheck" | "session-error" | undefined;
+  inScope?: boolean | undefined;
+}, {
+  id: string;
+  tool: "sonarjs" | "knip" | "jscpd" | "semgrep" | "osv" | "gitleaks";
+  status: "pending" | "fixing" | "fixed" | "reverted" | "unfixable" | "skipped";
+  message: string;
+  rule: string;
+  category: "bug" | "smell" | "dead-code" | "duplication" | "security" | "secret" | "vuln-dep";
+  severity: "error" | "warning" | "info";
+  file: string;
+  range: {
+    startLine: number;
+    startCol: number;
+    endLine: number;
+    endCol: number;
+  };
+  track: "ai-fix" | "deterministic" | "report-only";
+  attempts: number;
+  firstSeenLoop: number;
+  lastSeenLoop: number;
+  retryId?: string | undefined;
+  helpUri?: string | undefined;
+  flowPath?: {
+    file: string;
+    line: number;
+  }[] | undefined;
+  remediation?: string | undefined;
+  revertReason?: "broke-test" | "suppression" | "regression" | "typecheck" | "session-error" | undefined;
+  inScope?: boolean | undefined;
+}>;
+type Finding = z.infer<typeof FindingSchema>;
+type Tool = (typeof TOOLS)[number];
+type Track = Finding["track"];
+/** The components that give a finding its stable identity. */
+type FingerprintInput = {
+  tool: string;
+  rule: string;
+  file: string;
+  line: number;
+  message: string;
+};
+/**
+ * Stable identity for a finding: hash(tool | rule | file | line | message).
+ * Same components → same fingerprint, across loops and runs.
+ */
+declare function fingerprint(input: FingerprintInput): string; //#endregion
+//#region src/findings/normalize.d.ts
+/** A scanner-produced record, before tend assigns identity, track, and loop state. */
+type RawFinding = {
+  tool: Tool;
+  rule: string;
+  category: Finding["category"];
+  severity: Finding["severity"];
+  file: string;
+  range: Finding["range"];
+  message: string;
+  helpUri?: string;
+  flowPath?: Finding["flowPath"];
+  remediation?: string;
+};
+/** Which track a tool's findings flow into. */
+declare function trackForTool(tool: Tool): Track;
+/** Turn a raw scanner record into a tracked `Finding` for the given loop. */
+declare function normalize(raw: RawFinding, loop: number): Finding;
+
+//#endregion
+//#region src/findings/store.d.ts
+type RevertReason$1 = NonNullable<Finding["revertReason"]>;
+/** Holds Finding records keyed by fingerprint and tracks their state across loops. */
+declare class FindingStore {
+  private readonly findings;
+  add(finding: Finding): void;
+  get(id: string): Finding | undefined;
+  all(): Finding[];
+  /**
+   * Diff a fresh audit against what the store knows, by fingerprint:
+   *   - known but absent now  → marked `fixed`
+   *   - present both loops     → stays as-is, carries attempts/history, bumps lastSeenLoop
+   *   - new fingerprint         → added `pending`, firstSeenLoop = loop
+   */
+  reconcile(fresh: Finding[], loop: number): void;
+  /** Findings matching every provided filter (track / status / file). */
+  query(filter: {
+    track?: Finding["track"];
+    status?: Finding["status"];
+    file?: string;
+  }): Finding[];
+  /** Record a failed fix attempt against a finding's fingerprint. */
+  recordFailedAttempt(id: string, reason: RevertReason$1): void;
+  /** A finding's per-issue budget is exhausted once it has used `budget` attempts. */
+  isBudgetExhausted(id: string, budget: number): boolean;
+  /** Serialize to a plain array — `report.json`'s findings section. */
+  toJSON(): Finding[];
+  /** Rebuild a store from serialized findings, validating each against the schema. */
+  static fromJSON(data: unknown): FindingStore;
+}
+
+//#endregion
+//#region src/findings/router.d.ts
+type RouteResult = {
+  aiFix: Finding[];
+  deterministic: Finding[];
+  reportOnly: Finding[];
+  skipped: Finding[];
+};
+/** Split findings into their assigned fix tracks; unknown tools are skipped with a warning. */
+declare function route(findings: Finding[], opts?: {
+  warn?: (message: string) => void;
+}): RouteResult;
+
+//#endregion
+//#region src/scanners/scanner.d.ts
+type ScanContext = {
+  cwd: string;
+  /** Files in scope (e.g. changed vs HEAD); a scanner may ignore this if it scans wide. */
+  files: string[];
+  loop: number;
+};
+type SpawnResult = {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+};
+/** Runs a binary, never throwing on non-zero exit (parse decides), but may throw on timeout/ENOENT. */
+type Spawn = (binary: string, args: string[], opts: {
+  cwd: string;
+  timeout?: number;
+}) => Promise<SpawnResult>;
+/** Resolves whether a binary is on PATH. */
+type Which = (binary: string) => Promise<boolean>;
+interface Scanner {
+  readonly tool: Tool;
+  readonly binary: string;
+  buildArgs(ctx: ScanContext): string[];
+  /** Parse raw process output into findings. Throws on malformed output. */
+  parse(raw: SpawnResult, ctx: ScanContext): RawFinding[];
+}
+type ScanResult = {
+  tool: Tool;
+  findings: Finding[];
+  skipped: boolean;
+  error?: string;
+};
+/** Outcome of a scanner this loop, for the report's scanner-status line. */
+type ScannerStatusKind = "ran" | "skipped" | "failed";
+type ScannerStatus$1 = {
+  tool: Tool;
+  status: ScannerStatusKind;
+  reason?: string;
+};
+/** Collapse a ScanResult to its reportable status: skipped → ran → failed (error present). */
+
+declare function isAvailable(scanner: Scanner, which: Which): Promise<boolean>;
+/**
+ * Shared run sequence for every scanner:
+ *   availability → args → spawn → parse → normalize.
+ * Missing binary → skipped (not fatal). Timeout/spawn error or malformed output → error result.
+ */
+declare function runScanner(scanner: Scanner, ctx: ScanContext, deps: {
+  which: Which;
+  spawn: Spawn;
+  timeout?: number;
+}): Promise<ScanResult>;
+
+//#endregion
+//#region src/scanners/scope.d.ts
+/**
+ * Files changed vs `HEAD` (tracked modifications/additions/renames plus untracked),
+ * scoped and re-based to `git`'s working directory — see `changedVsHead` in git/repo.ts
+ * for why this matters when tend runs from a subdirectory of the repo.
+ */
+declare function changedFiles(git: SimpleGit): Promise<string[]>;
+/** Keep only findings whose file is in the changed set. */
+declare function filterToChanged(findings: Finding[], changed: string[]): Finding[];
+/** Apply the fix scope: `--all` fixes everything, otherwise only changed files. */
+declare function scopeFindings(findings: Finding[], opts: {
+  all: boolean;
+  changed: string[];
+}): Finding[];
+
+//#endregion
+//#region src/gate/check.d.ts
+type RevertReason = NonNullable<Finding["revertReason"]>;
+type CheckResult = {
+  ok: true;
+} | {
+  ok: false;
+  reason: RevertReason;
+  detail: string;
+};
+
+//#endregion
+//#region src/gate/gate.d.ts
+type Check = {
+  name: string;
+  run: () => Promise<CheckResult> | CheckResult;
+};
+type GateOutcome = {
+  kept: true;
+} | {
+  kept: false;
+  reason: RevertReason;
+  detail: string;
+  failedCheck: string;
+};
+/**
+ * Run the verification checks in order, stopping at the first rejection and
+ * surfacing its revert reason. A fix is kept only if every check passes.
+ */
+declare function runGate(checks: Check[]): Promise<GateOutcome>;
+
+//#endregion
+//#region src/fixing/change-set.d.ts
+type FileEdit = {
+  path: string;
+  contents: string;
+};
+/**
+ * The atomic unit of a fix: edits to one file plus (optionally) its sibling test,
+ * applied and reverted together. Captures each file's prior state on apply so a
+ * revert — even after a partial apply — restores the working tree exactly.
+ */
+declare class ChangeSet {
+  private readonly edits;
+  /** path → original contents, or null if the file did not exist before. */
+  private readonly originals;
+  constructor(edits: FileEdit[]);
+  apply(): void;
+  revert(): void;
+}
+
+//#endregion
+//#region src/fixing/dispatch.d.ts
+type WorkUnit = {
+  /** The code file this unit owns (the group key). */
+  file: string;
+  /** Every file this worker reserves — the code file plus any sibling test. */
+  files: string[];
+  findings: Finding[];
+};
+/** Whether a repo-relative path is a test file (`*.test.*` / `*.spec.*`). */
+
+/**
+ * Group findings into work units so each worker owns a disjoint set of files
+ * (a code file plus its sibling test). No two sessions ever touch the same file.
+ */
+declare function planWork(findings: Finding[]): WorkUnit[];
+/** Run each work unit through `runUnit`, capped at `concurrency` concurrent sessions. */
+declare function dispatch<T>(units: WorkUnit[], runUnit: (unit: WorkUnit) => Promise<T>, opts: {
+  concurrency: number;
+}): Promise<T[]>;
+
+//#endregion
+//#region src/session/types.d.ts
+type SessionRequest = {
+  /** The file this session owns (plus its sibling test). */
+  file: string;
+  /** Findings to fix in this file. */
+  findings: Finding[];
+  /** The fully-rendered prompt for the AI. */
+  prompt: string;
+};
+/**
+ * Estimated AI cost/usage for a unit of work. `total_cost_usd` from Claude's
+ * stream-json `result` message is a **client-side estimate**, never authoritative
+ * billing — always surface it as "estimated AI cost".
+ */
+type AiUsage = {
+  /** Claude's `total_cost_usd` estimate (USD). A client-side estimate, not a bill. */
+  estimatedCostUsd: number;
+  inputTokens: number;
+  outputTokens: number;
+  cacheCreationInputTokens: number;
+  cacheReadInputTokens: number;
+  /** Number of Claude sessions (result messages) observed. */
+  sessions: number;
+};
+/** Cost/token portion of usage parsed from a single stream (sessions tracked separately). */
+
+/** A usage record with everything zeroed. */
+declare const zeroUsage: () => AiUsage;
+/** Sum two usage records field-by-field (used to roll usage up through the run). */
+declare function addUsage(a: AiUsage, b: AiUsage): AiUsage;
+type SessionResult = {
+  ok: true;
+  edits: FileEdit[];
+  usage?: AiUsage;
+} | {
+  ok: false;
+  error: string;
+  rateLimited: boolean;
+  usage?: AiUsage;
+};
+/** One of the two interfaces in tend: drives an AI fix session. */
+interface SessionRunner {
+  run(request: SessionRequest): Promise<SessionResult>;
+}
+
+//#endregion
+//#region src/session/claude.d.ts
+type ClaudeSpawn = (request: SessionRequest) => Promise<{
+  stdout: string;
+  exitCode: number;
+}>;
+/** Drives a real `claude -p` session and parses its stream-json into edits. */
+declare class ClaudeSession implements SessionRunner {
+  private readonly deps;
+  constructor(deps: {
+    spawn: ClaudeSpawn;
+  });
+  run(request: SessionRequest): Promise<SessionResult>;
+}
+
+//#endregion
+//#region src/git/snapshot.d.ts
+/**
+ * A silent restore point for the working tree, stored as a git commit object pinned by a private
+ * ref (`refs/tend/snapshot`) — nothing committed to any branch, the editor sees no change. Backs
+ * `tend undo` (exact restore) and `tend diff` (only the tool's edits). Reuses git's content store,
+ * so the on-disk record is a 40-char id rather than a copy of every file.
+ */
+declare class Snapshot {
+  private readonly cwd;
+  private readonly root;
+  private readonly sha;
+  private constructor();
+  static capture(git: SimpleGit, cwd: string): Promise<Snapshot>;
+  /** Serialize to a tiny object for `.tend/snapshot.json` (powers `undo` across invocations). */
+  toJSON(): {
+    cwd: string;
+    root: string;
+    sha: string;
+  };
+  static fromJSON(data: {
+    cwd: string;
+    root: string;
+    sha: string;
+  }): Snapshot;
+  /** Files whose contents differ from the snapshot, or that are new/deleted since it (sorted). */
+  changedSince(_git: SimpleGit): Promise<string[]>;
+  /** Restore a single file to its captured contents (worktree only — the user's index is untouched). */
+  restoreFile(rel: string): Promise<void>;
+  /** Restore the working tree exactly to the captured state (incl. deleting files created since). */
+  restore(_git: SimpleGit): Promise<void>;
+}
+
+//#endregion
+//#region src/git/repo.d.ts
+/** Refuse to run outside a git repo — the snapshot/restore safety net needs it. */
+declare function assertGitRepo(git: SimpleGit): Promise<void>;
+/**
+ * Files changed vs `HEAD`: tracked modifications/additions/renames plus untracked files,
+ * scoped and re-based to `git`'s working directory (so a run from `apps/foo` only sees
+ * `apps/foo`'s changes, pathed as the scanners path them).
+ */
+declare function changedVsHead(git: SimpleGit): Promise<string[]>;
+/**
+ * Concrete files under the given path(s) — tracked plus untracked (so newly-added files
+ * are scoped too, mirroring `changedVsHead`). `git ls-files` reports paths relative to
+ * `git`'s working directory and interprets the pathspecs the same way, so the result is
+ * already in the coordinate system the scanners and `filterToChanged` expect. Expanding to
+ * concrete files (not bare directories) matters: `filterToChanged` matches exact paths.
+ */
+
+/** Revert a single file to its snapshot state. */
+declare function revertFile(snapshot: Snapshot, file: string): Promise<void>;
+
+//#endregion
+//#region src/detect/package-manager.d.ts
+type PackageManager = "pnpm" | "yarn" | "bun" | "npm";
+/** Detect the package manager from the lockfile present; defaults to npm. */
+declare function detectPackageManager(cwd: string): PackageManager;
+
+//#endregion
+//#region src/config/config.d.ts
+declare const ConfigSchema: z.ZodObject<{
+  maxSessions: z.ZodDefault<z.ZodNumber>;
+  maxLoops: z.ZodDefault<z.ZodNumber>;
+  perIssueBudget: z.ZodDefault<z.ZodNumber>;
+  test: z.ZodOptional<z.ZodString>;
+  teethCheck: z.ZodDefault<z.ZodBoolean>;
+  includeTests: z.ZodDefault<z.ZodBoolean>;
+  /** Model passed to `claude -p` for fixes — an alias (sonnet/opus/haiku) or a full model id. */
+  model: z.ZodDefault<z.ZodString>;
+  /** Reasoning effort for fixes; unset → claude's own default. */
+  effort: z.ZodOptional<z.ZodEnum<["low", "medium", "high", "xhigh", "max"]>>;
+  tools: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    configPath: z.ZodOptional<z.ZodString>;
+  }, "strip", z.ZodTypeAny, {
+    enabled: boolean;
+    configPath?: string | undefined;
+  }, {
+    enabled?: boolean | undefined;
+    configPath?: string | undefined;
+  }>>>;
+}, "strip", z.ZodTypeAny, {
+  maxSessions: number;
+  maxLoops: number;
+  perIssueBudget: number;
+  teethCheck: boolean;
+  includeTests: boolean;
+  model: string;
+  tools: Record<string, {
+    enabled: boolean;
+    configPath?: string | undefined;
+  }>;
+  test?: string | undefined;
+  effort?: "low" | "medium" | "high" | "xhigh" | "max" | undefined;
+}, {
+  maxSessions?: number | undefined;
+  maxLoops?: number | undefined;
+  perIssueBudget?: number | undefined;
+  test?: string | undefined;
+  teethCheck?: boolean | undefined;
+  includeTests?: boolean | undefined;
+  model?: string | undefined;
+  effort?: "low" | "medium" | "high" | "xhigh" | "max" | undefined;
+  tools?: Record<string, {
+    enabled?: boolean | undefined;
+    configPath?: string | undefined;
+  }> | undefined;
+}>;
+type TendConfig = z.infer<typeof ConfigSchema>;
+/** CLI flags that can override config; only defined keys take effect. */
+type CliOverrides = Partial<Pick<TendConfig, "maxSessions" | "maxLoops" | "perIssueBudget" | "test" | "teethCheck" | "includeTests" | "model" | "effort">>;
+/**
+ * Load config via cosmiconfig (searching from `cwd`), validate with zod, and apply
+ * zero-config defaults when no file is found. Invalid config throws a clear message.
+ */
+declare function loadConfig(cwd: string): Promise<TendConfig>;
+/** Overlay CLI flags onto a loaded config (flags win). */
+declare function applyCliOverrides(config: TendConfig, overrides: CliOverrides): TendConfig;
+
+//#endregion
+//#region src/report/retry-id.d.ts
+type RetryIdGenerator = () => string;
+
+//#endregion
+//#region src/report/schema.d.ts
+/** Ensure every finding in a persisted report has a human-facing id unique to that report. */
+/** Per-scanner outcome for a run: did it run clean, get skipped, or fail (with a reason). */
+declare const ScannerStatusSchema: z.ZodObject<{
+  tool: z.ZodEnum<["sonarjs", "knip", "jscpd", "semgrep", "osv", "gitleaks"]>;
+  status: z.ZodEnum<["ran", "skipped", "failed"]>;
+  reason: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+  tool: "sonarjs" | "knip" | "jscpd" | "semgrep" | "osv" | "gitleaks";
+  status: "skipped" | "ran" | "failed";
+  reason?: string | undefined;
+}, {
+  tool: "sonarjs" | "knip" | "jscpd" | "semgrep" | "osv" | "gitleaks";
+  status: "skipped" | "ran" | "failed";
+  reason?: string | undefined;
+}>;
+declare const BehaviorChangeSchema: z.ZodObject<{
+  findingId: z.ZodString;
+  file: z.ZodString;
+  note: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+  file: string;
+  findingId: string;
+  note: string;
+}, {
+  file: string;
+  findingId: string;
+  note: string;
+}>;
+/**
+ * Estimated AI cost/usage for a run. `estimatedCostUsd` is Claude's client-side
+ * `total_cost_usd` estimate — never authoritative billing.
+ */
+declare const AiUsageSchema: z.ZodObject<{
+  estimatedCostUsd: z.ZodNumber;
+  inputTokens: z.ZodNumber;
+  outputTokens: z.ZodNumber;
+  cacheCreationInputTokens: z.ZodNumber;
+  cacheReadInputTokens: z.ZodNumber;
+  sessions: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+  estimatedCostUsd: number;
+  inputTokens: number;
+  outputTokens: number;
+  cacheCreationInputTokens: number;
+  cacheReadInputTokens: number;
+  sessions: number;
+}, {
+  estimatedCostUsd: number;
+  inputTokens: number;
+  outputTokens: number;
+  cacheCreationInputTokens: number;
+  cacheReadInputTokens: number;
+  sessions: number;
+}>;
+declare const ReportSchema: z.ZodObject<{
+  findings: z.ZodArray<z.ZodObject<{
+    id: z.ZodString;
+    retryId: z.ZodOptional<z.ZodString>;
+    tool: z.ZodEnum<["sonarjs", "knip", "jscpd", "semgrep", "osv", "gitleaks"]>;
+    rule: z.ZodString;
+    category: z.ZodEnum<["bug", "smell", "dead-code", "duplication", "security", "secret", "vuln-dep"]>;
+    severity: z.ZodEnum<["error", "warning", "info"]>;
+    file: z.ZodString;
+    range: z.ZodObject<{
+      startLine: z.ZodNumber;
+      startCol: z.ZodNumber;
+      endLine: z.ZodNumber;
+      endCol: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+      startLine: number;
+      startCol: number;
+      endLine: number;
+      endCol: number;
+    }, {
+      startLine: number;
+      startCol: number;
+      endLine: number;
+      endCol: number;
+    }>;
+    message: z.ZodString;
+    helpUri: z.ZodOptional<z.ZodString>;
+    flowPath: z.ZodOptional<z.ZodArray<z.ZodObject<{
+      file: z.ZodString;
+      line: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+      file: string;
+      line: number;
+    }, {
+      file: string;
+      line: number;
+    }>, "many">>;
+    remediation: z.ZodOptional<z.ZodString>;
+    track: z.ZodEnum<["ai-fix", "deterministic", "report-only"]>;
+    status: z.ZodEnum<["pending", "fixing", "fixed", "reverted", "unfixable", "skipped"]>;
+    attempts: z.ZodNumber;
+    revertReason: z.ZodOptional<z.ZodEnum<["broke-test", "suppression", "regression", "typecheck", "session-error"]>>;
+    firstSeenLoop: z.ZodNumber;
+    lastSeenLoop: z.ZodNumber;
+    inScope: z.ZodOptional<z.ZodBoolean>;
+  }, "strip", z.ZodTypeAny, {
+    id: string;
+    tool: "sonarjs" | "knip" | "jscpd" | "semgrep" | "osv" | "gitleaks";
+    status: "pending" | "fixing" | "fixed" | "reverted" | "unfixable" | "skipped";
+    message: string;
+    rule: string;
+    category: "bug" | "smell" | "dead-code" | "duplication" | "security" | "secret" | "vuln-dep";
+    severity: "error" | "warning" | "info";
+    file: string;
+    range: {
+      startLine: number;
+      startCol: number;
+      endLine: number;
+      endCol: number;
+    };
+    track: "ai-fix" | "deterministic" | "report-only";
+    attempts: number;
+    firstSeenLoop: number;
+    lastSeenLoop: number;
+    retryId?: string | undefined;
+    helpUri?: string | undefined;
+    flowPath?: {
+      file: string;
+      line: number;
+    }[] | undefined;
+    remediation?: string | undefined;
+    revertReason?: "broke-test" | "suppression" | "regression" | "typecheck" | "session-error" | undefined;
+    inScope?: boolean | undefined;
+  }, {
+    id: string;
+    tool: "sonarjs" | "knip" | "jscpd" | "semgrep" | "osv" | "gitleaks";
+    status: "pending" | "fixing" | "fixed" | "reverted" | "unfixable" | "skipped";
+    message: string;
+    rule: string;
+    category: "bug" | "smell" | "dead-code" | "duplication" | "security" | "secret" | "vuln-dep";
+    severity: "error" | "warning" | "info";
+    file: string;
+    range: {
+      startLine: number;
+      startCol: number;
+      endLine: number;
+      endCol: number;
+    };
+    track: "ai-fix" | "deterministic" | "report-only";
+    attempts: number;
+    firstSeenLoop: number;
+    lastSeenLoop: number;
+    retryId?: string | undefined;
+    helpUri?: string | undefined;
+    flowPath?: {
+      file: string;
+      line: number;
+    }[] | undefined;
+    remediation?: string | undefined;
+    revertReason?: "broke-test" | "suppression" | "regression" | "typecheck" | "session-error" | undefined;
+    inScope?: boolean | undefined;
+  }>, "many">;
+  secrets: z.ZodArray<z.ZodObject<{
+    id: z.ZodString;
+    retryId: z.ZodOptional<z.ZodString>;
+    tool: z.ZodEnum<["sonarjs", "knip", "jscpd", "semgrep", "osv", "gitleaks"]>;
+    rule: z.ZodString;
+    category: z.ZodEnum<["bug", "smell", "dead-code", "duplication", "security", "secret", "vuln-dep"]>;
+    severity: z.ZodEnum<["error", "warning", "info"]>;
+    file: z.ZodString;
+    range: z.ZodObject<{
+      startLine: z.ZodNumber;
+      startCol: z.ZodNumber;
+      endLine: z.ZodNumber;
+      endCol: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+      startLine: number;
+      startCol: number;
+      endLine: number;
+      endCol: number;
+    }, {
+      startLine: number;
+      startCol: number;
+      endLine: number;
+      endCol: number;
+    }>;
+    message: z.ZodString;
+    helpUri: z.ZodOptional<z.ZodString>;
+    flowPath: z.ZodOptional<z.ZodArray<z.ZodObject<{
+      file: z.ZodString;
+      line: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+      file: string;
+      line: number;
+    }, {
+      file: string;
+      line: number;
+    }>, "many">>;
+    remediation: z.ZodOptional<z.ZodString>;
+    track: z.ZodEnum<["ai-fix", "deterministic", "report-only"]>;
+    status: z.ZodEnum<["pending", "fixing", "fixed", "reverted", "unfixable", "skipped"]>;
+    attempts: z.ZodNumber;
+    revertReason: z.ZodOptional<z.ZodEnum<["broke-test", "suppression", "regression", "typecheck", "session-error"]>>;
+    firstSeenLoop: z.ZodNumber;
+    lastSeenLoop: z.ZodNumber;
+    inScope: z.ZodOptional<z.ZodBoolean>;
+  }, "strip", z.ZodTypeAny, {
+    id: string;
+    tool: "sonarjs" | "knip" | "jscpd" | "semgrep" | "osv" | "gitleaks";
+    status: "pending" | "fixing" | "fixed" | "reverted" | "unfixable" | "skipped";
+    message: string;
+    rule: string;
+    category: "bug" | "smell" | "dead-code" | "duplication" | "security" | "secret" | "vuln-dep";
+    severity: "error" | "warning" | "info";
+    file: string;
+    range: {
+      startLine: number;
+      startCol: number;
+      endLine: number;
+      endCol: number;
+    };
+    track: "ai-fix" | "deterministic" | "report-only";
+    attempts: number;
+    firstSeenLoop: number;
+    lastSeenLoop: number;
+    retryId?: string | undefined;
+    helpUri?: string | undefined;
+    flowPath?: {
+      file: string;
+      line: number;
+    }[] | undefined;
+    remediation?: string | undefined;
+    revertReason?: "broke-test" | "suppression" | "regression" | "typecheck" | "session-error" | undefined;
+    inScope?: boolean | undefined;
+  }, {
+    id: string;
+    tool: "sonarjs" | "knip" | "jscpd" | "semgrep" | "osv" | "gitleaks";
+    status: "pending" | "fixing" | "fixed" | "reverted" | "unfixable" | "skipped";
+    message: string;
+    rule: string;
+    category: "bug" | "smell" | "dead-code" | "duplication" | "security" | "secret" | "vuln-dep";
+    severity: "error" | "warning" | "info";
+    file: string;
+    range: {
+      startLine: number;
+      startCol: number;
+      endLine: number;
+      endCol: number;
+    };
+    track: "ai-fix" | "deterministic" | "report-only";
+    attempts: number;
+    firstSeenLoop: number;
+    lastSeenLoop: number;
+    retryId?: string | undefined;
+    helpUri?: string | undefined;
+    flowPath?: {
+      file: string;
+      line: number;
+    }[] | undefined;
+    remediation?: string | undefined;
+    revertReason?: "broke-test" | "suppression" | "regression" | "typecheck" | "session-error" | undefined;
+    inScope?: boolean | undefined;
+  }>, "many">;
+  depBumps: z.ZodArray<z.ZodObject<{
+    findingId: z.ZodString;
+    remediation: z.ZodString;
+  }, "strip", z.ZodTypeAny, {
+    remediation: string;
+    findingId: string;
+  }, {
+    remediation: string;
+    findingId: string;
+  }>, "many">;
+  flaggedBehaviorChanges: z.ZodArray<z.ZodObject<{
+    findingId: z.ZodString;
+    file: z.ZodString;
+    note: z.ZodString;
+  }, "strip", z.ZodTypeAny, {
+    file: string;
+    findingId: string;
+    note: string;
+  }, {
+    file: string;
+    findingId: string;
+    note: string;
+  }>, "many">;
+  scannerStatuses: z.ZodDefault<z.ZodArray<z.ZodObject<{
+    tool: z.ZodEnum<["sonarjs", "knip", "jscpd", "semgrep", "osv", "gitleaks"]>;
+    status: z.ZodEnum<["ran", "skipped", "failed"]>;
+    reason: z.ZodOptional<z.ZodString>;
+  }, "strip", z.ZodTypeAny, {
+    tool: "sonarjs" | "knip" | "jscpd" | "semgrep" | "osv" | "gitleaks";
+    status: "skipped" | "ran" | "failed";
+    reason?: string | undefined;
+  }, {
+    tool: "sonarjs" | "knip" | "jscpd" | "semgrep" | "osv" | "gitleaks";
+    status: "skipped" | "ran" | "failed";
+    reason?: string | undefined;
+  }>, "many">>;
+  aiUsage: z.ZodDefault<z.ZodObject<{
+    estimatedCostUsd: z.ZodNumber;
+    inputTokens: z.ZodNumber;
+    outputTokens: z.ZodNumber;
+    cacheCreationInputTokens: z.ZodNumber;
+    cacheReadInputTokens: z.ZodNumber;
+    sessions: z.ZodNumber;
+  }, "strip", z.ZodTypeAny, {
+    estimatedCostUsd: number;
+    inputTokens: number;
+    outputTokens: number;
+    cacheCreationInputTokens: number;
+    cacheReadInputTokens: number;
+    sessions: number;
+  }, {
+    estimatedCostUsd: number;
+    inputTokens: number;
+    outputTokens: number;
+    cacheCreationInputTokens: number;
+    cacheReadInputTokens: number;
+    sessions: number;
+  }>>;
+  loops: z.ZodNumber;
+  durationMs: z.ZodNumber;
+  exitStatus: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+  findings: {
+    id: string;
+    tool: "sonarjs" | "knip" | "jscpd" | "semgrep" | "osv" | "gitleaks";
+    status: "pending" | "fixing" | "fixed" | "reverted" | "unfixable" | "skipped";
+    message: string;
+    rule: string;
+    category: "bug" | "smell" | "dead-code" | "duplication" | "security" | "secret" | "vuln-dep";
+    severity: "error" | "warning" | "info";
+    file: string;
+    range: {
+      startLine: number;
+      startCol: number;
+      endLine: number;
+      endCol: number;
+    };
+    track: "ai-fix" | "deterministic" | "report-only";
+    attempts: number;
+    firstSeenLoop: number;
+    lastSeenLoop: number;
+    retryId?: string | undefined;
+    helpUri?: string | undefined;
+    flowPath?: {
+      file: string;
+      line: number;
+    }[] | undefined;
+    remediation?: string | undefined;
+    revertReason?: "broke-test" | "suppression" | "regression" | "typecheck" | "session-error" | undefined;
+    inScope?: boolean | undefined;
+  }[];
+  secrets: {
+    id: string;
+    tool: "sonarjs" | "knip" | "jscpd" | "semgrep" | "osv" | "gitleaks";
+    status: "pending" | "fixing" | "fixed" | "reverted" | "unfixable" | "skipped";
+    message: string;
+    rule: string;
+    category: "bug" | "smell" | "dead-code" | "duplication" | "security" | "secret" | "vuln-dep";
+    severity: "error" | "warning" | "info";
+    file: string;
+    range: {
+      startLine: number;
+      startCol: number;
+      endLine: number;
+      endCol: number;
+    };
+    track: "ai-fix" | "deterministic" | "report-only";
+    attempts: number;
+    firstSeenLoop: number;
+    lastSeenLoop: number;
+    retryId?: string | undefined;
+    helpUri?: string | undefined;
+    flowPath?: {
+      file: string;
+      line: number;
+    }[] | undefined;
+    remediation?: string | undefined;
+    revertReason?: "broke-test" | "suppression" | "regression" | "typecheck" | "session-error" | undefined;
+    inScope?: boolean | undefined;
+  }[];
+  depBumps: {
+    remediation: string;
+    findingId: string;
+  }[];
+  flaggedBehaviorChanges: {
+    file: string;
+    findingId: string;
+    note: string;
+  }[];
+  scannerStatuses: {
+    tool: "sonarjs" | "knip" | "jscpd" | "semgrep" | "osv" | "gitleaks";
+    status: "skipped" | "ran" | "failed";
+    reason?: string | undefined;
+  }[];
+  aiUsage: {
+    estimatedCostUsd: number;
+    inputTokens: number;
+    outputTokens: number;
+    cacheCreationInputTokens: number;
+    cacheReadInputTokens: number;
+    sessions: number;
+  };
+  loops: number;
+  durationMs: number;
+  exitStatus: number;
+}, {
+  findings: {
+    id: string;
+    tool: "sonarjs" | "knip" | "jscpd" | "semgrep" | "osv" | "gitleaks";
+    status: "pending" | "fixing" | "fixed" | "reverted" | "unfixable" | "skipped";
+    message: string;
+    rule: string;
+    category: "bug" | "smell" | "dead-code" | "duplication" | "security" | "secret" | "vuln-dep";
+    severity: "error" | "warning" | "info";
+    file: string;
+    range: {
+      startLine: number;
+      startCol: number;
+      endLine: number;
+      endCol: number;
+    };
+    track: "ai-fix" | "deterministic" | "report-only";
+    attempts: number;
+    firstSeenLoop: number;
+    lastSeenLoop: number;
+    retryId?: string | undefined;
+    helpUri?: string | undefined;
+    flowPath?: {
+      file: string;
+      line: number;
+    }[] | undefined;
+    remediation?: string | undefined;
+    revertReason?: "broke-test" | "suppression" | "regression" | "typecheck" | "session-error" | undefined;
+    inScope?: boolean | undefined;
+  }[];
+  secrets: {
+    id: string;
+    tool: "sonarjs" | "knip" | "jscpd" | "semgrep" | "osv" | "gitleaks";
+    status: "pending" | "fixing" | "fixed" | "reverted" | "unfixable" | "skipped";
+    message: string;
+    rule: string;
+    category: "bug" | "smell" | "dead-code" | "duplication" | "security" | "secret" | "vuln-dep";
+    severity: "error" | "warning" | "info";
+    file: string;
+    range: {
+      startLine: number;
+      startCol: number;
+      endLine: number;
+      endCol: number;
+    };
+    track: "ai-fix" | "deterministic" | "report-only";
+    attempts: number;
+    firstSeenLoop: number;
+    lastSeenLoop: number;
+    retryId?: string | undefined;
+    helpUri?: string | undefined;
+    flowPath?: {
+      file: string;
+      line: number;
+    }[] | undefined;
+    remediation?: string | undefined;
+    revertReason?: "broke-test" | "suppression" | "regression" | "typecheck" | "session-error" | undefined;
+    inScope?: boolean | undefined;
+  }[];
+  depBumps: {
+    remediation: string;
+    findingId: string;
+  }[];
+  flaggedBehaviorChanges: {
+    file: string;
+    findingId: string;
+    note: string;
+  }[];
+  loops: number;
+  durationMs: number;
+  exitStatus: number;
+  scannerStatuses?: {
+    tool: "sonarjs" | "knip" | "jscpd" | "semgrep" | "osv" | "gitleaks";
+    status: "skipped" | "ran" | "failed";
+    reason?: string | undefined;
+  }[] | undefined;
+  aiUsage?: {
+    estimatedCostUsd: number;
+    inputTokens: number;
+    outputTokens: number;
+    cacheCreationInputTokens: number;
+    cacheReadInputTokens: number;
+    sessions: number;
+  } | undefined;
+}>;
+type Report = z.infer<typeof ReportSchema>;
+type BehaviorChange = z.infer<typeof BehaviorChangeSchema>;
+type ScannerStatus = z.infer<typeof ScannerStatusSchema>;
+type AiUsage$1 = z.infer<typeof AiUsageSchema>;
+
+//#endregion
+//#region src/report/builder.d.ts
+/** Accumulates per-finding outcomes and run metadata into a validated report.json. */
+declare class ReportBuilder {
+  private readonly generateRetryId?;
+  private readonly outcomes;
+  private readonly flagged;
+  private scannerStatuses;
+  constructor(generateRetryId?: RetryIdGenerator | undefined);
+  /** Record (or update) a finding's final outcome by fingerprint. */
+  recordOutcome(finding: Finding): void;
+  recordOutcomes(findings: Finding[]): void;
+  /** Flag a semantic test change for human review. */
+  flagBehaviorChange(entry: BehaviorChange): void;
+  /** Record per-scanner run outcomes (ran / skipped / failed) for the scanner-status line. */
+  recordScannerStatuses(statuses: ScannerStatus[]): void;
+  build(meta: {
+    loops: number;
+    durationMs: number;
+    exitStatus: number;
+    aiUsage?: AiUsage$1;
+  }): Report;
+}
+
+//#endregion
+//#region src/output/events.d.ts
+/** What happened to a file's fix attempt. "left" = in scope but never dispatched. */
+type FileOutcome = "fixed" | "reverted" | "left";
+type TendEvent = {
+  type: "snapshot";
+} | {
+  type: "detected";
+  packageManager: string;
+  typescript: boolean;
+  testRunner?: string;
+} | {
+  type: "scan-start";
+  loop: number;
+} | {
+  type: "audit";
+  loop: number;
+  findings: number;
+  files: number;
+  scanned?: number;
+} | {
+  type: "loop-start";
+  loop: number;
+  files: string[];
+  concurrency: number;
+} | {
+  type: "file-start";
+  loop: number;
+  file: string;
+  rule?: string;
+} | {
+  type: "file-result";
+  loop: number;
+  file: string;
+  outcome: FileOutcome;
+  reason?: string;
+} | {
+  type: "loop-complete";
+  loop: number;
+  fixed: number;
+} | {
+  type: "done";
+  exitStatus: number;
+};
+type Listener = (event: TendEvent) => void;
+/** Minimal synchronous event bus. With no listener, emit is a no-op (silent mode). */
+declare class EventBus {
+  private readonly listeners;
+  on(listener: Listener): () => void;
+  emit(event: TendEvent): void;
+}
+
+//#endregion
+//#region src/output/theme.d.ts
+/**
+ * The visual language. Restraint is the point: one accent color used for ~2 things (the
+ * wordmark + the active spinner), muted semantic colors for outcomes, everything else
+ * achromatic. Hierarchy comes from indentation + dim metadata, not from color.
+ */
+type Theme = {
+  /** The single accent — wordmark + active spinner only. */
+  accent: Style;
+  /** Soft green — a fix that landed. */
+  fixed: Style;
+  /** Soft amber — a fix that was reverted. */
+  reverted: Style;
+  /** Soft red — an error / something that needs the human. */
+  error: Style;
+  /** Dim grey — metadata, queued, rules, hints. */
+  dim: Style;
+  bold: Style;
+  plain: Style;
+  /** The "t e n d" wordmark: a subtle gradient when truecolor is available, else flat. */
+  wordmark: () => string;
+  glyph: Glyphs;
+};
+type Style = (s: string) => string;
+type Glyphs = {
+  fixed: string;
+  reverted: string;
+  left: string;
+  scanned: string;
+  bullet: string;
+  rule: string;
+  arrow: string;
+  spinner: string[];
+};
+
+//#endregion
+//#region src/output/summary.d.ts
+type SummaryOptions = {
+  theme?: Theme;
+  verbose?: boolean;
+  plain?: boolean;
+};
+/**
+ * The final summary: a real headline (fixed / couldn't-fix / left / secrets + elapsed),
+ * grouped by what the user must do, with revert reasons surfaced per file, and ending in
+ * next-step affordances. Brief by default; `--verbose` adds the full per-finding listing.
+ */
+declare function renderSummary(report: Report, opts?: SummaryOptions): string;
+type RemainingKey = "secrets" | "security" | "couldnt-fix" | "review";
+type RemainingGroup = {
+  key: RemainingKey;
+  title: string;
+  count: number;
+};
+/**
+ * Group the issues that still need a human, ordered by urgency:
+ * secrets → security → couldn't-fix → needs-review. Empty groups are omitted.
+ */
+declare function groupRemaining(report: Report): RemainingGroup[];
+
+//#endregion
+//#region src/orchestrator.d.ts
+type AuditResult = {
+  findings: Finding[];
+  allScannersMissing?: boolean;
+  scanned?: number;
+  scannerStatuses?: ScannerStatus$1[];
+};
+type FixOutcome = {
+  kept: boolean;
+  reason?: RevertReason;
+  usage?: AiUsage;
+};
+type OrchestrateDeps = {
+  /** Run the scanners for a loop and return normalized findings. */
+  audit: (loop: number) => Promise<AuditResult>;
+  /** Fix one work unit (session + gate); returns whether the fix was kept. */
+  fixUnit: (unit: WorkUnit, loop: number) => Promise<FixOutcome>;
+  config: {
+    maxLoops: number;
+    perIssueBudget: number;
+    maxSessions: number;
+    includeTests?: boolean;
+  };
+  /** Restrict findings to the fix scope (changed files); defaults to all. */
+  inScope?: (findings: Finding[]) => Finding[];
+  bus?: EventBus;
+};
+type Termination = "converged" | "max-loops" | "no-progress" | "no-scanners";
+type OrchestrateResult = {
+  termination: Termination;
+  loops: number;
+  exitStatus: number;
+  findings: Finding[];
+  secrets: Finding[];
+  depBumps: Finding[];
+  scannerStatuses: ScannerStatus$1[];
+  /** Estimated AI cost/usage summed across every fix attempt (including reverted ones). */
+  usage: AiUsage;
+};
+/**
+ * The scan → fix → re-audit loop. Terminates on the first of: converged (0 fixable),
+ * no-progress (no dispatchable units or an attempted loop changed no attempt/status
+ * state), per-issue budget exhaustion (mark unfixable, keep going), or max-loops.
+ */
+declare function orchestrate(deps: OrchestrateDeps): Promise<OrchestrateResult>;
+
+//#endregion
+//#region src/cli.d.ts
+type CliHandlers = {
+  run: (opts: {
+    paths?: string[];
+    all?: boolean;
+    maxLoops?: number;
+    maxSessions?: number;
+    model?: string;
+    effort?: string;
+    includeTests?: boolean;
+    plain?: boolean;
+    color?: boolean;
+    verbose?: boolean;
+  }) => Promise<void> | void;
+  diff: () => Promise<void> | void;
+  undo: () => Promise<void> | void;
+  show: (id: string) => Promise<void> | void;
+  retry: (id: string) => Promise<void> | void;
+};
+/** Build the commander program wiring each subcommand to a handler. */
+declare function buildProgram(handlers: CliHandlers): Command;
+
+//#endregion
+//#region src/commands/run.d.ts
+type RunDeps = OrchestrateDeps & {
+  now?: () => number;
+};
+/** `tend run` — wire audit → fix loop → report. */
+declare function runCommand(deps: RunDeps): Promise<{
+  report: Report;
+  exitStatus: number;
+}>;
+
+//#endregion
+//#region src/commands/diff.d.ts
+/** `tend diff` — the files the tool edited (snapshot vs now), the dev's own changes filtered out. */
+declare function diffCommand(deps: {
+  snapshot: Snapshot;
+  git: SimpleGit;
+}): Promise<string[]>;
+
+//#endregion
+//#region src/commands/undo.d.ts
+/** `tend undo` — restore the pre-run snapshot exactly. */
+declare function undoCommand(deps: {
+  snapshot: Snapshot;
+  git: SimpleGit;
+}): Promise<void>;
+
+//#endregion
+//#region src/commands/show.d.ts
+/** `tend show <id>` — full detail on one finding: attempts, revert reason, taint flow path. */
+declare function showCommand(id: string, findings: Finding[]): string;
+
+//#endregion
+//#region src/commands/retry.d.ts
+type RetryDeps = {
+  report?: Report;
+  findings?: Finding[];
+  baseBudget: number;
+  /** Re-run the fix for a finding with the given (larger) attempt budget. */
+  runFix: (finding: Finding, budget: number) => Promise<FixOutcome>;
+};
+type RetryResult = {
+  outcome: "fixed";
+  finding: Finding;
+  budget: number;
+} | {
+  outcome: "reverted";
+  finding: Finding;
+  budget: number;
+  reason: RevertReason;
+} | {
+  error: string;
+};
+/** `tend retry <id>` — re-attempt a stubborn finding with a larger attempt budget. */
+declare function retryCommand(id: string, deps: RetryDeps): Promise<RetryResult>;
+
+//#endregion
+export { AiUsage, AuditResult, ChangeSet, Check, ClaudeSession, CliHandlers, ConfigSchema, EventBus, FileEdit, Finding, FindingSchema, FindingStore, FixOutcome, GateOutcome, OrchestrateDeps, OrchestrateResult, PackageManager, RawFinding, Report, ReportBuilder, ReportSchema, RetryDeps, RetryResult, RouteResult, RunDeps, ScanContext, ScanResult, Scanner, SessionRequest, SessionResult, SessionRunner, Snapshot, Spawn, TendConfig, TendEvent, Termination, Tool, Track, Which, WorkUnit, addUsage, applyCliOverrides, assertGitRepo, buildProgram, changedFiles, changedVsHead, detectPackageManager, diffCommand, dispatch, filterToChanged, fingerprint, groupRemaining, isAvailable, loadConfig, normalize, orchestrate, planWork, renderSummary, retryCommand, revertFile, route, runCommand, runGate, runScanner, scopeFindings, showCommand, trackForTool, undoCommand, zeroUsage };