@yansirplus/cli 0.5.17 → 0.5.19

package/dist/generate/generate-carrier-reference.mjs

@@ -1,514 +0,0 @@
-#!/usr/bin/env bun
-import fs from "node:fs";
-import path from "node:path";
-import { pathToFileURL } from "node:url";
-import {
-  checkProjectionSink,
-  defineProjectionSpec,
-  runProjectionSink,
-} from "../lib/projection-sink.mjs";
-
-const root = process.cwd();
-const check = process.argv.includes("--check");
-const surface = JSON.parse(fs.readFileSync(path.join(root, "docs/surface.json"), "utf8"));
-const target = "docs/reference/carriers.md";
-const failures = [];
-
-const generatedNotice =
-  "<!-- generated by packages/cli/src/generate/generate-carrier-reference.mjs; edit carrier definitions -->";
-
-const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
-
-const isCarrier = (value) =>
-  isRecord(value) &&
-  typeof value.ownerId === "string" &&
-  typeof value.sourcePackageName === "string" &&
-  typeof value.prefix === "string" &&
-  isRecord(value.boundaryContract) &&
-  isRecord(value.settlementContract) &&
-  typeof value.boundaryPackage === "function" &&
-  typeof value.decode === "function";
-
-const isEventNamespace = (value) =>
-  isRecord(value) &&
-  typeof value.ownerId === "string" &&
-  typeof value.sourcePackageName === "string" &&
-  Array.isArray(value.kindPrefixes) &&
-  value.kindPrefixes.every((prefix) => typeof prefix === "string" && prefix.length > 0) &&
-  typeof value.version === "string";
-
-const walk = (relativePath, options = {}) => {
-  const absolutePath = path.join(root, relativePath);
-  if (!fs.existsSync(absolutePath)) return [];
-  const stat = fs.statSync(absolutePath);
-  if (stat.isFile()) return [relativePath];
-  const ignored = options.ignored ?? new Set(["node_modules", "dist", ".wrangler", ".turbo"]);
-  const files = [];
-  for (const entry of fs.readdirSync(absolutePath, { withFileTypes: true })) {
-    if (entry.isDirectory() && ignored.has(entry.name)) continue;
-    const child = path.join(relativePath, entry.name).split(path.sep).join("/");
-    if (entry.isDirectory()) files.push(...walk(child, options));
-    if (entry.isFile()) files.push(child);
-  }
-  return files.sort((left, right) => left.localeCompare(right));
-};
-
-const sourcePackages = surface.packages
-  .filter(
-    (pkg) =>
-      isRecord(pkg) &&
-      typeof pkg.name === "string" &&
-      typeof pkg.path === "string" &&
-      pkg.path.startsWith("packages/") &&
-      fs.existsSync(path.join(root, pkg.path, "package.json")),
-  )
-  .sort(
-    (left, right) => right.path.length - left.path.length || left.path.localeCompare(right.path),
-  );
-
-const sourcePackageForFile = (file) =>
-  sourcePackages.find((pkg) => file === pkg.path || file.startsWith(`${pkg.path}/`));
-
-const defineCarrierFiles = () =>
-  walk("packages")
-    .filter((file) => /\/src\/.*\.ts$/u.test(file))
-    .filter((file) => fs.readFileSync(path.join(root, file), "utf8").includes("defineCarrier("));
-
-const escapeCell = (value) => String(value).replaceAll("|", "\\|").replaceAll("\n", "<br>");
-
-const table = (headers, rows) => {
-  const escapedHeaders = headers.map(escapeCell);
-  const escapedRows = rows.map((row) => row.map(escapeCell));
-  const widths = escapedHeaders.map((header, index) =>
-    Math.max(header.length, ...escapedRows.map((row) => row[index].length)),
-  );
-  const pad = (value, width) => `${value}${" ".repeat(Math.max(0, width - value.length))}`;
-  const line = (cells) => `| ${cells.map((cell, index) => pad(cell, widths[index])).join(" | ")} |`;
-  const divider = `| ${widths.map((width) => "-".repeat(width)).join(" | ")} |`;
-  return [line(escapedHeaders), divider, ...escapedRows.map(line)].join("\n");
-};
-
-const list = (values) =>
-  values.length === 0 ? "None." : values.map((value) => `\`${value}\``).join(", ");
-
-const describeSchema = (schema) => {
-  if (!isRecord(schema)) return "unknown";
-  if (Array.isArray(schema.enum)) return `enum(${schema.enum.map(String).join(", ")})`;
-  if ("const" in schema) return `const(${String(schema.const)})`;
-  if (typeof schema.type === "string") {
-    if (schema.type === "object") return "object";
-    if (schema.type === "array") return `array<${describeSchema(schema.items)}>`;
-    return schema.type;
-  }
-  if (Array.isArray(schema.anyOf)) return "anyOf";
-  if (Array.isArray(schema.oneOf)) return "oneOf";
-  return "unknown";
-};
-
-const payloadFields = (schema) => {
-  if (!isRecord(schema) || !isRecord(schema.properties)) return "None.";
-  const required = new Set(Array.isArray(schema.required) ? schema.required : []);
-  const fields = Object.entries(schema.properties).map(([name, fieldSchema]) => {
-    const marker = required.has(name) ? "required" : "optional";
-    return `\`${name}\`: ${describeSchema(fieldSchema)} (${marker})`;
-  });
-  return fields.length === 0 ? "None." : fields.join("<br>");
-};
-
-const claimSummary = (claim) => {
-  if (claim === undefined) return "none";
-  if (claim.phase === "pre") return `pre \`${claim.key}\``;
-  if (claim.phase === "lived") {
-    return `lived \`${claim.key}\`; anchors ${list(claim.anchorKinds ?? [])}`;
-  }
-  if (claim.phase === "rejected") {
-    return `rejected \`${claim.key}\`; rejections ${list(claim.rejectionKinds ?? [])}`;
-  }
-  return "unknown";
-};
-
-const materialSummary = (material) => {
-  if (!isRecord(material)) return "unknown";
-  const parts = [`${material.required === false ? "optional" : "required"} ${material.kind}`];
-  if (typeof material.provider === "string") parts.push(`provider=${material.provider}`);
-  if (typeof material.purpose === "string") parts.push(`purpose=${material.purpose}`);
-  if (typeof material.protocol === "string") parts.push(`protocol=${material.protocol}`);
-  if (typeof material.bindingKind === "string") parts.push(`binding=${material.bindingKind}`);
-  if (typeof material.resourceKind === "string") parts.push(`resource=${material.resourceKind}`);
-  return parts.join(", ");
-};
-
-const materialRows = (materials) =>
-  materials.map((material) => [
-    `\`${material.slot ?? "<unknown>"}\``,
-    material.kind ?? "unknown",
-    material.required === false ? "no" : "yes",
-    [
-      typeof material.provider === "string" ? `provider=${material.provider}` : null,
-      typeof material.purpose === "string" ? `purpose=${material.purpose}` : null,
-      typeof material.protocol === "string" ? `protocol=${material.protocol}` : null,
-      typeof material.bindingKind === "string" ? `binding=${material.bindingKind}` : null,
-      typeof material.resourceKind === "string" ? `resource=${material.resourceKind}` : null,
-    ]
-      .filter((value) => value !== null)
-      .join(", ") || "-",
-  ]);
-
-const authorityRows = (authorities) =>
-  authorities.map((authority) => [
-    `\`${authority.authorityRef?.authorityId ?? "<unknown>"}\``,
-    authority.authorityRef?.authorityClass ?? "unknown",
-    (authority.requiredMaterials ?? [])
-      .map((material) => `\`${material.slot}\`: ${materialSummary(material)}`)
-      .join("<br>") || "None.",
-  ]);
-
-const validateCarrier = (carrier, pkg) => {
-  if (carrier.sourcePackageName !== pkg.name) {
-    failures.push(
-      `${pkg.name}: carrier sourcePackageName ${carrier.sourcePackageName} does not match surface name`,
-    );
-  }
-  if (carrier.boundaryContract.ownerId !== carrier.ownerId) {
-    failures.push(`${carrier.ownerId}: boundaryContract ownerId mismatch`);
-  }
-  if (carrier.boundaryContract.sourcePackageName !== carrier.sourcePackageName) {
-    failures.push(`${carrier.ownerId}: boundaryContract sourcePackageName mismatch`);
-  }
-  if (
-    !Array.isArray(carrier.boundaryContract.kindPrefixes) ||
-    carrier.boundaryContract.kindPrefixes.length === 0
-  ) {
-    failures.push(`${carrier.ownerId}: missing kind prefixes`);
-  }
-  if (
-    !isRecord(carrier.boundaryContract.events) ||
-    Object.keys(carrier.boundaryContract.events).length === 0
-  ) {
-    failures.push(`${carrier.ownerId}: missing boundary events`);
-  }
-  if (
-    carrier.boundaryContract.settlement?.settlementId !== carrier.settlementContract.settlementId
-  ) {
-    failures.push(`${carrier.ownerId}: settlement contract mismatch`);
-  }
-};
-
-const validateNamespace = (namespace, pkg) => {
-  if (namespace.sourcePackageName !== pkg.name) {
-    failures.push(
-      `${pkg.name}: namespace sourcePackageName ${namespace.sourcePackageName} does not match surface name`,
-    );
-  }
-};
-
-const carrierModuleEntries = async (file) => {
-  const entries = [];
-  const mod = await import(pathToFileURL(path.join(root, file)).href);
-  for (const [exportName, value] of Object.entries(mod)) {
-    entries.push({ exportName, value, file });
-  }
-  return entries;
-};
-
-const exportedNamespace = (entry, version) => {
-  if (isEventNamespace(entry.value)) return entry.value;
-  if (typeof entry.value !== "function" || !entry.exportName.endsWith("EventNamespace")) {
-    return undefined;
-  }
-  const value = entry.value(version);
-  return isEventNamespace(value) ? value : undefined;
-};
-
-/** @returns {string[]} */
-const namespaceEventKinds = (entries, prefixes) => {
-  /** @type {Set<string>} */
-  const events = new Set();
-  for (const entry of entries) {
-    if (!isRecord(entry.value)) continue;
-    if (!entry.exportName.endsWith("EVENTS") && !entry.exportName.endsWith("KIND")) continue;
-    for (const value of Object.values(entry.value)) {
-      if (typeof value === "string" && prefixes.some((prefix) => value.startsWith(prefix))) {
-        events.add(value);
-      }
-    }
-  }
-  return [...events].sort((left, right) => left.localeCompare(right));
-};
-
-const discoverCarriers = async () => {
-  const carriers = [];
-  const seenOwnerIds = new Set();
-  const seenEventKinds = new Set();
-  const files = defineCarrierFiles();
-
-  for (const file of files) {
-    const pkg = sourcePackageForFile(file);
-    if (pkg === undefined) {
-      failures.push(`${file}: defineCarrier declaration is outside a live workspace package`);
-      continue;
-    }
-    const entries = await carrierModuleEntries(file);
-    const exportedCarriers = [];
-    const seenCarrierOwnerIds = new Set();
-    for (const entry of entries) {
-      if (!isCarrier(entry.value) || seenCarrierOwnerIds.has(entry.value.ownerId)) continue;
-      seenCarrierOwnerIds.add(entry.value.ownerId);
-      exportedCarriers.push({ exportName: entry.exportName, carrier: entry.value });
-    }
-    const exportedNamespaces = [];
-    const seenNamespaceOwnerIds = new Set();
-    for (const entry of entries) {
-      const namespace = exportedNamespace(entry, pkg.version ?? "0.2.9");
-      if (namespace === undefined || seenNamespaceOwnerIds.has(namespace.ownerId)) continue;
-      seenNamespaceOwnerIds.add(namespace.ownerId);
-      exportedNamespaces.push({
-        exportName: entry.exportName,
-        namespace,
-        events: namespaceEventKinds(entries, namespace.kindPrefixes),
-      });
-    }
-
-    if (exportedCarriers.length > 1) {
-      failures.push(`${file}: exports multiple carrier-shaped values`);
-      continue;
-    }
-    if (exportedCarriers.length === 0 && exportedNamespaces.length > 1) {
-      failures.push(`${file}: exports multiple namespace-shaped values`);
-      continue;
-    }
-    if (exportedCarriers.length === 0 && exportedNamespaces.length === 0) {
-      failures.push(`${file}: defineCarrier declaration exports no carrier or namespace value`);
-      continue;
-    }
-
-    if (exportedCarriers.length === 1) {
-      const entry = exportedCarriers[0];
-      validateCarrier(entry.carrier, pkg);
-
-      if (seenOwnerIds.has(entry.carrier.ownerId)) {
-        failures.push(`${entry.carrier.ownerId}: duplicate carrier ownerId`);
-      }
-      seenOwnerIds.add(entry.carrier.ownerId);
-
-      for (const eventKind of Object.keys(entry.carrier.boundaryContract.events)) {
-        if (seenEventKinds.has(eventKind)) {
-          failures.push(`${entry.carrier.ownerId}: duplicate event kind ${eventKind}`);
-        }
-        seenEventKinds.add(eventKind);
-      }
-
-      carriers.push({
-        kind: "carrier",
-        pkg,
-        file,
-        exportName: entry.exportName,
-        carrier: entry.carrier,
-      });
-      continue;
-    }
-
-    const entry = exportedNamespaces[0];
-    validateNamespace(entry.namespace, pkg);
-    if (seenOwnerIds.has(entry.namespace.ownerId)) {
-      failures.push(`${entry.namespace.ownerId}: duplicate carrier ownerId`);
-    }
-    seenOwnerIds.add(entry.namespace.ownerId);
-    for (const eventKind of entry.events) {
-      if (seenEventKinds.has(eventKind)) {
-        failures.push(`${entry.namespace.ownerId}: duplicate event kind ${eventKind}`);
-      }
-      seenEventKinds.add(eventKind);
-    }
-    carriers.push({
-      kind: "namespace",
-      pkg,
-      file,
-      exportName: entry.exportName,
-      namespace: entry.namespace,
-      events: entry.events,
-    });
-  }
-
-  if (files.length > 0 && carriers.length === 0) {
-    failures.push(
-      `carrier reference projected zero carriers from ${files.length} defineCarrier declaration file(s)`,
-    );
-  }
-
-  return carriers.sort((left, right) =>
-    (left.kind === "carrier" ? left.carrier.ownerId : left.namespace.ownerId).localeCompare(
-      right.kind === "carrier" ? right.carrier.ownerId : right.namespace.ownerId,
-    ),
-  );
-};
-
-const renderCarrier = ({ pkg, file, exportName, carrier }) => {
-  const boundary = carrier.boundaryContract;
-  const settlement = carrier.settlementContract;
-  const eventRows = Object.entries(boundary.events)
-    .sort(([left], [right]) => left.localeCompare(right))
-    .map(([eventKind, contract]) => [
-      `\`${eventKind}\``,
-      claimSummary(contract.claim),
-      payloadFields(contract.payloadSchema),
-    ]);
-
-  const sections = [
-    `## ${carrier.ownerId}`,
-    "",
-    `Source package: \`${pkg.name}\``,
-    "",
-    `Source file: \`${file}\``,
-    "",
-    `Export: \`${exportName}\``,
-    "",
-    `Prefix: \`${carrier.prefix}\``,
-    "",
-    `Roles: ${list(boundary.roles ?? [])}`,
-    "",
-    "### Event Kinds",
-    "",
-    table(["Event kind", "Claim", "Payload fields"], eventRows),
-    "",
-    "### Settlement Vocabulary",
-    "",
-    `Settlement id: \`${settlement.settlementId}\``,
-    "",
-    `Anchor kinds: ${list(settlement.anchorKinds ?? [])}`,
-    "",
-    `Rejection kinds: ${list(settlement.rejectionKinds ?? [])}`,
-    "",
-    "### Authority Requirements",
-    "",
-    (boundary.effectAuthorityContracts ?? []).length === 0
-      ? "None."
-      : table(
-          ["Authority", "Class", "Required materials"],
-          authorityRows(boundary.effectAuthorityContracts),
-        ),
-    "",
-    "### Material Requirements",
-    "",
-    (boundary.materialRequirements ?? []).length === 0
-      ? "None."
-      : table(["Slot", "Kind", "Required", "Details"], materialRows(boundary.materialRequirements)),
-    "",
-  ];
-
-  return sections.join("\n");
-};
-
-const renderNamespace = ({ pkg, file, exportName, namespace, events }) => {
-  const eventRows = events.map((eventKind) => [`\`${eventKind}\``, "namespace-only", "None."]);
-  return [
-    `## ${namespace.ownerId}`,
-    "",
-    `Source package: \`${pkg.name}\``,
-    "",
-    `Source file: \`${file}\``,
-    "",
-    `Export: \`${exportName}\``,
-    "",
-    `Prefix: ${list(namespace.kindPrefixes)}`,
-    "",
-    "Roles: `reader`",
-    "",
-    "### Event Kinds",
-    "",
-    eventRows.length === 0 ? "None." : table(["Event kind", "Claim", "Payload fields"], eventRows),
-    "",
-    "### Settlement Vocabulary",
-    "",
-    "None.",
-    "",
-    "### Authority Requirements",
-    "",
-    "None.",
-    "",
-    "### Material Requirements",
-    "",
-    "None.",
-    "",
-  ].join("\n");
-};
-
-const renderReference = (carriers) => {
-  const summaryRows = carriers.map((entry) => [
-    `\`${entry.kind === "carrier" ? entry.carrier.ownerId : entry.namespace.ownerId}\``,
-    `\`${entry.pkg.name}\``,
-    entry.kind === "carrier" ? `\`${entry.carrier.prefix}\`` : list(entry.namespace.kindPrefixes),
-    String(
-      entry.kind === "carrier"
-        ? Object.keys(entry.carrier.boundaryContract.events).length
-        : entry.events.length,
-    ),
-    entry.kind === "carrier" ? list(entry.carrier.boundaryContract.roles ?? []) : "`reader`",
-  ]);
-
-  const sections = carriers.map((entry) =>
-    entry.kind === "carrier" ? renderCarrier(entry) : renderNamespace(entry),
-  );
-
-  return [
-    "# Carrier Reference",
-    "",
-    generatedNotice,
-    "",
-    "Generated from live `defineCarrier` declarations. Package docs explain intent; this page owns event, schema, settlement, authority, and material reference facts.",
-    "",
-    "## Carriers",
-    "",
-    table(["Owner", "Source package", "Prefix", "Events", "Roles"], summaryRows),
-    "",
-    ...sections,
-  ].join("\n");
-};
-
-const carriers = await discoverCarriers();
-const expected = `${renderReference(carriers).replace(/\s+$/u, "")}\n`;
-const targetPath = path.join(root, target);
-const carrierReferenceSourceFacts = {
-  kind: "source-set",
-  ref: "docs.generate-carrier-reference.source-facts",
-  sources: [{ kind: "carrier-declaration", ref: "defineCarrier declarations under packages/**" }],
-};
-const projection = defineProjectionSpec({
-  id: `docs.generate-carrier-reference:${target}`,
-  version: 1,
-  source: carrierReferenceSourceFacts,
-  project: (output, ctx) => ctx.ok(output),
-});
-const sink = {
-  id: target,
-  read: () =>
-    fs.existsSync(targetPath)
-      ? { _tag: "found", output: fs.readFileSync(targetPath, "utf8") }
-      : { _tag: "missing" },
-  write: (output) => {
-    fs.mkdirSync(path.dirname(targetPath), { recursive: true });
-    fs.writeFileSync(targetPath, output);
-  },
-  equals: (actual, projected) => actual === projected,
-};
-
-if (check) {
-  const result = await checkProjectionSink(projection, expected, sink);
-  if (result._tag === "projection_failed") {
-    failures.push(`${target} projection failed: ${result.result.reason}`);
-  } else if (result._tag === "stale") {
-    failures.push(`${target} is stale`);
-  }
-} else {
-  const result = await runProjectionSink(projection, expected, sink);
-  if (result._tag === "projection_failed") {
-    failures.push(`${target} projection failed: ${result.result.reason}`);
-  }
-}
-
-if (failures.length > 0) {
-  console.error(failures.join("\n"));
-  process.exit(1);
-}
-
-console.log(`${check ? "checked" : "generated"} carrier reference for ${carriers.length} carriers`);