@usefragments/core 1.0.0

package/src/rules/jsx-preferred-component.ts

@@ -0,0 +1,68 @@
+import type { FactIndex } from "../facts/index.js";
+import { ownedComponentIdsEqual } from "../package-identity-match.js";
+
+import { makeFinding } from "./finding.js";
+import type { Finding } from "./types.js";
+import { indexComponentByNodeId, readUsageNode } from "./utils.js";
+
+export const RULE_ID = "components/preferred-component";
+export const RULE_VERSION = "1";
+
+export function ruleJsxPreferredComponent(ix: FactIndex): Finding[] {
+  const policies = ix.policy.jsxComponentPreferred();
+  if (policies.length === 0) return [];
+
+  const findings: Finding[] = [];
+  const componentByNode = indexComponentByNodeId(ix);
+
+  for (const [nodeId, usageComponent] of componentByNode) {
+    const node = readUsageNode(ix, nodeId);
+    if (!node) continue;
+    if (node.element.includes(".")) continue;
+
+    for (const policy of policies) {
+      if (!ownedComponentIdsEqual(usageComponent.componentId, policy.from)) continue;
+
+      const replacement = componentNameFromId(policy.to);
+      if (!replacement) continue;
+
+      findings.push(
+        makeFinding({
+          ruleId: RULE_ID,
+          ruleVersion: RULE_VERSION,
+          severity: policy.severity,
+          message: `<${node.element}> should use <${replacement}>.`,
+          location: node.location,
+          evidence: ix.evidence([node.id, usageComponent.id, policy.id]),
+          fingerprintIdentity: {
+            file: node.file,
+            nodePath: node.nodePath,
+            from: policy.from,
+            to: policy.to,
+          },
+          fix: {
+            kind: "replaceComponent",
+            title: policy.because ?? `Replace <${node.element}> with <${replacement}>`,
+            from: node.element,
+            to: replacement,
+            deterministic: true,
+          },
+          attributes: {
+            componentId: usageComponent.componentId,
+            rawValue: node.element,
+            suggestedComponent: replacement,
+          },
+        })
+      );
+    }
+  }
+
+  return findings;
+}
+
+function componentNameFromId(componentId: string): string | undefined {
+  const hash = componentId.lastIndexOf("#");
+  const name = hash >= 0 ? componentId.slice(hash + 1) : componentId;
+  if (!/^[A-Za-z_$][\w$]*$/.test(name)) return undefined;
+  return name;
+}

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

