@usefragments/core 1.0.0

package/src/registry.test.ts

@@ -0,0 +1,245 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  REGISTRY_ARTIFACT_SCHEMA_VERSION,
+  REGISTRY_INSTALL_RECEIPT_SCHEMA_VERSION,
+  REGISTRY_MANIFEST_SCHEMA_VERSION,
+  buildRegistryArtifact,
+  buildRegistryFile,
+  computeRegistryHash,
+  finalizeRegistryManifest,
+  registryArtifactDigest,
+  registryArtifactSchema,
+  registryInstallReceiptSchema,
+  registryManifestSchema,
+  type RegistryManifestDraft,
+} from "./registry.js";
+
+function manifestDraft(): RegistryManifestDraft {
+  const buttonSource = buildRegistryFile({
+    path: "components/Button/index.tsx",
+    role: "source",
+    content: "export function Button() { return <button />; }\n",
+    contentType: "text/tsx",
+  });
+  const buttonStyle = buildRegistryFile({
+    path: "components/Button/Button.module.scss",
+    role: "style",
+    content: ".button { color: var(--brand-accent); }\n",
+    contentType: "text/scss",
+  });
+
+  return {
+    schemaVersion: REGISTRY_MANIFEST_SCHEMA_VERSION,
+    registryId: "acme-ui",
+    name: "Acme UI",
+    channel: "stable",
+    version: "2026.06.14",
+    fcid: "a".repeat(64),
+    generatedAt: "2026-06-14T12:00:00.000Z",
+    source: {
+      kind: "github",
+      repoFullName: "acme/ui",
+      commitSha: "abc123",
+      path: "packages/ui",
+    },
+    components: {
+      button: {
+        componentId: "button",
+        publicRef: "acme-ui:button",
+        name: "Button",
+        status: "stable",
+        tier: "core",
+        category: "actions",
+        files: [buttonSource.metadata, buttonStyle.metadata],
+        styleFiles: [buttonStyle.metadata.path],
+        tokenDependencies: ["--brand-accent"],
+        runtimeDependencies: [
+          {
+            name: "@base-ui/react",
+            versionRange: "^1.0.0",
+            type: "runtime",
+          },
+        ],
+        peerDependencies: [
+          {
+            name: "react",
+            versionRange: ">=18",
+            type: "peer",
+          },
+        ],
+        internalDependencies: [],
+        exports: [{ name: "Button", path: buttonSource.metadata.path }],
+        contract: { a11y: ["requires-name"] },
+        examples: [{ name: "Default", code: "<Button />" }],
+        provenance: { scanner: "fixture" },
+      },
+    },
+    dependencies: [],
+    installProfiles: [
+      {
+        name: "react-app",
+        targetPath: "src/fragments/ui",
+        importPath: "@/fragments/ui",
+        stylePath: "src/fragments/ui/styles.scss",
+        includeTests: false,
+      },
+    ],
+  };
+}
+
+describe("registry schemas", () => {
+  it("finalizes and validates a registry manifest", () => {
+    const manifest = finalizeRegistryManifest(manifestDraft());
+
+    expect(registryManifestSchema.parse(manifest).registryHash).toMatch(/^[0-9a-f]{64}$/);
+    expect(manifest.components.button.name).toBe("Button");
+  });
+
+  it("keeps the registry hash stable across generatedAt changes", () => {
+    const first = manifestDraft();
+    const second = {
+      ...first,
+      generatedAt: "2026-06-14T13:00:00.000Z",
+    };
+
+    expect(computeRegistryHash(first)).toBe(computeRegistryHash(second));
+  });
+
+  it("changes the registry hash when file content changes", () => {
+    const first = manifestDraft();
+    const changedFile = buildRegistryFile({
+      path: "components/Button/index.tsx",
+      role: "source",
+      content: "export function Button() { return <button data-x />; }\n",
+      contentType: "text/tsx",
+    });
+    const second = {
+      ...first,
+      components: {
+        button: {
+          ...first.components.button,
+          files: [changedFile.metadata, first.components.button.files[1]],
+        },
+      },
+    };
+
+    expect(computeRegistryHash(first)).not.toBe(computeRegistryHash(second));
+  });
+
+  it("rejects unsafe registry file paths", () => {
+    expect(() =>
+      buildRegistryFile({
+        path: "../Button.tsx",
+        role: "source",
+        content: "",
+        contentType: "text/tsx",
+      })
+    ).toThrow(/must not contain \.\./i);
+
+    expect(() =>
+      buildRegistryFile({
+        path: "/tmp/Button.tsx",
+        role: "source",
+        content: "",
+        contentType: "text/tsx",
+      })
+    ).toThrow(/not absolute/i);
+  });
+
+  it("builds local registry artifacts and detects missing content", () => {
+    const source = buildRegistryFile({
+      path: "components/Button/index.tsx",
+      role: "source",
+      content: "export const Button = () => null;\n",
+      contentType: "text/tsx",
+    });
+    const draft = manifestDraft();
+    const artifact = buildRegistryArtifact({
+      manifest: {
+        ...draft,
+        components: {
+          button: {
+            ...draft.components.button,
+            files: [source.metadata],
+          },
+        },
+      },
+      files: [source.content],
+    });
+
+    expect(registryArtifactDigest(artifact)).toMatch(/^[0-9a-f]{64}$/);
+    expect(() =>
+      buildRegistryArtifact({
+        manifest: artifact.manifest,
+        files: [source.content, source.content],
+      })
+    ).toThrow(/Duplicate registry file content/);
+
+    const manifest = finalizeRegistryManifest({
+      ...draft,
+      components: {
+        button: {
+          ...draft.components.button,
+          files: [source.metadata],
+        },
+      },
+    });
+
+    expect(() =>
+      registryArtifactSchema.parse({
+        schemaVersion: REGISTRY_ARTIFACT_SCHEMA_VERSION,
+        manifest,
+        files: {},
+      })
+    ).toThrow(/Missing content/);
+
+    expect(() =>
+      registryArtifactSchema.parse({
+        schemaVersion: REGISTRY_ARTIFACT_SCHEMA_VERSION,
+        manifest,
+        files: {
+          [source.metadata.path]: {
+            ...source.content,
+            path: "components/Button/other.tsx",
+          },
+        },
+      })
+    ).toThrow(/does not match content path/);
+  });
+
+  it("validates install receipts for committed local proof", () => {
+    const manifest = finalizeRegistryManifest(manifestDraft());
+
+    expect(() =>
+      registryInstallReceiptSchema.parse({
+        schemaVersion: REGISTRY_INSTALL_RECEIPT_SCHEMA_VERSION,
+        registryId: manifest.registryId,
+        registryVersion: manifest.version,
+        registryHash: manifest.registryHash,
+        fcid: manifest.fcid,
+        channel: manifest.channel,
+        targetPath: "src/fragments/ui",
+        importPath: "@/fragments/ui",
+        installedComponents: [
+          {
+            componentId: "button",
+            publicRef: "acme-ui:button",
+            name: "Button",
+            files: ["src/fragments/ui/components/Button/index.tsx"],
+          },
+        ],
+        files: [
+          {
+            path: "src/fragments/ui/components/Button/index.tsx",
+            sourcePath: "components/Button/index.tsx",
+            sha256: manifest.components.button.files[0].sha256,
+            componentId: "button",
+          },
+        ],
+        dependencies: manifest.components.button.peerDependencies,
+        installedAt: "2026-06-14T12:30:00.000Z",
+      })
+    ).not.toThrow();
+  });
+});

