@usefragments/core 1.0.0

package/src/rules/composition-pattern.ts

@@ -0,0 +1,271 @@
+/**
+ * `composition/cardinality` + `composition/co-occurrence` — region-scoped rules
+ * over how components are arranged inside a container, not just per node.
+ *
+ * Both share the same region machinery: `regionsByPrefix` groups usage into
+ * `(container, members)`; a `CompositionPattern` names the container (by
+ * canonical `componentId`), a child `select`or, and a `constraint`. The config
+ * rides in `governance_rule_config.options.patterns` — no new fact kind. Brief
+ * 04 delivers that config from cloud policy / fragment prose; this brief drives
+ * the rules from it directly.
+ *
+ * Static-resolution ceiling: a child is "selected" only when its prop resolves
+ * statically to the configured value. A dynamic `variant={kind}` is unknown —
+ * never a match, never treated as absent. Dynamic composition is the
+ * render-time validator's job (doc 14), not this static rule's.
+ *
+ * Matching is on the resolved canonical component (its `componentId`), never the
+ * raw `element` string — that is what makes the rule survive wrappers and
+ * renames. A policy component ref may be fully qualified (`pkg#Name`) or a bare
+ * name (the common authoring case); see `componentMatches`.
+ */
+
+import type {
+  FactId,
+  FactIndex,
+  UsageComponentFact,
+  UsageNodeFact,
+  UsagePropResolvedFact,
+} from "../facts/index.js";
+import type { GovernanceSeverity } from "../governance.js";
+import { ownedComponentIdsEqual } from "../package-identity-match.js";
+
+import {
+  type CompositionChildSelector,
+  type CompositionConstraint,
+  type CompositionPattern,
+  type CompositionRegionSelector,
+  isCompositionPattern,
+} from "./composition-pattern-schema.js";
+import { makeFinding } from "./finding.js";
+import type { Finding } from "./types.js";
+import {
+  indexComponentByNodeId,
+  indexPropsByNodeId,
+  regionsByPrefix,
+  type Region,
+} from "./utils.js";
+
+export const CARDINALITY_RULE_ID = "composition/cardinality";
+export const CO_OCCURRENCE_RULE_ID = "composition/co-occurrence";
+const RULE_VERSION = "1";
+
+/** ≤ `max` / ≥ `min` of a selected child per matching region. */
+export function ruleCompositionCardinality(ix: FactIndex): Finding[] {
+  return evaluate(ix, CARDINALITY_RULE_ID, "cardinality");
+}
+
+/** A selected child requires a co-occurring sibling in the same region. */
+export function ruleCompositionCoOccurrence(ix: FactIndex): Finding[] {
+  return evaluate(ix, CO_OCCURRENCE_RULE_ID, "co-occurrence");
+}
+
+interface EvalCtx {
+  ix: FactIndex;
+  ruleId: string;
+  severity: GovernanceSeverity;
+  componentByNode: Map<FactId, UsageComponentFact>;
+  propsByNode: Map<FactId, UsagePropResolvedFact[]>;
+}
+
+function evaluate(ix: FactIndex, ruleId: string, kind: CompositionConstraint["kind"]): Finding[] {
+  const config = ix.policy.ruleConfig(ruleId);
+  if (!config || !config.enabled) return [];
+  const patterns = readPatterns(config.options);
+  if (patterns.length === 0) return [];
+
+  const ctx: EvalCtx = {
+    ix,
+    ruleId,
+    severity: config.severity ?? "warn",
+    componentByNode: indexComponentByNodeId(ix),
+    propsByNode: indexPropsByNodeId(ix),
+  };
+  const regions = regionsByPrefix(ix);
+
+  const findings: Finding[] = [];
+  for (const pattern of patterns) {
+    const constraint = pattern.constraint;
+    if (constraint.kind !== kind) continue;
+    for (const region of regions) {
+      if (!regionMatches(region, pattern.region, ctx.componentByNode)) continue;
+      const selected = region.members.filter((m) => memberMatches(m.id, pattern.select, ctx));
+      const finding =
+        constraint.kind === "cardinality"
+          ? checkCardinality(ctx, region, pattern, constraint, selected)
+          : checkCoOccurrence(ctx, region, pattern, constraint, selected);
+      if (finding) findings.push(finding);
+    }
+  }
+  return findings;
+}
+
+function readPatterns(options: Record<string, unknown> | undefined): CompositionPattern[] {
+  const raw = options?.patterns;
+  // Validate each pattern rather than trusting the shape: config arrives from
+  // cloud policy / fragment prose (brief 04) and the facts layer passes
+  // `options` through untyped, so a malformed entry would otherwise emit garbage
+  // findings. A bad pattern is skipped and the rest keep scanning (architecture
+  // failure mode); a non-array yields nothing.
+  if (!Array.isArray(raw)) return [];
+  return raw.filter(isCompositionPattern);
+}
+
+function regionMatches(
+  region: Region,
+  selector: CompositionRegionSelector,
+  componentByNode: Map<FactId, UsageComponentFact>
+): boolean {
+  // v0 matches the container by canonical componentId only. `marker`/`role` are
+  // typed for brief 04 but unexercised by ACCEPTANCE §3–§8; a marker policy will
+  // land with its own case (see brief 03 Deviations).
+  if (!selector.component) return false;
+  return componentMatches(
+    componentByNode.get(region.container.id)?.componentId,
+    selector.component
+  );
+}
+
+/**
+ * Match a usage node's resolved `componentId` against a policy component ref.
+ * A ref may be fully qualified (`@scope/pkg#Name`) or a bare name (`Name`) — the
+ * common authoring case (ACCEPTANCE §3 and the §10 fragment sugar both write
+ * bare names). Matching the resolved componentId — not the raw JSX element —
+ * survives import aliasing and wrapper renames.
+ */
+function componentMatches(componentId: string | undefined, ref: string): boolean {
+  if (componentId === undefined) return false;
+  if (componentId === ref) return true;
+  if (ref.includes("#") && ownedComponentIdsEqual(componentId, ref)) return true;
+  const hash = componentId.indexOf("#");
+  return hash !== -1 && componentId.slice(hash + 1) === ref;
+}
+
+function memberMatches(nodeId: FactId, select: CompositionChildSelector, ctx: EvalCtx): boolean {
+  if (!componentMatches(ctx.componentByNode.get(nodeId)?.componentId, select.component))
+    return false;
+  if (select.prop === undefined) return true;
+  // Static ceiling: only a statically-resolved matching prop counts. A dynamic
+  // or spread prop is unknown — not a match (and not treated as absent).
+  const props = ctx.propsByNode.get(nodeId) ?? [];
+  return props.some((p) => {
+    if (p.prop !== select.prop || p.resolution !== "static") return false;
+    return select.value === undefined || p.value === select.value;
+  });
+}
+
+function checkCardinality(
+  ctx: EvalCtx,
+  region: Region,
+  pattern: CompositionPattern,
+  constraint: { kind: "cardinality"; max?: number; min?: number },
+  selected: UsageNodeFact[]
+): Finding | null {
+  const count = selected.length;
+  if (constraint.max !== undefined && count > constraint.max) {
+    const extras = selected.slice(constraint.max); // the (max+1)th and later
+    return makeFinding({
+      ruleId: ctx.ruleId,
+      ruleVersion: RULE_VERSION,
+      severity: ctx.severity,
+      message: cardinalityMaxMessage(pattern, constraint.max, count),
+      location: extras[0].location,
+      evidence: ctx.ix.evidence([region.container.id, ...extras.map((e) => e.id)]),
+      fingerprintIdentity: cardinalityFingerprint(region, pattern, "max"),
+    });
+  }
+  if (constraint.min !== undefined && count < constraint.min) {
+    return makeFinding({
+      ruleId: ctx.ruleId,
+      ruleVersion: RULE_VERSION,
+      severity: ctx.severity,
+      message: cardinalityMinMessage(pattern, constraint.min, count),
+      location: region.container.location,
+      evidence: ctx.ix.evidence([region.container.id, ...selected.map((s) => s.id)]),
+      fingerprintIdentity: cardinalityFingerprint(region, pattern, "min"),
+    });
+  }
+  return null;
+}
+
+function checkCoOccurrence(
+  ctx: EvalCtx,
+  region: Region,
+  pattern: CompositionPattern,
+  constraint: { kind: "co-occurrence"; requires: { prop: string; value: string } },
+  selected: UsageNodeFact[]
+): Finding | null {
+  if (selected.length === 0) return null; // nothing triggers the requirement
+  const requiredSelect: CompositionChildSelector = {
+    component: pattern.select.component,
+    prop: constraint.requires.prop,
+    value: constraint.requires.value,
+  };
+  const satisfied = region.members.some((m) => memberMatches(m.id, requiredSelect, ctx));
+  if (satisfied) return null;
+  return makeFinding({
+    ruleId: ctx.ruleId,
+    ruleVersion: RULE_VERSION,
+    severity: ctx.severity,
+    message: coOccurrenceMessage(pattern, constraint),
+    location: region.container.location,
+    evidence: ctx.ix.evidence([region.container.id, ...selected.map((s) => s.id)]),
+    fingerprintIdentity: {
+      kind: "co-occurrence",
+      file: region.container.file,
+      container: region.container.nodePath,
+      region: pattern.region.component,
+      requires: `${constraint.requires.prop}=${constraint.requires.value}`,
+    },
+  });
+}
+
+function cardinalityFingerprint(
+  region: Region,
+  pattern: CompositionPattern,
+  bound: "max" | "min"
+): Record<string, unknown> {
+  return {
+    kind: "cardinality",
+    bound,
+    file: region.container.file,
+    container: region.container.nodePath,
+    region: pattern.region.component,
+    select: `${pattern.select.prop ?? ""}=${pattern.select.value ?? ""}`,
+  };
+}
+
+function childLabel(select: CompositionChildSelector, plural: boolean): string {
+  const base = select.value ? `${select.value} ${select.component}` : select.component;
+  return plural ? `${base}s` : base;
+}
+
+/** The human-facing region name; falls back to a generic word when unnamed. */
+function regionLabel(pattern: CompositionPattern): string {
+  return pattern.region.component ?? "region";
+}
+
+function cardinalityMaxMessage(pattern: CompositionPattern, max: number, count: number): string {
+  const region = regionLabel(pattern);
+  const limit = max === 1 ? "one" : String(max);
+  const label = childLabel(pattern.select, max !== 1);
+  const verb = max === 1 ? "is" : "are";
+  return `At most ${limit} ${label} ${verb} allowed per ${region} (found ${count}).`;
+}
+
+function cardinalityMinMessage(pattern: CompositionPattern, min: number, count: number): string {
+  const region = regionLabel(pattern);
+  const label = childLabel(pattern.select, min !== 1);
+  const verb = min === 1 ? "is" : "are";
+  return `At least ${min} ${label} ${verb} required per ${region} (found ${count}).`;
+}
+
+function coOccurrenceMessage(
+  pattern: CompositionPattern,
+  constraint: { requires: { value: string } }
+): string {
+  const region = regionLabel(pattern);
+  const selectLabel = childLabel(pattern.select, false);
+  const requiresLabel = `${constraint.requires.value} ${pattern.select.component}`;
+  return `A ${region} with a ${selectLabel} should also contain a ${requiresLabel}.`;
+}

