@usefragments/core 1.5.0 → 1.5.2

package/src/rules/tokens-upstream-drift.test.ts

@@ -0,0 +1,111 @@
+import { describe, expect, it } from "vitest";
+import {
+  FactIndex,
+  makeStyleDeclarationFact,
+  makeStyleRawColorForbiddenFact,
+  makeTokenDefinitionFact,
+} from "../facts/index.js";
+import { ruleStylesNoRawColor } from "./styles-no-raw-color.js";
+import { ruleTokensUpstreamDrift } from "./tokens-upstream-drift.js";
+
+function token(input: {
+  name: string;
+  value: string;
+  role: "local" | "upstream";
+  file: string;
+  upstreamName?: string;
+}) {
+  return makeTokenDefinitionFact({
+    name: input.name,
+    value: input.value,
+    category: "color",
+    role: input.role,
+    authority: input.role === "local" ? "authored" : "declared-package",
+    sourceIdentity: input.file,
+    upstreamName: input.upstreamName,
+    location: { file: input.file, line: 1, column: 1 },
+  });
+}
+
+describe("tokens/upstream-drift", () => {
+  it("retains same-name authorities and emits one stable mismatch", () => {
+    const ix = new FactIndex();
+    const local = token({ name: "--brand", value: "#111111", role: "local", file: "tokens.css" });
+    const upstream = token({
+      name: "--brand",
+      value: "#222222",
+      role: "upstream",
+      file: "@fixture/ui/fragments.json",
+    });
+    ix.addMany([local, upstream]);
+
+    expect(ix.tokens.list()).toHaveLength(2);
+    expect(ruleTokensUpstreamDrift(ix)).toEqual([
+      expect.objectContaining({
+        code: "FUI2017",
+        ruleId: "tokens/upstream-drift",
+        location: expect.objectContaining({ file: "tokens.css" }),
+      }),
+    ]);
+  });
+
+  it("accepts matching values and compares differing names only through an authored alias", () => {
+    const ix = new FactIndex();
+    ix.addMany([
+      token({
+        name: "--local-brand",
+        value: "#222222",
+        role: "local",
+        file: "tokens.css",
+        upstreamName: "--upstream-brand",
+      }),
+      token({
+        name: "--upstream-brand",
+        value: "#222222",
+        role: "upstream",
+        file: "@fixture/ui/fragments.json",
+      }),
+    ]);
+
+    expect(ruleTokensUpstreamDrift(ix)).toEqual([]);
+  });
+
+  it("does not index upstream tokens as local raw-value replacement candidates", () => {
+    const ix = new FactIndex();
+    ix.add(
+      token({
+        name: "--upstream-brand",
+        value: "#222222",
+        role: "upstream",
+        file: "@fixture/ui/fragments.json",
+      })
+    );
+    expect(ix.tokens.definitionForSymbol("--upstream-brand")).toBeUndefined();
+  });
+
+  it("does not recommend a known-drift local token for an upstream-correct raw value", () => {
+    const ix = new FactIndex();
+    ix.addMany([
+      makeStyleRawColorForbiddenFact({ except: [], prefer: "token", severity: "error" }),
+      makeStyleDeclarationFact({
+        file: "Card.css",
+        selector: ".card",
+        declarationPath: "0",
+        property: "color",
+        value: "#222222",
+        location: { file: "Card.css", line: 1, column: 1 },
+      }),
+      token({ name: "--brand", value: "#111111", role: "local", file: "tokens.css" }),
+      token({
+        name: "--brand",
+        value: "#222222",
+        role: "upstream",
+        file: "@fixture/ui/fragments.json",
+      }),
+    ]);
+
+    const [finding] = ruleStylesNoRawColor(ix);
+    expect(finding.attributes?.suggestedToken).toBeUndefined();
+    expect(finding.fix).toBeUndefined();
+  });
+});

package/src/rules/tokens-upstream-drift.ts

