@usefragments/core 1.0.0

package/src/config-paths.ts

@@ -0,0 +1,47 @@
+import type { FragmentsConfig, TokenConfig } from "./types.js";
+
+const WINDOWS_DRIVE_RE = /^[a-zA-Z]:[\\/]/;
+
+export function normalizeConfigPath(path: string): string {
+  return path.trim().replace(/^\.\//, "").replace(/\/+$/, "") || ".";
+}
+
+export function portableRepoPathError(path: string): string | null {
+  const normalized = path.trim();
+  if (!normalized) return "Path must not be empty";
+  if (normalized.startsWith("/")) return "Path must be repo-relative, not absolute";
+  if (WINDOWS_DRIVE_RE.test(normalized)) {
+    return "Path must be repo-relative, not absolute";
+  }
+  if (normalized.startsWith("~")) return "Path must not use a home directory shortcut";
+  if (normalized.includes("\\")) return "Path must use POSIX / separators";
+
+  const parts = normalized.split("/");
+  if (parts.some((part) => part === "..")) {
+    return "Path must not contain .. segments";
+  }
+  if (parts.some((part) => part.length === 0)) {
+    return "Path must not contain empty segments";
+  }
+
+  return null;
+}
+
+export function isPortableRepoPath(path: string): boolean {
+  return portableRepoPathError(path) === null;
+}
+
+export function resolveConfiguredAppPath(config: Pick<FragmentsConfig, "app">): string {
+  return normalizeConfigPath(config.app?.path ?? ".");
+}
+
+export function topologyBase(config: Pick<FragmentsConfig, "topology">): "app" | "repo" {
+  return config.topology?.base ?? "app";
+}
+
+export function tokenIncludesFromConfig(tokens: TokenConfig): string[] {
+  if (tokens.sources?.length) {
+    return tokens.sources.map((source) => source.path);
+  }
+  return tokens.include ?? [];
+}

package/src/config.ts

@@ -0,0 +1,18 @@
+import { fragmentsConfigSchema } from "./schema.js";
+import type { FragmentsConfig } from "./types.js";
+import { normalizeGovernanceConfig } from "./governance.js";
+
+function formatZodErrors(errors: Array<{ path: (string | number)[]; message: string }>) {
+  return errors.map((error) => `  - ${error.path.join(".")}: ${error.message}`).join("\n");
+}
+
+export function defineConfig<TConfig extends FragmentsConfig>(config: TConfig): TConfig {
+  const normalized = normalizeGovernanceConfig(config);
+  const result = fragmentsConfigSchema.safeParse(normalized);
+
+  if (!result.success) {
+    throw new Error(`Invalid fragments config:\n${formatZodErrors(result.error.errors)}`);
+  }
+
+  return result.data as TConfig;
+}

package/src/conform-prove.test.ts

@@ -0,0 +1,274 @@
+import { describe, expect, it } from "vitest";
+import { sha256Hex } from "./contract/hash.js";
+import type { ConformInput, ConformResult } from "./conform.js";
+import {
+  PROVE_DEFAULT_MAX_PASSES,
+  PROVE_MAX_PASSES,
+  type ProveSamplerArgs,
+  clampMaxPasses,
+  emptyConformResult,
+  proveCompliant,
+  proveIssueCount,
+  resolveProveVerdict,
+} from "./conform-prove.js";
+
+// ── conform stubs ─────────────────────────────────────────────────────────
+
+function clean(code: string): ConformResult {
+  return {
+    conformed: code,
+    changed: false,
+    summary: "clean",
+    changes: [],
+    suggestions: [],
+    unresolved: [],
+  };
+}
+
+const oneChange: ConformResult["changes"] = [
+  {
+    kind: "replace-token",
+    ruleId: "styles/no-raw-color",
+    code: "FUI6001",
+    severity: "warning",
+    message: "Replaced hardcoded color.",
+    before: "#2563eb",
+    after: "var(--brand-600)",
+    confidence: "high",
+  },
+];
+
+const oneSuggestion: ConformResult["suggestions"] = [
+  { kind: "review-low-confidence", message: "Ambiguous variant.", confidence: "medium" },
+];
+
+/** Replaces a raw color once, then is clean — the canonical 2-pass convergence. */
+function tokenizing(input: ConformInput): ConformResult {
+  if (input.code.includes("#2563eb")) {
+    return {
+      conformed: input.code.replace("#2563eb", "var(--brand-600)"),
+      changed: true,
+      summary: "Mapped one hardcoded value.",
+      changes: oneChange,
+      suggestions: [],
+      unresolved: [],
+    };
+  }
+  return clean(input.code);
+}
+
+/** Always stalls (no deterministic change) with one residual suggestion. */
+function residual(input: ConformInput): ConformResult {
+  return {
+    conformed: input.code,
+    changed: false,
+    summary: "Needs review.",
+    changes: [],
+    suggestions: oneSuggestion,
+    unresolved: [],
+  };
+}
+
+describe("proveCompliant — pure validate-fix-validate primitive", () => {
+  it("loops deterministic fixes until a clean pass proves compliance", async () => {
+    const out = await proveCompliant(
+      { code: '<div style={{ color: "#2563eb" }}>Send</div>' },
+      { conform: tokenizing }
+    );
+    expect(out.verdict).toBe("pass");
+    expect(out.provedCompliant).toBe(true);
+    expect(out.issueCount).toBe(0);
+    expect(out.corrections).toBe(1);
+    expect(out.changed).toBe(true);
+    expect(out.conformed).toContain("var(--brand-600)");
+    expect(out.passHistory.map((p) => ({ pass: p.pass, issues: p.issues }))).toEqual([
+      { pass: 1, issues: 1 },
+      { pass: 2, issues: 0 },
+    ]);
+    expect(out.reason).toBe("0 findings after 2 passes.");
+  });
+
+  it("certifies a clean-on-first-pass result with no coverage signal", async () => {
+    const out = await proveCompliant({ code: "<div>hi</div>" }, { conform: (i) => clean(i.code) });
+    expect(out).toMatchObject({ verdict: "pass", provedCompliant: true, issueCount: 0 });
+    expect(out.passHistory).toHaveLength(1);
+    expect(out.reason).toBe("0 findings after 1 pass.");
+    expect(out.changed).toBe(false);
+  });
+
+  it("returns insufficient_coverage (NOT pass) for a clean run over an empty catalog", async () => {
+    const out = await proveCompliant(
+      { code: "<div>hi</div>" },
+      {
+        conform: (i) => ({
+          ...clean(i.code),
+          coverage: { tokens: 0, components: 0, evaluated: false },
+        }),
+      }
+    );
+    expect(out.verdict).toBe("insufficient_coverage");
+    expect(out.provedCompliant).toBe(false);
+    expect(out.issueCount).toBe(0);
+    expect(out.reason).toContain("could not be evaluated");
+  });
+
+  it("fails with residual findings when no sampler is provided", async () => {
+    const out = await proveCompliant({ code: "<x />" }, { conform: residual });
+    expect(out.verdict).toBe("fail");
+    expect(out.issueCount).toBe(1);
+    expect(out.reason).toBe("no sampler was available and residual issues remain.");
+    expect(out.residual.suggestions).toHaveLength(1);
+  });
+
+  it("does not sample when allowSampling is false", async () => {
+    let sampled = false;
+    const out = await proveCompliant(
+      { code: "<x />" },
+      {
+        conform: residual,
+        sampler: () => {
+          sampled = true;
+          return null;
+        },
+      },
+      { allowSampling: false }
+    );
+    expect(sampled).toBe(false);
+    expect(out.verdict).toBe("fail");
+    expect(out.reason).toBe("sampling was disabled and residual issues remain.");
+  });
+
+  it("uses the sampler for residual issues and re-validates the sampled code", async () => {
+    const out = await proveCompliant(
+      { code: "<button><Icon /></button>" },
+      {
+        conform: (i) => (i.code.includes("aria-label") ? clean(i.code) : residual(i)),
+        sampler: () => ({
+          code: '<button aria-label="Close"><Icon /></button>',
+          model: "test-model",
+        }),
+      }
+    );
+    expect(out.verdict).toBe("pass");
+    expect(out.conformed).toBe('<button aria-label="Close"><Icon /></button>');
+    expect(out.passHistory[0]?.sampling).toMatchObject({
+      requested: true,
+      used: true,
+      model: "test-model",
+    });
+    expect(out.passHistory).toHaveLength(2);
+  });
+
+  it("does NOT accept a sampled fix that still has residual findings", async () => {
+    const out = await proveCompliant(
+      { code: "<button><Icon /></button>" },
+      {
+        // Sampler returns a different-but-still-broken snippet; conform never
+        // reaches clean, so the loop must not certify compliance.
+        conform: (i) => residual(i),
+        sampler: ({ code }) => ({ code: `${code}\n{/* attempt */}` }),
+      },
+      { maxPasses: 3 }
+    );
+    expect(out.verdict).toBe("fail");
+    expect(out.provedCompliant).toBe(false);
+    expect(out.issueCount).toBe(1);
+  });
+
+  it("counts a declining sampler (null) as used:false and fails", async () => {
+    const out = await proveCompliant({ code: "<x />" }, { conform: residual, sampler: () => null });
+    expect(out.verdict).toBe("fail");
+    expect(out.passHistory[0]?.sampling).toMatchObject({ requested: true, used: false });
+  });
+
+  it("threads (pass, seq, codeHashAtRequest) into the sampler across rounds", async () => {
+    const seen: ProveSamplerArgs["metadata"][] = [];
+    const codesSampled: string[] = [];
+    await proveCompliant(
+      { code: "ROUND0" },
+      {
+        conform: (i) => residual(i), // always stalls -> sampler invoked each round
+        sampler: ({ code, metadata }) => {
+          seen.push(metadata);
+          codesSampled.push(code);
+          return { code: `ROUND${metadata.seq + 1}` }; // always a fresh snippet
+        },
+      },
+      { maxPasses: 4 }
+    );
+    // maxPasses 4 -> sampler fires at seq 0,1,2 (cap is samplingAttempts < maxPasses-1)
+    expect(seen.map((m) => m.seq)).toEqual([0, 1, 2]);
+    expect(seen.map((m) => m.pass)).toEqual([1, 2, 3]);
+    // codeHashAtRequest is the real SHA-256 of the code the sampler saw.
+    expect(seen.map((m) => m.codeHashAtRequest)).toEqual(codesSampled.map((c) => sha256Hex(c)));
+    expect(seen[0]?.codeHashAtRequest).toBe(sha256Hex("ROUND0"));
+    expect(seen[1]?.codeHashAtRequest).toBe(sha256Hex("ROUND1"));
+  });
+
+  it("stops at maxPasses when deterministic fixes keep producing findings", async () => {
+    let calls = 0;
+    const out = await proveCompliant(
+      { code: "raw" },
+      {
+        conform: (i) => {
+          calls += 1;
+          return {
+            conformed: `${i.code}\n/* ${calls} */`,
+            changed: true,
+            summary: "still dirty",
+            changes: oneChange,
+            suggestions: [],
+            unresolved: [],
+          };
+        },
+      },
+      { maxPasses: 2 }
+    );
+    expect(calls).toBe(2);
+    expect(out.verdict).toBe("fail");
+    expect(out.passHistory).toHaveLength(2);
+    expect(out.corrections).toBe(2);
+    expect(out.reason).toBe("stopped after 2 passes with 1 finding(s).");
+  });
+
+  it("is deterministic — identical inputs produce identical results", async () => {
+    const run = () =>
+      proveCompliant(
+        { code: '<div style={{ color: "#2563eb" }}>Send</div>' },
+        { conform: tokenizing }
+      );
+    expect(await run()).toEqual(await run());
+  });
+});
+
+describe("prove primitive helpers", () => {
+  it("proveIssueCount sums changes + suggestions + unresolved", () => {
+    expect(proveIssueCount(clean("x"))).toBe(0);
+    expect(proveIssueCount(residual({ code: "x" }))).toBe(1);
+  });
+
+  it("emptyConformResult is a neutral, unchanged result", () => {
+    const r = emptyConformResult("abc");
+    expect(r).toMatchObject({ conformed: "abc", changed: false });
+    expect(proveIssueCount(r)).toBe(0);
+  });
+
+  it("resolveProveVerdict: coverage trumps everything", () => {
+    expect(resolveProveVerdict({ coverageEvaluated: false, provedCompliant: true })).toBe(
+      "insufficient_coverage"
+    );
+    expect(resolveProveVerdict({ coverageEvaluated: true, provedCompliant: true })).toBe("pass");
+    expect(resolveProveVerdict({ coverageEvaluated: true, provedCompliant: false })).toBe("fail");
+  });
+
+  it("clampMaxPasses clamps to 1..8 and defaults non-numbers to 4", () => {
+    expect(clampMaxPasses(0)).toBe(1);
+    expect(clampMaxPasses(1)).toBe(1);
+    expect(clampMaxPasses(4)).toBe(PROVE_DEFAULT_MAX_PASSES);
+    expect(clampMaxPasses(8)).toBe(PROVE_MAX_PASSES);
+    expect(clampMaxPasses(99)).toBe(PROVE_MAX_PASSES);
+    expect(clampMaxPasses(3.7)).toBe(3);
+    expect(clampMaxPasses(undefined)).toBe(PROVE_DEFAULT_MAX_PASSES);
+    expect(clampMaxPasses(Number.NaN)).toBe(PROVE_DEFAULT_MAX_PASSES);
+  });
+});

package/src/conform-prove.ts

@@ -0,0 +1,326 @@
+/**
+ * Contract Mode — Phase 2: the prove-compliant loop as a PURE primitive.
+ *
+ * A validate-fix-validate loop over UI code: run the conform engine, apply its
+ * deterministic fixes, and re-validate until the engine proves zero findings,
+ * the pass budget is exhausted, or progress stalls. When deterministic fixes
+ * stall on residual issues, an optional async `sampler` repairs them (model
+ * call), and the loop re-validates the result — a sampled fix is never trusted
+ * without a clean re-validation pass.
+ *
+ * This is the engine behind `contract.prove` (architecture §2 move #4). It is
+ * deliberately framework-agnostic: it takes a `conform` callback (so Cloud,
+ * CLI, and the standalone MCP each inject their own engine binding) and returns
+ * a plain result — no MCP plumbing, no task store, no transport coupling.
+ *
+ * Determinism (architecture §6.3): the sampler receives `(seq, codeHashAtRequest)`
+ * so a durable-replay layer can key recorded sampler output on the exact code it
+ * was asked to repair, and hard-invalidate on a hash mismatch — instead of the
+ * pass-index-only key the standalone MCP tool uses.
+ *
+ * Browser-safe: depends only on the conform contract types + the pure SHA-256
+ * in this package. No Node APIs.
+ */
+import type {
+  ConformInput,
+  ConformResult,
+  ConformSuggestion,
+  ConformUnresolved,
+} from "./conform.js";
+import { sha256Hex } from "./contract/hash.js";
+
+/** Upper bound on validate/fix passes. */
+export const PROVE_MAX_PASSES = 8;
+/** Default validate/fix passes when the caller does not specify. */
+export const PROVE_DEFAULT_MAX_PASSES = 4;
+
+/**
+ * 3-valued verdict. `insufficient_coverage` is NOT a pass: a clean run over an
+ * empty catalog (no tokens, no component mappings) proves nothing, so the loop
+ * never certifies compliance it could not actually evaluate.
+ */
+export type ProveVerdict = "pass" | "fail" | "insufficient_coverage";
+
+export interface ProvePassSampling {
+  requested?: boolean;
+  used?: boolean;
+  model?: string;
+  stopReason?: string;
+  reason?: string;
+}
+
+export interface ProvePass {
+  pass: number;
+  issues: number;
+  deterministicChanges: number;
+  suggestions: number;
+  unresolved: number;
+  changed: boolean;
+  sampling?: ProvePassSampling;
+}
+
+export interface ProveResidual {
+  suggestions: ConformSuggestion[];
+  unresolved: ConformUnresolved[];
+}
+
+export interface ProveSample {
+  /** Repaired code, or omitted/empty when the sampler declined. */
+  code?: string;
+  model?: string;
+  stopReason?: string;
+  reason?: string;
+}
+
+export interface ProveSamplerArgs {
+  /** The current code the sampler is asked to repair. */
+  code: string;
+  /** The residual findings deterministic fixes could not resolve. */
+  residual: ProveResidual;
+  metadata: {
+    /** 1-indexed validate/fix pass that stalled. */
+    pass: number;
+    /** 0-indexed sampler attempt counter (independent of `pass`). */
+    seq: number;
+    /** SHA-256 of `code` — the durable-replay key + hard-invalidation guard. */
+    codeHashAtRequest: string;
+  };
+}
+
+export interface ProveCallbacks {
+  /** Validate + apply deterministic fixes for one pass. */
+  conform(input: ConformInput): Promise<ConformResult> | ConformResult;
+  /** Optional model-backed repair for residual issues conform cannot resolve. */
+  sampler?(args: ProveSamplerArgs): Promise<ProveSample | null> | ProveSample | null;
+}
+
+export interface ProveOptions {
+  /** Max validate/fix passes (clamped to 1..8). Defaults to 4. */
+  maxPasses?: number;
+  /** Allow the sampler to repair residual issues. Defaults to true. */
+  allowSampling?: boolean;
+}
+
+export interface ProveLoopResult {
+  /** Code after all passes + sampling. */
+  conformed: string;
+  /** Whether `conformed` differs from the input code. */
+  changed: boolean;
+  verdict: ProveVerdict;
+  /** True only on a clean, evaluated pass. */
+  provedCompliant: boolean;
+  /** Findings remaining in the final pass (changes + suggestions + unresolved). */
+  issueCount: number;
+  /** Total deterministic edits applied across all passes. */
+  corrections: number;
+  passHistory: ProvePass[];
+  residual: ProveResidual;
+  /** The final conform result (for receipt / summary rendering). */
+  result: ConformResult;
+  /** Human-readable reason for the verdict. */
+  reason: string;
+}
+
+/** Total findings in a conform result: applied changes + suggestions + unresolved. */
+export function proveIssueCount(result: ConformResult): number {
+  return result.changes.length + result.suggestions.length + result.unresolved.length;
+}
+
+/** A neutral conform result for the "no result produced" fallback path. */
+export function emptyConformResult(code: string): ConformResult {
+  return {
+    conformed: code,
+    changed: false,
+    summary: "No conform result was produced.",
+    changes: [],
+    suggestions: [],
+    unresolved: [],
+  };
+}
+
+/**
+ * Resolve the 3-valued verdict. Coverage trumps everything: an unevaluated
+ * catalog is `insufficient_coverage` regardless of issue count.
+ */
+export function resolveProveVerdict(args: {
+  coverageEvaluated: boolean;
+  provedCompliant: boolean;
+}): ProveVerdict {
+  if (!args.coverageEvaluated) return "insufficient_coverage";
+  return args.provedCompliant ? "pass" : "fail";
+}
+
+/** Clamp a requested pass count into the supported 1..8 range (default 4). */
+export function clampMaxPasses(value: number | undefined): number {
+  if (typeof value !== "number" || Number.isNaN(value)) {
+    return PROVE_DEFAULT_MAX_PASSES;
+  }
+  return Math.min(PROVE_MAX_PASSES, Math.max(1, Math.trunc(value)));
+}
+
+function incompleteReason(args: {
+  passCount: number;
+  maxPasses: number;
+  finalIssues: number;
+  allowSampling: boolean;
+  hasSampler: boolean;
+}): string {
+  if (args.passCount >= args.maxPasses) {
+    return `stopped after ${args.maxPasses} passes with ${args.finalIssues} finding(s).`;
+  }
+  if (!args.allowSampling) {
+    return "sampling was disabled and residual issues remain.";
+  }
+  if (!args.hasSampler) {
+    return "no sampler was available and residual issues remain.";
+  }
+  return `${args.finalIssues} residual finding(s) remain after deterministic and sampled fixes.`;
+}
+
+/**
+ * Run the validate-fix-validate loop. Pure: never mutates `input`; all state
+ * flows through the return value.
+ */
+export async function proveCompliant(
+  input: ConformInput,
+  callbacks: ProveCallbacks,
+  options: ProveOptions = {}
+): Promise<ProveLoopResult> {
+  const maxPasses = clampMaxPasses(options.maxPasses);
+  const allowSampling = options.allowSampling !== false;
+  const { filename } = input;
+  const hasSampler = typeof callbacks.sampler === "function";
+
+  let current = input.code;
+  const passHistory: ProvePass[] = [];
+  let corrections = 0;
+  let samplingAttempts = 0;
+  let lastResult: ConformResult | null = null;
+
+  while (passHistory.length < maxPasses) {
+    const pass = passHistory.length + 1;
+    const result = await callbacks.conform({
+      code: current,
+      filename,
+      apply: "deterministic",
+    });
+    lastResult = result;
+
+    const issues = proveIssueCount(result);
+    passHistory.push({
+      pass,
+      issues,
+      deterministicChanges: result.changes.length,
+      suggestions: result.suggestions.length,
+      unresolved: result.unresolved.length,
+      changed: result.changed,
+    });
+    corrections += result.changes.length;
+
+    if (issues === 0) {
+      const coverageEvaluated = result.coverage?.evaluated !== false;
+      return {
+        conformed: current,
+        changed: current !== input.code,
+        verdict: resolveProveVerdict({
+          coverageEvaluated,
+          provedCompliant: coverageEvaluated,
+        }),
+        provedCompliant: coverageEvaluated,
+        issueCount: 0,
+        corrections,
+        passHistory,
+        residual: { suggestions: [], unresolved: [] },
+        result,
+        reason: coverageEvaluated
+          ? `0 findings after ${pass} pass${pass === 1 ? "" : "es"}.`
+          : "the design-system catalog has no tokens or components, so compliance could not be evaluated.",
+      };
+    }
+
+    // Deterministic progress — keep looping on the rewritten code.
+    if (result.changed && result.conformed !== current) {
+      current = result.conformed;
+      continue;
+    }
+
+    // Conform stalled with residual issues. Try the sampler if it is available
+    // and we are under the attempt cap (kept strictly below maxPasses so a
+    // revalidation pass always remains in budget).
+    //
+    // Sampling semantics (intentional, and DIFFERENT from the standalone MCP
+    // tool): the loop re-samples only while the sampler keeps producing *new*
+    // code (each fresh snippet is re-validated on the next pass); a sample that
+    // returns nothing new — null, no `code`, or byte-identical code — ends the
+    // loop. Re-asking the model with the identical residual rarely helps and
+    // burns tokens. The MCP tool instead retries up to its cap on each stall
+    // (its suspend/resume transport makes per-stall retry the natural shape);
+    // both are bounded by maxPasses. See docs/contract-mode/01-architecture.md.
+    const residual: ProveResidual = {
+      suggestions: result.suggestions,
+      unresolved: result.unresolved,
+    };
+    const canSample =
+      allowSampling &&
+      hasSampler &&
+      samplingAttempts < maxPasses - 1 &&
+      (residual.suggestions.length > 0 || residual.unresolved.length > 0);
+
+    if (canSample) {
+      const seq = samplingAttempts;
+      const codeHashAtRequest = sha256Hex(current);
+      const last = passHistory[passHistory.length - 1];
+      if (last) last.sampling = { requested: true };
+
+      const sampled = await callbacks.sampler!({
+        code: current,
+        residual,
+        metadata: { pass, seq, codeHashAtRequest },
+      });
+      samplingAttempts += 1;
+
+      if (last) {
+        last.sampling = {
+          ...(last.sampling ?? {}),
+          used: Boolean(sampled?.code),
+          model: sampled?.model,
+          stopReason: sampled?.stopReason,
+          reason: sampled?.reason,
+        };
+      }
+
+      if (sampled?.code && sampled.code !== current) {
+        current = sampled.code;
+        continue;
+      }
+    }
+
+    break;
+  }
+
+  const fallback = lastResult ?? emptyConformResult(current);
+  const finalIssues = proveIssueCount(fallback);
+  const coverageEvaluated = fallback.coverage?.evaluated !== false;
+
+  return {
+    conformed: current,
+    changed: current !== input.code,
+    verdict: resolveProveVerdict({ coverageEvaluated, provedCompliant: false }),
+    provedCompliant: false,
+    issueCount: finalIssues,
+    corrections,
+    passHistory,
+    residual: {
+      suggestions: fallback.suggestions,
+      unresolved: fallback.unresolved,
+    },
+    result: fallback,
+    reason: incompleteReason({
+      passCount: passHistory.length,
+      maxPasses,
+      finalIssues,
+      allowSampling,
+      hasSampler,
+    }),
+  };
+}