package/src/rules/emit-gate.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, it } from "vitest";
+
+import { isDenyEligible } from "./emit-gate.js";
+import type { Finding } from "./types.js";
+
+// isDenyEligible reads only ruleId / severity / fix / attributes, so a minimal
+// cast keeps the fixtures focused on the deny criteria under test.
+const base = {
+  ruleId: "components/prefer-library",
+  severity: "serious",
+  fix: { deterministic: true },
+} as unknown as Finding;
+
+describe("isDenyEligible", () => {
+  it("denies a confident, allowlisted, CI-gating, deterministic finding", () => {
+    expect(isDenyEligible(base, false)).toBe(true);
+  });
+
+  it("never denies an advisory-flagged finding, even at error severity", () => {
+    const advisory = { ...base, attributes: { advisory: true } } as unknown as Finding;
+    expect(isDenyEligible(advisory, false)).toBe(false);
+    // failOnWarnings must not resurrect it either.
+    expect(isDenyEligible(advisory, true)).toBe(false);
+  });
+
+  it("does not deny a rule outside the blocking allowlist", () => {
+    expect(isDenyEligible({ ...base, ruleId: "composition/x" } as unknown as Finding, false)).toBe(
+      false
+    );
+  });
+
+  it("only denies a warn-level finding under failOnWarnings", () => {
+    const warn = { ...base, severity: "moderate" } as unknown as Finding;
+    expect(isDenyEligible(warn, false)).toBe(false);
+    expect(isDenyEligible(warn, true)).toBe(true);
+  });
+
+  it("does not deny an explicitly non-deterministic (heuristic) fix", () => {
+    const heuristic = { ...base, fix: { deterministic: false } } as unknown as Finding;
+    expect(isDenyEligible(heuristic, false)).toBe(false);
+  });
+});

