@usefragments/core 1.5.0 → 1.5.2

package/src/governance-integrity.ts

@@ -24,6 +24,23 @@ import { BLOCKING_RULE_ALLOWLIST } from "./rules/emit-gate.js";
 
 export type GovernanceIntegrityStatus = "healthy" | "degraded" | "inert";
 
+export type InertConfigDiagnosticKind = "orphan-scale" | "unconsumed-key";
+export type InertConfigDiagnosticCode = "FUI9004" | "FUI9005";
+
+export interface InertConfigDiagnostic {
+  code: InertConfigDiagnosticCode;
+  kind: InertConfigDiagnosticKind;
+  severity: "warn";
+  path: string;
+  message: string;
+}
+
+export interface GovernanceIntegrityRoster {
+  configured: number;
+  active: number;
+  inert: number;
+}
+
 export type GovernanceIntegrityFamilyId =
   | "policy"
   | "components"
@@ -53,6 +70,8 @@ export interface GovernanceIntegrityInput {
   /** Whether `tokens/css-vars-must-be-defined` is activated (caller supplies). */
   cssVarsActive?: boolean;
   mode?: "scan" | "ci" | "hook" | "doctor" | "setup";
+  /** Named, verdict-neutral diagnostics derived from the authored config. */
+  configDiagnostics?: readonly InertConfigDiagnostic[];
 }
 
 export interface GovernanceIntegrityVerdict {
@@ -64,6 +83,8 @@ export interface GovernanceIntegrityVerdict {
   armed: GovernanceIntegrityFamilyId[];
   summary: string;
   remediations: string[];
+  configDiagnostics?: InertConfigDiagnostic[];
+  roster?: GovernanceIntegrityRoster;
 }
 
 interface EffectiveRuleConfig {
@@ -131,6 +152,287 @@ function dedupe(values: string[]): string[] {
   return [...new Set(values)];
 }
 
+const RULE_FAMILY_IDS = new Set(["tokens/hardcoded-values", "components/usage", "a11y/wcag"]);
+const CONSUMED_RULE_IDS = new Set(Object.keys(RULE_TIER));
+const RECOGNIZED_RULE_IDS = new Set([...CONSUMED_RULE_IDS, ...RULE_FAMILY_IDS]);
+const RULE_CONFIG_KEYS = new Set(["enabled", "severity", "options"]);
+
+const PASSTHROUGH_KEYS = [
+  {
+    path: ["tokens"],
+    keys: [
+      "include",
+      "sources",
+      "packages",
+      "aliases",
+      "upstream",
+      "exclude",
+      "themeSelectors",
+      "enabled",
+      "format",
+      "namespace",
+    ],
+  },
+  {
+    path: ["screenshots"],
+    keys: ["viewport", "threshold", "delay", "outputDir", "themes"],
+  },
+  {
+    path: ["service"],
+    keys: ["poolSize", "idleTimeout"],
+  },
+  {
+    path: ["registry"],
+    keys: ["requireStory", "publicOnly", "categoryDepth", "includeProps", "embedFragments"],
+  },
+  {
+    path: ["govern", "tailwind"],
+    keys: ["palette"],
+  },
+  {
+    path: ["govern", "agent"],
+    keys: ["repairOrder"],
+  },
+  {
+    path: ["govern", "ci"],
+    keys: ["failOnWarnings"],
+  },
+] as const;
+
+function objectRecord(value: unknown): Record<string, unknown> | undefined {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+  return value as Record<string, unknown>;
+}
+
+function valueAtPath(value: unknown, path: readonly string[]): unknown {
+  let current = value;
+  for (const segment of path) {
+    const record = objectRecord(current);
+    if (!record) return undefined;
+    current = record[segment];
+  }
+  return current;
+}
+
+function configPath(path: readonly (string | number)[]): string {
+  return path.reduce<string>(
+    (output, segment) =>
+      typeof segment === "number"
+        ? `${output}[${segment}]`
+        : output
+          ? `${output}.${segment}`
+          : segment,
+    ""
+  );
+}
+
+function unconsumedKeyDiagnostic(path: readonly (string | number)[]): InertConfigDiagnostic {
+  const renderedPath = configPath(path);
+  return {
+    code: "FUI9004",
+    kind: "unconsumed-key",
+    severity: "warn",
+    path: renderedPath,
+    message: `${renderedPath} is not consumed by Fragments and has no effect. Remove it or use a supported config key.`,
+  };
+}
+
+function collectStrippedKeys(
+  authored: unknown,
+  parsed: unknown,
+  path: readonly (string | number)[],
+  diagnostics: InertConfigDiagnostic[]
+): void {
+  if (Array.isArray(authored)) {
+    if (!Array.isArray(parsed)) return;
+    authored.forEach((item, index) => {
+      collectStrippedKeys(item, parsed[index], [...path, index], diagnostics);
+    });
+    return;
+  }
+
+  const authoredRecord = objectRecord(authored);
+  const parsedRecord = objectRecord(parsed);
+  if (!authoredRecord || !parsedRecord) return;
+
+  for (const key of Object.keys(authoredRecord).sort()) {
+    if (!Object.prototype.hasOwnProperty.call(parsedRecord, key)) {
+      diagnostics.push(unconsumedKeyDiagnostic([...path, key]));
+      continue;
+    }
+    collectStrippedKeys(authoredRecord[key], parsedRecord[key], [...path, key], diagnostics);
+  }
+}
+
+function collectPassthroughKeys(
+  authored: unknown,
+  path: readonly string[],
+  allowed: ReadonlySet<string>,
+  diagnostics: InertConfigDiagnostic[]
+): void {
+  const record = objectRecord(valueAtPath(authored, path));
+  if (!record) return;
+  for (const key of Object.keys(record).sort()) {
+    if (!allowed.has(key)) diagnostics.push(unconsumedKeyDiagnostic([...path, key]));
+  }
+}
+
+function collectRuleConfigKeys(
+  authored: unknown,
+  path: readonly string[],
+  diagnostics: InertConfigDiagnostic[]
+): void {
+  const rules = objectRecord(valueAtPath(authored, path));
+  if (!rules) return;
+  for (const ruleId of Object.keys(rules).sort()) {
+    if (!RECOGNIZED_RULE_IDS.has(ruleId)) {
+      diagnostics.push(unconsumedKeyDiagnostic([...path, ruleId]));
+      continue;
+    }
+    const config = objectRecord(rules[ruleId]);
+    if (!config) continue;
+    for (const key of Object.keys(config).sort()) {
+      if (!RULE_CONFIG_KEYS.has(key)) {
+        diagnostics.push(unconsumedKeyDiagnostic([...path, ruleId, key]));
+      }
+    }
+  }
+}
+
+function collectPassthroughRecordValues(
+  authored: unknown,
+  path: readonly string[],
+  allowed: ReadonlySet<string>,
+  diagnostics: InertConfigDiagnostic[]
+): void {
+  const entries = objectRecord(valueAtPath(authored, path));
+  if (!entries) return;
+  for (const [entryName, value] of Object.entries(entries).sort(([left], [right]) =>
+    left.localeCompare(right)
+  )) {
+    const record = objectRecord(value);
+    if (!record) continue;
+    for (const key of Object.keys(record).sort()) {
+      if (!allowed.has(key)) {
+        diagnostics.push(unconsumedKeyDiagnostic([...path, entryName, key]));
+      }
+    }
+  }
+}
+
+function stableConfigDiagnostics(
+  diagnostics: readonly InertConfigDiagnostic[]
+): InertConfigDiagnostic[] {
+  const unique = new Map<string, InertConfigDiagnostic>();
+  for (const diagnostic of diagnostics) {
+    unique.set(`${diagnostic.code}\0${diagnostic.path}`, diagnostic);
+  }
+  return [...unique.values()].sort(
+    (left, right) =>
+      left.path.localeCompare(right.path) ||
+      left.code.localeCompare(right.code) ||
+      left.message.localeCompare(right.message)
+  );
+}
+
+/**
+ * Diagnose config keys that the permissive validation boundary accepts but the
+ * runtime cannot consume. The parsed config is the source of truth for stripped
+ * keys; explicit allow-sets cover intentional `.passthrough()`/record seams.
+ */
+export function detectUnconsumedConfigKeys(
+  authoredConfig: unknown,
+  parsedConfig: unknown
+): InertConfigDiagnostic[] {
+  const diagnostics: InertConfigDiagnostic[] = [];
+  collectStrippedKeys(authoredConfig, parsedConfig, [], diagnostics);
+
+  for (const boundary of PASSTHROUGH_KEYS) {
+    collectPassthroughKeys(
+      authoredConfig,
+      boundary.path,
+      new Set<string>(boundary.keys),
+      diagnostics
+    );
+  }
+
+  collectRuleConfigKeys(authoredConfig, ["govern", "rules"], diagnostics);
+  collectPassthroughRecordValues(
+    authoredConfig,
+    ["govern", "agents"],
+    new Set(["rules"]),
+    diagnostics
+  );
+  collectPassthroughKeys(authoredConfig, ["govern", "audit"], new Set(), diagnostics);
+  collectPassthroughRecordValues(authoredConfig, ["govern", "runners"], new Set(), diagnostics);
+
+  return stableConfigDiagnostics(diagnostics);
+}
+
+interface ScaleBinding {
+  label: string;
+  mechanism: string;
+  scale: string;
+}
+
+function effectiveScaleBindings(policy: GovernanceConfig | undefined): ScaleBinding[] {
+  const bindings: ScaleBinding[] = [];
+  for (const style of policy?.styles ?? []) {
+    if (style.kind === "style.rawSpacing.mustMatchScale") {
+      bindings.push({
+        label: "Spacing properties",
+        mechanism: "style.rawSpacing.mustMatchScale",
+        scale: style.scale,
+      });
+    } else if (style.kind === "style.fontSize.mustMatchScale") {
+      bindings.push({
+        label: "Font-size properties",
+        mechanism: "style.fontSize.mustMatchScale",
+        scale: style.scale,
+      });
+    }
+  }
+  return bindings;
+}
+
+/**
+ * Compare locally declared scales with the effective property-policy graph.
+ * Preset-only scales are not diagnosed because the user did not declare them.
+ */
+export function detectOrphanGovernanceScales(
+  declaredPolicy: GovernanceConfig | undefined,
+  effectivePolicy: GovernanceConfig | undefined
+): InertConfigDiagnostic[] {
+  const bindings = effectiveScaleBindings(effectivePolicy);
+  const referenced = new Set(bindings.map((binding) => binding.scale));
+  const diagnostics: InertConfigDiagnostic[] = [];
+
+  for (const scale of Object.keys(declaredPolicy?.scales ?? {}).sort()) {
+    if (referenced.has(scale)) continue;
+    const path = `govern.scales.${scale}`;
+    const preferred =
+      (scale.toLowerCase().includes("spac")
+        ? bindings.find((binding) => binding.mechanism === "style.rawSpacing.mustMatchScale")
+        : undefined) ??
+      (scale.toLowerCase().includes("font")
+        ? bindings.find((binding) => binding.mechanism === "style.fontSize.mustMatchScale")
+        : undefined) ??
+      bindings[0];
+    const remediation = preferred
+      ? `${preferred.label} are bound to the scale named "${preferred.scale}" — rename the key to "${preferred.scale}" or bind it via ${preferred.mechanism}.`
+      : `Bind it via style.rawSpacing.mustMatchScale or style.fontSize.mustMatchScale, or remove it.`;
+    diagnostics.push({
+      code: "FUI9005",
+      kind: "orphan-scale",
+      severity: "warn",
+      path,
+      message: `${path} is not referenced by any property policy. ${remediation}`,
+    });
+  }
+
+  return stableConfigDiagnostics(diagnostics);
+}
+
 function summarize(
   status: GovernanceIntegrityStatus,
   flags: { componentsArmed: boolean; tokensArmed: boolean; blockingArmed: boolean }
@@ -152,6 +454,7 @@ export function evaluateGovernanceIntegrity(
   input: GovernanceIntegrityInput
 ): GovernanceIntegrityVerdict {
   const configs = effectiveRuleConfigs(input.policy);
+  const configDiagnostics = stableConfigDiagnostics(input.configDiagnostics ?? []);
 
   // --- policy family --------------------------------------------------------
   const policyArmed = input.policy !== undefined && input.policySource !== "none";
@@ -166,23 +469,29 @@ export function evaluateGovernanceIntegrity(
 
   // --- components family ----------------------------------------------------
   const componentsConfig = configs.get("components/prefer-library");
+  const confirmedBridges = input.policy?.canonicalBridges ?? [];
   const componentsArmed =
-    componentsConfig?.enabled === true && hasEffectiveComponentVocabulary(componentsConfig.options);
+    confirmedBridges.length > 0 ||
+    (componentsConfig?.enabled === true &&
+      hasEffectiveComponentVocabulary(componentsConfig.options));
   const componentsFamily: GovernanceIntegrityFamily = {
     id: "components",
     armed: componentsArmed,
-    rules: ["components/prefer-library"],
+    rules: [
+      ...(confirmedBridges.length > 0 ? ["imports/preferred-path"] : []),
+      ...(componentsConfig?.enabled === true ? ["components/prefer-library"] : []),
+    ],
   };
   if (!componentsArmed) {
     if (componentsConfig?.enabled === true) {
       componentsFamily.reason =
         "components/prefer-library enabled but no effective canonical source";
       componentsFamily.remediation =
-        "add govern.canonicalSources (a directory source, or npm/registry with a non-empty include) or designSystem.path/packageName";
+        "add govern.canonicalBridges for local wrappers, govern.canonicalSources, or designSystem.path/packageName";
     } else {
       componentsFamily.reason = "components/prefer-library not enabled";
       componentsFamily.remediation =
-        "add govern.canonicalSources (a directory source, or npm/registry with a non-empty include) or designSystem.path/packageName";
+        "add govern.canonicalBridges for local wrappers, govern.canonicalSources, or designSystem.path/packageName";
     }
   }
 
@@ -274,6 +583,17 @@ export function evaluateGovernanceIntegrity(
       .filter((remediation): remediation is string => remediation !== undefined)
   );
   const summary = summarize(status, { componentsArmed, tokensArmed, blockingArmed });
+  const configuredRuleCount = [...configs.keys()].filter((ruleId) =>
+    CONSUMED_RULE_IDS.has(ruleId)
+  ).length;
+  const activeRuleCount = [...configs.entries()].filter(
+    ([ruleId, config]) => CONSUMED_RULE_IDS.has(ruleId) && config.enabled
+  ).length;
+  const roster = {
+    configured: configuredRuleCount + configDiagnostics.length,
+    active: activeRuleCount,
+    inert: configDiagnostics.length,
+  };
 
   return {
     status,
@@ -284,5 +604,7 @@ export function evaluateGovernanceIntegrity(
     armed,
     summary,
     remediations,
+    configDiagnostics,
+    roster,
   };
 }

package/src/governance.test.ts

@@ -1,5 +1,12 @@
 import { describe, expect, it } from "vitest";
-import { compileFragment, defineConfig, defineFragment, g } from "./index.js";
+import {
+  compileFragment,
+  configDeclarationForDiagnostics,
+  defineConfig,
+  defineFragment,
+  g,
+  type FragmentsConfig,
+} from "./index.js";
 
 type ButtonProps = {
   variant?: "primary" | "secondary" | "ghost" | "link";
@@ -12,6 +19,18 @@ function Button(_props: ButtonProps) {
 }
 
 describe("governance DSL", () => {
+  it("preserves the authored declaration for stripped-key diagnostics", () => {
+    const authored = {
+      include: ["src/**/*.fragment.ts"],
+      styles: { spacing: true },
+    };
+    const config = defineConfig(authored as FragmentsConfig);
+
+    expect(config).not.toHaveProperty("styles");
+    expect(configDeclarationForDiagnostics(config)).toBe(authored);
+    expect(Object.keys(config)).toEqual(["include"]);
+  });
+
   it("defineConfig accepts global governance records", () => {
     const config = defineConfig({
       include: ["src/**/*.fragment.ts"],
@@ -139,6 +158,73 @@ describe("governance DSL", () => {
     });
   });
 
+  it("accepts one confirmed package-to-local canonical bridge", () => {
+    const config = defineConfig({
+      govern: {
+        canonicalBridges: [
+          {
+            underlying: { packageName: "@mui/material", exportName: "Button" },
+            local: {
+              componentKey: "src/components/Button.tsx#Button",
+              moduleSpecifier: "@/components",
+              exportName: "Button",
+              implementationFiles: ["src/components/Button.tsx"],
+            },
+            decision: { state: "confirmed", source: "authored" },
+          },
+        ],
+      },
+    });
+
+    expect(config.govern?.canonicalBridges?.[0]).toMatchObject({
+      underlying: { packageName: "@mui/material", exportName: "Button" },
+      local: { moduleSpecifier: "@/components", exportName: "Button" },
+      decision: { state: "confirmed", source: "authored" },
+    });
+  });
+
+  it("rejects ambiguous or unsafe canonical bridge declarations", () => {
+    const bridge = {
+      underlying: { packageName: "@mui/material", exportName: "Button" },
+      local: {
+        componentKey: "src/components/Button.tsx#Button",
+        moduleSpecifier: "@/components",
+        exportName: "Button",
+        implementationFiles: ["src/components/Button.tsx"],
+      },
+      decision: { state: "confirmed" as const, source: "authored" as const },
+    };
+
+    expect(() => defineConfig({ govern: { canonicalBridges: [bridge, bridge] } })).toThrow(
+      "Invalid fragments config"
+    );
+    expect(() =>
+      defineConfig({
+        govern: {
+          canonicalBridges: [
+            bridge,
+            {
+              ...bridge,
+              underlying: { packageName: "@radix-ui/react-slot", exportName: "Slot" },
+            },
+          ],
+        },
+      })
+    ).toThrow("Invalid fragments config");
+    expect(() =>
+      defineConfig({
+        govern: {
+          canonicalBridges: [
+            {
+              ...bridge,
+              local: { ...bridge.local, moduleSpecifier: "../components" },
+            },
+          ],
+        },
+      })
+    ).toThrow("Invalid fragments config");
+  });
+
   it("preserves top-level component identity decisions", () => {
     const config = defineConfig({
       identity: {

package/src/governance.ts

@@ -192,6 +192,79 @@ const canonicalSourcePathSchema = z
 
 const canonicalSourceRegistryHashSchema = z.string().regex(/^[0-9a-f]{64}$/);
 
+const canonicalBridgeModuleSpecifierSchema = z
+  .string()
+  .min(1)
+  .superRefine((value, ctx) => {
+    const normalized = value.replace(/\\/gu, "/");
+    if (normalized.startsWith("/") || /^[A-Za-z]:\//u.test(normalized)) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: "Canonical bridge moduleSpecifier must be a portable import specifier",
+      });
+    }
+    if (normalized.split("/").includes("..")) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: "Canonical bridge moduleSpecifier must not traverse outside the project",
+      });
+    }
+  });
+
+export const canonicalBridgeV1Schema = z
+  .object({
+    underlying: z
+      .object({
+        packageName: z.string().min(1),
+        exportName: z.string().min(1),
+      })
+      .strict(),
+    local: z
+      .object({
+        componentKey: z.string().min(1),
+        moduleSpecifier: canonicalBridgeModuleSpecifierSchema,
+        exportName: z.string().min(1),
+        implementationFiles: z.array(canonicalSourcePathSchema).min(1),
+      })
+      .strict(),
+    decision: z
+      .object({
+        state: z.literal("confirmed"),
+        source: z.enum(["authored", "migration"]),
+      })
+      .strict(),
+  })
+  .strict();
+
+const canonicalBridgesV1Schema = z.array(canonicalBridgeV1Schema).superRefine((bridges, ctx) => {
+  const underlying = new Map<string, number>();
+  const componentKeys = new Map<string, number>();
+  for (const [index, bridge] of bridges.entries()) {
+    const underlyingKey = `${bridge.underlying.packageName}\u0000${bridge.underlying.exportName}`;
+    const previousUnderlying = underlying.get(underlyingKey);
+    if (previousUnderlying !== undefined) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: `Duplicate confirmed bridge target for ${bridge.underlying.packageName}#${bridge.underlying.exportName} (also at canonicalBridges.${previousUnderlying})`,
+        path: [index, "underlying"],
+      });
+    } else {
+      underlying.set(underlyingKey, index);
+    }
+
+    const previousComponent = componentKeys.get(bridge.local.componentKey);
+    if (previousComponent !== undefined) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: `Local component key overlaps canonicalBridges.${previousComponent}`,
+        path: [index, "local", "componentKey"],
+      });
+    } else {
+      componentKeys.set(bridge.local.componentKey, index);
+    }
+  }
+});
+
 const canonicalSourceSchema = z.discriminatedUnion("kind", [
   z.object({
     kind: z.literal("npm"),
@@ -237,6 +310,7 @@ export const governanceConfigSchema = z
     audit: z.object({}).passthrough().optional(),
     runners: z.record(z.string(), z.object({}).passthrough()).optional(),
     canonicalSources: z.array(canonicalSourceSchema).optional(),
+    canonicalBridges: canonicalBridgesV1Schema.optional(),
     presets: z.array(z.string()).optional(),
     scales: z.record(z.string(), scaleGovernanceRecordSchema).optional(),
     styles: z.array(globalStyleGovernanceRecordSchema).optional(),
@@ -278,19 +352,58 @@ export type ComponentPolicyMatch = z.infer<typeof componentPolicyMatchSchema>;
 export type ComponentPolicyRecord = z.infer<typeof componentPolicyRecordSchema>;
 export type ComponentPolicyOverride = z.infer<typeof componentPolicyOverrideSchema>;
 export type CanonicalSource = z.infer<typeof canonicalSourceSchema>;
+export type CanonicalBridgeV1 = z.infer<typeof canonicalBridgeV1Schema>;
 
 export interface GovernanceConfig {
+  /** Shared governance config modules to extend before applying this file's declarations. */
   extends?: string[];
+
+  /** Default severity for governance rules that do not declare their own severity. */
   severity?: GovernanceSeverity;
+
+  /**
+   * Rule-id keyed enablement and severity overrides. Only fields consumed by the named
+   * rule are valid; unsupported fields are reported as inert config.
+   */
   rules?: Record<string, unknown>;
+
+  /** Agent-id keyed rule overrides for supported agent-specific governance policies. */
   agents?: Record<string, { rules?: Record<string, unknown> }>;
+
+  /** Reserved audit compatibility object; undeclared child keys are reported as inert. */
   audit?: Record<string, unknown>;
+
+  /** Reserved runner compatibility map; undeclared child keys are reported as inert. */
   runners?: Record<string, Record<string, unknown>>;
+
+  /**
+   * Canonical component authorities: npm packages, repository directories, or registry
+   * receipts whose included exports arm canonical-component rules.
+   */
   canonicalSources?: CanonicalSource[];
+
+  /**
+   * Confirmed mappings from an underlying library export to the approved local wrapper.
+   * The wrapper's implementationFiles scope permits its direct underlying import.
+   */
+  canonicalBridges?: CanonicalBridgeV1[];
+
+  /** Versioned governance presets to resolve before applying local rule overrides. */
   presets?: string[];
+
+  /**
+   * Named numeric scales. Spacing rules bind through
+   * style.rawSpacing.mustMatchScale; the built-in spacing policy references `space`.
+   */
   scales?: Record<string, ScaleGovernanceRecord>;
+
+  /** Legacy typed style-policy records, normalized into the active rule policy. */
   styles?: GlobalStyleGovernanceRecord[];
+
+  /** Legacy typed JSX-policy records, normalized into the active rule policy. */
   jsx?: GlobalJsxGovernanceRecord[];
+
+  /** Tailwind palette allow/deny policy used by Tailwind governance rules. */
   tailwind?: {
     palette?: {
       allow?: string[];
@@ -298,12 +411,20 @@ export interface GovernanceConfig {
     };
     [key: string]: unknown;
   };
+
+  /** Agent repair-order guidance consumed when presenting deterministic fixes. */
   agent?: {
     repairOrder?: string[];
     [key: string]: unknown;
   };
+
+  /** Component-keyed governance records for canonical component metadata and prop policy. */
   components?: Record<string, ComponentPolicyRecord>;
+
+  /** Ordered component-policy overrides selected by component identity fields. */
   overrides?: ComponentPolicyOverride[];
+
+  /** Governance CI rendering options, including whether warnings fail the CI verdict. */
   ci?: {
     failOnWarnings?: boolean;
     [key: string]: unknown;