@usefragments/core 1.0.0

package/src/rules/tokens-require-dual-fallback.ts

@@ -0,0 +1,78 @@
+import type { FactIndex } from "../facts/index.js";
+
+import { makeFinding } from "./finding.js";
+import type { Finding } from "./types.js";
+import { cssVariableNames } from "./utils.js";
+
+export const RULE_ID = "tokens/require-dual-fallback";
+export const RULE_VERSION = "1";
+
+const CSS_VAR_WITH_OPTIONAL_FALLBACK = /var\(\s*(--[A-Za-z0-9_-]+)(\s*,\s*[^)]*)?\)/g;
+
+/**
+ * The dual-fallback convention — `var(--token, $token)` — is only meaningful in
+ * a Sass pipeline, where the `$token` half resolves at build time. In plain CSS
+ * (`.css`/`.module.css`), inline styles, or CSS-in-JS, a `$token` literal is
+ * invalid and would silently break the declaration, so the rule (and its
+ * autofix) must never touch those files.
+ */
+const SASS_FILE = /\.(scss|sass)$/i;
+
+export function ruleTokensRequireDualFallback(ix: FactIndex): Finding[] {
+  const policy = ix.policy.ruleConfig(RULE_ID);
+  if (!policy?.enabled) return [];
+
+  const knownTokenVars = cssVariableNames(ix.tokens.list());
+  const findings: Finding[] = [];
+
+  for (const decl of ix.byKind("style_declaration")) {
+    if (!SASS_FILE.test(decl.file)) continue;
+    CSS_VAR_WITH_OPTIONAL_FALLBACK.lastIndex = 0;
+    let match: RegExpExecArray | null;
+    while ((match = CSS_VAR_WITH_OPTIONAL_FALLBACK.exec(decl.value)) !== null) {
+      const tokenName = match[1];
+      const hasFallback = match[2] !== undefined;
+      if (hasFallback) continue;
+      if (!knownTokenVars.has(tokenName) && !tokenName.startsWith("--fui-")) continue;
+
+      const rawValue = match[0];
+      const scssVar = tokenName.replace(/^--/, "$");
+      const replacement = `var(${tokenName}, ${scssVar})`;
+      const nextValue = decl.value.replace(rawValue, replacement);
+
+      findings.push(
+        makeFinding({
+          ruleId: RULE_ID,
+          ruleVersion: RULE_VERSION,
+          severity: policy.severity ?? "warn",
+          message: `var(${tokenName}) is missing an SCSS fallback. Use var(${tokenName}, ${scssVar}).`,
+          location: decl.location,
+          evidence: ix.evidence([decl.id, policy.id]),
+          fingerprintIdentity: {
+            file: decl.file,
+            selector: decl.selector,
+            declarationPath: decl.declarationPath,
+            property: decl.property,
+            tokenName,
+          },
+          fix: {
+            kind: "replaceStyleValue",
+            title: `Add fallback for ${tokenName}`,
+            property: decl.property,
+            value: nextValue,
+            deterministic: true,
+          },
+          attributes: {
+            property: decl.property,
+            rawValue: decl.value,
+            tokenName,
+            suggestedValue: nextValue,
+            source: "css",
+          },
+        }),
+      );
+    }
+  }
+
+  return findings;
+}

package/src/rules/types.ts

@@ -0,0 +1,27 @@
+/**
+ * Rule output — `Finding` and `FindingFix`.
+ *
+ * Findings are emitted by pure rule functions over `FactIndex`. Every finding
+ * carries:
+ *   - `ruleId` and `ruleVersion` so Cloud can group, version, and re-run.
+ *   - `fingerprint`, a deterministic hash of (ruleId + identity tuple). Two
+ *     scans of unchanged source produce the same fingerprint, so Cloud can
+ *     dedupe and preserve event history.
+ *   - `evidence`, a non-empty list of fact IDs that justify the finding.
+ *     Phase 5 contract: a rule must never emit a finding without evidence.
+ *   - `location`, the source span the user should look at. Optional only for
+ *     facts that are not source-anchored (none in Phase 5).
+ *
+ * Fix records are pure descriptions; applying them to source is a Phase 6
+ * concern that lives in the CLI.
+ */
+
+export type {
+  Finding,
+  FindingFix,
+  FindingReplaceClassTokenFix,
+  FindingReplaceComponentFix,
+  FindingReplaceImportFix,
+  FindingReplacePropValueFix,
+  FindingReplaceStyleValueFix,
+} from "../schemas/index.js";

package/src/rules/utils.test.ts