package/src/rules/emit-gate.ts

@@ -0,0 +1,60 @@
+/**
+ * The blocking deny-set — the SINGLE source of truth for "which findings may
+ * hard-deny a UI write" across every altitude of the contract: the CLI
+ * pre-write hook (Node) AND the Contract Mode emit gate (a browser-safe
+ * serverless route). Lifted out of `packages/cli/src/hook/check.ts`
+ * (Contract Mode Phase 0) so the two cannot fork — a deny here must imply a CI
+ * failure, and that invariant only holds if both read the same criteria.
+ *
+ * Pure and browser-safe: it reads only a `Finding`'s `ruleId` / `severity` /
+ * `fix` shape — no Node APIs, no config off disk, no clock. The CLI hook
+ * re-exports `isDenyEligible` from here.
+ */
+import { severityLevel } from "../severity.js";
+import type { Finding } from "./types.js";
+
+/**
+ * The ONLY rules whose findings may hard-deny a write: deterministic,
+ * single-file-decidable, high-confidence classes (architecture Open Q2). A rule
+ * is added here DELIBERATELY — new rules gain no blocking power by default, so a
+ * future heuristic rule can't silently start denying writes. Heuristic/INFERRED
+ * classes (`composition/*`, `tailwind/*arbitrary*`) are absent on purpose: at
+ * most advisory, never a block.
+ */
+export const BLOCKING_RULE_ALLOWLIST: ReadonlySet<string> = new Set([
+  "styles/no-raw-color", // raw hex/rgb/hsl color literal
+  "styles/no-raw-spacing", // off-scale / untokenized spacing literal
+  "tailwind/off-scale-spacing-token", // off-scale Tailwind spacing utility
+  "components/prefer-library", // raw element bypasses a canonical component
+  "components/preferred-component", // imported component bypasses its canonical
+]);
+
+/**
+ * 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.
+ */
+export function gatesCi(finding: Finding, failOnWarnings: boolean): boolean {
+  const level = severityLevel(finding.severity);
+  return level === "error" || (failOnWarnings && level === "warn");
+}
+
+/** A finding may deny iff it is allowlisted, gates CI, and is not a flagged-heuristic fix. */
+export function isDenyEligible(finding: Finding, failOnWarnings: boolean): boolean {
+  if (!BLOCKING_RULE_ALLOWLIST.has(finding.ruleId)) return false;
+  // Advisory findings — the low-confidence precision tiers a rule flags with
+  // `attributes.advisory` (prefer-library's role-reimpl / interactive-div /
+  // html-advisory / icon-only tiers, and the reimplements-primitive className
+  // heuristic) — are surfaced but NEVER block a write, even if a project raises
+  // their severity or sets failOnWarnings. Same "only deny when the engine is
+  // confident" principle as the non-deterministic-fix guard below.
+  if (finding.attributes?.advisory === true) return false;
+  if (!gatesCi(finding, failOnWarnings)) return false;
+  // An explicitly non-deterministic fix is the engine's own "low confidence /
+  // ambiguous" signal (e.g. several tokens share a value, or a heuristic swap).
+  // Those stay advisory — only deny when the engine is confident. A finding with
+  // no fix at all (e.g. a raw color with no matching token) still gates CI, so it
+  // remains deny-eligible.
+  if (finding.fix?.deterministic === false) return false;
+  return true;
+}

