@usefragments/core 1.5.1 → 1.6.0

package/src/governance.ts

@@ -10,10 +10,18 @@ import type {
   PropDefinition,
 } from "./types.js";
 import { portableRepoPathError } from "./config-paths.js";
+import { policyExcludeSchema } from "./policy-exclude.js";
 
 export const governanceSeveritySchema = z.enum(["error", "warn", "info"]);
 export type GovernanceSeverity = z.infer<typeof governanceSeveritySchema>;
 
+/**
+ * Per-record path excludes. Scopes THIS policy record off the matching paths without
+ * hiding those paths from any other rule — an auditable exemption, not a baseline.
+ * Excluded findings are reported in the scan's ignored accounting with their reason.
+ */
+const recordExcludeSchema = policyExcludeSchema.optional();
+
 export const scaleGovernanceRecordSchema = z.object({
   kind: z.literal("scale").default("scale"),
   name: z.string().min(1).optional(),
@@ -28,6 +36,7 @@ const styleRawColorsForbidRecordSchema = z.object({
   except: z.array(z.string()),
   prefer: z.enum(["token", "css-variable"]),
   severity: governanceSeveritySchema,
+  exclude: recordExcludeSchema,
 });
 
 const styleRawDimensionsForbidRecordSchema = z.object({
@@ -35,6 +44,7 @@ const styleRawDimensionsForbidRecordSchema = z.object({
   appliesTo: z.array(z.string().min(1)),
   prefer: z.enum(["token", "css-variable"]),
   severity: governanceSeveritySchema,
+  exclude: recordExcludeSchema,
 });
 
 const styleRawSpacingMustMatchScaleRecordSchema = z.object({
@@ -42,17 +52,20 @@ const styleRawSpacingMustMatchScaleRecordSchema = z.object({
   scale: z.string().min(1),
   appliesTo: z.array(z.string().min(1)),
   severity: governanceSeveritySchema,
+  exclude: recordExcludeSchema,
 });
 
 const styleFontSizeMustMatchScaleRecordSchema = z.object({
   kind: z.literal("style.fontSize.mustMatchScale"),
   scale: z.string().min(1),
   severity: governanceSeveritySchema,
+  exclude: recordExcludeSchema,
 });
 
 const styleCssVarsMustBeDefinedRecordSchema = z.object({
   kind: z.literal("style.cssVars.mustBeDefined"),
   severity: governanceSeveritySchema,
+  exclude: recordExcludeSchema,
 });
 
 export const globalStyleGovernanceRecordSchema = z.discriminatedUnion("kind", [
@@ -66,12 +79,14 @@ export const globalStyleGovernanceRecordSchema = z.discriminatedUnion("kind", [
 const jsxUnknownPropsForbidRecordSchema = z.object({
   kind: z.literal("jsx.unknownProps.forbid"),
   severity: governanceSeveritySchema,
+  exclude: recordExcludeSchema,
 });
 
 const jsxInlineStyleForbidRawRecordSchema = z.object({
   kind: z.literal("jsx.inlineStyle.forbidRaw"),
   properties: z.array(z.string().min(1)),
   severity: governanceSeveritySchema,
+  exclude: recordExcludeSchema,
 });
 
 const jsxImportPathPreferRecordSchema = z.object({
@@ -81,6 +96,7 @@ const jsxImportPathPreferRecordSchema = z.object({
   imported: z.string().min(1).optional(),
   because: z.string().optional(),
   severity: governanceSeveritySchema,
+  exclude: recordExcludeSchema,
 });
 
 const jsxComponentPreferRecordSchema = z.object({
@@ -89,6 +105,7 @@ const jsxComponentPreferRecordSchema = z.object({
   to: z.string().min(1),
   because: z.string().optional(),
   severity: governanceSeveritySchema,
+  exclude: recordExcludeSchema,
 });
 
 export const globalJsxGovernanceRecordSchema = z.discriminatedUnion("kind", [
@@ -337,6 +354,7 @@ export const governanceConfigSchema = z
     ci: z
       .object({
         failOnWarnings: z.boolean().optional(),
+        failOnInert: z.boolean().optional(),
       })
       .passthrough()
       .optional(),
@@ -355,18 +373,55 @@ export type CanonicalSource = z.infer<typeof canonicalSourceSchema>;
 export type CanonicalBridgeV1 = z.infer<typeof canonicalBridgeV1Schema>;
 
 export interface GovernanceConfig {
+  /** Shared governance config modules to extend before applying this file's declarations. */
   extends?: string[];
+
+  /** Default severity for governance rules that do not declare their own severity. */
   severity?: GovernanceSeverity;
+
+  /**
+   * Rule-id keyed enablement and severity overrides. Only fields consumed by the named
+   * rule are valid; unsupported fields are reported as inert config.
+   */
   rules?: Record<string, unknown>;
+
+  /** Agent-id keyed rule overrides for supported agent-specific governance policies. */
   agents?: Record<string, { rules?: Record<string, unknown> }>;
+
+  /** Reserved audit compatibility object; undeclared child keys are reported as inert. */
   audit?: Record<string, unknown>;
+
+  /** Reserved runner compatibility map; undeclared child keys are reported as inert. */
   runners?: Record<string, Record<string, unknown>>;
+
+  /**
+   * Canonical component authorities: npm packages, repository directories, or registry
+   * receipts whose included exports arm canonical-component rules.
+   */
   canonicalSources?: CanonicalSource[];
+
+  /**
+   * Confirmed mappings from an underlying library export to the approved local wrapper.
+   * The wrapper's implementationFiles scope permits its direct underlying import.
+   */
   canonicalBridges?: CanonicalBridgeV1[];
+
+  /** Versioned governance presets to resolve before applying local rule overrides. */
   presets?: string[];
+
+  /**
+   * Named numeric scales. Spacing rules bind through
+   * style.rawSpacing.mustMatchScale; the built-in spacing policy references `space`.
+   */
   scales?: Record<string, ScaleGovernanceRecord>;
+
+  /** Legacy typed style-policy records, normalized into the active rule policy. */
   styles?: GlobalStyleGovernanceRecord[];
+
+  /** Legacy typed JSX-policy records, normalized into the active rule policy. */
   jsx?: GlobalJsxGovernanceRecord[];
+
+  /** Tailwind palette allow/deny policy used by Tailwind governance rules. */
   tailwind?: {
     palette?: {
       allow?: string[];
@@ -374,19 +429,95 @@ export interface GovernanceConfig {
     };
     [key: string]: unknown;
   };
+
+  /** Agent repair-order guidance consumed when presenting deterministic fixes. */
   agent?: {
     repairOrder?: string[];
     [key: string]: unknown;
   };
+
+  /** Component-keyed governance records for canonical component metadata and prop policy. */
   components?: Record<string, ComponentPolicyRecord>;
+
+  /** Ordered component-policy overrides selected by component identity fields. */
   overrides?: ComponentPolicyOverride[];
+
+  /**
+   * Governance CI rendering options: `failOnWarnings` makes warning findings fail the
+   * `--ci` verdict, `failOnInert` makes inert-config diagnostics (FUI9004-FUI9008) fail
+   * it. Both are opt-in; `--allow-inert` bypasses the inert gates.
+   */
   ci?: {
     failOnWarnings?: boolean;
+    /**
+     * Fail the `--ci` verdict when the run reports inert-config diagnostics
+     * (FUI9004-FUI9008). Opt-in: the diagnostics themselves stay verdict-neutral,
+     * so a team can adopt the gate once its config is clean. `--allow-inert`
+     * bypasses it, like the governance-inert gate.
+     */
+    failOnInert?: boolean;
     [key: string]: unknown;
   };
   [key: string]: unknown;
 }
 
+/**
+ * Provenance for a `govern.rules` entry: was it authored by the user, or contributed by
+ * a preset?
+ *
+ * A preset's broad entry (`tokens/hardcoded-values: { enabled: true, severity: "warn" }`)
+ * and a user's identical one mean different things. The preset's is a **default** — it
+ * says what the family looks like when nobody has an opinion. The user's is an
+ * **override** — they typed it. After merge the two are indistinguishable by shape, so
+ * the enforcement pass was capping user-authored `govern.styles[].severity: "error"`
+ * records at the preset's `warn` and saying nothing (report #2 B4).
+ *
+ * A global symbol rather than a config key, deliberately: provenance must not be
+ * authorable (a user cannot claim their entry came from a preset), must not survive the
+ * JSON round-trip into a served Cloud policy (where it would be a lie — that path merges
+ * no presets), and must not appear in a config the user reads back. `Symbol.for` so the
+ * marker survives duplicate module instances.
+ */
+const PRESET_SOURCED_RULE = Symbol.for("@usefragments/core:preset-sourced-rule");
+
+/**
+ * Tag every entry of a preset's `govern.rules` map as preset-sourced. Non-object entries
+ * (the `"warn"` string shorthand) cannot carry a symbol and are passed through untagged —
+ * presets author the object form, so this is a documented floor, not a silent gap.
+ *
+ * **Non-enumerable**, which is the difference between "does not serialize" and "is not
+ * there". A symbol key already survives neither `JSON.stringify` nor `Object.keys`, but
+ * it does survive `toEqual` — so an enumerable marker turns every consumer that compares
+ * a composed rule config structurally into a failing test, for a property they cannot see
+ * and did not ask for. Fragments Cloud's own policy composer was the first to hit it.
+ * Read it through `isPresetSourcedRule`; nothing else should know it exists.
+ */
+export function markPresetSourcedRules(
+  rules: Record<string, unknown> | undefined
+): Record<string, unknown> | undefined {
+  if (!rules) return rules;
+  const out: Record<string, unknown> = {};
+  for (const [ruleId, entry] of Object.entries(rules)) {
+    out[ruleId] =
+      entry && typeof entry === "object" && !Array.isArray(entry)
+        ? Object.defineProperty({ ...(entry as Record<string, unknown>) }, PRESET_SOURCED_RULE, {
+            value: true,
+            enumerable: false,
+          })
+        : entry;
+  }
+  return out;
+}
+
+/** Whether a merged `govern.rules` entry came from a preset rather than the user. */
+export function isPresetSourcedRule(entry: unknown): boolean {
+  return (
+    !!entry &&
+    typeof entry === "object" &&
+    (entry as Record<symbol, unknown>)[PRESET_SOURCED_RULE] === true
+  );
+}
+
 type SeverityOption = {
   severity?: GovernanceSeverity;
 };

package/src/index.ts

@@ -425,7 +425,7 @@ export {
 } from "./schema.js";
 
 // Main API
-export { defineConfig } from "./config.js";
+export { configDeclarationForDiagnostics, defineConfig } from "./config.js";
 export {
   defineFragment,
   compileFragment,
@@ -448,6 +448,8 @@ export {
   globalStyleGovernanceRecordSchema,
   governanceConfigSchema,
   governanceSeveritySchema,
+  isPresetSourcedRule,
+  markPresetSourcedRules,
   normalizeGovernanceConfig,
   scaleGovernanceRecordSchema,
 } from "./governance.js";
@@ -471,6 +473,18 @@ export type {
   ScaleGovernanceRecord,
 } from "./governance.js";
 
+// Scoped policy exemptions — per-record / per-rule path excludes
+export {
+  describePolicyExclude,
+  excludeGlobToRegExp,
+  matchPolicyExclude,
+  normalizeExcludePath,
+  normalizePolicyExcludes,
+  policyExcludeMatchesPath,
+  policyExcludeSchema,
+} from "./policy-exclude.js";
+export type { PolicyExclude, PolicyExcludeInput } from "./policy-exclude.js";
+
 // Story adapter (runtime conversion of Storybook modules)
 export {
   storyModuleToFragment,
@@ -706,6 +720,15 @@ export {
 } from "./rules/index.js";
 export type { RuleTier, PresetRuleState } from "./rules/index.js";
 
+// Rule families — the ONE expansion of a broad `govern.rules` id (`tokens/hardcoded-values`)
+// into the concrete rules it stands for. Three copies used to disagree.
+export {
+  RULE_FAMILY_IDS,
+  RULE_FAMILY_MEMBERS,
+  isRuleFamilyId,
+  ruleFamilyMembers,
+} from "./rules/index.js";
+
 // Blocking deny-set (Contract Mode Phase 0): shared "may this finding hard-deny
 // a write" criteria — single-sourced for the CLI hook + the emit gate.
 export { BLOCKING_RULE_ALLOWLIST, gatesCi, isDenyEligible } from "./rules/index.js";
@@ -713,6 +736,13 @@ export { BLOCKING_RULE_ALLOWLIST, gatesCi, isDenyEligible } from "./rules/index.
 // Governance integrity — armed-vs-declared verdict over a fully-resolved policy.
 // Encodes "enabled ≠ armed": a rule with no vocabulary enforces nothing.
 export {
+  collidingRecordDiagnostic,
+  collidingRecordDiagnostics,
+  configRecordShape,
+  overriddenRecordSeverityDiagnostic,
+  detectOrphanGovernanceScales,
+  detectUnconsumedConfigKeys,
+  detectUnmatchedPolicyExcludes,
   evaluateGovernanceIntegrity,
   hasEffectiveComponentVocabulary,
   isEffectiveCanonicalSource,
@@ -721,8 +751,12 @@ export type {
   GovernanceIntegrityFamily,
   GovernanceIntegrityFamilyId,
   GovernanceIntegrityInput,
+  GovernanceIntegrityRoster,
   GovernanceIntegrityStatus,
   GovernanceIntegrityVerdict,
+  InertConfigDiagnostic,
+  InertConfigDiagnosticCode,
+  InertConfigDiagnosticKind,
 } from "./governance-integrity.js";
 
 export {
@@ -731,7 +765,12 @@ export {
 } from "./canonical-direction.js";
 export type { CanonicalDirectionConflict } from "./canonical-direction.js";
 
-export { canonicalBridgeContractMappings } from "./canonical-bridge.js";
+export {
+  canonicalBridgeContractMappings,
+  canonicalBridgeIdentityBindings,
+  canonicalBridgeIdentitySources,
+} from "./canonical-bridge.js";
+export type { CanonicalBridgeIdentityBinding } from "./canonical-bridge.js";
 
 export {
   compileEffectiveGovernanceInputs,
@@ -794,7 +833,9 @@ export {
   makeTailwindTokenResolvedFact,
   compileGlobalGovernanceFacts,
   compileComponentFacts,
+  projectSupersededImportPathPreferences,
 } from "./facts/index.js";
+export type { SupersededImportPathPreference } from "./facts/index.js";
 export {
   canonicalPreimage,
   AGENT_CONTEXT_RELATIVE_PATH,
@@ -884,6 +925,7 @@ export type {
   ComponentId,
   FactId,
   Fact,
+  FactConflict,
   FactKind,
   FactOfKind,
   FactLocation,
@@ -926,6 +968,7 @@ export type {
   UsageInlineStyleFact,
   UsageTextChildFact,
   StyleDeclarationFact,
+  StyleValueProvenance,
   StyleUnsupportedFact,
   UnsupportedStyleReason,
   ClassNameLiteralFact,

package/src/policy-exclude.ts

@@ -0,0 +1,113 @@
+/**
+ * Policy path excludes — the one vocabulary every scoped-exemption surface shares.
+ *
+ * A global governance record (`govern.styles[]` / `govern.jsx[]`) or a rule-id-keyed
+ * override (`govern.rules["styles/no-raw-color"]`) may carry `exclude` globs that scope
+ * that policy off a path *without* hiding the path from every other rule — the
+ * difference between an exemption and a baseline. Two authoring forms are accepted:
+ *
+ * ```ts
+ * exclude: ["src/legacy/vendor/**"]
+ * exclude: [{ glob: "src/legacy/vendor/**", reason: "vendor drop, tracked in DS-611" }]
+ * ```
+ *
+ * Both normalize to `PolicyExclude`. The reason is free text and carries no expiry: an
+ * exclude is a standing scope decision, not a dated debt receipt (that is what
+ * suppressions and baselines are for). It travels into the scan's ignored-finding
+ * accounting so an exemption is never invisible policy.
+ *
+ * Browser-safe: pure string work, no filesystem.
+ */
+
+import { z } from "zod";
+
+export interface PolicyExclude {
+  /** Repo-relative glob; `*` stops at a path segment, `**` crosses segments. */
+  glob: string;
+  /** Why this path is out of scope for this policy. Surfaced in reports. */
+  reason?: string;
+}
+
+export const policyExcludeSchema = z.array(
+  z.union([
+    z.string().min(1),
+    z.object({
+      glob: z.string().min(1),
+      reason: z.string().min(1).optional(),
+    }),
+  ])
+);
+
+/** The authored (pre-normalization) shape of an `exclude` list. */
+export type PolicyExcludeInput = z.infer<typeof policyExcludeSchema>;
+
+/**
+ * Normalize an authored `exclude` list into `PolicyExclude[]`. Returns `undefined` when
+ * nothing usable was authored, so callers can omit the field entirely and keep fact
+ * shapes byte-identical for configs that declare no excludes.
+ */
+export function normalizePolicyExcludes(value: unknown): PolicyExclude[] | undefined {
+  if (!Array.isArray(value)) return undefined;
+  const out: PolicyExclude[] = [];
+  for (const entry of value) {
+    if (typeof entry === "string") {
+      if (entry.length > 0) out.push({ glob: entry });
+      continue;
+    }
+    if (!entry || typeof entry !== "object") continue;
+    const record = entry as { glob?: unknown; reason?: unknown };
+    if (typeof record.glob !== "string" || record.glob.length === 0) continue;
+    out.push({
+      glob: record.glob,
+      ...(typeof record.reason === "string" && record.reason.length > 0
+        ? { reason: record.reason }
+        : {}),
+    });
+  }
+  return out.length > 0 ? out : undefined;
+}
+
+/** Normalize a repo path for glob comparison (POSIX separators, no `./` prefix). */
+export function normalizeExcludePath(path: string): string {
+  return path.replaceAll("\\", "/").replace(/^\.\//, "");
+}
+
+/**
+ * Same glob dialect as the rest of the governance surface (`FactIndex.matchesGlob`,
+ * the scan's token-source matcher): `**` crosses path segments, `*` does not.
+ */
+export function excludeGlobToRegExp(glob: string): RegExp {
+  const source = normalizeExcludePath(glob)
+    .split("**")
+    .map((part) =>
+      part
+        .split("*")
+        .map((segment) => segment.replace(/[|\\{}()[\]^$+?.]/g, "\\$&"))
+        .join("[^/]*")
+    )
+    .join(".*");
+  return new RegExp(`^${source}$`);
+}
+
+/** Whether `filePath` is inside `exclude`'s glob. */
+export function policyExcludeMatchesPath(exclude: PolicyExclude, filePath: string): boolean {
+  return excludeGlobToRegExp(exclude.glob).test(normalizeExcludePath(filePath));
+}
+
+/** The first exclude covering `filePath`, or `undefined`. */
+export function matchPolicyExclude(
+  excludes: readonly PolicyExclude[] | undefined,
+  filePath: string
+): PolicyExclude | undefined {
+  if (!excludes?.length) return undefined;
+  const normalized = normalizeExcludePath(filePath);
+  return excludes.find((exclude) => excludeGlobToRegExp(exclude.glob).test(normalized));
+}
+
+/**
+ * The human half of the ignored-finding receipt: which policy stepped aside, on which
+ * glob, and why. `scope` is the policy's own identity (a record `kind` or a rule id).
+ */
+export function describePolicyExclude(scope: string, exclude: PolicyExclude): string {
+  return `${scope} exclude matched ${exclude.glob}${exclude.reason ? ` — ${exclude.reason}` : ""}`;
+}

package/src/rules/families.test.ts

@@ -0,0 +1,69 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  RULE_FAMILY_IDS,
+  RULE_FAMILY_MEMBERS,
+  isRuleFamilyId,
+  ruleFamilyMembers,
+} from "./families.js";
+import { compileGlobalGovernanceFacts } from "../facts/index.js";
+import { RULES } from "./index.js";
+import { RULE_TIER } from "./tiers.js";
+
+// The defect this file locks down: the family expansion used to be written out three
+// times (engine finding-overrides, fact compiler, integrity roster) and the three
+// disagreed — `styles/no-raw-typography` was a member in one and absent from another,
+// with nothing asserting they matched. There is one definition now; these tests are what
+// keeps a fourth copy from being worth writing.
+describe("rule families", () => {
+  it("expands only to rule ids that are actually registered", () => {
+    const registered = new Set(RULES.map((rule) => rule.id));
+    const unregistered = Object.values(RULE_FAMILY_MEMBERS)
+      .flat()
+      .filter((ruleId) => !registered.has(ruleId));
+
+    expect(unregistered).toEqual([]);
+  });
+
+  it("classifies every member in the tier map", () => {
+    const unclassified = Object.values(RULE_FAMILY_MEMBERS)
+      .flat()
+      .filter((ruleId) => !(ruleId in RULE_TIER));
+
+    expect(unclassified).toEqual([]);
+  });
+
+  // A family id is a config vocabulary word, not a rule: nothing runs under it. If one
+  // ever collided with a real rule id, `ruleFamilyMembers` would silently expand that
+  // rule into a different set.
+  it("keeps family ids disjoint from rule ids", () => {
+    const registered = new Set(RULES.map((rule) => rule.id));
+    expect([...RULE_FAMILY_IDS].filter((id) => registered.has(id))).toEqual([]);
+  });
+
+  // The member whose absence caused the original divergence. Asserting the definition is
+  // not enough — this pins the BEHAVIOR the consolidation changed: a family entry now
+  // compiles an effective rule config for typography like it always did for color.
+  it("compiles a rule config for every member of an authored family entry", () => {
+    const compiled = compileGlobalGovernanceFacts({
+      rules: { "tokens/hardcoded-values": { enabled: true, severity: "warn" } },
+    })
+      .filter((fact) => fact.kind === "governance_rule_config")
+      .map((fact) => fact.ruleId)
+      .sort();
+
+    // A superset check: the family id keeps its own passthrough entry alongside the
+    // expansion. What matters is that no member is missing.
+    for (const member of RULE_FAMILY_MEMBERS["tokens/hardcoded-values"]!) {
+      expect(compiled).toContain(member);
+    }
+    expect(compiled).toContain("styles/no-raw-typography");
+  });
+
+  it("expands a family and passes a concrete rule id through unchanged", () => {
+    expect(ruleFamilyMembers("tokens/hardcoded-values")).toContain("styles/no-raw-typography");
+    expect(ruleFamilyMembers("styles/no-raw-color")).toEqual(["styles/no-raw-color"]);
+    expect(isRuleFamilyId("tokens/hardcoded-values")).toBe(true);
+    expect(isRuleFamilyId("styles/no-raw-color")).toBe(false);
+  });
+});

package/src/rules/families.ts

@@ -0,0 +1,52 @@
+/**
+ * Rule families — the single source of truth for the broad ids a config may name
+ * instead of a concrete rule.
+ *
+ * `govern.rules` accepts two vocabularies: a concrete rule id (`styles/no-raw-color`)
+ * and a **family** id (`tokens/hardcoded-values`) that stands for several rules at once.
+ * Presets and Cloud-served policies author the family form, so this expansion decides
+ * what a preset or a served policy actually turns on.
+ *
+ * It used to be written out three times — the engine's finding-override pass, the fact
+ * compiler, and the governance-integrity roster — and the three disagreed:
+ * `styles/no-raw-typography` was a member of `tokens/hardcoded-values` in the engine and
+ * absent from the compiler, so one config produced two different answers about the same
+ * rule and nothing asserted they matched. One definition, one expansion, one coverage
+ * test (`families.test.ts` checks every member is a registered rule id).
+ *
+ * Family ids are NOT rule ids: nothing runs under `tokens/hardcoded-values`, it only
+ * expands. Adding a rule to a family is a behavior change for every config that names
+ * the family — classify new rules here in the same change that registers them.
+ */
+
+export const RULE_FAMILY_MEMBERS: Readonly<Record<string, readonly string[]>> = {
+  "tokens/hardcoded-values": [
+    "styles/no-raw-color",
+    "styles/no-raw-spacing",
+    "styles/no-raw-typography",
+    "tokens/require-dual-fallback",
+    "theme/no-theme-coupled-literal",
+  ],
+  "components/usage": [
+    "components/forbidden-prop-value",
+    "components/preferred-component",
+    "components/unknown-prop",
+    "props/invalid-value",
+  ],
+  "a11y/wcag": ["a11y/required-accessible-name"],
+};
+
+/** The family ids themselves — recognized in `govern.rules`, never executed. */
+export const RULE_FAMILY_IDS: ReadonlySet<string> = new Set(Object.keys(RULE_FAMILY_MEMBERS));
+
+export function isRuleFamilyId(ruleId: string): boolean {
+  return RULE_FAMILY_IDS.has(ruleId);
+}
+
+/**
+ * The concrete rule ids a `govern.rules` key applies to: a family expands, anything
+ * else is itself. Every consumer of the family vocabulary goes through this.
+ */
+export function ruleFamilyMembers(ruleId: string): readonly string[] {
+  return RULE_FAMILY_MEMBERS[ruleId] ?? [ruleId];
+}

package/src/rules/index.ts

@@ -232,6 +232,12 @@ export {
   compareByVocabularyRank,
 } from "./tiers.js";
 export type { RuleTier } from "./tiers.js";
+export {
+  RULE_FAMILY_IDS,
+  RULE_FAMILY_MEMBERS,
+  isRuleFamilyId,
+  ruleFamilyMembers,
+} from "./families.js";
 export { customerDefaultRuleStates, fragmentsPresetRuleStates } from "./presets.js";
 export type { PresetRuleState } from "./presets.js";
 export {

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

@@ -1,4 +1,4 @@
-import type { FactIndex } from "../facts/index.js";
+import type { FactIndex, JsxImportPathPreferredFact, UsageImportFact } from "../facts/index.js";
 import { ownedImportMatchesRoot, ownedImportsEqual } from "../package-identity-match.js";
 
 import { makeFinding } from "./finding.js";
@@ -15,22 +15,21 @@ export function ruleJsxPreferredImportPath(ix: FactIndex): Finding[] {
   const seen = new Set<string>();
 
   for (const usage of ix.byKind("usage_import")) {
+    // A confirmed bridge supersedes any non-bridge preference over the same
+    // underlying import (report #2 B6): without this, both policies emit with
+    // the same fingerprint (corrupting baseline/Cloud dedupe) and the hand
+    // rule flags the wrapper's own implementation file with a self-import fix.
+    // The bridge's domain — not its implementation-file exemption — decides
+    // supersession, so inside an exempt file the duplicate stays silent too.
+    const bridgeGoverned = policies.some((policy) => bridgeGovernsUnderlyingImport(policy, usage));
     const matches = policies.filter((policy) => {
       if (policy.bridge) {
         if (policy.bridge.implementationFiles.some((file) => sameRepoPath(file, usage.file))) {
           return false;
         }
-        if (!ownedImportMatchesRoot(usage.source, policy.from)) return false;
-        if (ownedImportsEqual(usage.source, policy.from)) {
-          return usage.imported === policy.bridge.underlyingExportName;
-        }
-        const subpath = usage.source.slice(policy.from.length + 1);
-        const leaf = subpath.split("/").at(-1);
-        return (
-          leaf === policy.bridge.underlyingExportName &&
-          (usage.imported === "default" || usage.imported === policy.bridge.underlyingExportName)
-        );
+        return bridgeGovernsUnderlyingImport(policy, usage);
       }
+      if (bridgeGoverned) return false;
       if (!ownedImportsEqual(policy.from, usage.source)) return false;
       if (policy.imported !== undefined && policy.imported !== usage.imported) return false;
       return true;
@@ -94,6 +93,25 @@ export function ruleJsxPreferredImportPath(ix: FactIndex): Finding[] {
   return findings;
 }
 
+/** Whether the bridge policy's underlying-import domain covers this usage. */
+function bridgeGovernsUnderlyingImport(
+  policy: JsxImportPathPreferredFact,
+  usage: UsageImportFact
+): boolean {
+  const bridge = policy.bridge;
+  if (!bridge) return false;
+  if (!ownedImportMatchesRoot(usage.source, policy.from)) return false;
+  if (ownedImportsEqual(usage.source, policy.from)) {
+    return usage.imported === bridge.underlyingExportName;
+  }
+  const subpath = usage.source.slice(policy.from.length + 1);
+  const leaf = subpath.split("/").at(-1);
+  return (
+    leaf === bridge.underlyingExportName &&
+    (usage.imported === "default" || usage.imported === bridge.underlyingExportName)
+  );
+}
+
 function sameRepoPath(left: string, right: string): boolean {
   return normalizeRepoPath(left) === normalizeRepoPath(right);
 }