@@ -0,0 +1,67 @@
+import type { FactIndex } from "../facts/index.js";
+import { ownedImportsEqual } from "../package-identity-match.js";
+
+import { makeFinding } from "./finding.js";
+import type { Finding } from "./types.js";
+
+export const RULE_ID = "imports/preferred-path";
+export const RULE_VERSION = "1";
+
+export function ruleJsxPreferredImportPath(ix: FactIndex): Finding[] {
+  const policies = ix.policy.jsxImportPathPreferred();
+  if (policies.length === 0) return [];
+
+  const findings: Finding[] = [];
+  const seen = new Set<string>();
+
+  for (const usage of ix.byKind("usage_import")) {
+    const matches = policies.filter((policy) => {
+      if (!ownedImportsEqual(policy.from, usage.source)) return false;
+      if (policy.imported !== undefined && policy.imported !== usage.imported) return false;
+      return true;
+    });
+
+    for (const policy of matches) {
+      if (ownedImportsEqual(usage.source, policy.to)) continue;
+      const importedIdentity = policy.imported ?? "*";
+      const key = `${policy.id}\0${usage.file}\0${usage.source}\0${usage.location.line}\0${usage.location.column}\0${importedIdentity}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+
+      findings.push(
+        makeFinding({
+          ruleId: RULE_ID,
+          ruleVersion: RULE_VERSION,
+          severity: policy.severity,
+          message: `Import from "${usage.source}" should use "${policy.to}".`,
+          location: usage.location,
+          evidence: ix.evidence([usage.id, policy.id]),
+          fingerprintIdentity: {
+            file: usage.file,
+            from: usage.source,
+            to: policy.to,
+            imported: policy.imported,
+            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,
+          },
+          attributes: {
+            importPath: usage.source,
+            suggestedImport: policy.to,
+            imported: usage.imported,
+            local: usage.local,
+            rawValue: usage.source,
+          },
+        })
+      );
+    }
+  }
+
+  return findings;
+}

package/src/rules/presets.ts

@@ -0,0 +1,57 @@
+/**
+ * Rule presets — the customer default vs the full `fragments` dogfood preset.
+ *
+ * Both are derived from the tier SSOT (`./tiers.ts`); neither re-lists rules.
+ *
+ *   - **customer default** — Tier A on (inert until a contract is authored),
+ *     Tier B off, Fragments-internal rules excluded entirely. This is the
+ *     vocabulary-first, no-flood default a customer repo gets.
+ *   - **`fragments`** — every rule on, for Fragments' own internal scans.
+ *
+ * These produce the rule-config half of a `GovernanceConfig`. The hygiene
+ * *policy facts* (e.g. `style.rawColors.forbid`, spacing scales) are a separate
+ * config axis the customer default simply omits — so a Tier-B rule that gates on
+ * a policy fact (raw-color/spacing/typography) stays inert regardless of its
+ * config flag, and the customer default produces zero findings without a
+ * contract.
+ */
+
+import {
+  FRAGMENTS_INTERNAL_RULE_IDS,
+  RULE_TIER,
+  isContractTierRule,
+} from "./tiers.js";
+
+export interface PresetRuleState {
+  enabled: boolean;
+  severity?: "error" | "warn" | "info";
+}
+
+/**
+ * Customer default rule states: Tier A enabled (self-gating on contract facts),
+ * Tier B disabled, Fragments-internal rules omitted entirely. Feed directly to
+ * `compileGlobalGovernanceFacts({ rules })` (with no hygiene `styles` config).
+ */
+export function customerDefaultRuleStates(): Record<string, PresetRuleState> {
+  const states: Record<string, PresetRuleState> = {};
+  for (const ruleId of Object.keys(RULE_TIER)) {
+    if (FRAGMENTS_INTERNAL_RULE_IDS.has(ruleId)) continue;
+    states[ruleId] = isContractTierRule(ruleId)
+      ? { enabled: true, severity: "warn" }
+      : { enabled: false };
+  }
+  return states;
+}
+
+/**
+ * Full `fragments` preset rule states: every rule on. Includes the
+ * Fragments-internal rules (e.g. `tokens/require-dual-fallback`) the customer
+ * default excludes.
+ */
+export function fragmentsPresetRuleStates(): Record<string, PresetRuleState> {
+  const states: Record<string, PresetRuleState> = {};
+  for (const ruleId of Object.keys(RULE_TIER)) {
+    states[ruleId] = { enabled: true, severity: "warn" };
+  }
+  return states;
+}

package/src/rules/props-invalid-value.ts

@@ -0,0 +1,115 @@
+/**
+ * `props/invalid-value` — fires when a JSX prop is statically assigned a
+ * value outside the component's declared enum values.
+ *
+ * The rule is intentionally conservative: it only runs for exact static
+ * prop values and prop metadata that declares an allowed values list.
+ * Dynamic expressions, spreads, JSX values, and open-ended prop schemas stay
+ * silent so the scanner does not turn weak metadata into false certainty.
+ */
+
+import type { FactIndex } from "../facts/index.js";
+
+import { makeFinding } from "./finding.js";
+import type { Finding } from "./types.js";
+import {
+  indexComponentByNodeId,
+  indexPropsByNodeId,
+  isUniversalJsxProp,
+  readUsageNode,
+} from "./utils.js";
+
+export const RULE_ID = "props/invalid-value";
+export const RULE_VERSION = "1";
+
+export function rulePropsInvalidValue(ix: FactIndex): Finding[] {
+  const policy = ix.policy.ruleConfig(RULE_ID);
+  if (!policy?.enabled) return [];
+
+  const findings: Finding[] = [];
+  const componentByNode = indexComponentByNodeId(ix);
+  const propsByNode = indexPropsByNodeId(ix);
+
+  for (const [nodeId, propUsages] of propsByNode) {
+    const usageComponent = componentByNode.get(nodeId);
+    if (!usageComponent) continue;
+    const node = readUsageNode(ix, nodeId);
+    if (!node) continue;
+
+    for (const propUsage of propUsages) {
+      if (propUsage.resolution !== "static") continue;
+      if (propUsage.value === undefined) continue;
+      if (isUniversalJsxProp(propUsage.prop)) continue;
+
+      const metadata = ix.components.propOf(usageComponent.componentId, propUsage.prop);
+      if (!metadata?.values?.length) continue;
+      const allowedValues = metadata.values;
+
+      const rawValue = toComparableValue(propUsage.value);
+      if (rawValue === null) continue;
+      if (allowedValues.includes(rawValue)) continue;
+
+      const fix =
+        allowedValues.length === 1
+          ? {
+              kind: "replacePropValue" as const,
+              title: `Replace ${propUsage.prop} with ${formatValue(allowedValues[0])}`,
+              prop: propUsage.prop,
+              value: allowedValues[0],
+              deterministic: true,
+            }
+          : undefined;
+
+      findings.push(
+        makeFinding({
+          ruleId: RULE_ID,
+          ruleVersion: RULE_VERSION,
+          severity: policy.severity ?? "warn",
+          message: buildMessage(node.element, propUsage.prop, propUsage.value, allowedValues),
+          location: propUsage.location ?? node.location,
+          evidence: ix.evidence([node.id, usageComponent.id, propUsage.id, metadata.id, policy.id]),
+          fingerprintIdentity: {
+            file: node.file,
+            componentId: usageComponent.componentId,
+            element: node.element,
+            nodePath: node.nodePath,
+            prop: propUsage.prop,
+            value: propUsage.value,
+          },
+          fix,
+          attributes: {
+            componentId: usageComponent.componentId,
+            prop: propUsage.prop,
+            rawValue: propUsage.value,
+            allowedValues,
+          },
+        })
+      );
+    }
+  }
+
+  return findings;
+}
+
+function toComparableValue(value: unknown): string | null {
+  if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+    return String(value);
+  }
+  if (value === null) return "null";
+  return null;
+}
+
+function formatValue(value: unknown): string {
+  if (typeof value === "string") return `"${value}"`;
+  return String(value);
+}
+
+function buildMessage(
+  element: string,
+  prop: string,
+  value: unknown,
+  allowedValues: readonly string[]
+): string {
+  const allowed = allowedValues.map(formatValue).join(", ");
+  return `<${element}> ${prop}=${formatValue(value)} is not an allowed value. Allowed values: ${allowed}.`;
+}