package/src/rules/finding.ts

@@ -0,0 +1,54 @@
+/**
+ * Finding builder — assembles a `Finding` and computes its fingerprint.
+ *
+ * The fingerprint is a content-addressed hash of a small identity tuple chosen
+ * by each rule. It is *not* the source location: two findings at different
+ * lines for the same offending value should have different fingerprints, but
+ * adding a blank line above them must not change either fingerprint. Rules
+ * pick identity inputs that capture "what's wrong" (file, ruleId, componentId,
+ * prop, property, value) without leaning on lineNumber/column.
+ */
+
+import type { GovernanceSeverity } from "../governance.js";
+import type { FactEvidence, FactLocation } from "../facts/index.js";
+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 { Finding, FindingFix } from "./types.js";
+
+export interface MakeFindingInput {
+  ruleId: string;
+  ruleVersion: string;
+  severity: GovernanceSeverity | Severity;
+  message: string;
+  location: FactLocation;
+  evidence: FactEvidence[];
+  fingerprintIdentity: Record<string, unknown>;
+  fix?: FindingFix;
+  attributes?: Record<string, unknown>;
+}
+
+export function makeFinding(input: MakeFindingInput): Finding {
+  if (input.evidence.length === 0) {
+    throw new Error(`makeFinding(${input.ruleId}): findings must carry at least one evidence fact`);
+  }
+  const fingerprint = hash64Hex(
+    canonicalJson({ ruleId: input.ruleId, ...input.fingerprintIdentity })
+  );
+  const code = byRuleId.get(input.ruleId);
+  return normalizeFinding({
+    ruleId: input.ruleId,
+    ruleVersion: input.ruleVersion,
+    severity: normalizeSeverity(input.severity),
+    code: code?.code,
+    helpUrl: code?.explainUrl,
+    message: input.message,
+    fingerprint,
+    location: input.location,
+    evidence: input.evidence,
+    fix: input.fix,
+    attributes: input.attributes,
+  });
+}

