@usefragments/core 1.3.0 → 1.5.0

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

@@ -1,5 +1,6 @@
 import type { CanonicalSource, GovernanceSeverity } from "../governance.js";
 import type {
+  FactId,
   FactIndex,
   UsageImportFact,
   UsageNodeFact,
@@ -262,12 +263,22 @@ export function ruleComponentsPreferLibrary(ix: FactIndex): Finding[] {
   const textByNode = indexTextChildrenByNodeId(ix);
   const classTokensByNode = indexClassTokensByNode(ix);
   const reimplTargets = canonicalReimplTargets(sources, mappings);
+  // #9e — nodes whose local import a Node-side module resolver already proved
+  // resolves INSIDE a directory canonical source (the extractor emitted a
+  // `usage_component` whose id points at that directory). These are the genuine
+  // canonical primitives imported by a relative/`@/` path; a browser-safe string
+  // comparison of the raw specifier could never recognize them, so the resolved
+  // fact is the identity of record. Never flag them as import impostors.
+  const canonicalDirectoryResolvedNodes = indexCanonicalDirectoryResolvedNodes(ix, sources);
+  const shadowRenderRootNodeIds = indexShadowRenderRootNodeIds(ix);
   const findings: Finding[] = [];
   const seenImportFixes = new Set<string>();
 
   for (const node of ix.byKind("usage_node")) {
     if (isCanonicalSourceImplementationFile(node.file, sources)) continue;
     if (node.element.includes(".")) continue;
+    if (canonicalDirectoryResolvedNodes.has(node.id)) continue;
+    if (shadowRenderRootNodeIds.has(node.id)) continue;
     const props = propsByNode.get(node.id) ?? [];
     const textChildren = textByNode.get(node.id) ?? [];
     const importsForFile = importsByFileAndLocal.get(node.file);
@@ -594,6 +605,20 @@ export function ruleComponentsPreferLibrary(ix: FactIndex): Finding[] {
   return findings;
 }
 
+function indexShadowRenderRootNodeIds(ix: FactIndex): Set<FactId> {
+  const identities = ix.byKind("component_identity");
+  if (identities.length === 0) return new Set();
+
+  const nodeIds = new Set<FactId>();
+  for (const identity of identities) {
+    if (identity.state !== "shadow") continue;
+    for (const evidenceId of identity.evidence) {
+      if (ix.get(evidenceId)?.kind === "usage_node") nodeIds.add(evidenceId);
+    }
+  }
+  return nodeIds;
+}
+
 interface BuiltInRawHtmlMatch {
   canonical: string;
   tier: RawHtmlPrecisionTier;
@@ -1065,7 +1090,49 @@ function sourceLabel(source: CanonicalSource): string {
 function canonicalImportPath(source: CanonicalSource): string | undefined {
   if (source.kind === "npm") return source.specifier;
   if (source.kind === "registry") return source.importPath;
-  return undefined;
+  // #9e — a directory canonical source *does* have a redirect target: its own
+  // directory path. Returning it lets the import-identity branch point a local
+  // impostor (`<Button>` from `../features/FakeButton`) back at the canonical
+  // directory instead of `continue`-ing to zero findings. Gate on an explicit
+  // include list: without curated NAMES, `sourceIncludesComponent` matches every
+  // PascalCase import, so a redirect target here would blanket-flag them all
+  // (#224). Include-less directory sources keep the old no-target behavior.
+  return source.include?.length ? source.path : undefined;
+}
+
+/**
+ * #9e — index the `usage_node` ids whose import a Node-side module resolver
+ * proved resolves INSIDE a directory canonical source. The scan orchestrator's
+ * `resolveComponentId` seam emits a `usage_component` fact for such imports with
+ * a `<canonicalDirPath>#<Name>` component id; this recovers those node ids so the
+ * rule can treat the genuine local canonical primitive as already-compliant.
+ */
+function indexCanonicalDirectoryResolvedNodes(
+  ix: FactIndex,
+  sources: readonly CanonicalSource[]
+): Set<FactId> {
+  const out = new Set<FactId>();
+  const directoryPaths = sources
+    .filter((source): source is Extract<CanonicalSource, { kind: "directory" }> =>
+      source.kind === "directory"
+    )
+    .map((source) => normalizePath(source.path));
+  if (directoryPaths.length === 0) return out;
+  for (const fact of ix.byKind("usage_component")) {
+    const module = componentIdModule(fact.componentId);
+    if (module === undefined) continue;
+    const normalizedModule = normalizePath(module);
+    if (directoryPaths.some((path) => isPathInSource(normalizedModule, path))) {
+      out.add(fact.nodeId);
+    }
+  }
+  return out;
+}
+
+/** Extract the module portion (`before#`) of a `module#Export` component id. */
+function componentIdModule(componentId: string): string | undefined {
+  const hash = componentId.indexOf("#");
+  return hash > 0 ? componentId.slice(0, hash) : undefined;
 }
 
 function isCanonicalSourceImplementationFile(

package/src/rules/components-shadow-component.test.ts

@@ -0,0 +1,145 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  BLOCKING_RULE_ALLOWLIST,
+  compileGlobalGovernanceFacts,
+  FactIndex,
+  isDenyEligible,
+  makeComponentDefinitionFact,
+  makeComponentIdentityFact,
+  makeUsageComponentFact,
+  makeUsageNodeFact,
+  ruleComponentsShadowComponent,
+} from "../index.js";
+
+describe("components/shadow-component", () => {
+  it("emits one definition finding with usage count, blast radius, and a stable fingerprint", () => {
+    const first = shadowIndex({ definitionLine: 8 });
+    const moved = shadowIndex({ definitionLine: 80 });
+
+    const finding = ruleComponentsShadowComponent(first)[0];
+    const movedFinding = ruleComponentsShadowComponent(moved)[0];
+
+    expect(finding).toMatchObject({
+      ruleId: "components/shadow-component",
+      level: "warn",
+      location: { file: "src/components/MyButton.tsx", line: 8, column: 2 },
+      attributes: {
+        canonicalTarget: "Button",
+        usageCount: 3,
+        blastRadius: 2,
+        confidence: "confirmed",
+        state: "shadow",
+      },
+    });
+    expect(finding?.attributes).not.toHaveProperty("advisory");
+    expect(finding?.fingerprint).toBe(movedFinding?.fingerprint);
+  });
+
+  it("keeps review-tier variants permanently advisory at info severity", () => {
+    const ix = shadowIndex({ state: "variant", confidence: "review", severity: "error" });
+
+    const finding = ruleComponentsShadowComponent(ix)[0];
+
+    expect(finding).toMatchObject({
+      severity: "minor",
+      level: "warn",
+      attributes: {
+        canonicalTarget: "Button",
+        confidence: "review",
+        state: "variant",
+        advisory: true,
+      },
+    });
+    expect(isDenyEligible(finding!, true)).toBe(false);
+  });
+
+  it("honors an error severity for a confirmed shadow but never enters the write deny-set", () => {
+    const finding = ruleComponentsShadowComponent(shadowIndex({ severity: "error" }))[0];
+
+    expect(finding?.level).toBe("error");
+    expect(finding?.attributes).not.toHaveProperty("advisory");
+    expect(BLOCKING_RULE_ALLOWLIST.has("components/shadow-component")).toBe(false);
+    expect(isDenyEligible(finding!, false)).toBe(false);
+  });
+
+  it("throws rather than emitting an evidence-free finding", () => {
+    const ix = shadowIndex();
+    const identity = ix.byKind("component_identity")[0]!;
+    const empty = new FactIndex();
+    empty.addMany(
+      ix
+        .all()
+        .filter((fact) => fact.id !== identity.id)
+    );
+    empty.add(makeComponentIdentityFact({ ...identity, evidence: [] }));
+
+    expect(() => ruleComponentsShadowComponent(empty)).toThrow(
+      "findings must carry at least one evidence fact"
+    );
+  });
+});
+
+function shadowIndex(
+  options: {
+    state?: "shadow" | "variant";
+    confidence?: "confirmed" | "review";
+    severity?: "warn" | "error";
+    definitionLine?: number;
+  } = {}
+): FactIndex {
+  const componentKey = "src/components/MyButton.tsx#MyButton";
+  const ix = new FactIndex();
+  ix.addMany(
+    compileGlobalGovernanceFacts({
+      rules: {
+        "components/shadow-component": {
+          enabled: true,
+          severity: options.severity ?? "warn",
+        },
+      },
+    })
+  );
+  const definition = makeComponentDefinitionFact({
+    file: "src/components/MyButton.tsx",
+    exportName: "MyButton",
+    componentKey,
+    renderRoot: { resolution: "intrinsic", tag: "button", interactive: true },
+    propSurface: ["children", "disabled"],
+  });
+  const renderRoot = makeUsageNodeFact({
+    file: definition.file,
+    nodePath: "0:0",
+    element: "button",
+    interactive: true,
+    location: {
+      file: definition.file,
+      line: options.definitionLine ?? 8,
+      column: 2,
+    },
+  });
+  ix.addMany([definition, renderRoot]);
+  ix.add(
+    makeComponentIdentityFact({
+      componentKey,
+      state: options.state ?? "shadow",
+      confidence: options.confidence ?? "confirmed",
+      canonicalTarget: "Button",
+      evidence: [definition.id, renderRoot.id],
+    })
+  );
+
+  for (const [index, file] of ["src/App.tsx", "src/App.tsx", "src/Checkout.tsx"].entries()) {
+    const node = makeUsageNodeFact({
+      file,
+      nodePath: `0:${index}`,
+      element: "MyButton",
+      location: { file, line: index + 1, column: 0 },
+    });
+    ix.addMany([
+      node,
+      makeUsageComponentFact({ nodeId: node.id, componentId: definition.componentId }),
+    ]);
+  }
+  return ix;
+}

package/src/rules/components-shadow-component.ts

@@ -0,0 +1,81 @@
+import type {
+  ComponentDefinitionFact,
+  ComponentIdentityFact,
+  FactIndex,
+  FactLocation,
+} from "../facts/index.js";
+import { indexComponentIdentityUsage } from "../identity/usage.js";
+
+import { makeFinding } from "./finding.js";
+import type { Finding } from "./types.js";
+
+export const RULE_ID = "components/shadow-component";
+export const RULE_VERSION = "1";
+
+export function ruleComponentsShadowComponent(ix: FactIndex): Finding[] {
+  const policy = ix.policy.ruleConfig(RULE_ID);
+  if (!policy?.enabled) return [];
+
+  const definitions = new Map(
+    ix.byKind("component_definition").map((definition) => [definition.componentKey, definition])
+  );
+  const usageByComponent = indexComponentIdentityUsage(ix);
+  const findings: Finding[] = [];
+
+  for (const identity of ix.byKind("component_identity")) {
+    const reviewVariant = identity.state === "variant" && identity.confidence === "review";
+    if (identity.state !== "shadow" && !reviewVariant) continue;
+
+    const definition = definitions.get(identity.componentKey);
+    if (!definition) continue;
+    const usage = usageByComponent.get(identity.componentKey);
+    const usageCount = usage?.usageCount ?? 0;
+    const blastRadius = usage?.blastRadius ?? 0;
+
+    findings.push(
+      makeFinding({
+        ruleId: RULE_ID,
+        ruleVersion: RULE_VERSION,
+        severity: reviewVariant ? "info" : (policy.severity ?? "warn"),
+        message: reviewVariant
+          ? `${definition.exportName} wraps ${identity.canonicalTarget ?? "a canonical component"}; sanction it as a variant or consolidate its usages.`
+          : `${definition.exportName} shadows ${identity.canonicalTarget ?? "a canonical component"} across ${usageCount} usage${usageCount === 1 ? "" : "s"}.`,
+        location: definitionLocation(ix, definition, identity),
+        evidence: ix.evidence(identity.evidence),
+        fingerprintIdentity: {
+          componentKey: identity.componentKey,
+          canonicalTarget: identity.canonicalTarget,
+        },
+        attributes: {
+          canonicalTarget: identity.canonicalTarget,
+          usageCount,
+          blastRadius,
+          confidence: identity.confidence,
+          state: identity.state,
+          ...(reviewVariant ? { advisory: true } : {}),
+        },
+      })
+    );
+  }
+
+  return findings;
+}
+
+function definitionLocation(
+  ix: FactIndex,
+  definition: ComponentDefinitionFact,
+  identity: ComponentIdentityFact
+): FactLocation {
+  const evidence = ix.evidence(identity.evidence).map(({ fact }) => fact);
+  const inDefinitionFile = evidence.find(
+    (fact) => "location" in fact && fact.location?.file === definition.file
+  );
+  if (inDefinitionFile && "location" in inDefinitionFile && inDefinitionFile.location) {
+    return inDefinitionFile.location;
+  }
+  const sourceLocated = evidence.find((fact) => "location" in fact && fact.location);
+  if (sourceLocated && "location" in sourceLocated && sourceLocated.location) {
+    return sourceLocated.location;
+  }
+  return { file: definition.file, line: 1, column: 0 };
+}

package/src/rules/fix-availability.ts

@@ -12,6 +12,7 @@ export const RULE_FIX_AVAILABLE = {
   "imports/preferred-path": true,
   "components/preferred-component": true,
   "components/prefer-library": true,
+  "components/shadow-component": false,
   "styles/no-raw-color": true,
   "styles/no-raw-dimensions": true,
   "styles/no-raw-spacing": true,

package/src/rules/index.ts

@@ -11,6 +11,7 @@ import type { FactIndex } from "../facts/index.js";
 
 import { ruleA11yRequiredAccessibleName } from "./a11y-required-accessible-name.js";
 import { ruleComponentsPreferLibrary } from "./components-prefer-library.js";
+import { ruleComponentsShadowComponent } from "./components-shadow-component.js";
 import { ruleComponentsForbiddenPropValue } from "./components-forbidden-prop-value.js";
 import { ruleComponentsUnknownProp } from "./components-unknown-prop.js";
 import { ruleCompositionCardinality, ruleCompositionCoOccurrence } from "./composition-pattern.js";
@@ -71,6 +72,11 @@ export const RULES: readonly Rule[] = [
     version: "1",
     run: ruleComponentsPreferLibrary,
   },
+  {
+    id: "components/shadow-component",
+    version: "1",
+    run: ruleComponentsShadowComponent,
+  },
   {
     id: "styles/no-raw-color",
     version: "1",
@@ -189,6 +195,7 @@ export { BLOCKING_RULE_ALLOWLIST, gatesCi, isDenyEligible } from "./emit-gate.js
 export { ruleComponentsUnknownProp } from "./components-unknown-prop.js";
 export { ruleComponentsForbiddenPropValue } from "./components-forbidden-prop-value.js";
 export { ruleComponentsPreferLibrary } from "./components-prefer-library.js";
+export { ruleComponentsShadowComponent } from "./components-shadow-component.js";
 export { rulePropsInvalidValue } from "./props-invalid-value.js";
 export { ruleJsxPreferredImportPath } from "./jsx-preferred-import-path.js";
 export { ruleJsxPreferredComponent } from "./jsx-preferred-component.js";

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

@@ -0,0 +1,213 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  compileGlobalGovernanceFacts,
+  FactIndex,
+  g,
+  makeTokenDefinitionFact,
+  makeUsageInlineStyleFact,
+  makeUsageNodeFact,
+  makeUsagePropResolvedFact,
+  ruleStylesNoRawColor,
+} from "../index.js";
+import type { FactId } from "../index.js";
+
+const FILE = "src/icon.tsx";
+
+function indexWithColorPolicy(severity: "error" | "warn" | "info" = "error"): FactIndex {
+  const ix = new FactIndex();
+  ix.addMany(
+    compileGlobalGovernanceFacts({
+      styles: [g.styles.rawColors().forbid({ except: ["transparent"], prefer: "token", severity })],
+    })
+  );
+  return ix;
+}
+
+function addNode(ix: FactIndex, element: string, nodePath = "0:0"): FactId {
+  const node = makeUsageNodeFact({
+    file: FILE,
+    nodePath,
+    element,
+    location: { file: FILE, line: 4, column: 6 },
+  });
+  ix.add(node);
+  return node.id;
+}
+
+// ---------------------------------------------------------------------------
+// #9d — SVG paint attributes (fill/stroke/…)
+// ---------------------------------------------------------------------------
+
+describe("styles/no-raw-color — #9d SVG paint attributes", () => {
+  it("flags a raw hex on a fill attribute", () => {
+    const ix = indexWithColorPolicy();
+    const nodeId = addNode(ix, "circle");
+    ix.add(
+      makeUsagePropResolvedFact({
+        nodeId,
+        prop: "fill",
+        resolution: "static",
+        value: "#00ff00",
+        location: { file: FILE, line: 4, column: 14 },
+      })
+    );
+
+    const findings = ruleStylesNoRawColor(ix);
+    expect(findings).toHaveLength(1);
+    expect(findings[0].attributes).toMatchObject({
+      property: "fill",
+      color: "#00ff00",
+      source: "jsx",
+    });
+  });
+
+  it("broadened SVG detection ships advisory (warn) even under an error policy", () => {
+    const ix = indexWithColorPolicy("error");
+    const nodeId = addNode(ix, "path");
+    ix.add(
+      makeUsagePropResolvedFact({ nodeId, prop: "stroke", resolution: "static", value: "#123456" })
+    );
+
+    const findings = ruleStylesNoRawColor(ix);
+    expect(findings).toHaveLength(1);
+    expect(findings[0].severity).toBe("moderate"); // capped warn (not "serious")
+  });
+
+  it("emits a deterministic token fix when stroke matches an accent token exactly", () => {
+    const ix = indexWithColorPolicy();
+    ix.add(
+      makeTokenDefinitionFact({ name: "--fui-color-accent", value: "#7c3aed", category: "color" })
+    );
+    const nodeId = addNode(ix, "path");
+    ix.add(
+      makeUsagePropResolvedFact({ nodeId, prop: "stroke", resolution: "static", value: "#7c3aed" })
+    );
+
+    const findings = ruleStylesNoRawColor(ix);
+    expect(findings).toHaveLength(1);
+    expect(findings[0].fix).toBeDefined();
+    expect(findings[0].fix).toMatchObject({ kind: "replaceStyleValue", deterministic: true });
+  });
+
+  it("maps React camelCase stopColor to the paint allowlist", () => {
+    const ix = indexWithColorPolicy();
+    const nodeId = addNode(ix, "stop");
+    ix.add(
+      makeUsagePropResolvedFact({
+        nodeId,
+        prop: "stopColor",
+        resolution: "static",
+        value: "#abcdef",
+      })
+    );
+
+    const findings = ruleStylesNoRawColor(ix);
+    expect(findings).toHaveLength(1);
+    expect(findings[0].attributes).toMatchObject({ property: "stopColor" });
+  });
+
+  it("does not fire for fill='none' or fill='currentColor'", () => {
+    const ix = indexWithColorPolicy();
+    const nodeId = addNode(ix, "circle");
+    ix.add(
+      makeUsagePropResolvedFact({ nodeId, prop: "fill", resolution: "static", value: "none" })
+    );
+    ix.add(
+      makeUsagePropResolvedFact({
+        nodeId,
+        prop: "stroke",
+        resolution: "static",
+        value: "currentColor",
+      })
+    );
+
+    expect(ruleStylesNoRawColor(ix)).toHaveLength(0);
+  });
+
+  it("does not fire for a dynamic fill prop", () => {
+    const ix = indexWithColorPolicy();
+    const nodeId = addNode(ix, "circle");
+    ix.add(makeUsagePropResolvedFact({ nodeId, prop: "fill", resolution: "dynamic" }));
+
+    expect(ruleStylesNoRawColor(ix)).toHaveLength(0);
+  });
+
+  it("does not fire for a non-paint attribute carrying a hex-shaped string (documented data-URI limit)", () => {
+    const ix = indexWithColorPolicy();
+    const nodeId = addNode(ix, "img");
+    // A data-URI color is intentionally out of scope — parsing colors out of
+    // encoded url() strings is high-noise and low-value for this release.
+    ix.add(
+      makeUsagePropResolvedFact({
+        nodeId,
+        prop: "src",
+        resolution: "static",
+        value: 'data:image/svg+xml,<svg fill="%2300ff00" />',
+      })
+    );
+
+    expect(ruleStylesNoRawColor(ix)).toHaveLength(0);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// #11b — runtime-constructed (dynamic-raw) colors
+// ---------------------------------------------------------------------------
+
+describe("styles/no-raw-color — #11b dynamic-raw colors", () => {
+  it("flags a dynamic-raw inline color with no fix object", () => {
+    const ix = indexWithColorPolicy();
+    const nodeId = addNode(ix, "div");
+    ix.add(
+      makeUsageInlineStyleFact({
+        nodeId,
+        property: "background",
+        valueKind: "dynamic-raw",
+        value: "#‹expr›",
+      })
+    );
+
+    const findings = ruleStylesNoRawColor(ix);
+    expect(findings).toHaveLength(1);
+    expect(findings[0].fix).toBeUndefined();
+    expect(findings[0].attributes).toMatchObject({
+      property: "background",
+      dynamic: true,
+      source: "jsx",
+    });
+  });
+
+  it("caps the dynamic-raw finding to advisory (warn) under an error policy", () => {
+    const ix = indexWithColorPolicy("error");
+    const nodeId = addNode(ix, "div");
+    ix.add(
+      makeUsageInlineStyleFact({
+        nodeId,
+        property: "color",
+        valueKind: "dynamic-raw",
+        value: "rgb(‹expr›,‹expr›,‹expr›)",
+      })
+    );
+
+    const findings = ruleStylesNoRawColor(ix);
+    expect(findings).toHaveLength(1);
+    expect(findings[0].severity).toBe("moderate"); // capped warn (not "serious")
+  });
+
+  it("keeps a distinct fingerprint source from static inline colors", () => {
+    const ix = indexWithColorPolicy();
+    const nodeId = addNode(ix, "div");
+    ix.add(
+      makeUsageInlineStyleFact({
+        nodeId,
+        property: "background",
+        valueKind: "dynamic-raw",
+        value: "#‹expr›",
+      })
+    );
+
+    const findings = ruleStylesNoRawColor(ix);
+    expect(findings[0].fingerprint).toEqual(expect.any(String));
+  });
+});