@usefragments/core 1.5.0 → 1.5.2

package/src/index.ts

@@ -227,6 +227,12 @@ export type {
 // Token types
 export type {
   TokenCategory,
+  TokenCatalog,
+  TokenCatalogDefinition,
+  TokenCatalogDiagnostic,
+  TokenCatalogLocation,
+  TokenCatalogReference,
+  TokenCatalogSourceState,
   DesignToken,
   TokenRegistry,
   TokenRegistryMeta,
@@ -419,7 +425,7 @@ export {
 } from "./schema.js";
 
 // Main API
-export { defineConfig } from "./config.js";
+export { configDeclarationForDiagnostics, defineConfig } from "./config.js";
 export {
   defineFragment,
   compileFragment,
@@ -435,6 +441,7 @@ export type { InferProps } from "./defineFragment.js";
 export {
   componentGovernanceRecordSchema,
   componentGovernanceRecordsSchema,
+  canonicalBridgeV1Schema,
   g,
   globalGovernanceRecordSchema,
   globalJsxGovernanceRecordSchema,
@@ -446,6 +453,7 @@ export {
 } from "./governance.js";
 export type {
   AccessibilityGovernanceBuilder,
+  CanonicalBridgeV1,
   CanonicalSource,
   ComponentGovernanceBuilder,
   ComponentGovernanceRecord,
@@ -645,10 +653,7 @@ export {
   ruleTokensRequireDualFallback,
   ruleA11yRequiredAccessibleName,
 } from "./rules/index.js";
-export {
-  indexComponentIdentityUsage,
-  type ComponentIdentityUsage,
-} from "./identity/usage.js";
+export { indexComponentIdentityUsage, type ComponentIdentityUsage } from "./identity/usage.js";
 export { nearestSignedScaleValue } from "./rules/utils.js";
 export {
   buildSpacingTokenLookup,
@@ -708,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,
@@ -716,10 +723,32 @@ export type {
   GovernanceIntegrityFamily,
   GovernanceIntegrityFamilyId,
   GovernanceIntegrityInput,
+  GovernanceIntegrityRoster,
   GovernanceIntegrityStatus,
   GovernanceIntegrityVerdict,
+  InertConfigDiagnostic,
+  InertConfigDiagnosticCode,
+  InertConfigDiagnosticKind,
 } from "./governance-integrity.js";
 
+export {
+  canonicalDirectionConflictsTarget,
+  projectCanonicalDirectionConflicts,
+} from "./canonical-direction.js";
+export type { CanonicalDirectionConflict } from "./canonical-direction.js";
+
+export { canonicalBridgeContractMappings } from "./canonical-bridge.js";
+
+export {
+  compileEffectiveGovernanceInputs,
+  EFFECTIVE_GOVERNANCE_INPUTS_SCHEMA,
+} from "./effective-governance-inputs.js";
+export type {
+  CompileEffectiveGovernanceInputsOptions,
+  EffectiveGovernanceInputs,
+  EffectiveGovernanceInputsSourceState,
+} from "./effective-governance-inputs.js";
+
 // Fact IR + index (Phase 3 of the governance compiler refactor)
 export {
   componentId,

package/src/rules/__tests__/fix-emission-invariant.test.ts

@@ -65,6 +65,34 @@ describe("proof-carrying fix invariant", () => {
       "token reference is not directly applicable"
     );
   });
+
+  it("keeps JavaScript member tokens advisory without inventing a CSS variable", () => {
+    const ix = buildFixtureCorpus("js-member", "radii.md");
+    const dimension = RULES.find((rule) => rule.id === "styles/no-raw-dimensions")
+      ?.run(ix)
+      .find((finding) => finding.fix);
+
+    expect(dimension?.fix).toMatchObject({
+      value: "radii.md",
+      deterministic: false,
+    });
+    expect(JSON.stringify(dimension?.fix)).not.toContain("var(--radii-md)");
+    expect(dimension?.attributes?.downgradeReason).toContain(
+      "token reference is not directly applicable"
+    );
+  });
+
+  it("fails closed when a legacy token fact has no authored reference format", () => {
+    const ix = buildFixtureCorpus("unknown");
+    const dimension = RULES.find((rule) => rule.id === "styles/no-raw-dimensions")
+      ?.run(ix)
+      .find((finding) => finding.fix);
+
+    expect(dimension?.fix?.deterministic).toBe(false);
+    expect(dimension?.attributes?.downgradeReason).toContain(
+      "token reference is not directly applicable"
+    );
+  });
 });
 
 function runEveryRule(ix: FactIndex): Finding[] {
@@ -98,7 +126,10 @@ function withoutDeterminism(fix: FindingFix): Omit<FindingFix, "deterministic">
   return rest;
 }
 
-function buildFixtureCorpus(radiusReferenceFormat: "css-var" | "dtcg" = "css-var"): FactIndex {
+function buildFixtureCorpus(
+  radiusReferenceFormat: "css-var" | "dtcg" | "js-member" | "unknown" = "css-var",
+  radiusName = "--proof-radius"
+): FactIndex {
   const ix = new FactIndex();
   ix.addMany([
     makeTokenDefinitionFact({
@@ -116,11 +147,11 @@ function buildFixtureCorpus(radiusReferenceFormat: "css-var" | "dtcg" = "css-var
       sourceNames: ["--proof-space"],
     }),
     makeTokenDefinitionFact({
-      name: "--proof-radius",
+      name: radiusName,
       value: "4px",
       category: "radius",
-      referenceFormat: radiusReferenceFormat,
-      sourceNames: ["--proof-radius"],
+      referenceFormat: radiusReferenceFormat === "unknown" ? undefined : radiusReferenceFormat,
+      sourceNames: [radiusName],
     }),
     makeTokenDefinitionFact({
       name: "--proof-font",

package/src/rules/components-prefer-library.test.ts

@@ -4,6 +4,7 @@ import {
   asComponentId,
   compileGlobalGovernanceFacts,
   FactIndex,
+  makeComponentDefinitionFact,
   makeComponentIdentityFact,
   makeUsageComponentFact,
   makeUsageImportFact,
@@ -11,6 +12,108 @@ import {
   ruleComponentsPreferLibrary,
 } from "../index.js";
 
+describe("components/prefer-library — canonical direction containment", () => {
+  const componentKey = "src/components/Button.tsx#Button";
+
+  function indexFor(decision?: "sanction" | "reject", exported = true) {
+    const ix = new FactIndex();
+    ix.addMany(
+      compileGlobalGovernanceFacts({
+        rules: {
+          "components/prefer-library": {
+            enabled: true,
+            severity: "warning",
+            options: {
+              canonicalSources: [
+                { kind: "npm", specifier: "@mui/material", include: ["Button", "Stepper"] },
+              ],
+            },
+          },
+        },
+      })
+    );
+    const definition = makeComponentDefinitionFact({
+      file: "src/components/Button.tsx",
+      exportName: "Button",
+      exported,
+      componentKey,
+      renderRoot: {
+        resolution: "canonical",
+        canonical: "@mui/material#Button",
+        importSource: "@mui/material",
+      },
+      propSurface: [],
+    });
+    ix.add(definition);
+    ix.add(
+      makeComponentIdentityFact({
+        componentKey,
+        state: decision === "reject" ? "shadow" : "variant",
+        confidence: decision ? "confirmed" : "review",
+        canonicalTarget: "Button",
+        ...(decision ? { decisionId: `local:${decision}:${componentKey}` } : {}),
+        evidence: [definition.id],
+      })
+    );
+    return ix;
+  }
+
+  function addLocalUsage(ix: FactIndex, name: "Button" | "Stepper") {
+    ix.add(
+      makeUsageNodeFact({
+        file: "src/App.tsx",
+        nodePath: `0:${name}`,
+        element: name,
+        location: { file: "src/App.tsx", line: 3, column: 2 },
+      })
+    );
+    ix.add(
+      makeUsageImportFact({
+        file: "src/App.tsx",
+        local: name,
+        imported: name,
+        source: `./components/${name}`,
+        location: { file: "src/App.tsx", line: 1, column: 0 },
+      })
+    );
+  }
+
+  it("suppresses only the exact conflicted npm export when direction is unresolved", () => {
+    const ix = indexFor();
+    addLocalUsage(ix, "Button");
+    addLocalUsage(ix, "Stepper");
+    ix.add(
+      makeUsageNodeFact({
+        file: "src/App.tsx",
+        nodePath: "0:raw-button",
+        element: "button",
+        interactive: true,
+        location: { file: "src/App.tsx", line: 4, column: 2 },
+      })
+    );
+
+    const findings = ruleComponentsPreferLibrary(ix);
+    expect(findings).toHaveLength(1);
+    expect(findings[0]?.attributes?.suggestedComponent).toBe("Stepper");
+  });
+
+  it("keeps a sanctioned wrapper exempt and restores npm guidance after explicit rejection", () => {
+    const sanctioned = indexFor("sanction");
+    addLocalUsage(sanctioned, "Button");
+    expect(ruleComponentsPreferLibrary(sanctioned)).toHaveLength(0);
+
+    const rejected = indexFor("reject");
+    addLocalUsage(rejected, "Button");
+    expect(ruleComponentsPreferLibrary(rejected)).toHaveLength(1);
+  });
+
+  it("does not let a private helper deactivate canonical policy", () => {
+    const ix = indexFor(undefined, false);
+    addLocalUsage(ix, "Button");
+    expect(ruleComponentsPreferLibrary(ix)).toHaveLength(1);
+  });
+});
+
 // #9e — import-path identity for a DIRECTORY canonical source. A directory
 // source (e.g. `src/components/ui`) declares its canonical component NAMES via an
 // include list. The rule must:

package/src/rules/components-prefer-library.ts

@@ -15,6 +15,11 @@ import {
   type RawHtmlPrecisionTier,
 } from "../raw-html-canonical.js";
 import { ownedImportMatchesRoot, ownedImportsEqual } from "../package-identity-match.js";
+import {
+  canonicalDirectionConflictsTarget,
+  projectCanonicalDirectionConflicts,
+  type CanonicalDirectionConflict,
+} from "../canonical-direction.js";
 
 import { makeFinding } from "./finding.js";
 import type { Finding } from "./types.js";
@@ -254,8 +259,12 @@ function findClassNameReimpl(
 export function ruleComponentsPreferLibrary(ix: FactIndex): Finding[] {
   const policy = ix.policy.ruleConfig(RULE_ID);
   if (!policy?.enabled) return [];
-  const sources = canonicalSourcesFromPolicy(policy.options?.canonicalSources);
-  const mappings = canonicalMappingsFromPolicy(policy.options?.canonicalMappings);
+  const configuredSources = canonicalSourcesFromPolicy(policy.options?.canonicalSources);
+  const conflicts = projectCanonicalDirectionConflicts(ix, configuredSources);
+  const sources = configuredSources.map((source) => suppressConflictedExports(source, conflicts));
+  const mappings = canonicalMappingsFromPolicy(policy.options?.canonicalMappings).filter(
+    (mapping) => !canonicalDirectionConflictsTarget(conflicts, mapping.importPath, mapping.name)
+  );
   if (sources.length === 0 && mappings.length === 0) return [];
 
   const importsByFileAndLocal = indexImportsByFileAndLocal(ix);
@@ -605,6 +614,22 @@ export function ruleComponentsPreferLibrary(ix: FactIndex): Finding[] {
   return findings;
 }
 
+function suppressConflictedExports(
+  source: CanonicalSource,
+  conflicts: readonly CanonicalDirectionConflict[]
+): CanonicalSource {
+  if (source.kind !== "npm") return source;
+  const names = conflicts
+    .filter((conflict) => ownedImportMatchesRoot(source.specifier, conflict.packageName))
+    .map((conflict) => conflict.exportName);
+  if (names.length === 0) return source;
+  const blocked = new Set(names);
+  if (source.include) {
+    return { ...source, include: source.include.filter((name) => !blocked.has(name)) };
+  }
+  return { ...source, exclude: [...new Set([...(source.exclude ?? []), ...names])].sort() };
+}
+
 function indexShadowRenderRootNodeIds(ix: FactIndex): Set<FactId> {
   const identities = ix.byKind("component_identity");
   if (identities.length === 0) return new Set();
@@ -1113,8 +1138,9 @@ function indexCanonicalDirectoryResolvedNodes(
 ): Set<FactId> {
   const out = new Set<FactId>();
   const directoryPaths = sources
-    .filter((source): source is Extract<CanonicalSource, { kind: "directory" }> =>
-      source.kind === "directory"
+    .filter(
+      (source): source is Extract<CanonicalSource, { kind: "directory" }> =>
+        source.kind === "directory"
     )
     .map((source) => normalizePath(source.path));
   if (directoryPaths.length === 0) return out;

package/src/rules/fix-availability.ts

@@ -25,6 +25,7 @@ export const RULE_FIX_AVAILABLE = {
   "tailwind/unknown-class": false,
   "tokens/require-dual-fallback": true,
   "tokens/css-vars-must-be-defined": false,
+  "tokens/upstream-drift": false,
   "theme/no-theme-coupled-literal": false,
   "a11y/required-accessible-name": false,
   "composition/cardinality": false,

package/src/rules/index.ts

@@ -31,6 +31,7 @@ import { ruleTailwindRawColorViaToken } from "./tailwind-raw-color-via-token.js"
 import { ruleTailwindUnknownClass } from "./tailwind-unknown-class.js";
 import { ruleTokensRequireDualFallback } from "./tokens-require-dual-fallback.js";
 import { ruleTokensCssVarsMustBeDefined } from "./tokens-css-vars-must-be-defined.js";
+import { ruleTokensUpstreamDrift } from "./tokens-upstream-drift.js";
 import type { Finding } from "./types.js";
 
 export type RuleFn = (ix: FactIndex) => Finding[];
@@ -137,6 +138,11 @@ export const RULES: readonly Rule[] = [
     version: "1",
     run: ruleTokensCssVarsMustBeDefined,
   },
+  {
+    id: "tokens/upstream-drift",
+    version: "1",
+    run: ruleTokensUpstreamDrift,
+  },
   {
     id: "theme/no-theme-coupled-literal",
     version: "1",
@@ -211,6 +217,7 @@ export { ruleTailwindRawColorViaToken } from "./tailwind-raw-color-via-token.js"
 export { ruleTailwindUnknownClass } from "./tailwind-unknown-class.js";
 export { ruleTokensRequireDualFallback } from "./tokens-require-dual-fallback.js";
 export { ruleTokensCssVarsMustBeDefined } from "./tokens-css-vars-must-be-defined.js";
+export { ruleTokensUpstreamDrift } from "./tokens-upstream-drift.js";
 export { ruleThemeNoThemeCoupledLiteral } from "./theme-no-theme-coupled-literal.js";
 export { ruleA11yRequiredAccessibleName } from "./a11y-required-accessible-name.js";
 export { ruleCompositionCardinality, ruleCompositionCoOccurrence } from "./composition-pattern.js";

package/src/rules/jsx-preferred-import-path.ts

@@ -1,5 +1,5 @@
 import type { FactIndex } from "../facts/index.js";
-import { ownedImportsEqual } from "../package-identity-match.js";
+import { ownedImportMatchesRoot, ownedImportsEqual } from "../package-identity-match.js";
 
 import { makeFinding } from "./finding.js";
 import type { Finding } from "./types.js";
@@ -16,6 +16,21 @@ export function ruleJsxPreferredImportPath(ix: FactIndex): Finding[] {
 
   for (const usage of ix.byKind("usage_import")) {
     const matches = policies.filter((policy) => {
+      if (policy.bridge) {
+        if (policy.bridge.implementationFiles.some((file) => sameRepoPath(file, usage.file))) {
+          return false;
+        }
+        if (!ownedImportMatchesRoot(usage.source, policy.from)) return false;
+        if (ownedImportsEqual(usage.source, policy.from)) {
+          return usage.imported === policy.bridge.underlyingExportName;
+        }
+        const subpath = usage.source.slice(policy.from.length + 1);
+        const leaf = subpath.split("/").at(-1);
+        return (
+          leaf === policy.bridge.underlyingExportName &&
+          (usage.imported === "default" || usage.imported === policy.bridge.underlyingExportName)
+        );
+      }
       if (!ownedImportsEqual(policy.from, usage.source)) return false;
       if (policy.imported !== undefined && policy.imported !== usage.imported) return false;
       return true;
@@ -33,7 +48,9 @@ export function ruleJsxPreferredImportPath(ix: FactIndex): Finding[] {
           ruleId: RULE_ID,
           ruleVersion: RULE_VERSION,
           severity: policy.severity,
-          message: `Import from "${usage.source}" should use "${policy.to}".`,
+          message: policy.bridge
+            ? `Import ${policy.bridge.underlyingExportName} through the confirmed local ${policy.bridge.localExportName} wrapper from "${policy.to}".`
+            : `Import from "${usage.source}" should use "${policy.to}".`,
           location: usage.location,
           evidence: ix.evidence([usage.id, policy.id]),
           fingerprintIdentity: {
@@ -44,19 +61,30 @@ export function ruleJsxPreferredImportPath(ix: FactIndex): Finding[] {
             line: usage.location.line,
             column: usage.location.column,
           },
-          fix: {
-            kind: "replaceImport",
-            title: policy.because ?? `Replace import path with "${policy.to}"`,
-            from: usage.source,
-            to: policy.to,
-            deterministic: true,
-          },
+          fix: policy.bridge
+            ? undefined
+            : {
+                kind: "replaceImport",
+                title: policy.because ?? `Replace import path with "${policy.to}"`,
+                from: usage.source,
+                to: policy.to,
+                deterministic: true,
+              },
           attributes: {
             importPath: usage.source,
             suggestedImport: policy.to,
             imported: usage.imported,
             local: usage.local,
             rawValue: usage.source,
+            ...(policy.bridge
+              ? {
+                  canonicalBridge: true,
+                  canonicalTarget: policy.bridge.componentKey,
+                  suggestedComponent: policy.bridge.localExportName,
+                  implementationFiles: policy.bridge.implementationFiles,
+                  decisionSource: policy.bridge.decisionSource,
+                }
+              : {}),
           },
         })
       );
@@ -65,3 +93,11 @@ export function ruleJsxPreferredImportPath(ix: FactIndex): Finding[] {
 
   return findings;
 }
+
+function sameRepoPath(left: string, right: string): boolean {
+  return normalizeRepoPath(left) === normalizeRepoPath(right);
+}
+
+function normalizeRepoPath(path: string): string {
+  return path.replace(/\\/gu, "/").replace(/^\.\//u, "");
+}