@usefragments/core 1.0.0

package/src/rules/components-unknown-prop.ts

@@ -0,0 +1,94 @@
+/**
+ * `components/unknown-prop` — fires when JSX uses a prop that isn't in the
+ * component's declared prop schema and the global `jsx.unknownProps.forbid`
+ * policy is active. Universal React/DOM props (data-*, aria-*, on*, key, ref,
+ * className, style, etc.) are exempt.
+ *
+ * The rule only fires for components we have prop metadata for. If the
+ * component has no `prop_metadata` facts (e.g., third-party imports we don't
+ * model yet), we cannot tell whether a prop is unknown and the rule stays
+ * silent.
+ */
+
+import type { FactIndex, FactId } from "../facts/index.js";
+
+import { makeFinding } from "./finding.js";
+import type { Finding } from "./types.js";
+import {
+  indexComponentByNodeId,
+  indexPropsByNodeId,
+  isUniversalJsxProp,
+  readUsageNode,
+} from "./utils.js";
+
+export const RULE_ID = "components/unknown-prop";
+export const RULE_VERSION = "1";
+
+export function ruleComponentsUnknownProp(ix: FactIndex): Finding[] {
+  const policy = ix.policy.jsxUnknownPropsForbidden();
+  if (!policy) return [];
+
+  const findings: Finding[] = [];
+  const componentByNode = indexComponentByNodeId(ix);
+  const propsByNode = indexPropsByNodeId(ix);
+
+  for (const [nodeId, propUsages] of propsByNode) {
+    const usageComponent = componentByNode.get(nodeId);
+    if (!usageComponent) continue;
+
+    const knownProps = ix.components.propsOf(usageComponent.componentId);
+    if (knownProps.length === 0) continue;
+    const knownNames = new Set(knownProps.map((p) => p.prop));
+
+    const node = readUsageNode(ix, nodeId);
+    if (!node) continue;
+
+    for (const propUsage of propUsages) {
+      if (propUsage.resolution === "spread") continue;
+      if (isUniversalJsxProp(propUsage.prop)) continue;
+      if (knownNames.has(propUsage.prop)) continue;
+
+      findings.push(
+        makeFinding({
+          ruleId: RULE_ID,
+          ruleVersion: RULE_VERSION,
+          severity: policy.severity,
+          message: `Unknown prop "${propUsage.prop}" on <${node.element}>. Allowed props: ${formatPropList(knownNames)}.`,
+          location: node.location,
+          evidence: ix.evidence([node.id, usageComponent.id, propUsage.id, policy.id]),
+          fingerprintIdentity: {
+            file: node.file,
+            componentId: usageComponent.componentId,
+            element: node.element,
+            nodePath: node.nodePath,
+            prop: propUsage.prop,
+          } satisfies UnknownPropFingerprint,
+          attributes: {
+            componentId: usageComponent.componentId,
+            prop: propUsage.prop,
+          },
+        })
+      );
+    }
+  }
+
+  return findings;
+}
+
+interface UnknownPropFingerprint {
+  file: string;
+  componentId: string;
+  element: string;
+  nodePath: string;
+  prop: string;
+}
+
+function formatPropList(names: Set<string>): string {
+  if (names.size === 0) return "(none)";
+  const sorted = [...names].sort();
+  if (sorted.length <= 6) return sorted.join(", ");
+  return `${sorted.slice(0, 6).join(", ")}, …`;
+}
+
+// Re-exported for type-tests / tooling that wants to read the rule's id.
+export type { FactId };

package/src/rules/composition-pattern-schema.ts