package/src/registry.ts

@@ -0,0 +1,369 @@
+import { z } from "zod";
+
+import { portableRepoPathError } from "./config-paths.js";
+import { canonicalPreimage, contractHash, sha256Hex } from "./contract/hash.js";
+
+export const REGISTRY_MANIFEST_SCHEMA_VERSION = "fragments.registry.v1";
+export const REGISTRY_ARTIFACT_SCHEMA_VERSION = "fragments.registry-artifact.v1";
+export const REGISTRY_INSTALL_RECEIPT_SCHEMA_VERSION = "fragments.registry-lock.v1";
+
+const sha256Schema = z.string().regex(/^[0-9a-f]{64}$/);
+
+const registryPathSchema = z
+  .string()
+  .min(1)
+  .superRefine((value, ctx) => {
+    const error = portableRepoPathError(value);
+    if (error) {
+      ctx.addIssue({ code: z.ZodIssueCode.custom, message: error });
+    }
+  });
+
+const registryFilePathSchema = registryPathSchema.superRefine((value, ctx) => {
+  if (value === ".") {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: "File path must point to a file, not the package root",
+    });
+  }
+});
+
+export const registryDependencyTypeSchema = z.enum(["runtime", "peer", "dev", "optional"]);
+
+export const registryDependencySchema = z.object({
+  name: z.string().min(1),
+  versionRange: z.string().min(1),
+  type: registryDependencyTypeSchema,
+  optional: z.boolean().optional(),
+});
+
+export const registryFileRoleSchema = z.enum([
+  "source",
+  "style",
+  "token",
+  "contract",
+  "test",
+  "story",
+  "example",
+  "asset",
+  "barrel",
+  "metadata",
+]);
+
+export const registryFileSchema = z.object({
+  path: registryFilePathSchema,
+  role: registryFileRoleSchema,
+  sha256: sha256Schema,
+  size: z.number().int().nonnegative(),
+  contentType: z.string().min(1),
+  contentRef: z.string().min(1),
+});
+
+export const registryFileContentSchema = z.object({
+  path: registryFilePathSchema,
+  content: z.string(),
+  sha256: sha256Schema,
+  size: z.number().int().nonnegative(),
+  contentType: z.string().min(1),
+});
+
+export const registrySourceSchema = z.discriminatedUnion("kind", [
+  z.object({
+    kind: z.literal("package"),
+    packageName: z.string().min(1),
+    version: z.string().optional(),
+    rootPath: registryPathSchema.optional(),
+    commitSha: z.string().optional(),
+  }),
+  z.object({
+    kind: z.literal("github"),
+    repoFullName: z.string().min(1),
+    commitSha: z.string().min(1),
+    path: registryPathSchema.optional(),
+  }),
+  z.object({
+    kind: z.literal("local"),
+    rootPath: registryPathSchema.optional(),
+    commitSha: z.string().optional(),
+  }),
+  z.object({
+    kind: z.literal("manual"),
+    label: z.string().min(1),
+  }),
+]);
+
+export const registryComponentExportSchema = z.object({
+  name: z.string().min(1),
+  kind: z.enum(["component", "hook", "utility", "type", "style"]).default("component"),
+  path: registryFilePathSchema.optional(),
+});
+
+export const registryComponentSchema = z.object({
+  componentId: z.string().min(1),
+  publicRef: z.string().min(1),
+  name: z.string().min(1),
+  status: z.string().min(1).default("stable"),
+  tier: z.enum(["core", "composition", "utility", "custom"]).default("core"),
+  category: z.string().optional(),
+  files: z.array(registryFileSchema).min(1),
+  styleFiles: z.array(registryFilePathSchema).default([]),
+  tokenDependencies: z.array(z.string().min(1)).default([]),
+  runtimeDependencies: z.array(registryDependencySchema).default([]),
+  peerDependencies: z.array(registryDependencySchema).default([]),
+  internalDependencies: z.array(z.string().min(1)).default([]),
+  exports: z.array(registryComponentExportSchema).default([]),
+  contract: z.unknown().optional(),
+  examples: z.array(z.unknown()).default([]),
+  provenance: z.record(z.unknown()).default({}),
+});
+
+export const registryEntrypointSchema = z.object({
+  specifier: z.string().min(1),
+  sourcePath: registryFilePathSchema,
+});
+
+export const registryInstallProfileSchema = z.object({
+  name: z.string().min(1),
+  targetPath: registryPathSchema,
+  importPath: z.string().min(1),
+  stylePath: registryPathSchema.optional(),
+  includeTests: z.boolean().default(false),
+});
+
+const registryManifestBaseSchema = z.object({
+  schemaVersion: z.literal(REGISTRY_MANIFEST_SCHEMA_VERSION),
+  registryId: z.string().min(1),
+  name: z.string().min(1),
+  channel: z.string().min(1),
+  version: z.string().min(1),
+  contractVersionId: z.string().optional(),
+  fcid: sha256Schema.optional(),
+  generatedAt: z.string().datetime(),
+  source: registrySourceSchema,
+  packageFiles: z.array(registryFileSchema).default([]),
+  entrypoints: z.array(registryEntrypointSchema).default([]),
+  components: z.record(z.string(), registryComponentSchema),
+  dependencies: z.array(registryDependencySchema).default([]),
+  installProfiles: z.array(registryInstallProfileSchema).default([]),
+});
+
+export const registryManifestDraftSchema = registryManifestBaseSchema;
+
+export const registryManifestSchema = registryManifestBaseSchema.extend({
+  registryHash: sha256Schema,
+});
+
+export const registryArtifactSchema = z
+  .object({
+    schemaVersion: z.literal(REGISTRY_ARTIFACT_SCHEMA_VERSION),
+    manifest: registryManifestSchema,
+    files: z.record(registryFilePathSchema, registryFileContentSchema),
+  })
+  .superRefine((artifact, ctx) => {
+    const filesByPath = artifact.files;
+    for (const [path, content] of Object.entries(filesByPath)) {
+      if (content.path !== path) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: ["files", path, "path"],
+          message: `Registry file map key ${path} does not match content path ${content.path}`,
+        });
+      }
+    }
+
+    const manifestFiles = [
+      ...artifact.manifest.packageFiles,
+      ...artifact.manifest.entrypoints.map((entrypoint) => ({
+        path: entrypoint.sourcePath,
+        role: "barrel" as const,
+        sha256: filesByPath[entrypoint.sourcePath]?.sha256 ?? "",
+        size: filesByPath[entrypoint.sourcePath]?.size ?? 0,
+        contentType: filesByPath[entrypoint.sourcePath]?.contentType ?? "text/plain",
+        contentRef: `sha256:${filesByPath[entrypoint.sourcePath]?.sha256 ?? ""}`,
+      })),
+      ...Object.values(artifact.manifest.components).flatMap((component) => component.files),
+    ];
+
+    for (const file of manifestFiles) {
+      const content = filesByPath[file.path];
+      if (!content) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: ["files", file.path],
+          message: `Missing content for registry file ${file.path}`,
+        });
+        continue;
+      }
+      if (content.sha256 !== file.sha256) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: ["files", file.path, "sha256"],
+          message: `Content hash for ${file.path} does not match manifest`,
+        });
+      }
+      if (content.size !== file.size) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: ["files", file.path, "size"],
+          message: `Content size for ${file.path} does not match manifest`,
+        });
+      }
+    }
+  });
+
+export const registryInstallReceiptFileSchema = z.object({
+  path: registryFilePathSchema,
+  sha256: sha256Schema,
+  sourcePath: registryFilePathSchema,
+  componentId: z.string().min(1).optional(),
+});
+
+export const registryInstallReceiptComponentSchema = z.object({
+  componentId: z.string().min(1),
+  publicRef: z.string().min(1),
+  name: z.string().min(1),
+  files: z.array(registryFilePathSchema),
+});
+
+export const registryInstallReceiptSchema = z.object({
+  schemaVersion: z.literal(REGISTRY_INSTALL_RECEIPT_SCHEMA_VERSION),
+  registryId: z.string().min(1),
+  registryVersion: z.string().min(1),
+  registryHash: sha256Schema,
+  fcid: sha256Schema.optional(),
+  channel: z.string().min(1).optional(),
+  targetPath: registryPathSchema,
+  importPath: z.string().min(1),
+  installedComponents: z.array(registryInstallReceiptComponentSchema),
+  files: z.array(registryInstallReceiptFileSchema),
+  dependencies: z.array(registryDependencySchema).default([]),
+  installedAt: z.string().datetime(),
+});
+
+export type RegistryDependencyType = z.infer<typeof registryDependencyTypeSchema>;
+export type RegistryDependency = z.infer<typeof registryDependencySchema>;
+export type RegistryFileRole = z.infer<typeof registryFileRoleSchema>;
+export type RegistryFile = z.infer<typeof registryFileSchema>;
+export type RegistryFileContent = z.infer<typeof registryFileContentSchema>;
+export type RegistrySource = z.infer<typeof registrySourceSchema>;
+export type RegistryComponentExport = z.infer<typeof registryComponentExportSchema>;
+export type RegistryComponent = z.infer<typeof registryComponentSchema>;
+export type RegistryEntrypoint = z.infer<typeof registryEntrypointSchema>;
+export type RegistryInstallProfile = z.infer<typeof registryInstallProfileSchema>;
+export type RegistryManifestDraft = z.input<typeof registryManifestDraftSchema>;
+export type RegistryManifest = z.infer<typeof registryManifestSchema>;
+export type RegistryArtifact = z.infer<typeof registryArtifactSchema>;
+export type RegistryInstallReceiptFile = z.infer<typeof registryInstallReceiptFileSchema>;
+export type RegistryInstallReceiptComponent = z.infer<typeof registryInstallReceiptComponentSchema>;
+export type RegistryInstallReceipt = z.infer<typeof registryInstallReceiptSchema>;
+
+export interface RegistryFileInput {
+  path: string;
+  role: RegistryFileRole;
+  content: string;
+  contentType: string;
+  contentRef?: string;
+}
+
+export interface RegistryArtifactInput {
+  manifest: RegistryManifestDraft;
+  files: readonly RegistryFileContent[];
+}
+
+function registryHashPayload(manifest: RegistryManifestDraft | RegistryManifest): unknown {
+  const { generatedAt: _generatedAt, ...withoutGeneratedAt } = manifest;
+  if ("registryHash" in withoutGeneratedAt) {
+    const { registryHash: _registryHash, ...withoutHash } = withoutGeneratedAt;
+    return withoutHash;
+  }
+  return withoutGeneratedAt;
+}
+
+export function computeRegistryHash(manifest: RegistryManifestDraft | RegistryManifest): string {
+  return contractHash(registryHashPayload(manifest));
+}
+
+export function finalizeRegistryManifest(input: RegistryManifestDraft): RegistryManifest {
+  const draft = registryManifestDraftSchema.parse(input);
+  return registryManifestSchema.parse({
+    ...draft,
+    registryHash: computeRegistryHash(draft),
+  });
+}
+
+export function hashRegistryFileContent(content: string): string {
+  return sha256Hex(content);
+}
+
+export function registryFileSize(content: string): number {
+  return new TextEncoder().encode(content).length;
+}
+
+export function buildRegistryFile(input: RegistryFileInput): {
+  metadata: RegistryFile;
+  content: RegistryFileContent;
+} {
+  const sha256 = hashRegistryFileContent(input.content);
+  const size = registryFileSize(input.content);
+  const path = registryFilePathSchema.parse(input.path);
+  const contentType = z.string().min(1).parse(input.contentType);
+  return {
+    metadata: registryFileSchema.parse({
+      path,
+      role: input.role,
+      sha256,
+      size,
+      contentType,
+      contentRef: input.contentRef ?? `sha256:${sha256}`,
+    }),
+    content: registryFileContentSchema.parse({
+      path,
+      content: input.content,
+      sha256,
+      size,
+      contentType,
+    }),
+  };
+}
+
+export function buildRegistryArtifact(input: RegistryArtifactInput): RegistryArtifact {
+  const manifest = finalizeRegistryManifest(input.manifest);
+  const files = new Map<string, RegistryFileContent>();
+  for (const file of input.files) {
+    const content = registryFileContentSchema.parse(file);
+    if (files.has(content.path)) {
+      throw new Error(`Duplicate registry file content for ${content.path}`);
+    }
+    files.set(content.path, content);
+  }
+
+  return registryArtifactSchema.parse({
+    schemaVersion: REGISTRY_ARTIFACT_SCHEMA_VERSION,
+    manifest,
+    files: Object.fromEntries(files),
+  });
+}
+
+export function assertValidRegistryArtifact(artifact: unknown): RegistryArtifact {
+  return registryArtifactSchema.parse(artifact);
+}
+
+export function registryArtifactDigest(artifact: RegistryArtifact): string {
+  const files = Object.fromEntries(
+    Object.entries(artifact.files)
+      .map(([path, file]) => [path, { sha256: file.sha256, size: file.size }] as const)
+      .sort(([leftPath], [rightPath]) => leftPath.localeCompare(rightPath))
+  );
+
+  return contractHash({
+    schemaVersion: artifact.schemaVersion,
+    manifest: registryHashPayload(artifact.manifest),
+    files,
+  });
+}
+
+export function registryManifestCanonicalPreimage(
+  manifest: RegistryManifestDraft | RegistryManifest
+): string {
+  return canonicalPreimage(registryHashPayload(manifest));
+}

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

