tokenclinic 0.1.1

package/src/record/health.ts

@@ -0,0 +1,44 @@
+import { mkdirSync, writeFileSync, appendFileSync } from "node:fs";
+import { join } from "node:path";
+import type { Finding, EOB } from "../types";
+import type { DepProfile } from "../detect/deps";
+
+// The Codebase Health Record: a .tokenclinic/ directory written into the scanned
+// repo. v1 persists the dep profile and an append-only run history. v2 adds
+// rules/ (promoted generated checks + fixtures), quarantine/, and routing.json
+// (learned per-class model routing). Every run reads it back, so every run gets
+// cheaper and smarter — this is the compounding asset, not the router.
+
+export function writeHealthRecord(
+  root: string,
+  deps: DepProfile,
+  findings: Finding[],
+  eob: EOB,
+  now: string,
+): string {
+  const dir = join(root, ".tokenclinic");
+  mkdirSync(dir, { recursive: true });
+
+  writeFileSync(
+    join(dir, "profile.json"),
+    JSON.stringify(
+      { updated: now, manager: deps.manager, deps: deps.deps, analyzers: ["tsc"] },
+      null,
+      2,
+    ),
+  );
+
+  const entry = {
+    at: now,
+    findings: findings.length,
+    fixedLocally: eob.fixedLocally,
+    escalated: eob.escalated,
+    spend: eob.spend,
+    naiveCost: eob.naiveCost,
+    saved: eob.saved,
+    estimated: eob.estimated,
+  };
+  appendFileSync(join(dir, "history.jsonl"), `${JSON.stringify(entry)}\n`);
+
+  return dir;
+}

package/src/scan.ts

@@ -0,0 +1,95 @@
+import type { Finding, EOB } from "./types";
+import { detectDeps, type DepProfile } from "./detect/deps";
+import { triage } from "./triage";
+import { partition } from "./diagnose/partition";
+import { buildContext } from "./diagnose/context";
+import { DryRunFixer } from "./treat/fixer";
+import { buildEOB } from "./bill/eob";
+
+// The read-only scan, assembled once and rendered two ways: a human EOB (CLI) or
+// a machine report (--json, for a host agent). No model is called here — this is
+// the advisory core that runs identically standalone or inside a harness.
+
+export interface ScanData {
+  deps: DepProfile;
+  findings: Finding[];
+  eob: EOB;
+}
+
+export async function assembleScan(root: string): Promise<ScanData> {
+  const deps = detectDeps(root);
+  const findings = partition(triage(root));
+
+  const fixer = new DryRunFixer();
+  for (const f of findings) {
+    if (f.fixability !== "needs-llm") continue;
+    f.context = buildContext(root, f); // the tight packet the host agent fixes from
+    f.resolution = (await fixer.fix(f)).resolution; // routed model = the recommendation
+  }
+
+  return { deps, findings, eob: buildEOB(root, findings, true) };
+}
+
+// --- machine report (the in-harness integration contract) ---
+
+type Lane = "local" | "model" | "ignore";
+
+export interface ScanReport {
+  version: string;
+  root: string;
+  prices: string;
+  deps: { manager: string; count: number };
+  eob: EOB;
+  findings: Array<{
+    id: string;
+    source: string;
+    rule: string;
+    severity: string;
+    message: string;
+    file: string;
+    line: number;
+    col: number;
+    lane: Lane;
+    difficulty?: string;
+    recommendedModel?: string;
+    context?: { snippet: string; startLine: number };
+  }>;
+  // What a host agent should do: apply the local lane cheaply; fix the escalate
+  // list with its OWN model, using each finding's context — don't crawl the repo.
+  advice: {
+    autoApply: string[];
+    escalate: Array<{ id: string; file: string; line: number; recommendedModel?: string }>;
+  };
+}
+
+const laneOf = (f: Finding): Lane => (f.fixability === "autofix" ? "local" : f.fixability === "ignore" ? "ignore" : "model");
+
+export function toReport(root: string, prices: string, { deps, findings, eob }: ScanData): ScanReport {
+  return {
+    version: "0.1",
+    root,
+    prices,
+    deps: { manager: deps.manager, count: Object.keys(deps.deps).length },
+    eob,
+    findings: findings.map((f) => ({
+      id: f.id,
+      source: f.source,
+      rule: f.rule,
+      severity: f.severity,
+      message: f.message,
+      file: f.file,
+      line: f.line,
+      col: f.col,
+      lane: laneOf(f),
+      difficulty: f.difficulty,
+      recommendedModel: f.resolution?.model,
+      context: f.context ? { snippet: f.context.snippet, startLine: f.context.startLine } : undefined,
+    })),
+    advice: {
+      autoApply: findings.filter((f) => f.fixability === "autofix").map((f) => f.id),
+      escalate: findings
+        .filter((f) => f.fixability === "needs-llm")
+        .map((f) => ({ id: f.id, file: f.file, line: f.line, recommendedModel: f.resolution?.model })),
+    },
+  };
+}

