@usefragments/core 1.5.1 → 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";
@@ -280,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,
@@ -290,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"],

package/src/governance.ts

@@ -355,18 +355,55 @@ 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[];
@@ -374,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;

package/src/index.ts

@@ -425,7 +425,7 @@ export {
 } from "./schema.js";
 
 // Main API
-export { defineConfig } from "./config.js";
+export { configDeclarationForDiagnostics, defineConfig } from "./config.js";
 export {
   defineFragment,
   compileFragment,
@@ -713,6 +713,8 @@ export { BLOCKING_RULE_ALLOWLIST, gatesCi, isDenyEligible } from "./rules/index.
 // Governance integrity — armed-vs-declared verdict over a fully-resolved policy.
 // Encodes "enabled ≠ armed": a rule with no vocabulary enforces nothing.
 export {
+  detectOrphanGovernanceScales,
+  detectUnconsumedConfigKeys,
   evaluateGovernanceIntegrity,
   hasEffectiveComponentVocabulary,
   isEffectiveCanonicalSource,
@@ -721,8 +723,12 @@ export type {
   GovernanceIntegrityFamily,
   GovernanceIntegrityFamilyId,
   GovernanceIntegrityInput,
+  GovernanceIntegrityRoster,
   GovernanceIntegrityStatus,
   GovernanceIntegrityVerdict,
+  InertConfigDiagnostic,
+  InertConfigDiagnosticCode,
+  InertConfigDiagnosticKind,
 } from "./governance-integrity.js";
 
 export {

package/src/rules/styles-no-raw-spacing.test.ts

@@ -0,0 +1,48 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  compileGlobalGovernanceFacts,
+  FactIndex,
+  g,
+  makeStyleDeclarationFact,
+  ruleStylesNoRawSpacing,
+} from "../index.js";
+
+describe("styles/no-raw-spacing fork copy", () => {
+  it("names the active scale and its config lever without changing machine attributes", () => {
+    const ix = new FactIndex();
+    ix.addMany(
+      compileGlobalGovernanceFacts({
+        scales: {
+          space: g.scale.px([0, 4, 8, 12, 16, 20, 24]),
+        },
+        styles: [
+          g.styles.rawSpacing().mustMatchScale("space", {
+            appliesTo: ["margin-top"],
+            severity: "warn",
+          }),
+        ],
+      })
+    );
+    ix.add(
+      makeStyleDeclarationFact({
+        file: "src/Card.css",
+        selector: ".card",
+        declarationPath: "0",
+        property: "margin-top",
+        value: "10px",
+        location: { file: "src/Card.css", line: 2, column: 3 },
+      })
+    );
+
+    const [finding] = ruleStylesNoRawSpacing(ix);
+
+    expect(finding?.message).toContain("not on the `space` scale");
+    expect(finding?.message).toContain("Configure `govern.scales.space` to change it");
+    expect(finding?.attributes).toMatchObject({
+      scale: "space",
+      rawValue: "10px",
+      source: "css",
+    });
+  });
+});

package/src/rules/styles-no-raw-spacing.ts

@@ -117,7 +117,7 @@ function checkDeclaration(
     ruleId: RULE_ID,
     ruleVersion: RULE_VERSION,
     severity: policy.severity,
-    message: spacingMessage(decl.property, decl.value, allowed, scale.unit, checked),
+    message: spacingMessage(decl.property, decl.value, allowed, scale, checked),
     location: decl.location,
     evidence: ix.evidence([decl.id, policy.id, scale.id]),
     fingerprintIdentity: {
@@ -185,7 +185,7 @@ function checkInlineStyle(
     ruleId: RULE_ID,
     ruleVersion: RULE_VERSION,
     severity: policy.severity,
-    message: spacingMessage(inline.property, inline.value, allowed, scale.unit, checked),
+    message: spacingMessage(inline.property, inline.value, allowed, scale, checked),
     location: node.location,
     evidence: ix.evidence(evidenceIds),
     fingerprintIdentity: {
@@ -245,7 +245,7 @@ function spacingMessage(
   property: string,
   value: string,
   allowed: number[],
-  unit: "px" | "rem",
+  scale: ScaleFact,
   checked: CheckedSpacingValue
 ): string {
   if (checked.reason === "token-equivalent" && checked.matchedToken) {
@@ -255,7 +255,7 @@ function spacingMessage(
     .slice()
     .sort((a, b) => a - b)
     .slice(0, 6);
-  const suffix = `${sample.join(unit + ", ")}${unit}`;
+  const suffix = `${sample.join(scale.unit + ", ")}${scale.unit}`;
   const ellipsis = allowed.length > sample.length ? ", …" : "";
-  return `\`${property}: ${value}\` is not on the spacing scale. Allowed: ${suffix}${ellipsis}.`;
+  return `\`${property}: ${value}\` is not on the \`${scale.name}\` scale. Allowed: ${suffix}${ellipsis}. Configure \`govern.scales.${scale.name}\` to change it.`;
 }

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[];
 
   /**
@@ -613,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') */
@@ -813,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;
     }>;
   };