@usefragments/core 1.0.0 → 1.3.0

package/dist/schemas/index.js

@@ -1,6 +1,10 @@
 import {
+  AGENT_FORMAT_SCHEMA_VERSION,
+  agentErrorEnvelopeSchema,
   agentFindingSchema,
   agentFormatSchema,
+  agentIntegritySchema,
+  agentOutputSchema,
   agentPlanSchema,
   factEvidenceSchema,
   factLocationSchema,
@@ -20,15 +24,19 @@ import {
   suppressionDirectiveSchema,
   validatorResultSchema,
   violationSchema
-} from "../chunk-R3X7UBHU.js";
+} from "../chunk-57QDBEHQ.js";
 import {
   legacySeverityLevelSchema,
   severityLevelSchema,
   severitySchema
 } from "../chunk-V4VQB57N.js";
 export {
+  AGENT_FORMAT_SCHEMA_VERSION,
+  agentErrorEnvelopeSchema,
   agentFindingSchema,
   agentFormatSchema,
+  agentIntegritySchema,
+  agentOutputSchema,
   agentPlanSchema,
   factEvidenceSchema,
   factLocationSchema,

package/dist/test-utils.d.ts

@@ -1,4 +1,4 @@
-import { C as CompiledBlock, b as CompiledFragment } from './governance-BOa3KyiJ.js';
+import { C as CompiledBlock, b as CompiledFragment } from './governance-DYSirwJu.js';
 import 'zod';
 import 'react';
 import './topology/index.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usefragments/core",
-  "version": "1.0.0",
+  "version": "1.3.0",
   "license": "MIT",
   "description": "Core types, schemas, and runtime API for Fragments component definitions",
   "author": "Conan McNicholl",

package/src/agent-format.test.ts

@@ -1,9 +1,22 @@
 import { describe, expect, it } from "vitest";
 
 import { buildAgentFormat } from "./agent-format.js";
-import { agentFormatSchema, type Finding } from "./schemas/index.js";
+import {
+  AGENT_FORMAT_SCHEMA_VERSION,
+  agentFormatSchema,
+  agentOutputSchema,
+  type AgentFormat,
+  type Finding,
+} from "./schemas/index.js";
 
 const DEAD_TOOL_NAMES = ["apply_fix", "swap_to_canonical", "tokens.suggest"];
+const HEALTHY_INTEGRITY = {
+  rulesLoaded: 1,
+  status: "healthy",
+  healthy: true,
+  inert: false,
+  reasons: [],
+} satisfies AgentFormat["integrity"];
 
 function finding(overrides: Partial<Finding> = {}): Finding {
   return {
@@ -32,6 +45,7 @@ describe("buildAgentFormat", () => {
   it("names only hosted MCP tools in fix plans", () => {
     const agentFormat = buildAgentFormat({
       filesScanned: 1,
+      integrity: HEALTHY_INTEGRITY,
       findings: [
         finding({
           fix: {
@@ -69,6 +83,7 @@ describe("buildAgentFormat", () => {
   it("keeps warn-only scans passed when the report summary passed", () => {
     const agentFormat = buildAgentFormat({
       filesScanned: 1,
+      integrity: HEALTHY_INTEGRITY,
       passed: true,
       findings: [
         finding({
@@ -84,6 +99,7 @@ describe("buildAgentFormat", () => {
   it("omits full findings and evidence by default", () => {
     const agentFormat = buildAgentFormat({
       filesScanned: 1,
+      integrity: HEALTHY_INTEGRITY,
       findings: [finding()],
     });
 
@@ -100,6 +116,132 @@ describe("buildAgentFormat", () => {
       })
     );
 
-    expect(buildAgentFormat({ filesScanned: 3, findings }).score).toBeGreaterThan(0);
+    expect(
+      buildAgentFormat({ filesScanned: 3, findings, integrity: HEALTHY_INTEGRITY }).score
+    ).toBeGreaterThan(0);
+  });
+
+  it("keeps a healthy empty scan passed with a perfect score", () => {
+    const agentFormat = buildAgentFormat({
+      filesScanned: 1,
+      findings: [],
+      integrity: HEALTHY_INTEGRITY,
+    });
+
+    expect(agentFormat).toMatchObject({
+      schemaVersion: AGENT_FORMAT_SCHEMA_VERSION,
+      passed: true,
+      score: 100,
+      integrity: HEALTHY_INTEGRITY,
+    });
+  });
+
+  it("marks an inert zero-rule scan indeterminate without inventing a score", () => {
+    const agentFormat = buildAgentFormat({
+      filesScanned: 1,
+      findings: [],
+      integrity: {
+        rulesLoaded: 0,
+        status: "inert",
+        healthy: false,
+        inert: true,
+        reasons: ["no_enforceable_rules"],
+      },
+    });
+
+    expect(agentFormat).toMatchObject({
+      passed: false,
+      status: "indeterminate",
+      reasons: ["zero_rules_loaded"],
+      integrity: {
+        rulesLoaded: 0,
+        healthy: false,
+        inert: true,
+        reasons: ["no_enforceable_rules"],
+      },
+    });
+    expect(agentFormat).not.toHaveProperty("score");
+    expect(agentFormat.summary).toContain("zero_rules_loaded");
+    expect(() => agentFormatSchema.parse(agentFormat)).not.toThrow();
+  });
+
+  it("rejects invalid determinate and indeterminate field combinations", () => {
+    const determinate = buildAgentFormat({
+      filesScanned: 1,
+      findings: [],
+      integrity: HEALTHY_INTEGRITY,
+    });
+    const indeterminate = buildAgentFormat({
+      filesScanned: 1,
+      findings: [],
+      integrity: {
+        rulesLoaded: 0,
+        status: "inert",
+        healthy: false,
+        inert: true,
+        reasons: ["no_enforceable_rules"],
+      },
+    });
+
+    expect(agentFormatSchema.safeParse({ ...determinate, score: undefined }).success).toBe(false);
+    expect(
+      agentFormatSchema.safeParse({
+        ...determinate,
+        status: "indeterminate",
+        reasons: ["zero_rules_loaded"],
+      }).success
+    ).toBe(false);
+    expect(agentFormatSchema.safeParse({ ...determinate, reasons: [] }).success).toBe(false);
+    expect(agentFormatSchema.safeParse({ ...indeterminate, passed: true }).success).toBe(false);
+    expect(agentFormatSchema.safeParse({ ...indeterminate, score: 0 }).success).toBe(false);
+    expect(
+      agentFormatSchema.safeParse({ ...indeterminate, reasons: ["no_enforceable_rules"] }).success
+    ).toBe(false);
+    expect(
+      agentFormatSchema.safeParse({
+        ...determinate,
+        integrity: { ...determinate.integrity, rulesLoaded: 0 },
+      }).success
+    ).toBe(false);
+    expect(
+      agentFormatSchema.safeParse({
+        ...indeterminate,
+        integrity: { ...indeterminate.integrity, rulesLoaded: 1 },
+      }).success
+    ).toBe(false);
+  });
+
+  it("validates the structured error envelope against the shared agent output schema", () => {
+    expect(() =>
+      agentOutputSchema.parse({
+        schemaVersion: AGENT_FORMAT_SCHEMA_VERSION,
+        passed: false,
+        error: { code: "check_failed", message: "Scan failed." },
+      })
+    ).not.toThrow();
+  });
+
+  it("preserves additive Run provenance and verdict through typed parsing", () => {
+    const agentFormat = buildAgentFormat({
+      filesScanned: 1,
+      findings: [],
+      integrity: HEALTHY_INTEGRITY,
+      provenance: {
+        runId: "run_0123456789ab",
+        fcid: "a".repeat(64),
+        scope: { method: "full", gitOk: true },
+        engineVersion: `sha256:${"b".repeat(64)}`,
+        scopeHash: "c".repeat(64),
+        inputFilesHash: "d".repeat(64),
+      },
+      verdict: { exitCode: 0, reasons: [], gatingFindingCount: 0 },
+    });
+
+    const parsed = agentOutputSchema.parse(agentFormat);
+
+    expect(parsed).toMatchObject({
+      provenance: { runId: "run_0123456789ab", scope: { method: "full", gitOk: true } },
+      verdict: { exitCode: 0, reasons: [], gatingFindingCount: 0 },
+    });
   });
 });

package/src/agent-format.ts

@@ -1,10 +1,11 @@
 import { severityLevel } from "./severity.js";
-import type { AgentFormat, Finding } from "./schemas/index.js";
+import { AGENT_FORMAT_SCHEMA_VERSION, type AgentFormat, type Finding } from "./schemas/index.js";
 import type { SuppressionDirectiveFact } from "./facts/index.js";
 
 export interface BuildAgentFormatInput {
   findings: readonly Finding[];
   filesScanned: number;
+  integrity: AgentFormat["integrity"];
   passed?: boolean;
   suppressions?: readonly SuppressionDirectiveFact[];
   iteration?: number;
@@ -13,10 +14,14 @@ export interface BuildAgentFormatInput {
   maxFindings?: number;
   includeEvidence?: boolean;
   includeFindings?: boolean;
+  provenance?: NonNullable<AgentFormat["provenance"]>;
+  verdict?: NonNullable<AgentFormat["verdict"]>;
 }
 
 export function buildAgentFormat(input: BuildAgentFormatInput): AgentFormat {
-  const score = scoreFindings(input.findings);
+  const zeroRulesLoaded = input.integrity.rulesLoaded === 0;
+  const integrityFailed = !input.integrity.healthy || input.integrity.inert;
+  const score = integrityFailed ? 0 : scoreFindings(input.findings);
   const visibleFindings = uniqueFindings(input.findings).slice(0, input.maxFindings ?? 50);
   const agentFindings = visibleFindings.map((finding) => ({
     code: finding.code,
@@ -27,6 +32,7 @@ export function buildAgentFormat(input: BuildAgentFormatInput): AgentFormat {
     severity: finding.severity,
     level: severityLevel(finding.severity),
     message: finding.message,
+    evidenceGrade: finding.evidenceGrade,
     evidence: input.includeEvidence ? finding.evidence : [],
     plan: planForFinding(finding),
   }));
@@ -36,11 +42,14 @@ export function buildAgentFormat(input: BuildAgentFormatInput): AgentFormat {
   // `passed:false`.
   const hasErrors = input.findings.some((finding) => severityLevel(finding.severity) === "error");
 
-  return {
-    schemaVersion: "typestyle.agent.v1",
-    passed: (input.passed ?? true) && !hasErrors,
-    score,
-    summary: agentSummary(input.findings.length, input.filesScanned, score),
+  const shared = {
+    schemaVersion: AGENT_FORMAT_SCHEMA_VERSION,
+    summary: zeroRulesLoaded
+      ? "indeterminate; zero_rules_loaded"
+      : integrityFailed
+        ? `failed with score ${score}; ${input.integrity.reasons.join("; ") || "governance integrity is unhealthy"}`
+        : agentSummary(input.findings.length, input.filesScanned, score),
+    integrity: input.integrity,
     fix_first: agentFindings.filter((finding) => finding.plan.confidence >= 0.8),
     remaining: agentFindings.filter((finding) => finding.plan.confidence < 0.8),
     suppression_template: {
@@ -65,6 +74,24 @@ export function buildAgentFormat(input: BuildAgentFormatInput): AgentFormat {
           })),
         }
       : {}),
+    ...(input.provenance ? { provenance: input.provenance } : {}),
+    ...(input.verdict ? { verdict: input.verdict } : {}),
+  };
+
+  if (zeroRulesLoaded) {
+    return {
+      ...shared,
+      integrity: { ...input.integrity, rulesLoaded: 0 },
+      passed: false,
+      status: "indeterminate",
+      reasons: ["zero_rules_loaded"],
+    };
+  }
+
+  return {
+    ...shared,
+    passed: !integrityFailed && (input.passed ?? true) && !hasErrors,
+    score,
   };
 }
 

package/src/codes/__tests__/codes.test.ts

@@ -3,18 +3,36 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { describe, expect, it } from "vitest";
 
-import {
-  CODES,
-  EXPLAIN_URL_BASE,
-  bridgeSourceViolation,
-  byCode,
-  byRuleId,
-} from "../index.js";
+import { CODES, EXPLAIN_URL_BASE, bridgeSourceViolation, byCode, byRuleId } from "../index.js";
+import { RULE_FIX_AVAILABLE, type RuleWithFixAvailability } from "../../rules/fix-availability.js";
+import { RULES } from "../../rules/index.js";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const registryPath = path.resolve(__dirname, "../../../../../docs/codes/registry.json");
 
+const SUBSYSTEM_EMITTED_CODES = ["FUI9001", "FUI9002", "FUI9003"] as const;
+
+const RESERVED_CODES = {
+  FUI1001: "Reserved for canonical primitive findings; no core rule emits it.",
+  FUI1005: "Reserved for component allow-set policy; no core rule emits it.",
+  FUI1006: "Reserved for component deny-set policy; no core rule emits it.",
+  FUI2001: "Reserved for generic design-token requirements; no core rule emits it.",
+  FUI2002: "Reserved for token-prefix policy; no core rule emits it.",
+  FUI2013: "Reserved for brand-seed enforcement; no core rule emits it.",
+  FUI3002: "Reserved for general accessibility standards; no core rule emits it.",
+  FUI5001: "Reserved for required-child composition; no core rule emits it.",
+  FUI5002: "Deprecated canonical-composition alias; no active core rule emits it.",
+  FUI6001: "Reserved for generic unknown props; no core rule emits it.",
+  FUI6003: "Reserved for banned prop patterns; no core rule emits it.",
+  FUI8001: "Reserved for event-handler safety policy; no core rule emits it.",
+  FUI8002: "Reserved for dangerous-prop safety policy; no core rule emits it.",
+  FUI8003: "Reserved for controlled-prop safety policy; no core rule emits it.",
+  FUI8004: "Reserved for function-prop safety policy; no core rule emits it.",
+  FUI8005: "Reserved for internal-prop safety policy; no core rule emits it.",
+  FUI8006: "Reserved for href-sanitization safety policy; no core rule emits it.",
+} as const;
+
 describe("FUI code registry", () => {
   it("does not contain duplicate codes", () => {
     expect(new Set(CODES.map((entry) => entry.code)).size).toBe(CODES.length);
@@ -32,6 +50,38 @@ describe("FUI code registry", () => {
     }
   });
 
+  it("maps every implemented rule to a code", () => {
+    const unmappedRuleIds = RULES.filter((rule) => !byRuleId.has(rule.id)).map((rule) => rule.id);
+    expect(unmappedRuleIds).toEqual([]);
+  });
+
+  it("partitions every code into exactly one implementation state", () => {
+    const ruleBackedCodes = RULES.map((rule) => byRuleId.get(rule.id)?.code).filter(
+      (code): code is string => code !== undefined
+    );
+    const classifiedCodes = [
+      ...ruleBackedCodes,
+      ...SUBSYSTEM_EMITTED_CODES,
+      ...Object.keys(RESERVED_CODES),
+    ];
+
+    expect(new Set(classifiedCodes).size).toBe(classifiedCodes.length);
+    expect(classifiedCodes.sort()).toEqual(CODES.map((entry) => entry.code).sort());
+    expect(
+      Object.values(RESERVED_CODES).every((reason) => reason.length > 0 && !reason.includes("\n"))
+    ).toBe(true);
+  });
+
+  it("keeps rule fix capability in lock-step with RULES and rule-backed codes", () => {
+    const ruleIds = RULES.map((rule) => rule.id).sort();
+    expect(Object.keys(RULE_FIX_AVAILABLE).sort()).toEqual(ruleIds);
+
+    for (const rule of RULES) {
+      const fixAvailable = RULE_FIX_AVAILABLE[rule.id as RuleWithFixAvailability];
+      expect(byRuleId.get(rule.id)?.fixAvailable, rule.id).toBe(fixAvailable);
+    }
+  });
+
   it("matches the committed docs registry snapshot", () => {
     const snapshot = JSON.parse(readFileSync(registryPath, "utf8"));
     expect(snapshot).toEqual(CODES);

package/src/codes/codes.ts

@@ -1,4 +1,5 @@
 import type { Severity } from "../severity.js";
+import { RULE_FIX_AVAILABLE, type RuleWithFixAvailability } from "../rules/fix-availability.js";
 export type { Severity } from "../severity.js";
 
 export const EXPLAIN_URL_BASE = "https://usefragments.com/errors/";
@@ -36,6 +37,19 @@ function code(entry: Omit<FuiCode, "explainUrl"> & { explainUrl?: never }): FuiC
   };
 }
 
+type RuleCodeEntry = Omit<FuiCode, "explainUrl" | "fixAvailable" | "ruleId"> & {
+  ruleId: RuleWithFixAvailability;
+};
+
+function ruleCode(entry: RuleCodeEntry): FuiCode {
+  const { evidenceRequired, ...metadata } = entry;
+  return code({
+    ...metadata,
+    fixAvailable: RULE_FIX_AVAILABLE[entry.ruleId],
+    evidenceRequired,
+  });
+}
+
 export const CODES = [
   code({
     code: "FUI1001",
@@ -47,34 +61,31 @@ export const CODES = [
     fixAvailable: true,
     evidenceRequired: true,
   }),
-  code({
+  ruleCode({
     code: "FUI1002",
     ruleId: "components/preferred-component",
     category: "canonical-usage",
     defaultSeverity: "serious",
     title: "Preferred component should be used",
     lifecycle: "experimental",
-    fixAvailable: true,
     evidenceRequired: true,
   }),
-  code({
+  ruleCode({
     code: "FUI1003",
     ruleId: "imports/preferred-path",
     category: "canonical-usage",
     defaultSeverity: "moderate",
     title: "Import should use the preferred path",
     lifecycle: "experimental",
-    fixAvailable: true,
     evidenceRequired: true,
   }),
-  code({
+  ruleCode({
     code: "FUI1004",
     ruleId: "components/prefer-library",
     category: "canonical-usage",
     defaultSeverity: "moderate",
     title: "Library component should be preferred",
     lifecycle: "experimental",
-    fixAvailable: true,
     evidenceRequired: true,
   }),
   code({
@@ -117,104 +128,94 @@ export const CODES = [
     fixAvailable: true,
     evidenceRequired: true,
   }),
-  code({
+  ruleCode({
     code: "FUI2003",
     ruleId: "tokens/require-dual-fallback",
     category: "tokens",
     defaultSeverity: "serious",
     title: "Token fallback is required",
     lifecycle: "experimental",
-    fixAvailable: true,
     evidenceRequired: true,
   }),
-  code({
+  ruleCode({
     code: "FUI2004",
     ruleId: "styles/no-raw-dimensions",
     category: "tokens",
     defaultSeverity: "serious",
     title: "Raw dimension should use a token",
     lifecycle: "experimental",
-    fixAvailable: true,
     evidenceRequired: true,
   }),
-  code({
+  ruleCode({
     code: "FUI2005",
     ruleId: "styles/no-raw-color",
     category: "tokens",
     defaultSeverity: "serious",
     title: "Raw color should use a token",
     lifecycle: "experimental",
-    fixAvailable: true,
     evidenceRequired: true,
   }),
-  code({
+  ruleCode({
     code: "FUI2006",
     ruleId: "styles/no-raw-spacing",
     category: "tokens",
     defaultSeverity: "serious",
     title: "Raw spacing should use the scale",
     lifecycle: "experimental",
-    fixAvailable: true,
     evidenceRequired: true,
   }),
-  code({
+  ruleCode({
     code: "FUI2007",
     ruleId: "tailwind/arbitrary-color",
     category: "tokens",
     defaultSeverity: "moderate",
     title: "Tailwind arbitrary color should use a token",
     lifecycle: "experimental",
-    fixAvailable: true,
     evidenceRequired: true,
   }),
-  code({
+  ruleCode({
     code: "FUI2008",
     ruleId: "tailwind/arbitrary-spacing",
     category: "tokens",
     defaultSeverity: "moderate",
     title: "Tailwind arbitrary spacing should use the scale",
     lifecycle: "experimental",
-    fixAvailable: true,
     evidenceRequired: true,
   }),
-  code({
+  ruleCode({
     code: "FUI2009",
     ruleId: "tailwind/forbidden-palette",
     category: "tokens",
     defaultSeverity: "moderate",
     title: "Tailwind palette is forbidden",
     lifecycle: "experimental",
-    fixAvailable: false,
     evidenceRequired: true,
   }),
-  code({
+  ruleCode({
     code: "FUI2010",
     ruleId: "tailwind/raw-color-via-token",
     category: "tokens",
     defaultSeverity: "moderate",
     title: "Tailwind color should use a resolved token",
     lifecycle: "experimental",
-    fixAvailable: true,
     evidenceRequired: true,
   }),
-  code({
+  ruleCode({
     code: "FUI2011",
     ruleId: "tailwind/off-scale-spacing-token",
     category: "tokens",
     defaultSeverity: "moderate",
     title: "Tailwind spacing token is off scale",
     lifecycle: "experimental",
-    fixAvailable: true,
     evidenceRequired: true,
   }),
-  code({
+  ruleCode({
     code: "FUI2012",
     ruleId: "tailwind/unknown-class",
     category: "tokens",
     defaultSeverity: "moderate",
     title: "Tailwind class is unknown",
     lifecycle: "experimental",
-    fixAvailable: false,
     evidenceRequired: true,
   }),
   code({
@@ -227,34 +228,40 @@ export const CODES = [
     fixAvailable: true,
     evidenceRequired: true,
   }),
-  code({
+  ruleCode({
     code: "FUI2014",
     ruleId: "theme/no-theme-coupled-literal",
     category: "tokens",
     defaultSeverity: "moderate",
     title: "Theme-coupled literal should use a semantic token",
     lifecycle: "experimental",
-    fixAvailable: false,
     evidenceRequired: true,
   }),
-  code({
+  ruleCode({
     code: "FUI2015",
     ruleId: "tokens/css-vars-must-be-defined",
     category: "tokens",
     defaultSeverity: "moderate",
     title: "CSS variable is not in the contract vocabulary",
     lifecycle: "experimental",
-    fixAvailable: false,
     evidenceRequired: true,
   }),
-  code({
+  ruleCode({
+    code: "FUI2016",
+    ruleId: "styles/no-raw-typography",
+    category: "tokens",
+    defaultSeverity: "serious",
+    title: "Raw typography should use a token",
+    lifecycle: "experimental",
+    evidenceRequired: true,
+  }),
+  ruleCode({
     code: "FUI3001",
     ruleId: "a11y/required-accessible-name",
     category: "a11y",
     defaultSeverity: "serious",
     title: "Accessible name is required",
     lifecycle: "experimental",
-    fixAvailable: false,
     evidenceRequired: true,
   }),
   code({
@@ -288,24 +295,22 @@ export const CODES = [
     fixAvailable: true,
     evidenceRequired: true,
   }),
-  code({
+  ruleCode({
     code: "FUI5003",
     ruleId: "composition/cardinality",
     category: "composition",
     defaultSeverity: "moderate",
     title: "Too many of a component in one region",
     lifecycle: "experimental",
-    fixAvailable: false,
     evidenceRequired: true,
   }),
-  code({
+  ruleCode({
     code: "FUI5004",
     ruleId: "composition/co-occurrence",
     category: "composition",
     defaultSeverity: "moderate",
     title: "Required companion component is missing from the region",
     lifecycle: "experimental",
-    fixAvailable: false,
     evidenceRequired: true,
   }),
   code({
@@ -318,14 +323,13 @@ export const CODES = [
     fixAvailable: false,
     evidenceRequired: true,
   }),
-  code({
+  ruleCode({
     code: "FUI6002",
     ruleId: "props/invalid-value",
     category: "props",
     defaultSeverity: "serious",
     title: "Prop value is invalid",
     lifecycle: "experimental",
-    fixAvailable: true,
     evidenceRequired: true,
   }),
   code({
@@ -338,24 +342,22 @@ export const CODES = [
     fixAvailable: false,
     evidenceRequired: true,
   }),
-  code({
+  ruleCode({
     code: "FUI6004",
     ruleId: "components/forbidden-prop-value",
     category: "props",
     defaultSeverity: "serious",
     title: "Prop value is forbidden",
     lifecycle: "experimental",
-    fixAvailable: true,
     evidenceRequired: true,
   }),
-  code({
+  ruleCode({
     code: "FUI6005",
     ruleId: "components/unknown-prop",
     category: "props",
     defaultSeverity: "moderate",
     title: "Component prop is unknown",
     lifecycle: "experimental",
-    fixAvailable: false,
     evidenceRequired: true,
   }),
   code({