@usefragments/core 1.5.1 → 1.5.2

package/dist/react-types.d.ts

@@ -1,5 +1,5 @@
 import { ComponentType, ReactNode, JSX } from 'react';
-export { F as FragmentDefinition, a as FragmentDefinitionV2 } from './governance-B88uR3Zq.js';
+export { F as FragmentDefinition, a as FragmentDefinitionV2 } from './governance-pKrfh517.js';
 import 'zod';
 import './topology/index.js';
 import './types-xJ2xyp_G.js';

package/dist/test-utils.d.ts

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

package/package.json

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

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

@@ -11,7 +11,7 @@ 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 SUBSYSTEM_EMITTED_CODES = ["FUI9001", "FUI9002", "FUI9003", "FUI9004", "FUI9005"] as const;
 
 const RESERVED_CODES = {
   FUI1001: "Reserved for canonical primitive findings; no core rule emits it.",

package/src/codes/codes.ts

@@ -468,6 +468,26 @@ export const CODES = [
     fixAvailable: true,
     evidenceRequired: true,
   }),
+  code({
+    code: "FUI9004",
+    ruleId: "config/unconsumed-key",
+    category: "system",
+    defaultSeverity: "moderate",
+    title: "Config key is not consumed",
+    lifecycle: "experimental",
+    fixAvailable: false,
+    evidenceRequired: false,
+  }),
+  code({
+    code: "FUI9005",
+    ruleId: "config/orphan-scale",
+    category: "system",
+    defaultSeverity: "moderate",
+    title: "Governance scale is not referenced",
+    lifecycle: "experimental",
+    fixAvailable: false,
+    evidenceRequired: false,
+  }),
 ] as const satisfies readonly FuiCode[];
 
 export const byCode: ReadonlyMap<string, FuiCode> = new Map(

package/src/config.ts

@@ -2,10 +2,24 @@ import { fragmentsConfigSchema } from "./schema.js";
 import type { FragmentsConfig } from "./types.js";
 import { normalizeGovernanceConfig } from "./governance.js";
 
+const RAW_CONFIG_DECLARATION = Symbol.for("@usefragments/core/raw-config-declaration");
+
 function formatZodErrors(errors: Array<{ path: (string | number)[]; message: string }>) {
   return errors.map((error) => `  - ${error.path.join(".")}: ${error.message}`).join("\n");
 }
 
+/**
+ * Recover the authored declaration before Zod stripped unknown keys.
+ *
+ * `defineConfig` still returns the schema-parsed config so its runtime semantics
+ * do not change. The non-enumerable source declaration exists only long enough
+ * for config loaders to diagnose keys that validated but would otherwise vanish.
+ */
+export function configDeclarationForDiagnostics(config: unknown): unknown {
+  if (!config || typeof config !== "object") return config;
+  return (config as Record<PropertyKey, unknown>)[RAW_CONFIG_DECLARATION] ?? config;
+}
+
 export function defineConfig<TConfig extends FragmentsConfig>(config: TConfig): TConfig {
   const normalized = normalizeGovernanceConfig(config);
   const result = fragmentsConfigSchema.safeParse(normalized);
@@ -14,5 +28,11 @@ export function defineConfig<TConfig extends FragmentsConfig>(config: TConfig):
     throw new Error(`Invalid fragments config:\n${formatZodErrors(result.error.errors)}`);
   }
 
+  Object.defineProperty(result.data, RAW_CONFIG_DECLARATION, {
+    value: normalized,
+    enumerable: false,
+    configurable: false,
+    writable: false,
+  });
   return result.data as TConfig;
 }

package/src/facts/fact-index.ts

@@ -45,6 +45,11 @@ export interface FactEvidence {
   fact: Fact;
 }
 
+export interface FactIndexOptions {
+  /** Optional internal diagnostic route. Product output is quiet by default. */
+  onConflict?: (message: string) => void;
+}
+
 interface FactWithComponent {
   componentId: ComponentId;
 }
