@usefragments/core 1.3.0 → 1.5.0

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-DYSirwJu.js';
+export { F as FragmentDefinition, a as FragmentDefinitionV2 } from './governance-BLsyk56o.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-DYSirwJu.js';
+import { C as CompiledBlock, b as CompiledFragment } from './governance-BLsyk56o.js';
 import 'zod';
 import 'react';
 import './topology/index.js';

package/package.json

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

package/src/codes/codes.ts

@@ -108,6 +108,15 @@ export const CODES = [
     fixAvailable: false,
     evidenceRequired: true,
   }),
+  ruleCode({
+    code: "FUI1007",
+    ruleId: "components/shadow-component",
+    category: "canonical-usage",
+    defaultSeverity: "moderate",
+    title: "Component shadows a canonical primitive",
+    lifecycle: "experimental",
+    evidenceRequired: true,
+  }),
   code({
     code: "FUI2001",
     ruleId: "tokens/require-design-tokens",

package/src/conform.ts

@@ -20,6 +20,11 @@ export interface ConformInput {
   filename?: string;
   /** deterministic (default) applies safe edits; none returns findings only. */
   apply?: "deterministic" | "none";
+  /** Explicit request to consolidate a known shadow into its canonical root. */
+  shadowConsolidation?: {
+    shadow: string;
+    canonicalTarget?: string;
+  };
 }
 
 export interface ConformLocation {

package/src/constants.ts

@@ -30,6 +30,9 @@ export const BRAND = {
   /** CLI command name (e.g., "fragments") */
   cliCommand: "fragments",
 
+  /** Full user-facing CLI invocation for copy printed to end users (e.g., "npx @usefragments/cli") */
+  cliInvocation: "npx @usefragments/cli",
+
   /** Directory for storing fragments, registry, and cache */
   dataDir: ".fragments",
 

package/src/facts/builders.ts

@@ -9,7 +9,7 @@
  */
 
 import type { GovernanceSeverity } from "../governance.js";
-import { factId } from "./ids.js";
+import { asComponentId, factId } from "./ids.js";
 import type {
   A11yNameRequiredFact,
   CanonicalCandidateFact,
@@ -20,7 +20,9 @@ import type {
   ClassNameLiteralFact,
   ClassNameOrigin,
   ComponentCapabilityFact,
+  ComponentDefinitionFact,
   ComponentId,
+  ComponentIdentityFact,
   ComponentMetadataFact,
   FactLocation,
   GovernanceRuleConfigFact,
@@ -99,6 +101,48 @@ export function makeComponentCapabilityFact(input: {
   };
 }
 
+export function makeComponentDefinitionFact(input: {
+  file: string;
+  exportName: string;
+  componentKey: string;
+  renderRoot: ComponentDefinitionFact["renderRoot"];
+  propSurface: string[];
+  stylingChannel?: ComponentDefinitionFact["stylingChannel"];
+}): ComponentDefinitionFact {
+  return {
+    id: factId("component_definition", { componentKey: input.componentKey }),
+    kind: "component_definition",
+    componentId: asComponentId(input.componentKey),
+    file: input.file,
+    exportName: input.exportName,
+    componentKey: input.componentKey,
+    renderRoot: input.renderRoot,
+    propSurface: [...input.propSurface],
+    ...(input.stylingChannel ? { stylingChannel: { ...input.stylingChannel } } : {}),
+  };
+}
+
+export function makeComponentIdentityFact(input: {
+  componentKey: string;
+  state: ComponentIdentityFact["state"];
+  confidence: ComponentIdentityFact["confidence"];
+  canonicalTarget?: string;
+  decisionId?: string;
+  evidence: FactId[];
+}): ComponentIdentityFact {
+  return {
+    id: factId("component_identity", { componentKey: input.componentKey }),
+    kind: "component_identity",
+    componentId: asComponentId(input.componentKey),
+    componentKey: input.componentKey,
+    state: input.state,
+    confidence: input.confidence,
+    ...(input.canonicalTarget ? { canonicalTarget: input.canonicalTarget } : {}),
+    ...(input.decisionId ? { decisionId: input.decisionId } : {}),
+    evidence: [...input.evidence],
+  };
+}
+
 // ---------------------------------------------------------------------------
 // Classifier facts
 // ---------------------------------------------------------------------------
@@ -620,7 +664,7 @@ export function makeUsagePropResolvedFact(input: {
 export function makeUsageInlineStyleFact(input: {
   nodeId: FactId;
   property: string;
-  valueKind: "static" | "number" | "css-variable";
+  valueKind: "static" | "number" | "css-variable" | "dynamic-raw";
   value: string;
 }): UsageInlineStyleFact {
   return {

package/src/facts/facts.test.ts

@@ -10,6 +10,8 @@ import {
   compileGlobalGovernanceFacts,
   g,
   makeTokenDefinitionFact,
+  makeComponentDefinitionFact,
+  makeComponentIdentityFact,
   makeUsageNodeFact,
 } from "../index.js";
 import type { ComponentId, FactId, PropValueForbiddenFact } from "../index.js";
@@ -151,6 +153,34 @@ describe("fact IR — content-addressed IDs", () => {
     expect(a).toBe(b);
   });
 
+  it("keys definition and identity facts by the portable componentKey", () => {
+    const first = makeComponentDefinitionFact({
+      file: "src/a/Button.tsx",
+      exportName: "Button",
+      componentKey: "src/a/Button.tsx#Button",
+      renderRoot: { resolution: "intrinsic", tag: "button", interactive: true },
+      propSurface: ["disabled"],
+    });
+    const second = makeComponentDefinitionFact({
+      file: "src/b/Button.tsx",
+      exportName: "Button",
+      componentKey: "src/b/Button.tsx#Button",
+      renderRoot: { resolution: "intrinsic", tag: "button", interactive: true },
+      propSurface: ["disabled"],
+    });
+    const identity = makeComponentIdentityFact({
+      componentKey: first.componentKey,
+      state: "shadow",
+      confidence: "confirmed",
+      canonicalTarget: "Button",
+      evidence: [first.id],
+    });
+
+    expect(first.id).not.toBe(second.id);
+    expect(String(identity.componentId)).toBe(first.componentKey);
+    expect(identity.evidence).toEqual([first.id]);
+  });
+
   it("keeps v1 IDs stable across owned package spellings only in typed identity fields", () => {
     const legacyComponentId = asComponentId("@fragments-sdk/ui#Button");
     const currentComponentId = asComponentId("@usefragments/ui#Button");

package/src/facts/index.ts

@@ -18,6 +18,10 @@ export type {
   CanonicalMappingFact,
   CanonicalReplacementFact,
   ComponentLevelFact,
+  ComponentDefinitionFact,
+  ComponentDefinitionRenderRoot,
+  ComponentIdentityFact,
+  IdentityFact,
   PolicyFact,
   UsageFact,
   ComponentMetadataFact,
@@ -73,6 +77,8 @@ export { componentId, asComponentId, factId, hash64Hex, canonicalJson } from "./
 export {
   makeComponentMetadataFact,
   makeComponentCapabilityFact,
+  makeComponentDefinitionFact,
+  makeComponentIdentityFact,
   makePropMetadataFact,
   makePropValueAvoidedFact,
   makePropValueForbiddenFact,

package/src/facts/types.ts

@@ -13,6 +13,7 @@
  */
 
 import type { GovernanceSeverity } from "../governance.js";
+import type { IdentityConfidence, IdentityState } from "../identity/classify.js";
 
 // ---------------------------------------------------------------------------
 // Branded IDs
@@ -310,7 +311,20 @@ export interface UsageInlineStyleFact extends BaseFact {
   kind: "usage_inline_style";
   nodeId: FactId;
   property: string;
-  valueKind: "static" | "number" | "css-variable";
+  /**
+   * How the extractor resolved the value:
+   * - `static`       — a string literal (`"#f00"`, `"12px"`).
+   * - `number`       — a numeric literal (React treats it as `px`).
+   * - `css-variable` — a `var(--token)` reference; rules treat it as a token.
+   * - `dynamic-raw`  — a value constructed at runtime whose *static* fragments
+   *   unambiguously begin a raw color literal (`` `#${red}` ``,
+   *   `` `rgb(${r},${g},${b})` ``, `"#" + hex`). `value` carries a reconstructed
+   *   skeleton with each interpolation rendered as `‹expr›`. Detect-only: a rule
+   *   may flag it as a raw color but must NEVER attach a deterministic fix
+   *   (the value is partly runtime). Only color-shaped dynamic values ever
+   *   surface as facts — a non-color dynamic value stays opaque.
+   */
+  valueKind: "static" | "number" | "css-variable" | "dynamic-raw";
   value: string;
 }
 
@@ -561,6 +575,63 @@ export interface CanonicalReplacementFact extends BaseFact {
   location?: FactLocation;
 }
 
+// ---------------------------------------------------------------------------
+// Component identity facts
+// ---------------------------------------------------------------------------
+
+export type ComponentDefinitionRenderRoot =
+  | {
+      resolution: "canonical";
+      canonical: string;
+      importSource: string;
+    }
+  | {
+      resolution: "intrinsic";
+      tag: string;
+      role?: string;
+      interactive?: boolean;
+    }
+  | {
+      resolution: "mixed";
+      canonicals: string[];
+      intrinsics: string[];
+    }
+  | {
+      resolution: "external";
+      importSource: string;
+    }
+  | {
+      resolution: "unresolved";
+      reason: string;
+    };
+
+export interface ComponentDefinitionFact extends BaseFact {
+  kind: "component_definition";
+  /** Index-compatible projection of `componentKey`. */
+  componentId: ComponentId;
+  file: string;
+  exportName: string;
+  componentKey: string;
+  renderRoot: ComponentDefinitionRenderRoot;
+  propSurface: string[];
+  stylingChannel?: {
+    module: string;
+    ownsVisualRole: boolean;
+  };
+}
+
+export interface ComponentIdentityFact extends BaseFact {
+  kind: "component_identity";
+  /** Index-compatible projection of `componentKey`. */
+  componentId: ComponentId;
+  componentKey: string;
+  state: IdentityState;
+  confidence: IdentityConfidence;
+  canonicalTarget?: string;
+  decisionId?: string;
+  evidence: FactId[];
+}
+
 // ---------------------------------------------------------------------------
 // Discriminated unions
 // ---------------------------------------------------------------------------
@@ -609,7 +680,9 @@ export type UsageFact =
   | StructuralConfidenceFact
   | CanonicalReplacementFact;
 
-export type Fact = ComponentLevelFact | PolicyFact | UsageFact;
+export type IdentityFact = ComponentDefinitionFact | ComponentIdentityFact;
+
+export type Fact = ComponentLevelFact | PolicyFact | UsageFact | IdentityFact;
 
 export type FactKind = Fact["kind"];
 

package/src/governance.test.ts

@@ -139,6 +139,32 @@ describe("governance DSL", () => {
     });
   });
 
+  it("preserves top-level component identity decisions", () => {
+    const config = defineConfig({
+      identity: {
+        decisions: [
+          {
+            component: "src/components/AppDialog.tsx#AppDialog",
+            kind: "sanction",
+            canonicalTarget: "Dialog",
+            reason: "Owns the application modal defaults.",
+            decisionId: "local:app-dialog",
+          },
+        ],
+      },
+    });
+
+    expect(config.identity?.decisions).toEqual([
+      {
+        component: "src/components/AppDialog.tsx#AppDialog",
+        kind: "sanction",
+        canonicalTarget: "Dialog",
+        reason: "Owns the application modal defaults.",
+        decisionId: "local:app-dialog",
+      },
+    ]);
+  });
+
   it("rejects unsafe registry canonical source paths", () => {
     expect(() =>
       defineConfig({

package/src/identity/classify.test.ts

@@ -0,0 +1,185 @@
+import { describe, expect, it } from "vitest";
+
+import { classifyIdentity, type ClassifyIdentityInput } from "./classify.js";
+
+const definition = {
+  componentKey: "src/MyButton.tsx#MyButton",
+  exportName: "MyButton",
+  canonical: false,
+};
+
+function classify(overrides: Partial<ClassifyIdentityInput>) {
+  return classifyIdentity({
+    definition,
+    renderRoot: { kind: "unresolved", reason: "test" },
+    ...overrides,
+  });
+}
+
+describe("classifyIdentity", () => {
+  it("gives canonical membership primary authority", () => {
+    expect(
+      classify({
+        definition: { ...definition, canonical: true },
+        renderRoot: { kind: "external", localName: "Primitive", source: "third-party" },
+      })
+    ).toEqual({ state: "canonical", confidence: "confirmed" });
+  });
+
+  it("keeps an undecided canonical-root wrapper at review confidence", () => {
+    expect(
+      classify({
+        renderRoot: {
+          kind: "canonical",
+          localName: "Button",
+          target: { componentKey: "packages/ui/Button.tsx#Button", role: "Button" },
+        },
+      })
+    ).toEqual({
+      state: "variant",
+      confidence: "review",
+      canonicalTarget: "packages/ui/Button.tsx#Button",
+    });
+  });
+
+  it("classifies an evidenced intrinsic only when the declared vocabulary has its role", () => {
+    expect(
+      classify({
+        renderRoot: {
+          kind: "intrinsic",
+          tag: "button",
+          hasRole: false,
+          interactive: true,
+          precisionTier: "exact-html",
+          canonicalTargets: [{ componentKey: "packages/ui/Button.tsx#Button", role: "Button" }],
+        },
+      })
+    ).toEqual({ state: "shadow", confidence: "confirmed", canonicalTarget: "Button" });
+
+    expect(
+      classify({
+        renderRoot: {
+          kind: "intrinsic",
+          tag: "button",
+          hasRole: false,
+          interactive: true,
+          precisionTier: "exact-html",
+          canonicalTargets: [],
+        },
+      })
+    ).toEqual({ state: "unresolved", confidence: "review" });
+  });
+
+  it("uses supporting evidence only to upgrade confidence", () => {
+    expect(
+      classify({
+        propSurfaceOverlap: 0.8,
+        stylingOwnership: "visual-role",
+        renderRoot: {
+          kind: "intrinsic",
+          tag: "textarea",
+          hasRole: false,
+          interactive: true,
+          precisionTier: "html-advisory",
+          canonicalTargets: [
+            { componentKey: "packages/ui/Textarea.tsx#Textarea", role: "Textarea" },
+          ],
+        },
+      })
+    ).toEqual({ state: "shadow", confidence: "confirmed", canonicalTarget: "Textarea" });
+
+    expect(
+      classify({
+        propSurfaceOverlap: 0.8,
+        stylingOwnership: "layout-only",
+        renderRoot: {
+          kind: "intrinsic",
+          tag: "textarea",
+          hasRole: false,
+          interactive: true,
+          precisionTier: "html-advisory",
+          canonicalTargets: [
+            { componentKey: "packages/ui/Textarea.tsx#Textarea", role: "Textarea" },
+          ],
+        },
+      })
+    ).toEqual({ state: "shadow", confidence: "likely", canonicalTarget: "Textarea" });
+  });
+
+  it("applies wrapper decisions as classification inputs", () => {
+    const renderRoot: ClassifyIdentityInput["renderRoot"] = {
+      kind: "canonical",
+      localName: "Button",
+      target: { componentKey: "packages/ui/Button.tsx#Button", role: "Button" },
+    };
+    expect(
+      classify({
+        renderRoot,
+        decisions: [{ componentKey: definition.componentKey, decision: "sanctioned-wrapper" }],
+      })
+    ).toEqual({
+      state: "variant",
+      confidence: "confirmed",
+      canonicalTarget: "packages/ui/Button.tsx#Button",
+    });
+    expect(
+      classify({
+        renderRoot,
+        decisions: [{ componentKey: definition.componentKey, decision: "rejected-wrapper" }],
+      })
+    ).toEqual({ state: "shadow", confidence: "confirmed", canonicalTarget: "Button" });
+  });
+
+  it("classifies canonical mixtures as composites", () => {
+    expect(
+      classify({
+        renderRoot: {
+          kind: "mixed",
+          canonicalTargets: [{ componentKey: "packages/ui/Card.tsx#Card", role: "Card" }],
+          localTargets: [
+            { componentKey: "src/UserAvatar.tsx#UserAvatar", exportName: "UserAvatar" },
+          ],
+          externalTargets: [],
+          intrinsics: [],
+          unresolvedNames: [],
+        },
+      })
+    ).toEqual({
+      state: "composite",
+      confidence: "confirmed",
+      canonicalTarget: "packages/ui/Card.tsx#Card",
+    });
+  });
+
+  it("distinguishes a canonical consumer from a pass-through wrapper", () => {
+    expect(
+      classify({
+        usageCounts: { staticTextChildren: 1 },
+        renderRoot: {
+          kind: "canonical",
+          localName: "Button",
+          target: { componentKey: "packages/ui/Button.tsx#Button", role: "Button" },
+        },
+      })
+    ).toEqual({
+      state: "composite",
+      confidence: "confirmed",
+      canonicalTarget: "packages/ui/Button.tsx#Button",
+    });
+  });
+
+  it("classifies third-party roots and keeps name similarity message-only", () => {
+    expect(
+      classify({
+        renderRoot: { kind: "external", localName: "Widget", source: "third-party" },
+      })
+    ).toEqual({ state: "external", confidence: "confirmed" });
+
+    expect(
+      classify({
+        nameSimilarityTargets: ["Card", "Button"],
+        renderRoot: { kind: "unresolved", reason: "dynamic factory" },
+      })
+    ).toEqual({ state: "unresolved", confidence: "review", canonicalTarget: "Button" });
+  });
+});