@@ -0,0 +1,57 @@
+import type { FactIndex, TokenDefinitionFact } from "../facts/index.js";
+import { makeFinding } from "./finding.js";
+import { normalizedTokenValue } from "./token-candidates.js";
+import type { Finding } from "./types.js";
+
+export const RULE_ID = "tokens/upstream-drift";
+export const RULE_VERSION = "1";
+
+/** Compare only authored same-name or explicit-alias local/upstream pairs. */
+export function ruleTokensUpstreamDrift(ix: FactIndex): Finding[] {
+  const local = ix.tokens.list().filter((token) => token.role !== "upstream");
+  const upstream = ix.tokens.list().filter((token) => token.role === "upstream");
+  const upstreamByName = new Map<string, TokenDefinitionFact[]>();
+  for (const token of upstream) {
+    const matches = upstreamByName.get(token.name) ?? [];
+    matches.push(token);
+    upstreamByName.set(token.name, matches);
+  }
+
+  const findings: Finding[] = [];
+  for (const token of local) {
+    const upstreamName = token.upstreamName ?? token.name;
+    const matches = (upstreamByName.get(upstreamName) ?? []).sort((a, b) =>
+      (a.sourceIdentity ?? "").localeCompare(b.sourceIdentity ?? "")
+    );
+    if (matches.length !== 1) continue;
+    const expected = matches[0];
+    if (normalizedTokenValue(token) === normalizedTokenValue(expected)) continue;
+    const location = token.location ?? {
+      file: token.sourceIdentity ?? "tokens",
+      line: 1,
+      column: 1,
+    };
+    findings.push(
+      makeFinding({
+        ruleId: RULE_ID,
+        ruleVersion: RULE_VERSION,
+        severity: "warn",
+        message: `Local token ${token.name} is ${token.value}, but upstream ${upstreamName} is ${expected.value}.`,
+        location,
+        evidence: ix.evidence([token.id, expected.id]),
+        fingerprintIdentity: {
+          local: token.name,
+          upstream: upstreamName,
+          localSource: token.sourceIdentity,
+          upstreamSource: expected.sourceIdentity,
+        },
+        attributes: {
+          local: { name: token.name, value: token.value, location: token.location },
+          upstream: { name: expected.name, value: expected.value, location: expected.location },
+          autoFix: false,
+        },
+      })
+    );
+  }
+  return findings;
+}

package/src/rules/utils.ts

@@ -622,29 +622,37 @@ export function isExemptColor(value: string, except: readonly string[]): boolean
 }
 
 /**
- * Render a token name as the reference an author would write: SCSS `$vars`
- * pass through, dotted/bare names become a `var(--…)` custom property. Shared by
- * the color and spacing rules so a "use the token" fix is expressed the same way
- * everywhere.
+ * Render a token using only its proven authored reference form. Non-applicable
+ * formats retain their source spelling for an advisory suggestion; they never
+ * get rewritten into an invented CSS custom property.
  */