package/src/treat/anthropic.ts

@@ -0,0 +1,85 @@
+import Anthropic from "@anthropic-ai/sdk";
+import type { Finding } from "../types";
+import { cost } from "../pricing/table";
+import { routeModel } from "./route";
+import type { Fixer, FixResult } from "./fixer";
+
+// Live fixer: sends the tight context packet to the routed model, gets back a
+// corrected snippet via structured output, and reports the EXACT token cost from
+// the API's usage. Used by `scan --apply`. The apply loop (in cli.ts) writes the
+// patch and verifies by re-running the source analyzer — a fix is not done until
+// the finding is gone.
+//
+// Reads ANTHROPIC_API_KEY from the environment (standard SDK credential resolution).
+
+const SYSTEM =
+  "You are a precise code-fixing assistant. You are given a single compiler/linter " +
+  "error and the source lines around it. Return a corrected version of EXACTLY those " +
+  "lines that resolves the error, changing as little as possible. Preserve indentation " +
+  "and surrounding lines verbatim; only change what the error requires.";
+
+// Structured-output schema — constrains the model to return the replacement
+// snippet as data, so the apply step never parses prose.
+const SCHEMA = {
+  type: "object",
+  properties: {
+    fixedSnippet: { type: "string", description: "the corrected replacement for the provided lines" },
+    explanation: { type: "string", description: "one sentence on what changed" },
+  },
+  required: ["fixedSnippet", "explanation"],
+  additionalProperties: false,
+};
+
+export class AnthropicFixer implements Fixer {
+  private client: Anthropic;
+
+  constructor() {
+    this.client = new Anthropic();
+  }
+
+  async fix(finding: Finding): Promise<FixResult> {
+    const model = routeModel(finding.difficulty);
+    const snippet = finding.context?.snippet ?? "";
+    const startLine = finding.context?.startLine ?? finding.line;
+
+    const user =
+      `Error ${finding.rule} at ${finding.file}:${finding.line} — ${finding.message}\n\n` +
+      `The lines below start at line ${startLine}. Return a corrected replacement for them.\n` +
+      "```\n" +
+      snippet +
+      "\n```";
+
+    const res = await this.client.messages.create({
+      model,
+      max_tokens: 2000,
+      system: SYSTEM,
+      messages: [{ role: "user", content: user }],
+      output_config: { format: { type: "json_schema", schema: SCHEMA } },
+    });
+
+    const text = res.content.find((b) => b.type === "text")?.text ?? "{}";
+    let fixedSnippet = snippet;
+    try {
+      const parsed = JSON.parse(text) as { fixedSnippet?: string };
+      if (typeof parsed.fixedSnippet === "string") fixedSnippet = parsed.fixedSnippet;
+    } catch {
+      // model returned non-JSON despite the schema — leave the snippet unchanged
+    }
+
+    const tokensIn = res.usage.input_tokens;
+    const tokensOut = res.usage.output_tokens;
+
+    return {
+      resolution: {
+        model,
+        tokensIn,
+        tokensOut,
+        cost: cost(model, tokensIn, tokensOut), // exact, from real usage
+        patched: false,
+        verified: false,
+        patch: fixedSnippet,
+      },
+      newSnippet: fixedSnippet,
+    };
+  }
+}

package/src/treat/apply.ts