@@ -0,0 +1,125 @@
+/**
+ * The composition config contract — shared across the policy boundary.
+ *
+ * `CompositionPattern` is what the `composition/cardinality` and
+ * `composition/co-occurrence` rules read from
+ * `governance_rule_config.options.patterns`. Brief 03 defined it inline in the
+ * rule; brief 04 lifted it here because the same shape now has to round-trip
+ * across three boundaries that must not all hand-roll it:
+ *   - the rule's `isCompositionPattern` guard (validates untyped policy facts),
+ *   - cloud policy storage + delivery (`apps/cloud` validates on write against
+ *     `compositionPatternSchema` before persisting), and
+ *   - fragment authoring sugar (`lowerCompositionContract` lowers a fragment's
+ *     `contract.composition` block to the same `CompositionPattern[]`).
+ *
+ * Defining it once as a zod schema means the wire shape and the runtime guard
+ * are the same artifact — the guard is `safeParse().success`, never a second
+ * copy that can drift from the type.
+ *
+ * Browser-safe: imports `zod` only. No facts, no Node, no JSX.
+ */
+
+import { z } from "zod";
+
+// ── The rule-input contract ──────────────────────────────────────────────
+
+/** Which container a pattern applies to. `component` = canonical componentId. */
+export const compositionRegionSelectorSchema = z.object({
+  component: z.string().optional(),
+  /** Marker attribute (e.g. `data-fui-region`). Typed; matched in a later brief. */
+  marker: z.string().optional(),
+  role: z.string().optional(),
+});
+
+/** Which children inside the region the constraint counts. */
+export const compositionChildSelectorSchema = z.object({
+  component: z.string(),
+  prop: z.string().optional(),
+  value: z.string().optional(),
+});
+
+export const compositionConstraintSchema = z.discriminatedUnion("kind", [
+  z.object({
+    kind: z.literal("cardinality"),
+    max: z.number().optional(),
+    min: z.number().optional(),
+  }),
+  z.object({
+    kind: z.literal("co-occurrence"),
+    requires: z.object({ prop: z.string(), value: z.string() }),
+  }),
+]);
+
+export const compositionPatternSchema = z.object({
+  region: compositionRegionSelectorSchema,
+  select: compositionChildSelectorSchema,
+  constraint: compositionConstraintSchema,
+});
+
+export type CompositionRegionSelector = z.infer<typeof compositionRegionSelectorSchema>;
+export type CompositionChildSelector = z.infer<typeof compositionChildSelectorSchema>;
+export type CompositionConstraint = z.infer<typeof compositionConstraintSchema>;
+export type CompositionPattern = z.infer<typeof compositionPatternSchema>;
+
+/**
+ * Type guard for a single policy entry. Config arrives untyped from cloud
+ * policy / fragment prose and the facts layer passes `options` through without
+ * a shape, so a malformed entry would otherwise emit garbage findings. The rule
+ * filters `options.patterns` through this; a bad entry is skipped, the rest keep
+ * scanning (architecture failure mode).
+ */
+export function isCompositionPattern(value: unknown): value is CompositionPattern {
+  return compositionPatternSchema.safeParse(value).success;
+}
+
+// ── Authoring sugar → constraint (Layer 3, brief 04 §10) ──────────────────
+
+/**
+ * The structured block a fragment author writes in `contract.composition`. This
+ * is the enforceable form of the prose they already keep (`relations`,
+ * `usage.whenNot`); `lowerCompositionContract` turns it into the same
+ * `CompositionPattern[]` the rule reads from cloud policy. v0 is this explicit
+ * block — free-text inference from `whenNot` strings is out of scope.
+ */
+export const compositionAuthoringEntrySchema = z.object({
+  inRegion: z.string(),
+  rule: z.union([
+    z.object({ atMost: z.number(), of: compositionChildSelectorSchema }),
+    z.object({
+      when: z.object({
+        component: z.string(),
+        prop: z.string(),
+        value: z.string(),
+      }),
+      require: z.object({ prop: z.string(), value: z.string() }),
+    }),
+  ]),
+});
+
+export type CompositionAuthoringEntry = z.infer<typeof compositionAuthoringEntrySchema>;
+
+/**
+ * Lower a fragment's `contract.composition` block to the policy patterns the
+ * rule consumes. The authoring shape ({ inRegion, rule }) and the rule shape
+ * ({ region, select, constraint }) converge here, so fragment-authored and
+ * cloud-delivered constraints reach the rule as one identical config.
+ */
+export function lowerCompositionContract(
+  entries: CompositionAuthoringEntry[] | undefined
+): CompositionPattern[] {
+  return (entries ?? []).map((entry) => {
+    const region = { component: entry.inRegion };
+    if ("atMost" in entry.rule) {
+      return {
+        region,
+        select: entry.rule.of,
+        constraint: { kind: "cardinality", max: entry.rule.atMost },
+      };
+    }
+    return {
+      region,
+      select: entry.rule.when,
+      constraint: { kind: "co-occurrence", requires: entry.rule.require },
+    };
+  });
+}

