@usefragments/core 1.9.0 → 1.10.0

package/dist/react-types.d.ts

@@ -1,5 +1,5 @@
 import { ComponentType, ReactNode, JSX } from 'react';
-export { F as FragmentDefinition, a as FragmentDefinitionV2 } from './governance-eEzCyfes.js';
+export { F as FragmentDefinition, a as FragmentDefinitionV2 } from './governance-B5WWcmFY.js';
 import 'zod';
 import './topology/index.js';
 import './types-xJ2xyp_G.js';

package/dist/schemas/index.js

@@ -24,7 +24,7 @@ import {
   suppressionDirectiveSchema,
   validatorResultSchema,
   violationSchema
-} from "../chunk-DGHZQTLH.js";
+} from "../chunk-XN3LSDPY.js";
 import "../chunk-JNBFJ34I.js";
 import "../chunk-EIYNNS77.js";
 import {

package/dist/test-utils.d.ts

@@ -1,4 +1,4 @@
-import { C as CompiledBlock, b as CompiledFragment } from './governance-eEzCyfes.js';
+import { C as CompiledBlock, b as CompiledFragment } from './governance-B5WWcmFY.js';
 import 'zod';
 import 'react';
 import './topology/index.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usefragments/core",
-  "version": "1.9.0",
+  "version": "1.10.0",
   "license": "MIT",
   "description": "Core types, schemas, and runtime API for Fragments component definitions",
   "author": "Conan McNicholl",

package/src/governance-integrity.test.ts

@@ -118,6 +118,90 @@ describe("inert config diagnostics", () => {
     expect(detectUnconsumedConfigKeys(authored, parsed)).toEqual([]);
   });
 
+  it("accepts valid options declared by a registered rule schema", () => {
+    const options = { ignoreParents: ["FormControlLabel"], ignoreSpread: true };
+    const authored = {
+      govern: {
+        rules: {
+          "a11y/required-accessible-name": { enabled: true, options },
+        },
+      },
+    };
+    const parsed = fragmentsConfigSchema.parse(authored);
+
+    expect(detectUnconsumedConfigKeys(authored, parsed)).toEqual([]);
+    expect(
+      (
+        parsed.govern?.rules?.["a11y/required-accessible-name"] as {
+          options?: unknown;
+        }
+      ).options
+    ).toEqual(options);
+  });
+
+  it("diagnoses invalid options against the registered rule schema", () => {
+    const authored = {
+      govern: {
+        rules: {
+          "a11y/required-accessible-name": {
+            enabled: true,
+            options: { ignoreSpread: "yes" },
+          },
+        },
+      },
+    };
+    const parsed = fragmentsConfigSchema.parse(authored);
+
+    expect(detectUnconsumedConfigKeys(authored, parsed)).toEqual([
+      expect.objectContaining({
+        code: "FUI9004",
+        path: "govern.rules.a11y/required-accessible-name.options",
+        message: expect.stringMatching(
+          /a11y\/required-accessible-name.*ignoreSpread.*Expected boolean/
+        ),
+      }),
+    ]);
+  });
+
+  it("diagnoses a typo'd option key instead of letting it silently no-op", () => {
+    const authored = {
+      govern: {
+        rules: {
+          "a11y/required-accessible-name": {
+            enabled: true,
+            options: { ignoredParents: ["FormControlLabel"] },
+          },
+        },
+      },
+    };
+    const parsed = fragmentsConfigSchema.parse(authored);
+
+    expect(detectUnconsumedConfigKeys(authored, parsed)).toEqual([
+      expect.objectContaining({
+        code: "FUI9004",
+        path: "govern.rules.a11y/required-accessible-name.options",
+        message: expect.stringMatching(/ignoredParents/),
+      }),
+    ]);
+  });
+
+  it("leaves options on rules without a schema untouched", () => {
+    const options = { projectSpecificSetting: "unchanged" };
+    const authored = {
+      govern: {
+        rules: {
+          "styles/no-raw-color": { enabled: true, options },
+        },
+      },
+    };
+    const parsed = fragmentsConfigSchema.parse(authored);
+
+    expect(detectUnconsumedConfigKeys(authored, parsed)).toEqual([]);
+    expect(
+      (parsed.govern?.rules?.["styles/no-raw-color"] as { options?: unknown }).options
+    ).toEqual(options);
+  });
+
   it("reports an authored spacing scale that no effective property policy references", () => {
     const declared: GovernanceConfig = {
       scales: {
@@ -167,8 +251,15 @@ describe("inert config diagnostics", () => {
     expect(detectOrphanGovernanceScales(policy, policy)).toEqual([]);
   });
 
-  it("accepts govern.ci.failOnInert as a consumed key", () => {
-    const authored = { govern: { ci: { failOnInert: true } } };
+  it("accepts governance CI gates as consumed keys", () => {
+    const authored = {
+      govern: {
+        ci: {
+          failOnInert: true,
+          failOnAdoptionRegression: true,
+        },
+      },
+    };
 
     expect(detectUnconsumedConfigKeys(authored, fragmentsConfigSchema.parse(authored))).toEqual([]);
   });

package/src/governance-integrity.ts

@@ -17,6 +17,8 @@
  * calling in.
  */
 
+import { ZodObject } from "zod";
+
 import type { CanonicalSource, GovernanceConfig, GovernanceSeverity } from "./governance.js";
 import {
   normalizePolicyExcludes,
@@ -25,7 +27,8 @@ import {
 } from "./policy-exclude.js";
 import { compileGlobalGovernanceFacts } from "./facts/index.js";
 import type { FactConflict } from "./facts/index.js";
-import { RULE_FAMILY_IDS } from "./rules/families.js";
+import { RULES } from "./rules/index.js";
+import { RULE_FAMILY_IDS, ruleFamilyMembers } from "./rules/families.js";
 import { FRAGMENTS_INTERNAL_RULE_IDS, RULE_TIER } from "./rules/tiers.js";
 import { BLOCKING_RULE_ALLOWLIST } from "./rules/emit-gate.js";
 
@@ -175,6 +178,23 @@ function dedupe(values: string[]): string[] {
 
 const CONSUMED_RULE_IDS = new Set(Object.keys(RULE_TIER));
 const RECOGNIZED_RULE_IDS = new Set([...CONSUMED_RULE_IDS, ...RULE_FAMILY_IDS]);
+// Reporter-strict, executor-lenient: unknown option keys are diagnosed here as
+// the inert-config class FUI9004 exists to name, while rules keep their own
+// tolerant parse (unknown keys stripped, valid keys still honored).
+const RULE_OPTIONS_SCHEMAS = new Map(
+  RULES.flatMap((rule) =>
+    rule.optionsSchema
+      ? [
+          [
+            rule.id,
+            rule.optionsSchema instanceof ZodObject
+              ? rule.optionsSchema.strict()
+              : rule.optionsSchema,
+          ] as const,
+        ]
+      : []
+  )
+);
 // `exclude` is consumed by the scan's finding-override pass (it scopes the rule off
 // the matching paths and reports each drop in the ignored accounting). It was absent
 // from this allow-set, so a working key was diagnosed as inert — the diagnostic was
@@ -219,7 +239,7 @@ const PASSTHROUGH_KEYS = [
   },
   {
     path: ["govern", "ci"],
-    keys: ["failOnWarnings", "failOnInert"],
+    keys: ["failOnWarnings", "failOnInert", "failOnAdoptionRegression"],
   },
 ] as const;
 
@@ -546,6 +566,30 @@ function collectRuleConfigKeys(
         diagnostics.push(unconsumedKeyDiagnostic([...path, ruleId, key]));
       }
     }
+    if (config["options"] === undefined) continue;
+
+    const invalidOptions = ruleFamilyMembers(ruleId).flatMap((memberRuleId) => {
+      const schema = RULE_OPTIONS_SCHEMAS.get(memberRuleId);
+      if (!schema) return [];
+      const parsed = schema.safeParse(config["options"]);
+      if (parsed.success) return [];
+      const problem = parsed.error.errors
+        .map((issue) => `${issue.path.join(".") || "options"}: ${issue.message}`)
+        .join("; ");
+      return [memberRuleId === ruleId ? problem : `${memberRuleId}: ${problem}`];
+    });
+    if (invalidOptions.length === 0) continue;
+
+    const diagnosticPath = configPath([...path, ruleId, "options"]);
+    diagnostics.push({
+      code: "FUI9004",
+      kind: "unconsumed-key",
+      severity: "warn",
+      path: diagnosticPath,
+      message:
+        `${diagnosticPath} is invalid for rule \`${ruleId}\`: ${invalidOptions.join("; ")}. ` +
+        "Fix the option values or remove the options block.",
+    });
   }
 }
 

package/src/governance.ts

@@ -355,6 +355,7 @@ export const governanceConfigSchema = z
       .object({
         failOnWarnings: z.boolean().optional(),
         failOnInert: z.boolean().optional(),
+        failOnAdoptionRegression: z.boolean().optional(),
       })
       .passthrough()
       .optional(),
@@ -443,9 +444,13 @@ export interface GovernanceConfig {
   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.
+   * Governance CI rendering options. Under `--ci`, `failOnWarnings` defaults to `true`
+   * when absent; set it to `false` to keep warning findings reported but advisory.
+   * `failOnInert` is opt-in and makes inert-config diagnostics (FUI9004-FUI9008) fail
+   * the verdict; `--allow-inert` bypasses the inert gates.
+   * `failOnAdoptionRegression` is opt-in and makes `check --ci` compare the
+   * current component-identity adoption percentage with the committed
+   * `.fragments/adoption-baseline.json` floor.
    */
   ci?: {
     failOnWarnings?: boolean;
@@ -456,6 +461,13 @@ export interface GovernanceConfig {
      * bypasses it, like the governance-inert gate.
      */
     failOnInert?: boolean;
+    /**
+     * Fail `check --ci` when measurable component-identity adoption falls below
+     * the committed local floor. Update the floor through `check
+     * --update-baseline`; accepting a lower floor additionally requires
+     * `--allow-regression`.
+     */
+    failOnAdoptionRegression?: boolean;
     [key: string]: unknown;
   };
   [key: string]: unknown;

package/src/rules/a11y-required-accessible-name.ts

@@ -24,6 +24,7 @@ import type {
   UsageNodeFact,
   UsagePropResolvedFact,
 } from "../facts/index.js";
+import { z } from "zod";
 
 import { isAriaHidden } from "./a11y-utils.js";
 import { makeFinding } from "./finding.js";
@@ -31,7 +32,16 @@ import type { Finding } from "./types.js";
 import { indexPropsByNodeId, indexTextChildrenByNodeId } from "./utils.js";
 
 export const RULE_ID = "a11y/required-accessible-name";
-export const RULE_VERSION = "2";
+export const RULE_VERSION = "3";
+
+export const a11yRequiredAccessibleNameOptionsSchema = z.object({
+  ignoreParents: z.array(z.string().min(1)).optional(),
+  ignoreSpread: z.boolean().optional(),
+});
+
+export type A11yRequiredAccessibleNameOptions = z.infer<
+  typeof a11yRequiredAccessibleNameOptionsSchema
+>;
 
 const NAME_SOURCE_PROPS = new Set(["aria-label", "aria-labelledby", "title"]);
 const COMPONENT_NAME_SOURCE_PROPS = new Set([...NAME_SOURCE_PROPS, "label"]);
@@ -57,7 +67,12 @@ export function ruleA11yRequiredAccessibleName(ix: FactIndex): Finding[] {
     ix.byKind("usage_child_content").map((content) => [content.nodeId, content])
   );
   const globalPolicy = ix.policy.ruleConfig(RULE_ID);
+  const parsedOptions = a11yRequiredAccessibleNameOptionsSchema.safeParse(globalPolicy?.options);
+  const options: A11yRequiredAccessibleNameOptions = parsedOptions.success
+    ? parsedOptions.data
+    : {};
   const usageByNode = new Map(ix.byKind("usage_component").map((usage) => [usage.nodeId, usage]));
+  const usageNodes = ix.byKind("usage_node");
   const definitions = new Map(
     ix.byKind("component_definition").map((definition) => [definition.componentKey, definition])
   );
@@ -73,6 +88,7 @@ export function ruleA11yRequiredAccessibleName(ix: FactIndex): Finding[] {
       globalPolicy?.enabled === true &&
       requiresAccessibleName(node, usageComponent, definitions, props);
     if (!componentPolicy && !genericControl) continue;
+    if (isInsideIgnoredAttributeParent(node, usageNodes, options.ignoreParents)) continue;
 
     if (
       hasAccessibleName(
@@ -86,11 +102,16 @@ export function ruleA11yRequiredAccessibleName(ix: FactIndex): Finding[] {
       continue;
     }
 
+    const hasSpreadProps = props.some((prop) => prop.resolution === "spread");
+    if (hasSpreadProps && options.ignoreSpread === true) continue;
+
     findings.push(
       makeFinding({
         ruleId: RULE_ID,
         ruleVersion: RULE_VERSION,
-        severity: componentPolicy?.severity ?? globalPolicy?.severity ?? "warn",
+        severity: hasSpreadProps
+          ? "minor"
+          : (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."
@@ -119,6 +140,28 @@ export function ruleA11yRequiredAccessibleName(ix: FactIndex): Finding[] {
   return findings;
 }
 
+function isInsideIgnoredAttributeParent(
+  node: UsageNodeFact,
+  usageNodes: readonly UsageNodeFact[],
+  ignoreParents: readonly string[] | undefined
+): boolean {
+  if (!ignoreParents?.length || !node.nodePath.includes("/attr:")) return false;
+  const ignored = new Set(ignoreParents);
+  const segments = node.nodePath.split("/");
+  const ancestorPaths = new Set<string>();
+  for (let index = 1; index < segments.length; index += 1) {
+    if (segments[index].startsWith("attr:")) {
+      ancestorPaths.add(segments.slice(0, index).join("/"));
+    }
+  }
+  return usageNodes.some(
+    (candidate) =>
+      candidate.file === node.file &&
+      ancestorPaths.has(candidate.nodePath) &&
+      ignored.has(candidate.element)
+  );
+}
+
 function hasAccessibleName(
   props: UsagePropResolvedFact[],
   textChildren: ReadonlyArray<{ text: string }>,

package/src/rules/index.ts

@@ -8,8 +8,10 @@
  */
 
 import type { FactIndex } from "../facts/index.js";
+import type { ZodTypeAny } from "zod";
 
 import {
+  a11yRequiredAccessibleNameOptionsSchema,
   RULE_VERSION as A11Y_REQUIRED_ACCESSIBLE_NAME_VERSION,
   ruleA11yRequiredAccessibleName,
 } from "./a11y-required-accessible-name.js";
@@ -44,6 +46,7 @@ export interface Rule {
   id: string;
   version: string;
   run: RuleFn;
+  optionsSchema?: ZodTypeAny;
 }
 
 export const RULES: readonly Rule[] = [
@@ -156,6 +159,7 @@ export const RULES: readonly Rule[] = [
     id: "a11y/required-accessible-name",
     version: A11Y_REQUIRED_ACCESSIBLE_NAME_VERSION,
     run: ruleA11yRequiredAccessibleName,
+    optionsSchema: a11yRequiredAccessibleNameOptionsSchema,
   },
   {
     id: "a11y/standard",

package/src/rules/rules.test.ts

@@ -36,6 +36,7 @@ import {
   runRules,
 } from "../index.js";
 import type { CanonicalBridgeV1, Fact, FactId } from "../index.js";
+import { makeGovernanceRuleConfigFact } from "../facts/index.js";
 import { RULE_VERSION as A11Y_REQUIRED_ACCESSIBLE_NAME_VERSION } from "./a11y-required-accessible-name.js";
 import { makeFinding } from "./finding.js";
 
@@ -1425,6 +1426,77 @@ describe("a11y/required-accessible-name", () => {
     expect(ruleA11yRequiredAccessibleName(ix)).toHaveLength(0);
   });
 
+  it("ignores controls rendered through an ignored same-file attribute parent", () => {
+    const ix = emptyIndexWithGovernance();
+    ix.add(
+      makeGovernanceRuleConfigFact({
+        ruleId: "a11y/required-accessible-name",
+        enabled: true,
+        options: { ignoreParents: ["FormControlLabel"] },
+      })
+    );
+    ix.add(
+      makeUsageNodeFact({
+        file: "apps/x.tsx",
+        nodePath: "0:0",
+        element: "FormControlLabel",
+        location: { file: "apps/x.tsx", line: 1, column: 0 },
+      })
+    );
+    addButtonUsage(ix, {
+      file: "apps/x.tsx",
+      nodePath: "0:0/attr:control/0:0",
+      line: 1,
+      column: 28,
+    });
+
+    expect(ruleA11yRequiredAccessibleName(ix)).toHaveLength(0);
+  });
+
+  it("demotes an unnamed component with spread props to minor", () => {
+    const ix = emptyIndexWithGovernance();
+    addButtonUsage(ix, {
+      file: "apps/x.tsx",
+      nodePath: "0:0",
+      line: 1,
+      column: 0,
+      props: [{ prop: "...props", resolution: "spread" }],
+    });
+
+    expect(ruleA11yRequiredAccessibleName(ix)).toMatchObject([{ severity: "minor" }]);
+  });
+
+  it("skips an unnamed component with spread props when ignoreSpread is enabled", () => {
+    const ix = emptyIndexWithGovernance();
+    ix.add(
+      makeGovernanceRuleConfigFact({
+        ruleId: "a11y/required-accessible-name",
+        enabled: true,
+        options: { ignoreSpread: true },
+      })
+    );
+    addButtonUsage(ix, {
+      file: "apps/x.tsx",
+      nodePath: "0:0",
+      line: 1,
+      column: 0,
+      props: [{ prop: "...props", resolution: "spread" }],
+    });
+
+    expect(ruleA11yRequiredAccessibleName(ix)).toHaveLength(0);
+  });
+
+  it("registers ignoreParents and ignoreSpread as supported rule options", () => {
+    const registered = RULES.find((rule) => rule.id === "a11y/required-accessible-name");
+
+    expect(
+      registered?.optionsSchema?.safeParse({
+        ignoreParents: ["FormControlLabel"],
+        ignoreSpread: true,
+      }).success
+    ).toBe(true);
+  });
+
   it("keeps the registry version in lockstep with the emitted finding version", () => {
     const registered = RULES.find((rule) => rule.id === "a11y/required-accessible-name");
     expect(registered?.version).toBe(A11Y_REQUIRED_ACCESSIBLE_NAME_VERSION);