-export function tokenReference(name: string): string {
-  if (name.startsWith("$")) return name;
-  const cssVarName = name.startsWith("--") ? name : `--${name.replace(/\./g, "-")}`;
-  return `var(${cssVarName})`;
+export function tokenReference(token: TokenDefinitionFact): string {
+  if (token.referenceFormat === "css-var") {
+    const cssVarName = [token.name, ...(token.sourceNames ?? [])].find((name) =>
+      name.startsWith("--")
+    );
+    return cssVarName ? `var(${cssVarName})` : token.name;
+  }
+  if (token.referenceFormat === "scss-var") {
+    return (
+      [token.name, ...(token.sourceNames ?? [])].find((name) => name.startsWith("$")) ??
+      (token.name.startsWith("--") ? `$${token.name.slice(2)}` : token.name)
+    );
+  }
+  return token.sourceNames?.[0] ?? token.name;
 }
 
 /**
  * Whether a token reference can be *applied* automatically (written verbatim
  * and still compile). A `css-var` / `scss-var` token resolves on its own; a
  * `scss-map` member (synthetic `$colors-primary` minted from a Sass map) or a
- * `dtcg` JSON token (no CSS custom property emitted by default) does not, so
- * those fixes are surfaced as suggestions rather than deterministic rewrites.
- * Tokens without a known format (legacy/hand-built facts) are treated as safe.
+ * `dtcg` JSON token (no CSS custom property emitted by default), or a JS member
+ * path does not, so those fixes are surfaced as suggestions rather than
+ * deterministic rewrites. Tokens without a known format fail closed: unknown
+ * provenance is not proof that a replacement compiles.
  */
 export function isApplicableTokenReference(
   referenceFormat: TokenDefinitionFact["referenceFormat"]
 ): boolean {
-  return (
-    referenceFormat === undefined || referenceFormat === "css-var" || referenceFormat === "scss-var"
-  );
+  return referenceFormat === "css-var" || referenceFormat === "scss-var";
 }

package/src/schema.ts

@@ -248,6 +248,19 @@ const tokenConfigSchema = z
     // vocabulary seeds the known-token set (#7c). A packages-only tokens block
     // is valid — see the superRefine below.
     packages: z.array(z.string().min(1)).optional(),
+    aliases: z.record(z.string().min(1)).optional(),
+    upstream: z
+      .array(
+        z.object({
+          packageName: z.string().min(1),
+          version: z.string().min(1).optional(),
+          digest: z
+            .string()
+            .regex(/^[a-f0-9]{64}$/u)
+            .optional(),
+        })
+      )
+      .optional(),
     exclude: z.array(repoRelativePathSchema).optional(),
     themeSelectors: z.record(z.string()).optional(),
     enabled: z.boolean().optional(),

package/src/schemas/index.ts

@@ -254,18 +254,15 @@ const agentRunProvenanceSchema = z.object({
   fcid: z.string().min(1),
   baselineId: z.string().min(1).optional(),
   scope: z.object({
-    method: z.enum([
-      "three-dot",
-      "tree-diff",
-      "status",
-      "fallback-full",
-      "explicit",
-      "full",
-    ]),
+    method: z.enum(["three-dot", "tree-diff", "status", "fallback-full", "explicit", "full"]),
     gitOk: z.boolean(),
   }),
   engineVersion: z.string().min(1),
   scopeHash: z.string().regex(/^[a-f0-9]{64}$/),
+  inputsHash: z
+    .string()
+    .regex(/^[a-f0-9]{64}$/)
+    .optional(),
   inputFilesHash: z.string().regex(/^[a-f0-9]{64}$/),
 });
 

package/src/token-types.ts

@@ -25,6 +25,63 @@ export type TokenCategory =
   | "z-index"
   | "other";
 
+/** Stable, renderer-independent token catalog contract. */
+export interface TokenCatalog {
+  schemaVersion: "token-catalog:v1";
+  configuredSources: string[];
+  parsedSources: string[];
+  definitions: TokenCatalogDefinition[];
+  diagnostics: TokenCatalogDiagnostic[];
+  references: TokenCatalogReference[];
+  sourceStates?: TokenCatalogSourceState[];
+}
+
+export interface TokenCatalogSourceState {
+  source: string;
+  role: "local" | "upstream";
+  state:
+    | "verified"
+    | "version_mismatch"
+    | "digest_mismatch"
+    | "source_unavailable"
+    | "cache_unverified";
+  installedVersion?: string;
+  contentDigest?: string;
+  expectedVersion?: string;
+  expectedDigest?: string;
+}
+
+export interface TokenCatalogLocation {
+  file: string;
+  line: number;
+  column: number;
+}
+
+export interface TokenCatalogDefinition {
+  /** Authored member path, for example `spacing.smaller` or `theme.palette.primary.main`. */
+  name: string;
+  value: string;
+  category: TokenCategory;
+  location: TokenCatalogLocation;
+  exportName?: string;
+  referenceSyntax: "css-var" | "scss-var" | "scss-map" | "dtcg" | "js-member";
+  authority: "authored" | "declared-package";
+  role: "local" | "upstream";
+}
+
+export interface TokenCatalogDiagnostic {
+  code: "tokens/unsupported-static-value" | "tokens/source-unavailable";
+  severity: "warning";
+  message: string;
+  location: TokenCatalogLocation;
+}
+
+export interface TokenCatalogReference {
+  name: string;
+  location: TokenCatalogLocation;
+  syntax: "css-var" | "scss-var" | "scss-map" | "dtcg" | "js-member";
+}
+
 /**
  * A single design token (CSS custom property)
  */
@@ -60,7 +117,7 @@ export interface DesignToken {
   sourceFile: string;
 
   /** Authored reference form, when the parser can prove it from the source. */
-  referenceFormat?: "css-var" | "scss-var" | "scss-map" | "dtcg";
+  referenceFormat?: "css-var" | "scss-var" | "scss-map" | "dtcg" | "js-member";
 
   /** Authored spellings preserved before normalization (for example `$x` and `--x`). */
   sourceNames?: string[];
@@ -205,6 +262,16 @@ export interface TokenConfig {
    */
   packages?: string[];
 
+  /** Explicit local-name -> upstream-name mappings for cross-authority drift checks. */
+  aliases?: Record<string, string>;
+
+  /** Deterministic pins for upstream token manifests; local scans never fetch them. */
+  upstream?: Array<{
+    packageName: string;
+    version?: string;
+    digest?: string;
+  }>;
+
   /**
    * Map CSS selectors to theme names
    * @example { ":root": "default", "[data-theme='dark']": "dark" }
@@ -230,6 +297,9 @@ export interface TokenParseResult {
 
   /** Parse time in ms */
   parseTimeMs: number;
+
+  /** The shared catalog used to produce `tokens`. Additive for compatibility. */
+  catalog?: TokenCatalog;
 }
 
 /**

package/src/types.ts

@@ -567,7 +567,10 @@ export interface TokenSourceConfig {
   /** Repo-root-relative token file or glob. */
   path: RepoRelativePath;
 
-  /** Explicit token format, or "auto" to infer from extension/content. */
+  /**
+   * Explicit token format, or "auto" to infer from extension/content. Use
+   * "auto" for statically analyzable TypeScript and JavaScript token modules.
+   */
   format?: TokenSourceFormat;
 }
 
@@ -578,7 +581,10 @@ export interface TokenConfig {
    */
   include?: string[];
 
-  /** Repo-root-relative token source files/globs for monorepos and Cloud setup. */
+  /**
+   * Repo-root-relative token source files/globs for monorepos and Cloud setup.
+   * Set each source to format "auto" for TypeScript or JavaScript token modules.
+   */
   sources?: TokenSourceConfig[];
 
   /**
@@ -592,6 +598,12 @@ export interface TokenConfig {
    */
   packages?: string[];
 
+  /** Explicit local-name -> upstream-name mappings for cross-authority drift checks. */
+  aliases?: Record<string, string>;
+
+  /** Deterministic pins for upstream token manifests; local scans never fetch them. */
+  upstream?: Array<{ packageName: string; version?: string; digest?: string }>;
+
   /**
    * Glob patterns to exclude
    * @example ["node_modules"]
@@ -607,7 +619,10 @@ export interface TokenConfig {
   /** Enable token comparison in style diffs (default: true) */
   enabled?: boolean;
 
-  /** Token source format detection ('auto' detects from file extension) */
+  /**
+   * Token source format detection. "auto" infers supported formats from the
+   * file extension, including statically analyzable TypeScript/JavaScript modules.
+   */
   format?: TokenSourceFormat;
 
   /** Vendor namespace for Fragments extensions in DTCG files (default: 'com.usefragments') */
@@ -807,12 +822,21 @@ export interface FragmentsConfig {
 
   /** Local component-identity decisions used when Cloud does not own the key. */
   identity?: {
+    /** Authored sanctions, rejections, and dismissals keyed by portable component identity. */
     decisions?: Array<{
       /** Portable component key (`file#exportName`). */
       component: string;
+
+      /** The identity disposition recorded for this component. */
       kind: "sanction" | "reject" | "dismiss";
+
+      /** Optional canonical target (`moduleSpecifier#exportName`) for sanctions. */
       canonicalTarget?: string;
+
+      /** Human-readable rationale stored with the decision. */
       reason?: string;
+
+      /** Stable external identifier used to reconcile an existing decision. */
       decisionId?: string;
     }>;
   };

package/dist/chunk-57QDBEHQ.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/schemas/index.ts"],"sourcesContent":["import { z } from \"zod\";\n\nimport {\n  legacySeverityLevelSchema,\n  severityFromLevel,\n  severityLevel,\n  severityLevelSchema,\n  severitySchema,\n} from \"../severity.js\";\nimport type { LegacySeverityLevel, Severity } from \"../severity.js\";\nimport type { EvidenceGrade } from \"../evidence.js\";\n\nconst evidenceGradeSchema: z.ZodType<EvidenceGrade> = z.enum([\n  \"none\",\n  \"runtime_advisory\",\n  \"provenance_bound\",\n  \"source_backed\",\n  \"receipt_backed\",\n]);\n\nexport { legacySeverityLevelSchema, severityLevelSchema, severitySchema };\nexport type { LegacySeverityLevel, Severity, SeverityLevel } from \"../severity.js\";\n\nexport const factLocationSchema = z.object({\n  file: z.string(),\n  line: z.number().int().nonnegative(),\n  column: z.number().int().nonnegative(),\n  endLine: z.number().int().nonnegative().optional(),\n  endColumn: z.number().int().nonnegative().optional(),\n});\nexport type FactLocation = z.infer<typeof factLocationSchema>;\n\nexport const findingReplacePropValueFixSchema = z.object({\n  kind: z.literal(\"replacePropValue\"),\n  title: z.string(),\n  prop: z.string(),\n  value: z.unknown(),\n  deterministic: z.boolean().optional(),\n});\n\nexport const findingReplaceStyleValueFixSchema = z.object({\n  kind: z.literal(\"replaceStyleValue\"),\n  title: z.string(),\n  property: z.string(),\n  value: z.string(),\n  deterministic: z.boolean().optional(),\n});\n\nexport const findingReplaceImportFixSchema = z.object({\n  kind: z.literal(\"replaceImport\"),\n  title: z.string(),\n  from: z.string(),\n  to: z.string(),\n  deterministic: z.boolean().optional(),\n});\n\nexport const findingReplaceComponentFixSchema = z.object({\n  kind: z.literal(\"replaceComponent\"),\n  title: z.string(),\n  from: z.string(),\n  to: z.string(),\n  deterministic: z.boolean().optional(),\n});\n\nexport const findingReplaceClassTokenFixSchema = z.object({\n  kind: z.literal(\"replaceClassToken\"),\n  title: z.string(),\n  from: z.string(),\n  to: z.string().nullable(),\n  utility: z.string(),\n  deterministic: z.boolean().optional(),\n});\n\nexport const findingFixSchema = z.discriminatedUnion(\"kind\", [\n  findingReplacePropValueFixSchema,\n  findingReplaceStyleValueFixSchema,\n  findingReplaceImportFixSchema,\n  findingReplaceComponentFixSchema,\n  findingReplaceClassTokenFixSchema,\n]);\nexport type FindingFix = z.infer<typeof findingFixSchema>;\nexport type FindingReplacePropValueFix = z.infer<typeof findingReplacePropValueFixSchema>;\nexport type FindingReplaceStyleValueFix = z.infer<typeof findingReplaceStyleValueFixSchema>;\nexport type FindingReplaceImportFix = z.infer<typeof findingReplaceImportFixSchema>;\nexport type FindingReplaceComponentFix = z.infer<typeof findingReplaceComponentFixSchema>;\nexport type FindingReplaceClassTokenFix = z.infer<typeof findingReplaceClassTokenFixSchema>;\n\nexport interface FactEvidence {\n  factId: string;\n  fact: {\n    kind: string;\n    location?: FactLocation;\n  };\n}\n\nexport const factEvidenceSchema: z.ZodType<FactEvidence> = z.object({\n  factId: z.string(),\n  fact: z\n    .object({\n      kind: z.string(),\n      location: factLocationSchema.optional(),\n    })\n    .passthrough(),\n});\n\nexport const findingSchema = z.object({\n  ruleId: z.string(),\n  ruleVersion: z.string(),\n  severity: severitySchema,\n  level: severityLevelSchema,\n  code: z\n    .string()\n    .regex(/^FUI\\d{4}$/)\n    .optional(),\n  helpUrl: z.string().url().optional(),\n  message: z.string(),\n  fingerprint: z.string(),\n  location: factLocationSchema,\n  evidence: z.array(factEvidenceSchema).min(1),\n  evidenceGrade: evidenceGradeSchema.optional(),\n  fix: findingFixSchema.optional(),\n  attributes: z.record(z.unknown()).optional(),\n  /**\n   * Product area this finding's file resolved to (topology layer). Optional —\n   * absent when the repo has no `topology` config. See `topology/resolve-area`.\n   */\n  area: z\n    .object({\n      areaId: z.string(),\n      areaName: z.string(),\n      criticality: z.enum([\"low\", \"medium\", \"high\", \"revenue\", \"regulated\"]),\n      owners: z.array(z.string()),\n      matchedGlob: z.string(),\n    })\n    .optional(),\n});\nexport type Finding = z.infer<typeof findingSchema>;\n\nexport const violationSchema = z.object({\n  nodeId: z.string(),\n  nodeType: z.string(),\n  rule: z.string(),\n  severity: severitySchema,\n  level: severityLevelSchema.optional(),\n  code: z\n    .string()\n    .regex(/^FUI\\d{4}$/)\n    .optional(),\n  helpUrl: z.string().url().optional(),\n  message: z.string(),\n  path: z.string().optional(),\n  suggestion: z.string().optional(),\n  prop: z.string().optional(),\n  filePath: z.string().optional(),\n  line: z.number().int().nonnegative().optional(),\n  column: z.number().int().nonnegative().optional(),\n  rawValue: z.string().optional(),\n  extra: z.record(z.unknown()).optional(),\n});\nexport type Violation = z.infer<typeof violationSchema>;\n\nexport const fixSchema = z.object({\n  nodeId: z.string(),\n  prop: z.string().optional(),\n  action: z.enum([\"remove\", \"replace\", \"add\"]),\n  value: z.unknown().optional(),\n  description: z.string(),\n});\nexport type Fix = z.infer<typeof fixSchema>;\n\nexport const validatorResultSchema = z.object({\n  validator: z.string(),\n  severity: severitySchema,\n  passed: z.boolean(),\n  violations: z.array(violationSchema),\n  findings: z.array(findingSchema).optional(),\n  suggestions: z.array(fixSchema).optional(),\n});\nexport type ValidatorResult = z.infer<typeof validatorResultSchema>;\n\nexport const governanceVerdictMetadataSchema = z.object({\n  runner: z.string(),\n  policyVersion: z.string().optional(),\n  duration: z.number().nonnegative(),\n  nodeCount: z.number().int().nonnegative(),\n  componentTypes: z.array(z.string()),\n});\nexport type GovernanceVerdictMetadata = z.infer<typeof governanceVerdictMetadataSchema>;\n\nexport const governanceVerdictSchema = z.object({\n  verdict: z.enum([\"pass\", \"warn\", \"fail\"]).optional(),\n  passed: z.boolean(),\n  score: z.number(),\n  results: z.array(validatorResultSchema),\n  metadata: governanceVerdictMetadataSchema,\n});\nexport type GovernanceVerdict = z.infer<typeof governanceVerdictSchema>;\n\nexport const suppressionDirectiveSchema = z.object({\n  ruleId: z.string().optional(),\n  reason: z.string().min(1),\n  expiresAt: z.string().datetime().optional(),\n  expiresOn: z\n    .string()\n    .regex(/^\\d{4}-\\d{2}-\\d{2}$/)\n    .optional(),\n  scope: z.enum([\"line\", \"block\", \"file\"]).default(\"line\"),\n  code: z\n    .string()\n    .regex(/^FUI\\d{4}$/)\n    .optional(),\n});\nexport type SuppressionDirective = z.infer<typeof suppressionDirectiveSchema>;\n\nexport const agentPlanSchema = z.object({\n  tool: z.enum([\n    \"design_system/list_primitives\",\n    \"design_system/conform\",\n    \"design_system/prove_compliant\",\n  ]),\n  args: z.record(z.unknown()),\n  confidence: z.number().min(0).max(1),\n});\n\nexport const agentFindingSchema = z.object({\n  code: z\n    .string()\n    .regex(/^FUI\\d{4}$/)\n    .optional(),\n  ruleId: z.string(),\n  filePath: z.string(),\n  line: z.number().int().nonnegative(),\n  col: z.number().int().nonnegative(),\n  severity: severitySchema,\n  level: severityLevelSchema,\n  message: z.string(),\n  evidenceGrade: evidenceGradeSchema.optional(),\n  evidence: z.array(factEvidenceSchema),\n  plan: agentPlanSchema,\n});\n\nexport const AGENT_FORMAT_SCHEMA_VERSION = \"typestyle.agent.v2\" as const;\n\nexport const agentIntegritySchema = z.object({\n  rulesLoaded: z.number().int().nonnegative(),\n  status: z.enum([\"healthy\", \"degraded\", \"inert\"]),\n  healthy: z.boolean(),\n  inert: z.boolean(),\n  reasons: z.array(z.string()),\n});\n\nconst agentRunProvenanceSchema = z.object({\n  runId: z.string().regex(/^run_[a-f0-9]{12}$/),\n  fcid: z.string().min(1),\n  baselineId: z.string().min(1).optional(),\n  scope: z.object({\n    method: z.enum([\n      \"three-dot\",\n      \"tree-diff\",\n      \"status\",\n      \"fallback-full\",\n      \"explicit\",\n      \"full\",\n    ]),\n    gitOk: z.boolean(),\n  }),\n  engineVersion: z.string().min(1),\n  scopeHash: z.string().regex(/^[a-f0-9]{64}$/),\n  inputFilesHash: z.string().regex(/^[a-f0-9]{64}$/),\n});\n\nconst agentRunVerdictSchema = z.object({\n  exitCode: z.union([z.literal(0), z.literal(1)]),\n  reasons: z.array(z.string()),\n  gatingFindingCount: z.number().int().nonnegative(),\n});\n\nconst agentFormatBaseSchema = z.object({\n  schemaVersion: z.literal(AGENT_FORMAT_SCHEMA_VERSION),\n  summary: z.string(),\n  integrity: agentIntegritySchema,\n  fix_first: z.array(agentFindingSchema),\n  remaining: z.array(agentFindingSchema),\n  suppression_template: z.object({\n    directive: z.string(),\n    requiredFields: z.array(z.string()),\n    example: z.string(),\n  }),\n  budget: z.object({\n    iteration: z.number().int().nonnegative(),\n    maxIterations: z.number().int().positive(),\n    scoreDelta: z.number(),\n  }),\n  findings: z.array(findingSchema).optional(),\n  suppressions: z.array(suppressionDirectiveSchema).optional(),\n  provenance: agentRunProvenanceSchema.optional(),\n  verdict: agentRunVerdictSchema.optional(),\n});\n\nexport const agentFormatSchema = z.union([\n  agentFormatBaseSchema.extend({\n    passed: z.boolean(),\n    score: z.number(),\n    status: z.never().optional(),\n    reasons: z.never().optional(),\n    integrity: agentIntegritySchema.extend({\n      rulesLoaded: z.number().int().positive(),\n    }),\n  }),\n  agentFormatBaseSchema.extend({\n    passed: z.literal(false),\n    score: z.never().optional(),\n    status: z.literal(\"indeterminate\"),\n    reasons: z.tuple([z.literal(\"zero_rules_loaded\")]),\n    integrity: agentIntegritySchema.extend({\n      rulesLoaded: z.literal(0),\n    }),\n  }),\n  // A finalized Run can explicitly allow inert governance. Preserve the\n  // indeterminate integrity truth while making `passed` match that Run's sole\n  // verdict; requiring Run pins prevents generic zero-rule envelopes from\n  // accidentally becoming green.\n  agentFormatBaseSchema.extend({\n    passed: z.literal(true),\n    score: z.never().optional(),\n    status: z.literal(\"indeterminate\"),\n    reasons: z.tuple([z.literal(\"zero_rules_loaded\")]),\n    integrity: agentIntegritySchema.extend({\n      rulesLoaded: z.literal(0),\n    }),\n    provenance: agentRunProvenanceSchema,\n    verdict: agentRunVerdictSchema.extend({ exitCode: z.literal(0) }),\n  }),\n]);\nexport type AgentFormat = z.infer<typeof agentFormatSchema>;\n\nexport const agentErrorEnvelopeSchema = z.object({\n  schemaVersion: z.literal(AGENT_FORMAT_SCHEMA_VERSION),\n  passed: z.literal(false),\n  error: z.object({\n    code: z.string().min(1),\n    message: z.string().min(1),\n  }),\n  provenance: agentRunProvenanceSchema.optional(),\n  verdict: agentRunVerdictSchema.optional(),\n  cloudReport: z.enum([\"reported\", \"failed\", \"skipped\"]).optional(),\n  notices: z.array(z.string()).optional(),\n});\nexport type AgentErrorEnvelope = z.infer<typeof agentErrorEnvelopeSchema>;\n\nexport const agentOutputSchema = z.union([agentFormatSchema, agentErrorEnvelopeSchema]);\nexport type AgentOutput = z.infer<typeof agentOutputSchema>;\n\nexport function normalizeSeverity(severity: Severity | LegacySeverityLevel): Severity {\n  return severitySchema.safeParse(severity).success\n    ? (severity as Severity)\n    : severityFromLevel(legacySeverityLevelSchema.parse(severity));\n}\n\nexport function normalizeFinding(\n  input: Omit<Finding, \"level\"> & { level?: Finding[\"level\"] }\n): Finding {\n  return {\n    ...input,\n    evidenceGrade: input.evidenceGrade ?? \"source_backed\",\n    level: input.level ?? severityLevel(input.severity),\n  };\n}\n\nexport function normalizeViolation(\n  input: Omit<Violation, \"level\"> & { level?: Violation[\"level\"] }\n): Violation {\n  return {\n    ...input,\n    level: input.level ?? severityLevel(input.severity),\n  };\n}\n"],"mappings":"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","names":[]}