@@ -115,6 +120,8 @@ export class FactIndex {
   private readonly idsByComponent = new Map<ComponentId, Set<FactId>>();
   private readonly tokenBySymbol = new Map<string, TokenDefinitionFact>();
 
+  constructor(private readonly options: FactIndexOptions = {}) {}
+
   add(fact: Fact): void {
     if (fact.kind === "token_definition") {
       this.indexTokenSymbols(fact);
@@ -125,7 +132,7 @@ export class FactIndex {
         canonicalJson(logicalFactForComparison(existing)) !==
         canonicalJson(logicalFactForComparison(fact))
       ) {
-        console.warn(
+        this.options.onConflict?.(
           `FactIndex: conflicting facts for id ${fact.id} — keeping ${describeFactForConflict(existing)}, skipping ${describeFactForConflict(fact)}`
         );
       }

package/src/facts/facts.test.ts

@@ -446,9 +446,9 @@ describe("FactIndex — query layer", () => {
     expect(() => ix.evidence([componentFact.id, ghost])).toThrow(/missing/i);
   });
 
-  it("warns and keeps the first fact when a conflicting fact reuses an id", () => {
-    const ix = new FactIndex();
-    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+  it("reports through an opt-in callback and keeps the first fact when an id conflicts", () => {
+    const onConflict = vi.fn();
+    const ix = new FactIndex({ onConflict });
     const id = factId("prop_value_forbidden", {
       componentId: buttonId,
       prop: "variant",
@@ -469,14 +469,13 @@ describe("FactIndex — query layer", () => {
     };
     ix.add(a);
     expect(() => ix.add(b)).not.toThrow();
-    expect(warn).toHaveBeenCalledWith(expect.stringContaining("conflicting facts"));
+    expect(onConflict).toHaveBeenCalledWith(expect.stringContaining("conflicting facts"));
     expect(ix.get(id)).toEqual(a);
-    warn.mockRestore();
   });
 
   it("does not treat token-definition provenance as a logical conflict", () => {
-    const ix = new FactIndex();
-    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const onConflict = vi.fn();
+    const ix = new FactIndex({ onConflict });
     const first = makeTokenDefinitionFact({
       name: "--fui-color-accent",
       value: "#2563eb",
@@ -491,14 +490,13 @@ describe("FactIndex — query layer", () => {
     ix.add(first);
     ix.add(second);
 
-    expect(warn).not.toHaveBeenCalled();
+    expect(onConflict).not.toHaveBeenCalled();
     expect(ix.get(first.id)).toEqual(first);
-    warn.mockRestore();
   });
 
-  it("includes token-definition provenance in logical conflict warnings", () => {
-    const ix = new FactIndex();
-    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+  it("includes token-definition provenance in logical conflict reports", () => {
+    const onConflict = vi.fn();
+    const ix = new FactIndex({ onConflict });
     const first = makeTokenDefinitionFact({
       name: "--fui-color-accent",
       value: "#2563eb",
@@ -513,13 +511,12 @@ describe("FactIndex — query layer", () => {
     ix.add(first);
     ix.add(second);
 
-    expect(warn).toHaveBeenCalledWith(
+    expect(onConflict).toHaveBeenCalledWith(
       expect.stringMatching(
         /conflicting facts.*keeping kind=token_definition location=tokens\/base\.css:2:1, skipping kind=token_definition location=tokens\/theme\.css:4:1/
       )
     );
     expect(ix.get(first.id)).toEqual(first);
-    warn.mockRestore();
   });
 
   it("treats old and current owned component spellings as the same indexed facts", () => {
@@ -527,17 +524,16 @@ describe("FactIndex — query layer", () => {
     const currentId = asComponentId("@usefragments/ui#Button");
     const legacy = compileComponentFacts(legacyId, buildSampleFragment());
     const current = compileComponentFacts(currentId, buildSampleFragment());
-    const ix = new FactIndex();
-    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const onConflict = vi.fn();
+    const ix = new FactIndex({ onConflict });
 
     ix.addMany(legacy);
     ix.addMany(current);
 
-    expect(warn).not.toHaveBeenCalled();
+    expect(onConflict).not.toHaveBeenCalled();
     expect(ix.size()).toBe(legacy.length);
     expect(ix.components.byId(legacyId)?.name).toBe("Button");
     expect(ix.components.byId(currentId)?.name).toBe("Button");
-    warn.mockRestore();
   });
 });
 

package/src/governance-integrity.test.ts

@@ -2,12 +2,15 @@ import { describe, expect, it } from "vitest";
 
 import type { GovernanceConfig } from "./governance.js";
 import {
+  detectOrphanGovernanceScales,
+  detectUnconsumedConfigKeys,
   evaluateGovernanceIntegrity,
   hasEffectiveComponentVocabulary,
   isEffectiveCanonicalSource,
   type GovernanceIntegrityInput,
 } from "./governance-integrity.js";
 import { customerDefaultRuleStates } from "./rules/presets.js";
+import { fragmentsConfigSchema } from "./schema.js";
 
 function evaluate(
   overrides: Partial<GovernanceIntegrityInput>
@@ -66,6 +69,84 @@ describe("hasEffectiveComponentVocabulary", () => {
   });
 });
 
+describe("inert config diagnostics", () => {
+  it("reports stripped, passthrough, unknown-rule, and rule-field keys in stable order", () => {
+    const authored = {
+      styles: { spacing: true },
+      screenshots: { threshold: 0.1, renderer: "chromium" },
+      tokens: { include: ["tokens.css"], mystery: true },
+      govern: {
+        scales: {
+          space: { kind: "scale", unit: "px", values: [0, 4, 8], source: "legacy" },
+        },
+        rules: {
+          "styles/no-raw-color": { enabled: true, exclude: ["vendor/**"] },
+          "styles/not-a-real-rule": { enabled: true },
+        },
+      },
+    };
+    const parsed = fragmentsConfigSchema.parse(authored);
+
+    expect(detectUnconsumedConfigKeys(authored, parsed)).toMatchObject([
+      { code: "FUI9004", path: "govern.rules.styles/no-raw-color.exclude" },
+      { code: "FUI9004", path: "govern.rules.styles/not-a-real-rule" },
+      { code: "FUI9004", path: "govern.scales.space.source" },
+      { code: "FUI9004", path: "screenshots.renderer" },
+      { code: "FUI9004", path: "styles" },
+      { code: "FUI9004", path: "tokens.mystery" },
+    ]);
+  });
+
+  it("reports an authored spacing scale that no effective property policy references", () => {
+    const declared: GovernanceConfig = {
+      scales: {
+        spacing: { kind: "scale", unit: "px", values: [0, 4, 8] },
+      },
+    };
+    const effective: GovernanceConfig = {
+      ...declared,
+      scales: {
+        ...declared.scales,
+        space: { kind: "scale", unit: "px", values: [0, 4, 8] },
+      },
+      styles: [
+        {
+          kind: "style.rawSpacing.mustMatchScale",
+          scale: "space",
+          appliesTo: ["margin", "padding"],
+          severity: "warn",
+        },
+      ],
+    };
+
+    expect(detectOrphanGovernanceScales(declared, effective)).toEqual([
+      expect.objectContaining({
+        code: "FUI9005",
+        path: "govern.scales.spacing",
+        message: expect.stringContaining('bound to the scale named "space"'),
+      }),
+    ]);
+  });
+
+  it("does not report a scale referenced by an effective property policy", () => {
+    const policy: GovernanceConfig = {
+      scales: {
+        space: { kind: "scale", unit: "px", values: [0, 4, 8] },
+      },
+      styles: [
+        {
+          kind: "style.rawSpacing.mustMatchScale",
+          scale: "space",
+          appliesTo: ["margin"],
+          severity: "warn",
+        },
+      ],
+    };
+
+    expect(detectOrphanGovernanceScales(policy, policy)).toEqual([]);
+  });
+});
+
 describe("evaluateGovernanceIntegrity", () => {
   it("1. no policy at all → inert, not fatal, not blocking-capable", () => {
     const verdict = evaluate({ policy: undefined, policySource: "none", declared: false });
@@ -207,4 +288,28 @@ describe("evaluateGovernanceIntegrity", () => {
     // degraded is enforceable, so not CI-fatal
     expect(verdict.fatalForCi).toBe(false);
   });
+
+  it("includes inert config diagnostics in the doctor roster without changing integrity status", () => {
+    const policy: GovernanceConfig = {
+      rules: { "styles/no-raw-color": { enabled: true, severity: "warn" } },
+    };
+    const baseline = evaluate({ policy, policySource: "config", declared: true });
+    const withDiagnostic = evaluate({
+      policy,
+      policySource: "config",
+      declared: true,
+      configDiagnostics: Array.from({ length: 2 }, () => ({
+        code: "FUI9005",
+        kind: "orphan-scale",
+        severity: "warn",
+        path: "govern.scales.spacing",
+        message: "orphan",
+      })),
+    });
+
+    expect(withDiagnostic.status).toBe(baseline.status);
+    expect(withDiagnostic.fatalForCi).toBe(baseline.fatalForCi);
+    expect(withDiagnostic.roster).toMatchObject({ active: 1, inert: 1 });
+    expect(withDiagnostic.configDiagnostics).toHaveLength(1);
+  });
 });