@@ -0,0 +1,74 @@
+import { readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import type { Finding } from "../types";
+import type { Fixer } from "./fixer";
+import { triage } from "../triage";
+import { partition } from "../diagnose/partition";
+import { buildContext } from "../diagnose/context";
+
+// The live apply loop, decoupled from the CLI and the concrete fixer so it can be
+// driven by a fake fixer in tests (no API key required).
+//
+// Each pass re-triages from scratch, so line shifts introduced by earlier edits
+// are handled automatically. Hardening:
+//   - a finding is attempted at most once (by id) → bounded by maxPasses
+//   - a no-op patch (unchanged snippet) is skipped, never written
+//   - a patch that increases the total finding count is reverted (don't let a
+//     "fix" leave the repo worse than it found it)
+//   - verified = the finding is gone on the next triage
+
+export interface ApplyResult {
+  before: Finding[]; // initial snapshot, for the EOB's autofix/ignore buckets
+  fixed: Finding[]; // findings the loop escalated, each carrying its resolution
+}
+
+export async function runApplyLoop(root: string, fixer: Fixer, maxPasses = 25): Promise<ApplyResult> {
+  const before = partition(triage(root));
+  const attempted = new Set<string>();
+  const fixed: Finding[] = [];
+
+  for (let pass = 0; pass < maxPasses; pass++) {
+    const current = partition(triage(root));
+    const totalBefore = current.length;
+    const target = current.find((f) => f.fixability === "needs-llm" && !attempted.has(f.id));
+    if (!target) break;
+    attempted.add(target.id);
+
+    target.context = buildContext(root, target);
+    const { resolution, newSnippet } = await fixer.fix(target);
+    target.resolution = resolution;
+    fixed.push(target);
+
+    // No-op patch — nothing to write.
+    if (newSnippet === undefined || newSnippet === target.context?.snippet) {
+      resolution.patched = false;
+      resolution.verified = false;
+      continue;
+    }
+
+    const path = join(root, target.file);
+    const original = readFileSync(path, "utf8");
+    writeSnippet(path, target, newSnippet);
+
+    const after = partition(triage(root));
+    if (after.length > totalBefore) {
+      // The patch introduced more problems than it solved — revert.
+      writeFileSync(path, original);
+      resolution.patched = false;
+      resolution.verified = false;
+    } else {
+      resolution.patched = true;
+      resolution.verified = !after.some((f) => f.id === target.id);
+    }
+  }
+
+  return { before, fixed };
+}
+
+function writeSnippet(path: string, f: Finding, newSnippet: string) {
+  const lines = readFileSync(path, "utf8").split("\n");
+  const start = (f.context?.startLine ?? f.line) - 1;
+  const oldCount = (f.context?.snippet ?? "").split("\n").length;
+  lines.splice(start, oldCount, ...newSnippet.split("\n"));
+  writeFileSync(path, lines.join("\n"));
+}

package/src/treat/fixer.ts

@@ -0,0 +1,38 @@
+import type { Finding, Resolution } from "../types";
+import { cost, estimateTokens } from "../pricing/table";
+import { routeModel } from "./route";
+
+// The seam where a fix is actually performed. Treat routes each escalated
+// finding through a Fixer.
+export interface FixResult {
+  resolution: Resolution;
+  newSnippet?: string; // present only when the fix can be applied to the file
+}
+
+export interface Fixer {
+  fix(finding: Finding): Promise<FixResult>;
+}
+
+// Estimating fixer: computes the cost of an escalation from real measured token
+// counts of the real context packet, but does NOT call a model or mutate files.
+// Used by `scan` (the default, read-only path). Every number it produces is
+// honest about being an estimate; the EOB is flagged `estimated`.
+const ASSUMED_OUTPUT_TOKENS = 200; // a typical small patch
+
+export class DryRunFixer implements Fixer {
+  async fix(finding: Finding): Promise<FixResult> {
+    const model = routeModel(finding.difficulty);
+    const tokensIn = (finding.context?.tokensEstimate ?? 0) + estimateTokens(finding.message);
+    const tokensOut = ASSUMED_OUTPUT_TOKENS;
+    return {
+      resolution: {
+        model,
+        tokensIn,
+        tokensOut,
+        cost: cost(model, tokensIn, tokensOut),
+        patched: false,
+        verified: false,
+      },
+    };
+  }
+}

package/src/treat/route.ts

@@ -0,0 +1,39 @@
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import type { DifficultyClass } from "../types";
+
+// Model routing: map a fix's difficulty class to the cheapest model that clears
+// the bar. Declarative and provider-agnostic — the defaults are Anthropic, but a
+// repo can override per class with ANY model id (including OpenRouter-style
+// `openai/…` / `google/…`) via .tokenclinic/routing.json. Pricing resolves
+// whatever id is configured through llm-intel, so other providers work for the
+// cost/EOB/audit layers without touching this file.
+
+const DEFAULT: Record<DifficultyClass, string> = {
+  mechanical: "claude-haiku-4-5",
+  semantic: "claude-sonnet-4-6",
+  architectural: "claude-opus-4-8",
+};
+
+let routing: Record<DifficultyClass, string> = { ...DEFAULT };
+
+export function loadRouting(root: string): void {
+  routing = { ...DEFAULT };
+  const path = join(root, ".tokenclinic", "routing.json");
+  if (!existsSync(path)) return;
+  try {
+    const cfg = JSON.parse(readFileSync(path, "utf8")) as Partial<Record<DifficultyClass, string>>;
+    routing = { ...DEFAULT, ...cfg };
+  } catch {
+    /* malformed config — keep defaults */
+  }
+}
+
+export function routeModel(difficulty: DifficultyClass = "semantic"): string {
+  return routing[difficulty] ?? DEFAULT[difficulty];
+}
+
+// The distinct model ids routing can target — used to warm the price book.
+export function routedModels(): string[] {
+  return [...new Set(Object.values(routing))];
+}

package/src/triage/analyzers/astgrep.ts

@@ -0,0 +1,74 @@
+import { readdirSync, readFileSync, existsSync, statSync } from "node:fs";
+import { join, relative } from "node:path";
+import type { Finding, GeneratedRule } from "../../types";
+import { hash } from "../../util";
+import { runRule } from "../../amortize/sg";
+
+// The payoff side of amortization: load the repo's promoted rules and run them
+// on-device. Every match is a $0 finding the model never has to see again.
+
+const EXT_BY_LANG: Record<string, string[]> = {
+  TypeScript: [".ts"],
+  Tsx: [".tsx"],
+  JavaScript: [".js", ".mjs", ".cjs"],
+};
+const SKIP_DIRS = new Set(["node_modules", ".git", ".tokenclinic", "dist", "build"]);
+
+export function runAstGrep(root: string): Finding[] {
+  const rulesDir = join(root, ".tokenclinic", "rules");
+  if (!existsSync(rulesDir)) return [];
+
+  const rules: GeneratedRule[] = [];
+  for (const f of readdirSync(rulesDir)) {
+    if (!f.endsWith(".json")) continue;
+    try {
+      rules.push(JSON.parse(readFileSync(join(rulesDir, f), "utf8")) as GeneratedRule);
+    } catch {
+      /* skip a corrupt rule file */
+    }
+  }
+  if (rules.length === 0) return [];
+
+  const wantedExts = new Set(rules.flatMap((r) => EXT_BY_LANG[r.language] ?? []));
+  const findings: Finding[] = [];
+
+  for (const file of walk(root)) {
+    if (![...wantedExts].some((e) => file.endsWith(e))) continue;
+    const code = readFileSync(file, "utf8");
+    const rel = relative(root, file);
+
+    for (const rule of rules) {
+      if (!(EXT_BY_LANG[rule.language] ?? []).some((e) => file.endsWith(e))) continue;
+      let matches;
+      try {
+        matches = runRule(rule.language, code, rule.rule);
+      } catch {
+        continue; // a promoted rule that somehow no longer parses — skip, don't crash a scan
+      }
+      for (const m of matches) {
+        findings.push({
+          id: hash("ast-grep", rule.id, rel, m.line, m.col),
+          source: `ast-grep:${rule.id}`,
+          rule: rule.id,
+          severity: rule.severity,
+          message: rule.message,
+          file: rel,
+          line: m.line,
+          col: m.col,
+          fixability: "autofix", // a promoted rule is, by definition, a $0 on-device check
+        });
+      }
+    }
+  }
+
+  return findings;
+}
+
+function* walk(dir: string): Generator<string> {
+  for (const entry of readdirSync(dir)) {
+    if (SKIP_DIRS.has(entry)) continue;
+    const p = join(dir, entry);
+    if (statSync(p).isDirectory()) yield* walk(p);
+    else yield p;
+  }
+}

package/src/triage/analyzers/tsc.ts

@@ -0,0 +1,49 @@
+import { spawnSync } from "node:child_process";
+import { createRequire } from "node:module";
+import type { Finding } from "../../types";
+import { hash } from "../../util";
+
+const require = createRequire(import.meta.url);
+
+// tsc --pretty false emits one diagnostic per line:
+//   src/index.ts(3,7): error TS2322: Type 'number' is not assignable to type 'string'.
+const LINE_RE = /^(.+?)\((\d+),(\d+)\): (error|warning) (TS\d+): (.+)$/;
+
+// Run the project's type checker and normalize its output into Findings.
+// We resolve tsc from tokenclinic's own node_modules and point it at the target
+// via cwd, so the scanned repo doesn't need typescript installed itself.
+export function runTsc(root: string): Finding[] {
+  let tscBin: string;
+  try {
+    tscBin = require.resolve("typescript/bin/tsc");
+  } catch {
+    return []; // typescript not installed in tokenclinic — skip this analyzer
+  }
+
+  const res = spawnSync(process.execPath, [tscBin, "--noEmit", "--pretty", "false"], {
+    cwd: root,
+    encoding: "utf8",
+  });
+
+  const out = `${res.stdout ?? ""}${res.stderr ?? ""}`;
+  const findings: Finding[] = [];
+
+  for (const raw of out.split("\n")) {
+    const m = LINE_RE.exec(raw.trim());
+    if (!m) continue; // continuation/elaboration lines are skipped in v1
+    const [, file, line, col, sev, rule, message] = m;
+    findings.push({
+      id: hash("tsc", rule, file, line, col),
+      source: "tsc",
+      rule,
+      severity: sev === "error" ? "error" : "warning",
+      message,
+      file,
+      line: Number(line),
+      col: Number(col),
+      fixability: "needs-llm", // refined in Diagnose/partition
+    });
+  }
+
+  return findings;
+}

package/src/triage/index.ts

@@ -0,0 +1,20 @@
+import type { Finding } from "../types";
+import { runTsc } from "./analyzers/tsc";
+import { runAstGrep } from "./analyzers/astgrep";
+
+// Triage: run every applicable on-device analyzer, normalize their output into a
+// single Finding[], and rank by signal (errors before warnings).
+//
+// Each analyzer is a (root) => Finding[] function. runTsc is the native type
+// checker; runAstGrep runs the repo's promoted (amortized) rules on-device — the
+// $0 lane that grows as recurring classes get synthesized into local checks.
+const ANALYZERS: Array<(root: string) => Finding[]> = [runTsc, runAstGrep];
+
+const SEVERITY_RANK: Record<string, number> = { error: 0, warning: 1, info: 2 };
+
+export function triage(root: string): Finding[] {
+  const findings = ANALYZERS.flatMap((run) => run(root));
+  return findings.sort(
+    (a, b) => (SEVERITY_RANK[a.severity] ?? 9) - (SEVERITY_RANK[b.severity] ?? 9),
+  );
+}

package/src/types.ts

@@ -0,0 +1,114 @@
+// The single record that flows through every stage of the clinic loop.
+// Triage creates Findings; Diagnose enriches them; Treat resolves them; Bill sums them.
+
+export type Severity = "error" | "warning" | "info";
+
+// How a finding can be resolved:
+//   autofix   - deterministically fixable on-device, $0, no model
+//   needs-llm - requires a model; escalated with a tight context packet
+//   ignore    - informational, not worth a fix
+export type Fixability = "autofix" | "needs-llm" | "ignore";
+
+// Difficulty class -> drives model routing in Treat.
+export type DifficultyClass = "mechanical" | "semantic" | "architectural";
+
+export interface Finding {
+  id: string; // stable hash of (source, rule, file, line) so it dedupes across runs
+  source: string; // "tsc" | "eslint" | "ast-grep:<rule>" | ...
+  rule: string; // e.g. "TS2322"
+  severity: Severity;
+  message: string;
+  file: string; // relative to scan root
+  line: number;
+  col: number;
+  fixability: Fixability;
+  difficulty?: DifficultyClass;
+  context?: ContextPacket; // assembled only when escalated
+  resolution?: Resolution; // filled by Treat
+}
+
+// The tight, pre-assembled packet handed to the model instead of the whole repo.
+export interface ContextPacket {
+  snippet: string;
+  startLine: number;
+  tokensEstimate: number;
+}
+
+export interface Resolution {
+  model: string; // "local" | model id
+  tokensIn: number;
+  tokensOut: number;
+  cost: number; // USD
+  patched: boolean;
+  verified: boolean; // a fix is not "done" until its source check passes again
+  patch?: string; // the corrected snippet that replaces the finding's context lines
+}
+
+// --- Audit (Approach A: the retroactive audit over existing call logs) ---
+
+// Two-bucket economics (Premise 5):
+//   eliminable - reducible to a deterministic rule; could have cost $0 on-device
+//   routable   - real work, but resolvable on a cheaper model (not eliminable)
+//   essential  - genuine reasoning; left untouched
+export type Bucket = "eliminable" | "routable" | "essential";
+
+// One past LLM call, read from a team's logs / agent traces. `category` is the
+// instrumented/concierge signal — when present it's authoritative; otherwise the
+// call is bucketed heuristically from `task` text (and the result flagged estimated).
+export interface CallRecord {
+  model: string;
+  inputTokens: number;
+  outputTokens: number;
+  task?: string;
+  category?: string;
+}
+
+export interface AuditResult {
+  calls: number;
+  spend: number; // real USD, from tokens × price
+  byBucket: Record<Bucket, { count: number; spend: number }>;
+  eliminableFraction: number; // share of spend in the eliminable bucket — the bet
+  projectedSpend: number; // eliminable→$0, routable→re-priced to cheapest tier, essential→unchanged
+  projectedSaved: number;
+  estimated: boolean; // true if any call was bucketed heuristically (no category)
+  unpriced: number; // calls whose model had no known price (excluded from cost)
+}
+
+// --- Amortization (v2): synthesize a deterministic check from a recurring class ---
+
+// A generated check, stored as DATA not code: an ast-grep rule object plus the
+// fixtures that gate its promotion. Lives in .tokenclinic/rules/<id>.json once it
+// passes validation, or .tokenclinic/quarantine/ if it doesn't.
+export interface GeneratedRule {
+  id: string; // kebab-case; also the filename
+  language: string; // an ast-grep Lang key, e.g. "TypeScript"
+  message: string;
+  severity: Severity;
+  rule: Record<string, unknown>; // the ast-grep rule object, e.g. { pattern: "..." }
+  fix?: string; // optional ast-grep fix template (informational in v2)
+  origin?: string; // the analyzer rule this was amortized from, e.g. "TS2304"
+  fixtures: {
+    positive: string[]; // code the rule MUST flag
+    negative: string[]; // similar code the rule must NOT flag
+  };
+}
+
+// A group of recurring needs-llm findings of the same shape — the trigger for synthesis.
+export interface Cluster {
+  rule: string; // the source rule code shared by the group
+  message: string;
+  findings: Finding[];
+}
+
+// Explanation Of Benefits — the screenshot-able receipt.
+export interface EOB {
+  total: number;
+  fixedLocally: number;
+  escalated: number;
+  ignored: number;
+  spend: number; // USD actually (or, in v1, would-be) spent by the clinic loop
+  naiveCost: number; // USD estimate for the naive "dump the file at a top model" approach
+  saved: number; // naiveCost - spend
+  byModel: Record<string, { count: number; cost: number }>;
+  estimated: boolean; // true while the LLM step is simulated (no key wired)
+}