@usefragments/core 1.5.2 → 1.7.0

package/src/index.ts

@@ -133,6 +133,11 @@ export {
 } from "./config-paths.js";
 
 // Types
+export {
+  CompiledFragmentsFileValidationError,
+  parseCompiledFragmentsFile,
+} from "./compiled-types/index.js";
+
 export type {
   FragmentComponent,
   ComponentRef,
@@ -448,6 +453,8 @@ export {
   globalStyleGovernanceRecordSchema,
   governanceConfigSchema,
   governanceSeveritySchema,
+  isPresetSourcedRule,
+  markPresetSourcedRules,
   normalizeGovernanceConfig,
   scaleGovernanceRecordSchema,
 } from "./governance.js";
@@ -471,6 +478,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,
@@ -652,6 +671,7 @@ export {
   ruleTailwindUnknownClass,
   ruleTokensRequireDualFallback,
   ruleA11yRequiredAccessibleName,
+  ruleA11yStandard,
 } from "./rules/index.js";
 export { indexComponentIdentityUsage, type ComponentIdentityUsage } from "./identity/usage.js";
 export { nearestSignedScaleValue } from "./rules/utils.js";
@@ -706,6 +726,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,8 +742,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,
@@ -737,7 +771,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,
@@ -787,6 +826,7 @@ export {
   makeTailwindUnknownClassEnabledFact,
   makeUsageNodeFact,
   makeUsageComponentFact,
+  makeUsageChildContentFact,
   makeUsageImportFact,
   makeUsagePropResolvedFact,
   makeUsageInlineStyleFact,
@@ -800,7 +840,9 @@ export {
   makeTailwindTokenResolvedFact,
   compileGlobalGovernanceFacts,
   compileComponentFacts,
+  projectSupersededImportPathPreferences,
 } from "./facts/index.js";
+export type { SupersededImportPathPreference } from "./facts/index.js";
 export {
   canonicalPreimage,
   AGENT_CONTEXT_RELATIVE_PATH,
@@ -890,6 +932,7 @@ export type {
   ComponentId,
   FactId,
   Fact,
+  FactConflict,
   FactKind,
   FactOfKind,
   FactLocation,
@@ -927,11 +970,13 @@ export type {
   TailwindUnknownClassEnabledFact,
   UsageNodeFact,
   UsageComponentFact,
+  UsageChildContentFact,
   UsageImportFact,
   UsagePropResolvedFact,
   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/a11y-required-accessible-name.ts

@@ -1,7 +1,7 @@
 /**
- * `a11y/required-accessible-name` — fires for components with an
- * `a11y.requireName` policy whose JSX usage has no discoverable accessible
- * name.
+ * `a11y/required-accessible-name` — fires for a component with an authored
+ * `a11y.requireName` policy, or for a statically proven control when the global
+ * rule is enabled, whose JSX usage has no discoverable accessible name.
  *
  * Accepted name sources (any one is enough):
  *   - non-empty `usage_text_child` content
@@ -9,55 +9,107 @@
  *     dynamic value is empty at scan time)
  *   - `aria-labelledby={...}`
  *   - `title="..."`
+ *   - statically non-empty or conservatively classified runtime child content
+ *     on controls whose accessible-name model permits naming from contents
  *
  * Components that explicitly opt out via `aria-hidden="true"` are skipped —
  * they are not part of the accessibility tree.
  */
 
-import type { FactIndex, UsagePropResolvedFact } from "../facts/index.js";
+import type {
+  ComponentDefinitionFact,
+  FactIndex,
+  UsageComponentFact,
+  UsageChildContentFact,
+  UsageNodeFact,
+  UsagePropResolvedFact,
+} from "../facts/index.js";
 
+import { isAriaHidden } from "./a11y-utils.js";
 import { makeFinding } from "./finding.js";
 import type { Finding } from "./types.js";
-import { indexPropsByNodeId, indexTextChildrenByNodeId, readUsageNode } from "./utils.js";
+import { indexPropsByNodeId, indexTextChildrenByNodeId } from "./utils.js";
 
 export const RULE_ID = "a11y/required-accessible-name";
-export const RULE_VERSION = "1";
+export const RULE_VERSION = "2";
 
 const NAME_SOURCE_PROPS = new Set(["aria-label", "aria-labelledby", "title"]);
+const COMPONENT_NAME_SOURCE_PROPS = new Set([...NAME_SOURCE_PROPS, "label"]);
+const NAME_REQUIRED_TAGS = new Set(["button", "input", "select", "textarea"]);
+const NAME_REQUIRED_ROLES = new Set(["button", "checkbox", "radio", "switch", "tab"]);
+const NAME_FROM_CONTENT_TAGS = new Set(["button"]);
+const NAME_FROM_CONTENT_ROLES = new Set(["button", "checkbox", "radio", "switch", "tab"]);
+const NAME_REQUIRED_COMPONENT_SUFFIXES = [
+  "button",
+  "input",
+  "select",
+  "textarea",
+  "checkbox",
+  "radio",
+  "switch",
+] as const;
 
 export function ruleA11yRequiredAccessibleName(ix: FactIndex): Finding[] {
   const findings: Finding[] = [];
   const propsByNode = indexPropsByNodeId(ix);
   const textByNode = indexTextChildrenByNodeId(ix);
+  const childContentByNode = new Map(
+    ix.byKind("usage_child_content").map((content) => [content.nodeId, content])
+  );
+  const globalPolicy = ix.policy.ruleConfig(RULE_ID);
+  const usageByNode = new Map(ix.byKind("usage_component").map((usage) => [usage.nodeId, usage]));
+  const definitions = new Map(
+    ix.byKind("component_definition").map((definition) => [definition.componentKey, definition])
+  );
 
-  for (const usageComponent of ix.byKind("usage_component")) {
-    const policy = ix.policy.a11yNameRequired(usageComponent.componentId);
-    if (!policy) continue;
-
-    const node = readUsageNode(ix, usageComponent.nodeId);
-    if (!node) continue;
-
+  for (const node of ix.byKind("usage_node")) {
+    const usageComponent = usageByNode.get(node.id);
+    const componentPolicy = usageComponent
+      ? ix.policy.a11yNameRequired(usageComponent.componentId)
+      : undefined;
     const props = propsByNode.get(node.id) ?? [];
-    if (props.some(isAriaHidden)) continue;
+    if (isAriaHidden(props)) continue;
+    const genericControl =
+      globalPolicy?.enabled === true &&
+      requiresAccessibleName(node, usageComponent, definitions, props);
+    if (!componentPolicy && !genericControl) continue;
 
-    if (hasAccessibleName(props, textByNode.get(node.id) ?? [])) continue;
+    if (
+      hasAccessibleName(
+        props,
+        textByNode.get(node.id) ?? [],
+        childContentByNode.get(node.id),
+        usageComponent !== undefined,
+        canNameFromContent(node, usageComponent, definitions)
+      )
+    ) {
+      continue;
+    }
 
     findings.push(
       makeFinding({
         ruleId: RULE_ID,
         ruleVersion: RULE_VERSION,
-        severity: policy.severity,
-        message: `<${node.element}> has no accessible name. ${policy.because}`.trim(),
+        severity: componentPolicy?.severity ?? globalPolicy?.severity ?? "warn",
+        message: `<${node.element}> has no accessible name. ${
+          componentPolicy?.because ??
+          "Add visible text, aria-label, aria-labelledby, or a component label."
+        }`.trim(),
         location: node.location,
-        evidence: ix.evidence([node.id, usageComponent.id, policy.id]),
+        evidence: ix.evidence([
+          node.id,
+          ...(usageComponent ? [usageComponent.id] : []),
+          ...(componentPolicy ? [componentPolicy.id] : []),
+          ...(genericControl && globalPolicy ? [globalPolicy.id] : []),
+        ]),
         fingerprintIdentity: {
           file: node.file,
-          componentId: usageComponent.componentId,
+          componentId: usageComponent?.componentId,
           element: node.element,
           nodePath: node.nodePath,
         },
         attributes: {
-          componentId: usageComponent.componentId,
+          ...(usageComponent ? { componentId: usageComponent.componentId } : {}),
           element: node.element,
         },
       })
@@ -69,13 +121,22 @@ export function ruleA11yRequiredAccessibleName(ix: FactIndex): Finding[] {
 
 function hasAccessibleName(
   props: UsagePropResolvedFact[],
-  textChildren: ReadonlyArray<{ text: string }>
+  textChildren: ReadonlyArray<{ text: string }>,
+  childContent: UsageChildContentFact | undefined,
+  componentControl: boolean,
+  nameFromContent: boolean
 ): boolean {
-  for (const child of textChildren) {
-    if (typeof child.text === "string" && child.text.trim().length > 0) return true;
+  const sourceProps = componentControl ? COMPONENT_NAME_SOURCE_PROPS : NAME_SOURCE_PROPS;
+  if (nameFromContent) {
+    for (const child of textChildren) {
+      if (typeof child.text === "string" && child.text.trim().length > 0) return true;
+    }
+    if (childContent?.content === "static-text" || childContent?.content === "runtime") {
+      return true;
+    }
   }
   for (const prop of props) {
-    if (!NAME_SOURCE_PROPS.has(prop.prop)) continue;
+    if (!sourceProps.has(prop.prop)) continue;
     if (prop.resolution === "spread") continue;
     if (prop.resolution === "dynamic") return true;
     if (prop.resolution === "static") {
@@ -86,8 +147,94 @@ function hasAccessibleName(
   return false;
 }
 
-function isAriaHidden(prop: UsagePropResolvedFact): boolean {
-  if (prop.prop !== "aria-hidden") return false;
-  if (prop.resolution !== "static") return false;
-  return prop.value === true || prop.value === "true";
+function canNameFromContent(
+  node: UsageNodeFact,
+  usage: UsageComponentFact | undefined,
+  definitions: ReadonlyMap<string, ComponentDefinitionFact>
+): boolean {
+  const element = node.element.toLowerCase();
+  if (NAME_REQUIRED_TAGS.has(element)) return NAME_FROM_CONTENT_TAGS.has(element);
+  if (node.role && NAME_FROM_CONTENT_ROLES.has(node.role.toLowerCase())) return true;
+  if (!usage) return false;
+
+  const definition = definitions.get(String(usage.componentId));
+  if (definition) {
+    const root = definition.renderRoot;
+    if (root.resolution === "intrinsic") {
+      return intrinsicCanNameFromContent(root.tag, root.role);
+    }
+    if (root.resolution === "canonical") return isContentNamedControl(root.canonical);
+    if (root.resolution === "mixed") {
+      return (
+        root.intrinsics.some((tag) => intrinsicCanNameFromContent(tag)) ||
+        root.canonicals.some(isContentNamedControl)
+      );
+    }
+  }
+  return isContentNamedControl(String(usage.componentId));
+}
+
+function intrinsicCanNameFromContent(tag: string, role?: string): boolean {
+  const normalizedTag = tag.toLowerCase();
+  if (NAME_REQUIRED_TAGS.has(normalizedTag)) {
+    return NAME_FROM_CONTENT_TAGS.has(normalizedTag);
+  }
+  return role !== undefined && NAME_FROM_CONTENT_ROLES.has(role.toLowerCase());
+}
+
+function requiresAccessibleName(
+  node: UsageNodeFact,
+  usage: UsageComponentFact | undefined,
+  definitions: ReadonlyMap<string, ComponentDefinitionFact>,
+  props: readonly UsagePropResolvedFact[]
+): boolean {
+  if (node.role && NAME_REQUIRED_ROLES.has(node.role.toLowerCase())) return true;
+  if (NAME_REQUIRED_TAGS.has(node.element.toLowerCase())) {
+    if (
+      node.element.toLowerCase() === "input" &&
+      props.some(
+        (prop) =>
+          prop.prop === "type" &&
+          prop.resolution === "static" &&
+          String(prop.value).toLowerCase() === "hidden"
+      )
+    ) {
+      return false;
+    }
+    return true;
+  }
+  if (!usage) return false;
+
+  const definition = definitions.get(String(usage.componentId));
+  if (definition) {
+    const root = definition.renderRoot;
+    if (root.resolution === "intrinsic") {
+      return (
+        NAME_REQUIRED_TAGS.has(root.tag.toLowerCase()) ||
+        (root.role !== undefined && NAME_REQUIRED_ROLES.has(root.role.toLowerCase()))
+      );
+    }
+    if (root.resolution === "canonical") return isNamedControl(root.canonical);
+    if (root.resolution === "mixed") {
+      return (
+        root.intrinsics.some((tag) => NAME_REQUIRED_TAGS.has(tag.toLowerCase())) ||
+        root.canonicals.some(isNamedControl)
+      );
+    }
+  }
+  return isNamedControl(String(usage.componentId));
+}
+
+function isContentNamedControl(identity: string): boolean {
+  return normalizedControlName(identity).endsWith("button");
+}
+
+function isNamedControl(identity: string): boolean {
+  const normalized = normalizedControlName(identity);
+  return NAME_REQUIRED_COMPONENT_SUFFIXES.some((suffix) => normalized.endsWith(suffix));
+}
+
+function normalizedControlName(identity: string): string {
+  const exported = identity.split("#").at(-1)?.split(".").at(-1) ?? identity;
+  return exported.replace(/[^a-z0-9]/gi, "").toLowerCase();
 }

package/src/rules/a11y-standard.ts

@@ -0,0 +1,102 @@
+import type { FactIndex, UsagePropResolvedFact } from "../facts/index.js";
+
+import { isAriaHidden } from "./a11y-utils.js";
+import { makeFinding } from "./finding.js";
+import type { Finding } from "./types.js";
+import { indexPropsByNodeId } from "./utils.js";
+
+export const RULE_ID = "a11y/standard";
+export const RULE_VERSION = "1";
+
+const KEY_HANDLERS = new Set(["onKeyDown", "onKeyUp", "onKeyPress"]);
+
+/**
+ * Narrow static standard check: a non-native `role="button"` needs both a
+ * keyboard-focus path and a keyboard activation handler. This intentionally
+ * does not claim to be a complete WCAG or axe implementation.
+ */
+export function ruleA11yStandard(ix: FactIndex): Finding[] {
+  const policy = ix.policy.ruleConfig(RULE_ID);
+  if (!policy?.enabled) return [];
+
+  const propsByNode = indexPropsByNodeId(ix);
+  const findings: Finding[] = [];
+  for (const node of ix.byKind("usage_node")) {
+    if (node.role?.trim().toLowerCase() !== "button") continue;
+    const props = propsByNode.get(node.id) ?? [];
+    if (isAriaHidden(props) || isNativeButton(node.element, props)) continue;
+
+    const missing = [
+      ...(hasFocusableTabIndex(props) ? [] : ["tabIndex"]),
+      ...(hasKeyHandler(props) ? [] : ["keyboard handler"]),
+    ];
+    if (missing.length === 0) continue;
+
+    findings.push(
+      makeFinding({
+        ruleId: RULE_ID,
+        ruleVersion: RULE_VERSION,
+        severity: policy.severity ?? "warn",
+        message: `<${node.element} role="button"> is missing ${missing.join(
+          " and "
+        )}. Non-native buttons need tabIndex plus keyboard activation handling.`,
+        location: node.location,
+        evidence: ix.evidence([
+          node.id,
+          policy.id,
+          ...props
+            .filter(
+              (prop) =>
+                prop.prop === "tabIndex" ||
+                prop.prop === "tabindex" ||
+                KEY_HANDLERS.has(prop.prop)
+            )
+            .map((prop) => prop.id),
+        ]),
+        fingerprintIdentity: {
+          file: node.file,
+          element: node.element,
+          nodePath: node.nodePath,
+          standard: "keyboard-role-button",
+        },
+        attributes: {
+          standard: "keyboard-role-button",
+          role: "button",
+          missing,
+        },
+      })
+    );
+  }
+  return findings;
+}
+
+function isNativeButton(element: string, props: readonly UsagePropResolvedFact[]): boolean {
+  if (element.toLowerCase() === "button") return true;
+  if (element.toLowerCase() !== "input") return false;
+  return props.some(
+    (prop) =>
+      prop.prop === "type" &&
+      prop.resolution === "static" &&
+      ["button", "submit", "reset"].includes(String(prop.value).toLowerCase())
+  );
+}
+
+function hasFocusableTabIndex(props: readonly UsagePropResolvedFact[]): boolean {
+  return props.some((prop) => {
+    if (prop.prop !== "tabIndex" && prop.prop !== "tabindex") return false;
+    if (prop.resolution === "dynamic") return true;
+    if (prop.resolution !== "static") return false;
+    const value = typeof prop.value === "number" ? prop.value : Number(prop.value);
+    return Number.isFinite(value) && value >= 0;
+  });
+}
+
+function hasKeyHandler(props: readonly UsagePropResolvedFact[]): boolean {
+  return props.some(
+    (prop) =>
+      KEY_HANDLERS.has(prop.prop) &&
+      prop.resolution !== "spread" &&
+      prop.value !== null &&
+      prop.value !== false
+  );
+}

package/src/rules/a11y-utils.ts

@@ -0,0 +1,7 @@
+import type { UsagePropResolvedFact } from "../facts/index.js";
+
+export function isAriaHidden(props: readonly UsagePropResolvedFact[]): boolean {
+  const prop = props.find((candidate) => candidate.prop === "aria-hidden");
+  if (!prop || prop.resolution !== "static") return false;
+  return prop.value === true || prop.value === "true";
+}