package/src/rules/composition-pattern.test.ts

@@ -0,0 +1,320 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  asComponentId,
+  compileGlobalGovernanceFacts,
+  componentId as makeComponentId,
+  FactIndex,
+  makeGovernanceRuleConfigFact,
+  makeUsageComponentFact,
+  makeUsageNodeFact,
+  makeUsagePropResolvedFact,
+} from "../facts/index.js";
+import type { GovernanceConfig } from "../governance.js";
+
+import { ruleCompositionCardinality, ruleCompositionCoOccurrence } from "./composition-pattern.js";
+import {
+  type CompositionAuthoringEntry,
+  type CompositionPattern,
+  lowerCompositionContract,
+} from "./composition-pattern-schema.js";
+
+const BUTTON_GROUP = makeComponentId("@usefragments/ui", "ButtonGroup");
+const BUTTON = makeComponentId("@usefragments/ui", "Button");
+const FILE = "src/App.tsx";
+
+// The shared example policies from ACCEPTANCE.md.
+const POLICY_CARDINALITY: CompositionPattern = {
+  region: { component: "ButtonGroup" },
+  select: { component: "Button", prop: "variant", value: "primary" },
+  constraint: { kind: "cardinality", max: 1 },
+};
+const POLICY_COOCCURRENCE: CompositionPattern = {
+  region: { component: "ButtonGroup" },
+  select: { component: "Button", prop: "variant", value: "primary" },
+  constraint: { kind: "co-occurrence", requires: { prop: "variant", value: "secondary" } },
+};
+
+interface NodeSpec {
+  path: string;
+  element: string;
+  /** Canonical component the node resolves to (omit for an untracked element). */
+  component?: ReturnType<typeof makeComponentId>;
+  /** A `variant` prop and how it resolves (omit for none). */
+  variant?: { value?: string; resolution?: "static" | "dynamic" };
+}
+
+function add(ix: FactIndex, spec: NodeSpec): void {
+  const node = makeUsageNodeFact({
+    file: FILE,
+    nodePath: spec.path,
+    element: spec.element,
+    location: { file: FILE, line: 1, column: 1 },
+  });
+  ix.add(node);
+  if (spec.component) {
+    ix.add(makeUsageComponentFact({ nodeId: node.id, componentId: spec.component }));
+  }
+  if (spec.variant) {
+    ix.add(
+      makeUsagePropResolvedFact({
+        nodeId: node.id,
+        prop: "variant",
+        resolution: spec.variant.resolution ?? "static",
+        value: spec.variant.value,
+      })
+    );
+  }
+}
+
+function withPolicy(ix: FactIndex, ruleId: string, patterns: CompositionPattern[]): FactIndex {
+  ix.add(makeGovernanceRuleConfigFact({ ruleId, enabled: true, options: { patterns } }));
+  return ix;
+}
+
+const buttonGroup = (path: string): NodeSpec => ({
+  path,
+  element: "ButtonGroup",
+  component: BUTTON_GROUP,
+});
+const button = (path: string, variant?: NodeSpec["variant"]): NodeSpec => ({
+  path,
+  element: "Button",
+  component: BUTTON,
+  variant,
+});
+
+describe("composition/cardinality", () => {
+  // ACCEPTANCE §3
+  it("flags a second primary Button in one ButtonGroup", () => {
+    const ix = new FactIndex();
+    add(ix, buttonGroup("0:0"));
+    add(ix, button("0:0/0", { value: "primary" }));
+    add(ix, button("0:0/1", { value: "primary" }));
+    withPolicy(ix, "composition/cardinality", [POLICY_CARDINALITY]);
+
+    const findings = ruleCompositionCardinality(ix);
+    expect(findings).toHaveLength(1);
+    expect(findings[0]).toMatchObject({
+      ruleId: "composition/cardinality",
+      level: "warn",
+      code: "FUI5003",
+      message: "At most one primary Button is allowed per ButtonGroup (found 2).",
+    });
+  });
+
+  it("matches fully-qualified component refs across package authoring epochs", () => {
+    const ix = new FactIndex();
+    add(ix, {
+      path: "0:0",
+      element: "ButtonGroup",
+      component: asComponentId("@usefragments/ui#ButtonGroup"),
+    });
+    add(ix, {
+      path: "0:0/0",
+      element: "Button",
+      component: asComponentId("@usefragments/ui#Button"),
+      variant: { value: "primary" },
+    });
+    add(ix, {
+      path: "0:0/1",
+      element: "Button",
+      component: asComponentId("@usefragments/ui#Button"),
+      variant: { value: "primary" },
+    });
+    withPolicy(ix, "composition/cardinality", [
+      {
+        region: { component: "@usefragments/ui#ButtonGroup" },
+        select: {
+          component: "@usefragments/ui#Button",
+          prop: "variant",
+          value: "primary",
+        },
+        constraint: { kind: "cardinality", max: 1 },
+      },
+    ]);
+
+    expect(ruleCompositionCardinality(ix)).toHaveLength(1);
+  });
+
+  // ACCEPTANCE §4
+  it("does not flag a primary + secondary Button", () => {
+    const ix = new FactIndex();
+    add(ix, buttonGroup("0:0"));
+    add(ix, button("0:0/0", { value: "primary" }));
+    add(ix, button("0:0/1", { value: "secondary" }));
+    withPolicy(ix, "composition/cardinality", [POLICY_CARDINALITY]);
+
+    expect(ruleCompositionCardinality(ix)).toHaveLength(0);
+  });
+
+  // ACCEPTANCE §5 — per region, not per file.
+  it("counts cardinality per region, not across the file", () => {
+    const ix = new FactIndex();
+    // <> <ButtonGroup><Button primary/></ButtonGroup> <ButtonGroup><Button primary/></ButtonGroup> </>
+    add(ix, { path: "0:0", element: "Fragment" }); // untracked container
+    add(ix, buttonGroup("0:0/0"));
+    add(ix, button("0:0/0/0", { value: "primary" }));
+    add(ix, buttonGroup("0:0/1"));
+    add(ix, button("0:0/1/0", { value: "primary" }));
+    withPolicy(ix, "composition/cardinality", [POLICY_CARDINALITY]);
+
+    expect(ruleCompositionCardinality(ix)).toHaveLength(0);
+  });
+
+  // ACCEPTANCE §6 — static-resolution ceiling.
+  it("does not flag dynamic variants (unknown, not primary)", () => {
+    const ix = new FactIndex();
+    add(ix, buttonGroup("0:0"));
+    add(ix, button("0:0/0", { resolution: "dynamic" }));
+    add(ix, button("0:0/1", { resolution: "dynamic" }));
+    withPolicy(ix, "composition/cardinality", [POLICY_CARDINALITY]);
+
+    expect(ruleCompositionCardinality(ix)).toHaveLength(0);
+  });
+
+  // Foundation guard (not an ACCEPTANCE case): `min` is symmetric to `max`.
+  it("flags fewer than the required minimum", () => {
+    const ix = new FactIndex();
+    add(ix, buttonGroup("0:0"));
+    add(ix, button("0:0/0", { value: "primary" }));
+    withPolicy(ix, "composition/cardinality", [
+      {
+        region: { component: "ButtonGroup" },
+        select: { component: "Button", prop: "variant", value: "primary" },
+        constraint: { kind: "cardinality", min: 2 },
+      },
+    ]);
+
+    const findings = ruleCompositionCardinality(ix);
+    expect(findings).toHaveLength(1);
+    expect(findings[0].message).toBe(
+      "At least 2 primary Buttons are required per ButtonGroup (found 1)."
+    );
+  });
+
+  it("emits nothing when no policy is configured", () => {
+    const ix = new FactIndex();
+    add(ix, buttonGroup("0:0"));
+    add(ix, button("0:0/0", { value: "primary" }));
+    add(ix, button("0:0/1", { value: "primary" }));
+
+    expect(ruleCompositionCardinality(ix)).toHaveLength(0);
+  });
+
+  // Hardening: a malformed pattern is skipped; valid ones in the same array still fire.
+  it("skips malformed patterns without breaking the scan", () => {
+    const ix = new FactIndex();
+    add(ix, buttonGroup("0:0"));
+    add(ix, button("0:0/0", { value: "primary" }));
+    add(ix, button("0:0/1", { value: "primary" }));
+    ix.add(
+      makeGovernanceRuleConfigFact({
+        ruleId: "composition/cardinality",
+        enabled: true,
+        options: { patterns: [{ nonsense: true }, POLICY_CARDINALITY] },
+      })
+    );
+
+    const findings = ruleCompositionCardinality(ix);
+    expect(findings).toHaveLength(1);
+    expect(findings[0].message).toBe(
+      "At most one primary Button is allowed per ButtonGroup (found 2)."
+    );
+  });
+});
+
+describe("composition/co-occurrence", () => {
+  // ACCEPTANCE §7
+  it("flags a primary Button without the required secondary", () => {
+    const ix = new FactIndex();
+    add(ix, buttonGroup("0:0"));
+    add(ix, button("0:0/0", { value: "primary" }));
+    withPolicy(ix, "composition/co-occurrence", [POLICY_COOCCURRENCE]);
+
+    const findings = ruleCompositionCoOccurrence(ix);
+    expect(findings).toHaveLength(1);
+    expect(findings[0]).toMatchObject({
+      ruleId: "composition/co-occurrence",
+      level: "warn",
+      code: "FUI5004",
+      message: "A ButtonGroup with a primary Button should also contain a secondary Button.",
+    });
+  });
+
+  // ACCEPTANCE §8
+  it("does not flag when the required secondary is present", () => {
+    const ix = new FactIndex();
+    add(ix, buttonGroup("0:0"));
+    add(ix, button("0:0/0", { value: "primary" }));
+    add(ix, button("0:0/1", { value: "secondary" }));
+    withPolicy(ix, "composition/co-occurrence", [POLICY_COOCCURRENCE]);
+
+    expect(ruleCompositionCoOccurrence(ix)).toHaveLength(0);
+  });
+});
+
+// ACCEPTANCE §9 — a cloud-managed config round-trips into the rule input.
+describe("composition policy round-trip (§9)", () => {
+  it("compiles a delivered governance config into the §3 finding", () => {
+    const ix = new FactIndex();
+    add(ix, buttonGroup("0:0"));
+    add(ix, button("0:0/0", { value: "primary" }));
+    add(ix, button("0:0/1", { value: "primary" }));
+
+    // The exact shape Cloud delivers via GET /api/govern/policy (governConfig):
+    // a `composition/cardinality` rule config carrying `options.patterns`. This
+    // exercises the GovernanceConfig → governance_rule_config fact path the CLI
+    // runs, not a hand-built fact — proving the cloud→CLI contract end to end.
+    const govern: GovernanceConfig = {
+      rules: {
+        "composition/cardinality": {
+          enabled: true,
+          severity: "warn",
+          options: { patterns: [POLICY_CARDINALITY] },
+        },
+      },
+    };
+    for (const fact of compileGlobalGovernanceFacts(govern)) ix.add(fact);
+
+    const findings = ruleCompositionCardinality(ix);
+    expect(findings).toHaveLength(1);
+    expect(findings[0]).toMatchObject({
+      ruleId: "composition/cardinality",
+      level: "warn",
+      code: "FUI5003",
+      message: "At most one primary Button is allowed per ButtonGroup (found 2).",
+    });
+  });
+});
+
+// ACCEPTANCE §10 — fragment authoring sugar lowers to the same pattern the rule
+// reads, so authoring and cloud policy converge on one config.
+describe("lowerCompositionContract (§10)", () => {
+  it("lowers a cardinality block to POLICY_CARDINALITY", () => {
+    const block: CompositionAuthoringEntry[] = [
+      {
+        inRegion: "ButtonGroup",
+        rule: { atMost: 1, of: { component: "Button", prop: "variant", value: "primary" } },
+      },
+    ];
+    expect(lowerCompositionContract(block)).toEqual([POLICY_CARDINALITY]);
+  });
+
+  it("lowers a co-occurrence block to POLICY_COOCCURRENCE", () => {
+    const block: CompositionAuthoringEntry[] = [
+      {
+        inRegion: "ButtonGroup",
+        rule: {
+          when: { component: "Button", prop: "variant", value: "primary" },
+          require: { prop: "variant", value: "secondary" },
+        },
+      },
+    ];
+    expect(lowerCompositionContract(block)).toEqual([POLICY_COOCCURRENCE]);
+  });
+
+  it("returns no patterns for an absent block", () => {
+    expect(lowerCompositionContract(undefined)).toEqual([]);
+  });
+});