@@ -0,0 +1,93 @@
+/**
+ * `a11y/required-accessible-name` — fires for components with an
+ * `a11y.requireName` policy whose JSX usage has no discoverable accessible
+ * name.
+ *
+ * Accepted name sources (any one is enough):
+ *   - non-empty `usage_text_child` content
+ *   - `aria-label="..."` (static or dynamic both pass; we cannot prove a
+ *     dynamic value is empty at scan time)
+ *   - `aria-labelledby={...}`
+ *   - `title="..."`
+ *
+ * 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 { makeFinding } from "./finding.js";
+import type { Finding } from "./types.js";
+import { indexPropsByNodeId, indexTextChildrenByNodeId, readUsageNode } from "./utils.js";
+
+export const RULE_ID = "a11y/required-accessible-name";
+export const RULE_VERSION = "1";
+
+const NAME_SOURCE_PROPS = new Set(["aria-label", "aria-labelledby", "title"]);
+
+export function ruleA11yRequiredAccessibleName(ix: FactIndex): Finding[] {
+  const findings: Finding[] = [];
+  const propsByNode = indexPropsByNodeId(ix);
+  const textByNode = indexTextChildrenByNodeId(ix);
+
+  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;
+
+    const props = propsByNode.get(node.id) ?? [];
+    if (props.some(isAriaHidden)) continue;
+
+    if (hasAccessibleName(props, textByNode.get(node.id) ?? [])) continue;
+
+    findings.push(
+      makeFinding({
+        ruleId: RULE_ID,
+        ruleVersion: RULE_VERSION,
+        severity: policy.severity,
+        message: `<${node.element}> has no accessible name. ${policy.because}`.trim(),
+        location: node.location,
+        evidence: ix.evidence([node.id, usageComponent.id, policy.id]),
+        fingerprintIdentity: {
+          file: node.file,
+          componentId: usageComponent.componentId,
+          element: node.element,
+          nodePath: node.nodePath,
+        },
+        attributes: {
+          componentId: usageComponent.componentId,
+          element: node.element,
+        },
+      })
+    );
+  }
+
+  return findings;
+}
+
+function hasAccessibleName(
+  props: UsagePropResolvedFact[],
+  textChildren: ReadonlyArray<{ text: string }>
+): boolean {
+  for (const child of textChildren) {
+    if (typeof child.text === "string" && child.text.trim().length > 0) return true;
+  }
+  for (const prop of props) {
+    if (!NAME_SOURCE_PROPS.has(prop.prop)) continue;
+    if (prop.resolution === "spread") continue;
+    if (prop.resolution === "dynamic") return true;
+    if (prop.resolution === "static") {
+      if (typeof prop.value === "string" && prop.value.trim().length > 0) return true;
+      if (prop.value !== undefined && prop.value !== "" && prop.value !== null) return true;
+    }
+  }
+  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";
+}