@@ -0,0 +1,110 @@
+import { describe, expect, it } from "vitest";
+
+import { FactIndex, makeUsageNodeFact } from "../index.js";
+import type { UsageNodeFact } from "../index.js";
+import { regionsByPrefix, type Region } from "./utils.js";
+
+/**
+ * Build a `usage_node` fact and add it to the index. Tests assert container /
+ * member *relationships*, never literal `nodePath` strings — segments are
+ * opaque (per the usage-node-fact contract).
+ */
+function node(
+  ix: FactIndex,
+  nodePath: string,
+  element: string,
+  file = "src/App.tsx"
+): UsageNodeFact {
+  const fact = makeUsageNodeFact({
+    file,
+    nodePath,
+    element,
+    location: { file, line: 1, column: 1 },
+  });
+  ix.add(fact);
+  return fact;
+}
+
+function regionFor(regions: Region[], container: UsageNodeFact): Region {
+  const region = regions.find((r) => r.container.id === container.id);
+  if (!region) throw new Error(`no region for container ${container.nodePath}`);
+  return region;
+}
+
+const memberIds = (region: Region) => new Set(region.members.map((m) => m.id));
+
+describe("regionsByPrefix", () => {
+  // ACCEPTANCE §1 — sibling grouping under a container.
+  it("groups sibling children under their container", () => {
+    const ix = new FactIndex();
+    const n0 = node(ix, "0:0", "ButtonGroup");
+    const n1 = node(ix, "0:0/0", "Button");
+    const n2 = node(ix, "0:0/1", "Button");
+
+    const regions = regionsByPrefix(ix);
+    const members = memberIds(regionFor(regions, n0));
+    expect(members.has(n1.id)).toBe(true);
+    expect(members.has(n2.id)).toBe(true);
+
+    // n1 and n2 are siblings: neither contains the other.
+    expect(regionFor(regions, n1).members).toHaveLength(0);
+    expect(regionFor(regions, n2).members).toHaveLength(0);
+  });
+
+  // ACCEPTANCE §2 — opaque conditional segment stays in-region.
+  it("keeps an opaque conditional (expr:) child in the container's region", () => {
+    const ix = new FactIndex();
+    const n0 = node(ix, "0:0", "ButtonGroup");
+    const n1 = node(ix, "0:0/0", "Button");
+    const n2 = node(ix, "0:0/expr:0/0", "Button"); // {show && <Button/>}
+
+    const members = memberIds(regionFor(regionsByPrefix(ix), n0));
+    expect(members.has(n1.id)).toBe(true);
+    // `expr:0` is one opaque segment, so `0:0` is still a strict prefix.
+    expect(members.has(n2.id)).toBe(true);
+  });
+
+  it("compares whole segments — distinct conditional branches stay separate", () => {
+    const ix = new FactIndex();
+    const branchA = node(ix, "0:0/expr:0/0", "Button");
+    const branchB = node(ix, "0:0/expr:1/0", "Button");
+
+    const regions = regionsByPrefix(ix);
+    expect(memberIds(regionFor(regions, branchA)).has(branchB.id)).toBe(false);
+    expect(memberIds(regionFor(regions, branchB)).has(branchA.id)).toBe(false);
+  });
+
+  it("includes all descendants, not only direct children", () => {
+    const ix = new FactIndex();
+    const root = node(ix, "0:0", "Card");
+    const child = node(ix, "0:0/0", "ButtonGroup");
+    const grandchild = node(ix, "0:0/0/0", "Button");
+
+    const members = memberIds(regionFor(regionsByPrefix(ix), root));
+    expect(members.has(child.id)).toBe(true);
+    expect(members.has(grandchild.id)).toBe(true);
+  });
+
+  it("scopes regions by file — identical paths in different files do not merge", () => {
+    const ix = new FactIndex();
+    const a0 = node(ix, "0:0", "ButtonGroup", "src/A.tsx");
+    const a1 = node(ix, "0:0/0", "Button", "src/A.tsx");
+    const b1 = node(ix, "0:0/0", "Button", "src/B.tsx");
+
+    const members = memberIds(regionFor(regionsByPrefix(ix), a0));
+    expect(members.has(a1.id)).toBe(true);
+    expect(members.has(b1.id)).toBe(false);
+  });
+
+  it("scopes regions by rootIndex — separate root trees in one file do not merge", () => {
+    const ix = new FactIndex();
+    const r0 = node(ix, "0:0", "ButtonGroup");
+    const r0child = node(ix, "0:0/0", "Button");
+    // Same segments as r0child but a different leading root index.
+    const r1child = node(ix, "1:0/0", "Button");
+
+    const members = memberIds(regionFor(regionsByPrefix(ix), r0));
+    expect(members.has(r0child.id)).toBe(true);
+    expect(members.has(r1child.id)).toBe(false);
+  });
+});