@usefragments/core 1.2.0 → 1.4.0

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

@@ -0,0 +1,148 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  asComponentId,
+  compileGlobalGovernanceFacts,
+  FactIndex,
+  makeUsageComponentFact,
+  makeUsageImportFact,
+  makeUsageNodeFact,
+  ruleComponentsPreferLibrary,
+} from "../index.js";
+
+// #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:
+//   (a) leave a genuine `<Button>` alone once the scan resolver proved its import
+//       resolves INSIDE the directory (a `usage_component` with a `<dir>#Name` id);
+//   (b) flag a local impostor `<Button>` imported from OUTSIDE the directory,
+//       redirecting the import at the canonical directory path (advisory / warn);
+//   (c) never flag a third-party or aliased same-name import (collision guard).
+describe("components/prefer-library — #9e directory import-path identity", () => {
+  const CANONICAL_DIR = "src/components/ui";
+
+  function directoryIndex() {
+    const ix = new FactIndex();
+    ix.addMany(
+      compileGlobalGovernanceFacts({
+        rules: {
+          "components/prefer-library": {
+            enabled: true,
+            severity: "warning",
+            options: {
+              canonicalSources: [
+                { kind: "directory", path: CANONICAL_DIR, include: ["Button", "Input"] },
+              ],
+            },
+          },
+        },
+      })
+    );
+    return ix;
+  }
+
+  function addButtonUsage(
+    ix: FactIndex,
+    input: { local?: string; imported?: string; source: string }
+  ) {
+    const node = makeUsageNodeFact({
+      file: "src/pages/Home.tsx",
+      nodePath: "0:0",
+      element: "Button",
+      location: { file: "src/pages/Home.tsx", line: 5, column: 4 },
+    });
+    ix.add(node);
+    ix.add(
+      makeUsageImportFact({
+        file: "src/pages/Home.tsx",
+        local: input.local ?? "Button",
+        imported: input.imported ?? "Button",
+        source: input.source,
+        location: { file: "src/pages/Home.tsx", line: 1, column: 0 },
+      })
+    );
+    return node;
+  }
+
+  it("does not flag a Button whose import the scan resolver proved resolves inside the canonical directory", () => {
+    const ix = directoryIndex();
+    // The genuine primitive, imported through a `@/` alias into the canonical dir.
+    const node = addButtonUsage(ix, { source: "@/components/ui/Button" });
+    // The extractor's resolveComponentId seam emitted this canonical id because
+    // the module resolved INSIDE `src/components/ui`.
+    ix.add(
+      makeUsageComponentFact({
+        nodeId: node.id,
+        componentId: asComponentId(`${CANONICAL_DIR}#Button`),
+      })
+    );
+
+    expect(ruleComponentsPreferLibrary(ix)).toHaveLength(0);
+  });
+
+  it("flags a local impostor Button imported from outside the canonical directory and redirects to the canonical path", () => {
+    const ix = directoryIndex();
+    // No usage_component fact: the impostor's import resolved OUTSIDE the dir.
+    addButtonUsage(ix, { source: "../features/FakeButton" });
+
+    const findings = ruleComponentsPreferLibrary(ix);
+    expect(findings).toHaveLength(1);
+    expect(findings[0]).toMatchObject({
+      ruleId: "components/prefer-library",
+      code: "FUI1004",
+      fix: {
+        kind: "replaceImport",
+        from: "../features/FakeButton",
+        to: CANONICAL_DIR,
+        deterministic: false,
+      },
+      attributes: {
+        suggestedComponent: "Button",
+        suggestedImport: CANONICAL_DIR,
+        advisory: true,
+        contractProof: "missing",
+      },
+    });
+    // Advisory only — never a hard error/block.
+    expect(findings[0].level).toBe("warn");
+  });
+
+  it("does not flag a same-name Button imported from a third-party package (collision guard)", () => {
+    const ix = directoryIndex();
+    addButtonUsage(ix, { source: "@tanstack/react-router" });
+
+    expect(ruleComponentsPreferLibrary(ix)).toHaveLength(0);
+  });
+
+  it("does not flag an aliased same-name import whose bound export differs (collision guard)", () => {
+    const ix = directoryIndex();
+    // `import { Foo as Button } from "../x"` — the local JSX name collides, but
+    // the imported binding is not the canonical `Button`, so it is not a redirect
+    // candidate.
+    addButtonUsage(ix, { local: "Button", imported: "Foo", source: "../x" });
+
+    expect(ruleComponentsPreferLibrary(ix)).toHaveLength(0);
+  });
+
+  it("does not blanket-flag local imports for a directory source without an include list (#224 guard)", () => {
+    const ix = new FactIndex();
+    ix.addMany(
+      compileGlobalGovernanceFacts({
+        rules: {
+          "components/prefer-library": {
+            enabled: true,
+            severity: "warning",
+            options: {
+              // No include list → no curated canonical NAME vocabulary, so there
+              // is no basis to redirect an arbitrary local component import.
+              canonicalSources: [{ kind: "directory", path: CANONICAL_DIR }],
+            },
+          },
+        },
+      })
+    );
+    addButtonUsage(ix, { source: "../features/FakeButton" });
+
+    expect(ruleComponentsPreferLibrary(ix)).toHaveLength(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,20 @@ 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 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;
     const props = propsByNode.get(node.id) ?? [];
     const textChildren = textByNode.get(node.id) ?? [];
     const importsForFile = importsByFileAndLocal.get(node.file);
@@ -1065,7 +1074,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/emit-gate.test.ts

@@ -35,6 +35,22 @@ describe("isDenyEligible", () => {
     expect(isDenyEligible(warn, true)).toBe(true);
   });
 
+  it.each(["none", "runtime_advisory", "provenance_bound"] as const)(
+    "never gates or denies %s evidence",
+    (evidenceGrade) => {
+      const lowEvidence = { ...base, evidenceGrade } as unknown as Finding;
+      expect(isDenyEligible(lowEvidence, false)).toBe(false);
+    }
+  );
+
+  it.each(["source_backed", "receipt_backed"] as const)(
+    "allows %s evidence to reach the remaining deny checks",
+    (evidenceGrade) => {
+      const proven = { ...base, evidenceGrade } as unknown as Finding;
+      expect(isDenyEligible(proven, false)).toBe(true);
+    }
+  );
+
   it("does not deny an explicitly non-deterministic token heuristic", () => {
     const heuristic = {
       ...base,

package/src/rules/emit-gate.ts

@@ -10,6 +10,7 @@
  * `fix` shape — no Node APIs, no config off disk, no clock. The CLI hook
  * re-exports `isDenyEligible` from here.
  */
+import { canBlock } from "../evidence.js";
 import { severityLevel } from "../severity.js";
 import type { Finding } from "./types.js";
 
@@ -30,11 +31,13 @@ export const BLOCKING_RULE_ALLOWLIST: ReadonlySet<string> = new Set([
 ]);
 
 /**
- * Mirrors `scanWithFacts`'s own CI exit logic: a finding gates CI when it is
- * error-severity, or warn-severity under `ci.failOnWarnings`. Gating on exactly
- * this set is what makes a local/emit deny imply a CI failure.
+ * A finding gates CI only when its evidence is source-backed or stronger, it is
+ * not explicitly advisory, and its severity is configured to gate. Missing
+ * grades are treated as source-backed for compatibility with older reports.
  */
 export function gatesCi(finding: Finding, failOnWarnings: boolean): boolean {
+  if (!canBlock(finding.evidenceGrade ?? "source_backed")) return false;
+  if (finding.attributes?.advisory === true) return false;
   const level = severityLevel(finding.severity);
   return level === "error" || (failOnWarnings && level === "warn");
 }

package/src/rules/finding.ts

@@ -15,6 +15,7 @@ import { canonicalJson, hash64Hex } from "../facts/ids.js";
 import { byRuleId } from "../codes/index.js";
 import { normalizeFinding, normalizeSeverity } from "../schemas/index.js";
 import type { Severity } from "../schemas/index.js";
+import type { EvidenceGrade } from "../evidence.js";
 
 import type { Finding, FindingFix } from "./types.js";
 
@@ -25,6 +26,7 @@ export interface MakeFindingInput {
   message: string;
   location: FactLocation;
   evidence: FactEvidence[];
+  evidenceGrade?: EvidenceGrade;
   fingerprintIdentity: Record<string, unknown>;
   fix?: FindingFix;
   attributes?: Record<string, unknown>;
@@ -48,6 +50,7 @@ export function makeFinding(input: MakeFindingInput): Finding {
     fingerprint,
     location: input.location,
     evidence: input.evidence,
+    evidenceGrade: input.evidenceGrade ?? "source_backed",
     fix: input.fix,
     attributes: input.attributes,
   });

package/src/rules/rules.test.ts

@@ -1509,9 +1509,10 @@ describe("tokens/require-dual-fallback", () => {
     );
     ix.addMany([
       makeTokenDefinitionFact({
-        name: "--fui-color-brand",
+        name: "$fui-color-brand",
         value: "#123456",
         category: "color",
+        referenceFormat: "scss-var",
       }),
       makeStyleDeclarationFact({
         file: "src/button.scss",

package/src/rules/spacing-resolution.ts

@@ -1,7 +1,6 @@
 import type { TokenDefinitionFact } from "../facts/index.js";
 
 import {
-  isApplicableTokenReference,
   matchesScale,
   nearestSignedScaleValue,
   normalizeLengthForScale,
@@ -75,7 +74,7 @@ export function resolveSpacingValue(input: {
   let reliableSuggestion = true;
   // Deterministic only when every violating part is a value-preserving,
   // verbatim-resolvable token swap.
-  let allApplicableValuePreserving = true;
+  let allValuePreserving = true;
 
   for (const part of parts) {
     const normalized = normalizeLengthForScale(part.parsed, input.scale);
@@ -93,9 +92,7 @@ export function resolveSpacingValue(input: {
       // On-grid literal that equals a token: value-preserving swap.
       anyViolation = true;
       const reference = tokenReference(exactToken.name);
-      const applicable =
-        isApplicableTokenReference(exactToken.referenceFormat) && normalized.deterministicFix;
-      if (!applicable) allApplicableValuePreserving = false;
+      if (!normalized.deterministicFix) allValuePreserving = false;
       suggestedParts.push(reference);
       if (!firstViolation) {
         firstViolation = {
@@ -103,7 +100,7 @@ export function resolveSpacingValue(input: {
           suggestedValue: reference,
           suggestedToken: exactToken.name,
           fixEmittable: true,
-          deterministicFix: applicable,
+          deterministicFix: normalized.deterministicFix,
           reason: "token-equivalent",
           matchedToken: exactToken.name,
           assumedRootFontSizePx: normalized.assumedRootFontSizePx,
@@ -117,7 +114,7 @@ export function resolveSpacingValue(input: {
     // one exists. Snapping changes rendered value, so this is not deterministic.
     anyViolation = true;
     anyOffScale = true;
-    allApplicableValuePreserving = false;
+    allValuePreserving = false;
 
     const nearest = nearestSignedScaleValue(normalized.value, input.allowed);
     const snapsToZero = nearest === 0 && normalized.value !== 0;
@@ -158,7 +155,7 @@ export function resolveSpacingValue(input: {
   const joined = suggestedParts.join(" ");
   const changes = joined !== input.raw.trim().replace(/\s+/g, " ");
   const fixEmittable = canFixAll && reliableSuggestion && changes;
-  const deterministic = fixEmittable && !anyOffScale && allApplicableValuePreserving;
+  const deterministic = fixEmittable && !anyOffScale && allValuePreserving;
 
   return {
     ...firstViolation,

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));
+  });
+});