package/src/rules/index.ts

@@ -0,0 +1,235 @@
+/**
+ * Rules — pure functions over `FactIndex` that return `Finding[]`.
+ *
+ * Phase 5 ships five generic rules. They are content-addressed: scanning the
+ * same source twice produces the same fingerprints, so Cloud can dedupe and
+ * preserve event history. Rules never reach into raw fact arrays — every
+ * lookup goes through `FactIndex`.
+ */
+
+import type { FactIndex } from "../facts/index.js";
+
+import { ruleA11yRequiredAccessibleName } from "./a11y-required-accessible-name.js";
+import { ruleComponentsPreferLibrary } from "./components-prefer-library.js";
+import { ruleComponentsForbiddenPropValue } from "./components-forbidden-prop-value.js";
+import { ruleComponentsUnknownProp } from "./components-unknown-prop.js";
+import { ruleCompositionCardinality, ruleCompositionCoOccurrence } from "./composition-pattern.js";
+import { ruleJsxPreferredComponent } from "./jsx-preferred-component.js";
+import { ruleJsxPreferredImportPath } from "./jsx-preferred-import-path.js";
+import { rulePropsInvalidValue } from "./props-invalid-value.js";
+import { ruleStylesNoRawColor } from "./styles-no-raw-color.js";
+import { ruleStylesNoRawDimensions } from "./styles-no-raw-dimensions.js";
+import { ruleStylesNoRawSpacing } from "./styles-no-raw-spacing.js";
+import { ruleStylesNoRawTypography } from "./styles-no-raw-typography.js";
+import { ruleThemeNoThemeCoupledLiteral } from "./theme-no-theme-coupled-literal.js";
+import { ruleTailwindArbitraryColor } from "./tailwind-arbitrary-color.js";
+import { ruleTailwindArbitrarySpacing } from "./tailwind-arbitrary-spacing.js";
+import { ruleTailwindForbiddenPalette } from "./tailwind-forbidden-palette.js";
+import { ruleTailwindOffScaleSpacingToken } from "./tailwind-off-scale-spacing-token.js";
+import { ruleTailwindRawColorViaToken } from "./tailwind-raw-color-via-token.js";
+import { ruleTailwindUnknownClass } from "./tailwind-unknown-class.js";
+import { ruleTokensRequireDualFallback } from "./tokens-require-dual-fallback.js";
+import { ruleTokensCssVarsMustBeDefined } from "./tokens-css-vars-must-be-defined.js";
+import type { Finding } from "./types.js";
+
+export type RuleFn = (ix: FactIndex) => Finding[];
+
+export interface Rule {
+  id: string;
+  version: string;
+  run: RuleFn;
+}
+
+export const RULES: readonly Rule[] = [
+  {
+    id: "components/unknown-prop",
+    version: "1",
+    run: ruleComponentsUnknownProp,
+  },
+  {
+    id: "components/forbidden-prop-value",
+    version: "1",
+    run: ruleComponentsForbiddenPropValue,
+  },
+  {
+    id: "props/invalid-value",
+    version: "1",
+    run: rulePropsInvalidValue,
+  },
+  {
+    id: "imports/preferred-path",
+    version: "1",
+    run: ruleJsxPreferredImportPath,
+  },
+  {
+    id: "components/preferred-component",
+    version: "1",
+    run: ruleJsxPreferredComponent,
+  },
+  {
+    id: "components/prefer-library",
+    version: "1",
+    run: ruleComponentsPreferLibrary,
+  },
+  {
+    id: "styles/no-raw-color",
+    version: "1",
+    run: ruleStylesNoRawColor,
+  },
+  {
+    id: "styles/no-raw-dimensions",
+    version: "1",
+    run: ruleStylesNoRawDimensions,
+  },
+  {
+    id: "styles/no-raw-spacing",
+    version: "1",
+    run: ruleStylesNoRawSpacing,
+  },
+  {
+    id: "styles/no-raw-typography",
+    version: "1",
+    run: ruleStylesNoRawTypography,
+  },
+  {
+    id: "tailwind/arbitrary-color",
+    version: "1",
+    run: ruleTailwindArbitraryColor,
+  },
+  {
+    id: "tailwind/arbitrary-spacing",
+    version: "1",
+    run: ruleTailwindArbitrarySpacing,
+  },
+  {
+    id: "tailwind/forbidden-palette",
+    version: "1",
+    run: ruleTailwindForbiddenPalette,
+  },
+  {
+    id: "tailwind/off-scale-spacing-token",
+    version: "1",
+    run: ruleTailwindOffScaleSpacingToken,
+  },
+  {
+    id: "tailwind/raw-color-via-token",
+    version: "1",
+    run: ruleTailwindRawColorViaToken,
+  },
+  {
+    id: "tailwind/unknown-class",
+    version: "1",
+    run: ruleTailwindUnknownClass,
+  },
+  {
+    id: "tokens/require-dual-fallback",
+    version: "1",
+    run: ruleTokensRequireDualFallback,
+  },
+  {
+    id: "tokens/css-vars-must-be-defined",
+    version: "1",
+    run: ruleTokensCssVarsMustBeDefined,
+  },
+  {
+    id: "theme/no-theme-coupled-literal",
+    version: "1",
+    run: ruleThemeNoThemeCoupledLiteral,
+  },
+  {
+    id: "a11y/required-accessible-name",
+    version: "1",
+    run: ruleA11yRequiredAccessibleName,
+  },
+  {
+    id: "composition/cardinality",
+    version: "1",
+    run: ruleCompositionCardinality,
+  },
+  {
+    id: "composition/co-occurrence",
+    version: "1",
+    run: ruleCompositionCoOccurrence,
+  },
+];
+
+/**
+ * Run every Phase 5 rule and return findings sorted by `(file, line, column,
+ * fingerprint)` so output is stable across runs.
+ */
+export function runRules(ix: FactIndex): Finding[] {
+  const findings: Finding[] = [];
+  for (const rule of RULES) findings.push(...rule.run(ix));
+  return sortFindings(findings);
+}
+
+function sortFindings(findings: Finding[]): Finding[] {
+  return findings.slice().sort((a, b) => {
+    const fileCmp = a.location.file.localeCompare(b.location.file);
+    if (fileCmp !== 0) return fileCmp;
+    if (a.location.line !== b.location.line) return a.location.line - b.location.line;
+    if (a.location.column !== b.location.column) return a.location.column - b.location.column;
+    return a.fingerprint.localeCompare(b.fingerprint);
+  });
+}
+
+export type {
+  Finding,
+  FindingFix,
+  FindingReplaceComponentFix,
+  FindingReplaceImportFix,
+  FindingReplacePropValueFix,
+  FindingReplaceStyleValueFix,
+  FindingReplaceClassTokenFix,
+} from "./types.js";
+export { makeFinding } from "./finding.js";
+// Blocking deny-set (Contract Mode Phase 0): the shared "may this finding
+// hard-deny a write" criteria, used by the CLI pre-write hook and the emit gate.
+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 { rulePropsInvalidValue } from "./props-invalid-value.js";
+export { ruleJsxPreferredImportPath } from "./jsx-preferred-import-path.js";
+export { ruleJsxPreferredComponent } from "./jsx-preferred-component.js";
+export { ruleStylesNoRawColor } from "./styles-no-raw-color.js";
+export { ruleStylesNoRawDimensions } from "./styles-no-raw-dimensions.js";
+export { ruleStylesNoRawSpacing } from "./styles-no-raw-spacing.js";
+export { ruleStylesNoRawTypography } from "./styles-no-raw-typography.js";
+export { ruleTailwindArbitraryColor } from "./tailwind-arbitrary-color.js";
+export { ruleTailwindArbitrarySpacing } from "./tailwind-arbitrary-spacing.js";
+export { ruleTailwindForbiddenPalette } from "./tailwind-forbidden-palette.js";
+export { ruleTailwindOffScaleSpacingToken } from "./tailwind-off-scale-spacing-token.js";
+export { ruleTailwindRawColorViaToken } from "./tailwind-raw-color-via-token.js";
+export { ruleTailwindUnknownClass } from "./tailwind-unknown-class.js";
+export { ruleTokensRequireDualFallback } from "./tokens-require-dual-fallback.js";
+export { ruleTokensCssVarsMustBeDefined } from "./tokens-css-vars-must-be-defined.js";
+export { ruleThemeNoThemeCoupledLiteral } from "./theme-no-theme-coupled-literal.js";
+export { ruleA11yRequiredAccessibleName } from "./a11y-required-accessible-name.js";
+export { ruleCompositionCardinality, ruleCompositionCoOccurrence } from "./composition-pattern.js";
+export {
+  RULE_TIER,
+  FRAGMENTS_INTERNAL_RULE_IDS,
+  tierFor,
+  isContractTierRule,
+  contractTierRuleIds,
+  hygieneTierRuleIds,
+  vocabularyRank,
+  compareByVocabularyRank,
+} from "./tiers.js";
+export type { RuleTier } from "./tiers.js";
+export { customerDefaultRuleStates, fragmentsPresetRuleStates } from "./presets.js";
+export type { PresetRuleState } from "./presets.js";
+export {
+  compositionPatternSchema,
+  compositionAuthoringEntrySchema,
+  isCompositionPattern,
+  lowerCompositionContract,
+} from "./composition-pattern-schema.js";
+export type {
+  CompositionPattern,
+  CompositionRegionSelector,
+  CompositionChildSelector,
+  CompositionConstraint,
+  CompositionAuthoringEntry,
+} from "./composition-pattern-schema.js";