lua-cli 3.42.0-beta.1 → 3.42.0-beta.3

package/scripts/generate-catalog.lib.ts

@@ -0,0 +1,813 @@
+/**
+ * U34 (LUA-1008) — the machine-readable platform catalogue (`catalog.json`), generated from source on a
+ * lua-cli release. Contract: `PlatformCatalog` in `@lua/shared-types` (`platform-catalog.types.ts`) and
+ * docs/agent-builder/wave2-contracts.md §U34.
+ *
+ * Pure functions only: every input (paths, the status manifest, the known flags, the clock, the CLI version)
+ * is a parameter, so the test drives it with fixtures. The CLI wrapper is `generate-catalog.ts`.
+ *
+ * Sources, all read through the TypeScript compiler API:
+ *  - SDK exports and their signatures: `src/api-exports.ts` (type checker);
+ *  - CLI commands, flags and command aliases: `src/cli/command-definitions.ts` (commander call chains);
+ *  - positional value aliases: `src/utils/aliases.ts` (`ALIAS_MAP`);
+ *  - primitives: exported classes whose constructor takes a `…Config`;
+ *  - limits: constants annotated `@catalogLimit <key> [unit]` anywhere under `src/`;
+ *  - feature status: the `catalog-status.json` manifest.
+ */
+import fs from 'fs';
+import path from 'path';
+import ts from 'typescript';
+import type {
+  PlatformCatalog,
+  PlatformCatalogArgumentValues,
+  PlatformCatalogCommand,
+  PlatformCatalogDiff,
+  PlatformCatalogFeature,
+  PlatformCatalogLimit,
+  PlatformCatalogSdkEntry,
+  PlatformFeatureStatus,
+} from '@lua/shared-types';
+
+/** Mirrors `PLATFORM_CATALOG_VERSION` (a type-only import keeps this file free of runtime workspace deps). */
+export const CATALOG_VERSION = 1 as const;
+
+const FEATURE_STATUSES: readonly PlatformFeatureStatus[] = ['ga', 'beta', 'flag'];
+
+export interface CatalogStatusManifest {
+  features: Record<
+    string,
+    { status: PlatformFeatureStatus; flag?: string; description?: string; sdk?: string[]; commands?: string[] }
+  >;
+}
+
+export interface GenerateCatalogInput {
+  /** The lua-cli package directory; `source` paths are relative to it. */
+  packageDir: string;
+  /** Package-relative paths (defaults are the real lua-cli layout). */
+  apiExportsFile?: string;
+  commandDefinitionsFile?: string;
+  aliasesFile?: string;
+  /** Directory scanned for `@catalogLimit` constants. */
+  limitsDir?: string;
+  /** The tsconfig whose options resolve the SDK program (default `<packageDir>/tsconfig.json`). */
+  tsconfigFile?: string;
+  manifest: CatalogStatusManifest;
+  /** Env flag names a `flag` feature may name without a warning (`WAVE2_FLAGS` + `WAVE2_REUSED_FLAGS`). */
+  knownFlags: readonly string[];
+  cliVersion: string;
+  now: Date;
+}
+
+export interface GenerateCatalogResult {
+  catalog: PlatformCatalog;
+  warnings: string[];
+}
+
+export class CatalogError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'CatalogError';
+  }
+}
+
+const toPosix = (p: string): string => p.split(path.sep).join('/');
+
+const byKey =
+  <T>(key: (t: T) => string) =>
+  (a: T, b: T): number =>
+    key(a) < key(b) ? -1 : key(a) > key(b) ? 1 : 0;
+
+export function generateCatalog(input: GenerateCatalogInput): GenerateCatalogResult {
+  const warnings: string[] = [];
+  const pkg = input.packageDir;
+  const apiExportsFile = path.resolve(pkg, input.apiExportsFile ?? 'src/api-exports.ts');
+  const commandsFile = path.resolve(pkg, input.commandDefinitionsFile ?? 'src/cli/command-definitions.ts');
+  const aliasesFile = path.resolve(pkg, input.aliasesFile ?? 'src/utils/aliases.ts');
+  const limitsDir = path.resolve(pkg, input.limitsDir ?? 'src');
+
+  const program = createProgram(path.resolve(pkg, input.tsconfigFile ?? 'tsconfig.json'), [
+    apiExportsFile,
+    commandsFile,
+    aliasesFile,
+  ]);
+  const checker = program.getTypeChecker();
+
+  const { sdk, primitives } = extractSdk(program, checker, apiExportsFile);
+  const commands = extractCommands(requireSourceFile(program, commandsFile));
+  const argumentValues = extractArgumentValues(requireSourceFile(program, aliasesFile), checker);
+  const limits = extractLimits(limitsDir, pkg);
+  const features = applyManifest(input.manifest, sdk, commands, input.knownFlags, warnings);
+
+  const catalog: PlatformCatalog = {
+    catalogVersion: CATALOG_VERSION,
+    cliVersion: input.cliVersion,
+    generatedAt: input.now.toISOString(),
+    sdk,
+    commands,
+    primitives,
+    limits,
+    features,
+    argumentValues,
+  };
+  return { catalog, warnings };
+}
+
+export function serializeCatalog(catalog: PlatformCatalog | PlatformCatalogDiff): string {
+  return `${JSON.stringify(catalog, null, 2)}\n`;
+}
+
+// ─── Program ───
+
+function createProgram(tsconfigFile: string, rootNames: string[]): ts.Program {
+  const read = ts.readConfigFile(tsconfigFile, ts.sys.readFile);
+  if (read.error) {
+    throw new CatalogError(
+      `cannot read ${tsconfigFile}: ${ts.flattenDiagnosticMessageText(read.error.messageText, '\n')}`
+    );
+  }
+  const parsed = ts.parseJsonConfigFileContent(read.config, ts.sys, path.dirname(tsconfigFile));
+  return ts.createProgram({ rootNames, options: { ...parsed.options, noEmit: true } });
+}
+
+function requireSourceFile(program: ts.Program, file: string): ts.SourceFile {
+  const sf = program.getSourceFile(file);
+  if (!sf) throw new CatalogError(`source file not found: ${file}`);
+  return sf;
+}
+
+// ─── SDK exports ───
+
+const FORMAT = ts.TypeFormatFlags.NoTruncation | ts.TypeFormatFlags.UseSingleQuotesForStringLiteralType;
+
+function extractSdk(
+  program: ts.Program,
+  checker: ts.TypeChecker,
+  entryFile: string
+): { sdk: PlatformCatalogSdkEntry[]; primitives: PlatformCatalog['primitives'] } {
+  const sf = requireSourceFile(program, entryFile);
+  // A missing or stale workspace build turns every imported type into `any` without an error of its own:
+  // refuse instead of publishing a catalogue of `any`s.
+  const unresolved = program
+    .getSemanticDiagnostics(sf)
+    .filter((d) => d.code === 2307 || d.code === 2305 || d.code === 2614);
+  if (unresolved.length > 0) {
+    const lines = unresolved.map((d) => ts.flattenDiagnosticMessageText(d.messageText, ' '));
+    throw new CatalogError(
+      `${path.basename(entryFile)} has unresolved imports (run \`pnpm run build:shared\` first):\n  ${lines.join('\n  ')}`
+    );
+  }
+  const moduleSymbol = checker.getSymbolAtLocation(sf);
+  if (!moduleSymbol) throw new CatalogError(`${entryFile} is not a module`);
+
+  const sdk: PlatformCatalogSdkEntry[] = [];
+  const primitives: PlatformCatalog['primitives'] = [];
+  for (const exported of checker.getExportsOfModule(moduleSymbol)) {
+    const symbol = exported.flags & ts.SymbolFlags.Alias ? checker.getAliasedSymbol(exported) : exported;
+    const name = exported.getName();
+    const kind = sdkKind(symbol);
+    if (!kind) continue;
+    const signature = stripImportQualifiers(sdkSignature(checker, symbol, kind, name, sf));
+    const entry: PlatformCatalogSdkEntry = { name, kind, signature };
+    const docs = firstParagraph(ts.displayPartsToString(symbol.getDocumentationComment(checker)));
+    if (docs) entry.docs = docs;
+    sdk.push(entry);
+    if (kind === 'class') {
+      const configType = primitiveConfigType(checker, symbol, sf);
+      if (configType) primitives.push({ name, configType });
+    }
+  }
+  sdk.sort(byKey((e) => e.name));
+  primitives.sort(byKey((p) => p.name));
+  return { sdk, primitives };
+}
+
+/**
+ * `import("/abs/path/dist/index").X` → `X`: the checker qualifies types it cannot name at the entry file with
+ * the declaring module's path, which differs per machine and would make every CI diff noisy.
+ */
+export function stripImportQualifiers(signature: string): string {
+  return signature.replace(/import\("[^"]*"\)\./g, '');
+}
+
+function sdkKind(symbol: ts.Symbol): PlatformCatalogSdkEntry['kind'] | undefined {
+  const f = symbol.flags;
+  if (f & ts.SymbolFlags.Class) return 'class';
+  if (f & ts.SymbolFlags.Function) return 'function';
+  if (f & (ts.SymbolFlags.Variable | ts.SymbolFlags.Enum)) return 'const';
+  if (f & ts.SymbolFlags.Module) return 'namespace';
+  if (f & ts.SymbolFlags.Interface) return 'interface';
+  if (f & ts.SymbolFlags.TypeAlias) return 'type';
+  return undefined;
+}
+
+function typeParamsText(symbol: ts.Symbol): string {
+  const decl = symbol.declarations?.find(
+    (d): d is ts.ClassDeclaration | ts.InterfaceDeclaration | ts.TypeAliasDeclaration | ts.FunctionDeclaration =>
+      ts.isClassDeclaration(d) ||
+      ts.isInterfaceDeclaration(d) ||
+      ts.isTypeAliasDeclaration(d) ||
+      ts.isFunctionDeclaration(d)
+  );
+  if (!decl?.typeParameters?.length) return '';
+  return `<${decl.typeParameters.map((p) => normalizeWs(p.getText())).join(', ')}>`;
+}
+
+function memberLines(checker: ts.TypeChecker, type: ts.Type, at: ts.Node): string[] {
+  const lines: string[] = [];
+  for (const sig of type.getCallSignatures()) lines.push(checker.signatureToString(sig, at, FORMAT));
+  for (const sig of type.getConstructSignatures()) lines.push(`new ${checker.signatureToString(sig, at, FORMAT)}`);
+  for (const info of checker.getIndexInfosOfType(type)) {
+    lines.push(
+      `[key: ${checker.typeToString(info.keyType, at, FORMAT)}]: ${checker.typeToString(info.type, at, FORMAT)}`
+    );
+  }
+  for (const prop of checker.getPropertiesOfType(type)) {
+    const decl = prop.valueDeclaration ?? prop.declarations?.[0];
+    if (decl && ts.canHaveModifiers(decl)) {
+      const mods = ts.getModifiers(decl) ?? [];
+      if (mods.some((m) => m.kind === ts.SyntaxKind.PrivateKeyword || m.kind === ts.SyntaxKind.ProtectedKeyword))
+        continue;
+    }
+    if (prop.getName().startsWith('#')) continue;
+    const optional = prop.flags & ts.SymbolFlags.Optional ? '?' : '';
+    const readonly =
+      decl && ts.getCombinedModifierFlags(decl as ts.Declaration) & ts.ModifierFlags.Readonly ? 'readonly ' : '';
+    lines.push(
+      `${readonly}${prop.getName()}${optional}: ${checker.typeToString(checker.getTypeOfSymbolAtLocation(prop, at), at, FORMAT)}`
+    );
+  }
+  return lines;
+}
+
+function sdkSignature(
+  checker: ts.TypeChecker,
+  symbol: ts.Symbol,
+  kind: PlatformCatalogSdkEntry['kind'],
+  name: string,
+  at: ts.SourceFile
+): string {
+  switch (kind) {
+    case 'function': {
+      const type = checker.getTypeOfSymbolAtLocation(symbol, at);
+      return type
+        .getCallSignatures()
+        .map((s) => `function ${name}${checker.signatureToString(s, at, FORMAT)}`)
+        .join('\n');
+    }
+    case 'const':
+      return `const ${name}: ${checker.typeToString(checker.getTypeOfSymbolAtLocation(symbol, at), at, FORMAT)}`;
+    case 'class': {
+      const staticType = checker.getTypeOfSymbolAtLocation(symbol, at);
+      const ctors = staticType.getConstructSignatures().map((s) => `new ${checker.signatureToString(s, at, FORMAT)}`);
+      const members = memberLines(checker, checker.getDeclaredTypeOfSymbol(symbol), at);
+      return `class ${name}${typeParamsText(symbol)} { ${[...new Set(ctors), ...members].join('; ')} }`;
+    }
+    case 'interface':
+      return `interface ${name}${typeParamsText(symbol)} { ${memberLines(checker, checker.getDeclaredTypeOfSymbol(symbol), at).join('; ')} }`;
+    case 'type': {
+      const decl = symbol.declarations?.find(ts.isTypeAliasDeclaration);
+      const expanded = checker.typeToString(
+        checker.getDeclaredTypeOfSymbol(symbol),
+        at,
+        FORMAT | ts.TypeFormatFlags.InTypeAlias
+      );
+      const body = expanded !== name || !decl ? expanded : normalizeWs(decl.type.getText());
+      return `type ${name}${typeParamsText(symbol)} = ${body}`;
+    }
+    case 'namespace':
+      return `namespace ${name}`;
+  }
+}
+
+function primitiveConfigType(checker: ts.TypeChecker, symbol: ts.Symbol, at: ts.SourceFile): string | undefined {
+  const staticType = checker.getTypeOfSymbolAtLocation(symbol, at);
+  for (const sig of staticType.getConstructSignatures()) {
+    const first = sig.getParameters()[0];
+    if (!first) continue;
+    const t = checker.getTypeOfSymbolAtLocation(first, at);
+    const typeName = (t.aliasSymbol ?? t.getSymbol())?.getName();
+    if (typeName && /Config$/.test(typeName)) return typeName;
+  }
+  return undefined;
+}
+
+function firstParagraph(text: string): string | undefined {
+  const para = text
+    .trim()
+    .split(/\n\s*\n/)[0]
+    ?.trim();
+  return para ? normalizeWs(para) : undefined;
+}
+
+function normalizeWs(text: string): string {
+  return text.replace(/\s+/g, ' ').trim();
+}
+
+// ─── Commands (commander call chains) ───
+
+interface ChainLink {
+  method: string;
+  args: ts.NodeArray<ts.Expression>;
+}
+
+/** Unwinds `a.b(x).c(y)` into its root expression and `[b(x), c(y)]`. */
+function flattenChain(call: ts.CallExpression): { root: ts.Expression; links: ChainLink[] } | undefined {
+  const links: ChainLink[] = [];
+  let expr: ts.Expression = call;
+  while (ts.isCallExpression(expr) && ts.isPropertyAccessExpression(expr.expression)) {
+    links.unshift({ method: expr.expression.name.text, args: expr.arguments });
+    expr = expr.expression.expression;
+  }
+  if (links.length === 0) return undefined;
+  return { root: expr, links };
+}
+
+function stringValue(node: ts.Expression | undefined): string | undefined {
+  if (!node) return undefined;
+  if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) return node.text;
+  if (ts.isBinaryExpression(node) && node.operatorToken.kind === ts.SyntaxKind.PlusToken) {
+    const l = stringValue(node.left);
+    const r = stringValue(node.right);
+    return l !== undefined && r !== undefined ? l + r : undefined;
+  }
+  if (ts.isParenthesizedExpression(node)) return stringValue(node.expression);
+  return undefined;
+}
+
+function parseCommandSpec(spec: string): { name: string; args: NonNullable<PlatformCatalogCommand['arguments']> } {
+  const [name, ...rest] = spec.trim().split(/\s+/);
+  return { name, args: rest.map(parseArgumentToken).filter((a): a is NonNullable<typeof a> => !!a) };
+}
+
+function parseArgumentToken(token: string): { name: string; required: boolean; variadic?: boolean } | undefined {
+  const m = /^([<[])(.+?)(\.\.\.)?([>\]])$/.exec(token);
+  if (!m) return undefined;
+  const arg: { name: string; required: boolean; variadic?: boolean } = { name: m[2], required: m[1] === '<' };
+  if (m[3]) arg.variadic = true;
+  return arg;
+}
+
+function parseFlags(
+  spec: string,
+  description: string | undefined,
+  required: boolean
+): PlatformCatalogCommand['flags'][number] {
+  const tokens = spec.split(/[\s,|]+/).filter(Boolean);
+  const longs = tokens.filter((t) => t.startsWith('--'));
+  const shorts = tokens.filter((t) => /^-[^-]/.test(t));
+  const takesValue = tokens.some((t) => /^[<[]/.test(t));
+  const name = longs[0] ?? shorts[0] ?? spec;
+  const aliases = [...longs.slice(1), ...shorts].filter((a) => a !== name);
+  const flag: PlatformCatalogCommand['flags'][number] = { name, takesValue };
+  if (aliases.length) flag.aliases = aliases;
+  if (description) flag.description = normalizeWs(description);
+  if (required) flag.required = true;
+  return flag;
+}
+
+export function extractCommands(sf: ts.SourceFile): PlatformCatalogCommand[] {
+  const commands = new Map<string, PlatformCatalogCommand>();
+  // Command variables are tracked per enclosing function (`const logsGroup = program.command('logs')`).
+  const scopes = new Map<ts.Node, Map<string, string[]>>();
+
+  const scopeOf = (node: ts.Node): ts.Node => {
+    let n: ts.Node | undefined = node.parent;
+    while (n && !ts.isFunctionLike(n) && !ts.isSourceFile(n)) n = n.parent;
+    return n ?? sf;
+  };
+  const lookup = (node: ts.Node, name: string): string[] | undefined => {
+    let scope: ts.Node | undefined = scopeOf(node);
+    while (scope) {
+      const hit = scopes.get(scope)?.get(name);
+      if (hit) return hit;
+      if (ts.isSourceFile(scope)) break;
+      scope = scopeOf(scope);
+    }
+    return undefined;
+  };
+  const ensure = (p: string[]): PlatformCatalogCommand => {
+    const key = p.join(' ');
+    let cmd = commands.get(key);
+    if (!cmd) {
+      cmd = { name: key, aliases: [], flags: [] };
+      commands.set(key, cmd);
+    }
+    return cmd;
+  };
+
+  const processChain = (call: ts.CallExpression): string[] | undefined => {
+    const chain = flattenChain(call);
+    if (!chain) return undefined;
+    const createsCommand = chain.links.some((l) => l.method === 'command' && stringValue(l.args[0]) !== undefined);
+    const rootPath = ts.isIdentifier(chain.root) ? lookup(call, chain.root.text) : undefined;
+    // Only commander chains: rooted at a known command variable, or creating a command (then an unknown
+    // root identifier is the `program` parameter).
+    if (!rootPath && !(createsCommand && ts.isIdentifier(chain.root))) return undefined;
+    let current: string[] = rootPath ?? [];
+    for (const link of chain.links) {
+      const first = link.args[0];
+      switch (link.method) {
+        case 'command': {
+          const spec = stringValue(first);
+          if (spec === undefined) return undefined;
+          const { name, args } = parseCommandSpec(spec);
+          current = [...current, name];
+          const cmd = ensure(current);
+          if (args.length) cmd.arguments = args;
+          break;
+        }
+        case 'description': {
+          const text = stringValue(first);
+          if (text !== undefined && current.length) ensure(current).description = normalizeWs(text);
+          break;
+        }
+        case 'alias': {
+          const alias = stringValue(first);
+          if (alias !== undefined && current.length) ensure(current).aliases.push(alias);
+          break;
+        }
+        case 'aliases': {
+          if (first && ts.isArrayLiteralExpression(first) && current.length) {
+            for (const el of first.elements) {
+              const alias = stringValue(el);
+              if (alias !== undefined) ensure(current).aliases.push(alias);
+            }
+          }
+          break;
+        }
+        case 'argument': {
+          const spec = stringValue(first);
+          const arg = spec ? parseArgumentToken(spec.trim()) : undefined;
+          if (arg && current.length) {
+            const cmd = ensure(current);
+            cmd.arguments = [...(cmd.arguments ?? []), arg];
+          }
+          break;
+        }
+        case 'option':
+        case 'requiredOption': {
+          const spec = stringValue(first);
+          if (spec !== undefined && current.length) {
+            ensure(current).flags.push(parseFlags(spec, stringValue(link.args[1]), link.method === 'requiredOption'));
+          }
+          break;
+        }
+        case 'addOption': {
+          if (first && ts.isNewExpression(first) && current.length) {
+            const spec = stringValue(first.arguments?.[0]);
+            if (spec !== undefined)
+              ensure(current).flags.push(parseFlags(spec, stringValue(first.arguments?.[1]), false));
+          }
+          break;
+        }
+        default:
+          break;
+      }
+    }
+    return current.length ? current : undefined;
+  };
+
+  const visit = (node: ts.Node): void => {
+    // The outermost call of a chain: its parent is not `.x` on it, and it is not the callee of another call.
+    if (ts.isCallExpression(node) && !ts.isPropertyAccessExpression(node.parent)) {
+      const result = processChain(node);
+      if (result && ts.isVariableDeclaration(node.parent) && ts.isIdentifier(node.parent.name)) {
+        const scope = scopeOf(node.parent);
+        if (!scopes.has(scope)) scopes.set(scope, new Map());
+        scopes.get(scope)!.set(node.parent.name.text, result);
+      }
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(sf);
+
+  const out = [...commands.values()];
+  for (const cmd of out) {
+    cmd.aliases = [...new Set(cmd.aliases)].sort();
+    const seen = new Set<string>();
+    cmd.flags = cmd.flags
+      .filter((f) => (seen.has(f.name) ? false : (seen.add(f.name), true)))
+      .sort(byKey((f) => f.name));
+  }
+  return out.sort(byKey((c) => c.name));
+}
+
+// ─── Positional value aliases (`ALIAS_MAP`) ───
+
+function stringsOfType(checker: ts.TypeChecker, type: ts.Type): string[] | undefined {
+  if (type.isStringLiteral()) return [type.value];
+  if (type.isUnion()) {
+    const parts = type.types.map((t) => stringsOfType(checker, t));
+    return parts.every((p): p is string[] => !!p) ? parts.flat() : undefined;
+  }
+  if (checker.isTupleType(type) || checker.isArrayType(type)) {
+    const args = checker.getTypeArguments(type as ts.TypeReference);
+    const parts = args.map((t) => stringsOfType(checker, t));
+    return parts.every((p): p is string[] => !!p) ? parts.flat() : undefined;
+  }
+  return undefined;
+}
+
+function evalStringArray(node: ts.Expression, checker: ts.TypeChecker): string[] | undefined {
+  if (!ts.isArrayLiteralExpression(node)) return stringsOfType(checker, checker.getTypeAtLocation(node));
+  const out: string[] = [];
+  for (const el of node.elements) {
+    const s = stringValue(el as ts.Expression);
+    if (s !== undefined) {
+      out.push(s);
+      continue;
+    }
+    const inner = ts.isSpreadElement(el) ? el.expression : el;
+    const resolved = stringsOfType(checker, checker.getTypeAtLocation(inner));
+    if (!resolved) return undefined;
+    out.push(...resolved);
+  }
+  return out;
+}
+
+function propertyKey(name: ts.PropertyName): string | undefined {
+  if (ts.isIdentifier(name) || ts.isStringLiteral(name) || ts.isNumericLiteral(name)) return name.text;
+  return undefined;
+}
+
+export function extractArgumentValues(
+  sf: ts.SourceFile,
+  checker: ts.TypeChecker,
+  mapName = 'ALIAS_MAP'
+): PlatformCatalogArgumentValues[] {
+  const decls = new Map<string, ts.Expression>();
+  const collect = (node: ts.Node): void => {
+    if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name) && node.initializer) {
+      decls.set(node.name.text, node.initializer);
+    }
+    ts.forEachChild(node, collect);
+  };
+  collect(sf);
+  const map = decls.get(mapName);
+  if (!map || !ts.isObjectLiteralExpression(map)) {
+    throw new CatalogError(`${sf.fileName}: no \`${mapName}\` object literal`);
+  }
+  const resolveObject = (expr: ts.Expression): ts.ObjectLiteralExpression | undefined => {
+    let e: ts.Expression = expr;
+    while (ts.isAsExpression(e) || ts.isSatisfiesExpression(e) || ts.isParenthesizedExpression(e)) e = e.expression;
+    if (ts.isObjectLiteralExpression(e)) return e;
+    if (ts.isIdentifier(e)) {
+      const target = decls.get(e.text);
+      return target ? resolveObject(target) : undefined;
+    }
+    return undefined;
+  };
+
+  const out: PlatformCatalogArgumentValues[] = [];
+  for (const prop of map.properties) {
+    if (!ts.isPropertyAssignment(prop) && !ts.isShorthandPropertyAssignment(prop)) continue;
+    const group = propertyKey(prop.name);
+    if (group === undefined) continue;
+    const entry = resolveObject(ts.isPropertyAssignment(prop) ? prop.initializer : prop.name);
+    if (!entry) throw new CatalogError(`${mapName}['${group}']: cannot resolve the entry statically`);
+    let canonical: string[] | undefined;
+    const aliases: Record<string, string> = {};
+    for (const field of entry.properties) {
+      if (!ts.isPropertyAssignment(field)) continue;
+      const key = propertyKey(field.name);
+      if (key === 'canonical') canonical = evalStringArray(field.initializer, checker);
+      if (key === 'aliases') {
+        let obj: ts.Expression = field.initializer;
+        let lower = false;
+        if (ts.isCallExpression(obj) && obj.arguments[0]) {
+          lower = ts.isIdentifier(obj.expression) && obj.expression.text === 'lowerKeys';
+          obj = obj.arguments[0];
+        }
+        const literal = resolveObject(obj);
+        if (!literal) throw new CatalogError(`${mapName}['${group}'].aliases: cannot resolve statically`);
+        for (const a of literal.properties) {
+          if (!ts.isPropertyAssignment(a)) continue;
+          const k = propertyKey(a.name);
+          const v = stringValue(a.initializer);
+          if (k !== undefined && v !== undefined) aliases[lower ? k.toLowerCase() : k] = v;
+        }
+      }
+    }
+    if (!canonical) throw new CatalogError(`${mapName}['${group}'].canonical: cannot resolve statically`);
+    out.push({ group, canonical: [...new Set(canonical)].sort(), aliases: sortRecord(aliases) });
+  }
+  return out.sort(byKey((g) => g.group));
+}
+
+function sortRecord<T>(rec: Record<string, T>): Record<string, T> {
+  return Object.fromEntries(Object.entries(rec).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)));
+}
+
+// ─── Limits (`@catalogLimit <key> [unit]`) ───
+
+function listTsFiles(dir: string): string[] {
+  const out: string[] = [];
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (entry.name === '__tests__' || entry.name === 'node_modules') continue;
+      out.push(...listTsFiles(full));
+    } else if (/\.ts$/.test(entry.name) && !/\.(d|spec|test)\.ts$/.test(entry.name)) {
+      out.push(full);
+    }
+  }
+  return out.sort();
+}
+
+/** Evaluates a constant initializer: number/string literals, unary minus, + - * / %, parens, `as const`. */
+export function evalConstant(node: ts.Expression): number | string | undefined {
+  if (ts.isNumericLiteral(node)) return Number(node.text.replace(/_/g, ''));
+  const s = stringValue(node);
+  if (s !== undefined) return s;
+  if (ts.isParenthesizedExpression(node) || ts.isAsExpression(node) || ts.isSatisfiesExpression(node)) {
+    return evalConstant(node.expression);
+  }
+  if (ts.isPrefixUnaryExpression(node) && node.operator === ts.SyntaxKind.MinusToken) {
+    const v = evalConstant(node.operand);
+    return typeof v === 'number' ? -v : undefined;
+  }
+  if (ts.isBinaryExpression(node)) {
+    const l = evalConstant(node.left);
+    const r = evalConstant(node.right);
+    if (typeof l !== 'number' || typeof r !== 'number') return undefined;
+    switch (node.operatorToken.kind) {
+      case ts.SyntaxKind.PlusToken:
+        return l + r;
+      case ts.SyntaxKind.MinusToken:
+        return l - r;
+      case ts.SyntaxKind.AsteriskToken:
+        return l * r;
+      case ts.SyntaxKind.SlashToken:
+        return l / r;
+      case ts.SyntaxKind.PercentToken:
+        return l % r;
+      default:
+        return undefined;
+    }
+  }
+  return undefined;
+}
+
+export function extractLimits(dir: string, packageDir: string): PlatformCatalogLimit[] {
+  const limits = new Map<string, PlatformCatalogLimit>();
+  for (const file of listTsFiles(dir)) {
+    const text = fs.readFileSync(file, 'utf8');
+    if (!text.includes('@catalogLimit')) continue;
+    const sf = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true);
+    const rel = toPosix(path.relative(packageDir, file));
+    const visit = (node: ts.Node): void => {
+      if (ts.isVariableDeclaration(node)) {
+        const tag = ts.getJSDocTags(node).find((t) => t.tagName.text === 'catalogLimit');
+        if (tag) {
+          const comment = typeof tag.comment === 'string' ? tag.comment : ts.getTextOfJSDocComment(tag.comment);
+          const [key, unit] = (comment ?? '').trim().split(/\s+/);
+          const where = `${rel}:${sf.getLineAndCharacterOfPosition(node.getStart()).line + 1}`;
+          if (!key) throw new CatalogError(`${where}: @catalogLimit needs a key (\`@catalogLimit <key> [unit]\`)`);
+          const value = node.initializer ? evalConstant(node.initializer) : undefined;
+          if (value === undefined)
+            throw new CatalogError(`${where}: @catalogLimit ${key}: initializer is not a constant`);
+          if (limits.has(key)) throw new CatalogError(`${where}: duplicate @catalogLimit key '${key}'`);
+          const limit: PlatformCatalogLimit = { key, value, source: rel };
+          if (unit) limit.unit = unit;
+          const jsDoc = ts.getJSDocCommentsAndTags(node).find(ts.isJSDoc);
+          const description = jsDoc?.comment
+            ? firstParagraph(ts.getTextOfJSDocComment(jsDoc.comment) ?? '')
+            : undefined;
+          if (description) limit.description = description;
+          limits.set(key, limit);
+        }
+      }
+      ts.forEachChild(node, visit);
+    };
+    visit(sf);
+  }
+  return [...limits.values()].sort(byKey((l) => l.key));
+}
+
+// ─── Feature status (`catalog-status.json`) ───
+
+export function applyManifest(
+  manifest: CatalogStatusManifest,
+  sdk: PlatformCatalogSdkEntry[],
+  commands: PlatformCatalogCommand[],
+  knownFlags: readonly string[],
+  warnings: string[]
+): PlatformCatalogFeature[] {
+  if (!manifest || typeof manifest.features !== 'object' || manifest.features === null) {
+    throw new CatalogError('catalog-status.json: `features` must be an object');
+  }
+  const sdkByName = new Map(sdk.map((e) => [e.name, e]));
+  const commandNames = new Set(commands.map((c) => c.name));
+  const known = new Set(knownFlags);
+  const errors: string[] = [];
+  const features: PlatformCatalogFeature[] = [];
+
+  for (const [key, spec] of Object.entries(manifest.features)) {
+    if (!FEATURE_STATUSES.includes(spec.status)) {
+      errors.push(
+        `feature '${key}': status must be one of ${FEATURE_STATUSES.join(', ')} (got '${String(spec.status)}')`
+      );
+      continue;
+    }
+    if (spec.status === 'flag' && !spec.flag) errors.push(`feature '${key}': status 'flag' needs a \`flag\``);
+    if (spec.status !== 'flag' && spec.flag) errors.push(`feature '${key}': \`flag\` is only valid with status 'flag'`);
+    if (spec.flag && !known.has(spec.flag)) {
+      warnings.push(`feature '${key}': flag '${spec.flag}' is not a WAVE2_FLAGS / WAVE2_REUSED_FLAGS name`);
+    }
+    const feature: PlatformCatalogFeature = { key, status: spec.status };
+    if (spec.flag) feature.flag = spec.flag;
+    if (spec.description) feature.description = normalizeWs(spec.description);
+    if (spec.sdk?.length) {
+      for (const name of spec.sdk) {
+        const entry = sdkByName.get(name);
+        if (!entry) {
+          errors.push(`feature '${key}': sdk export '${name}' does not exist in api-exports.ts`);
+          continue;
+        }
+        if (entry.status && entry.status !== spec.status) {
+          errors.push(`sdk export '${name}' is claimed by two features with different statuses`);
+        }
+        entry.status = spec.status;
+      }
+      feature.sdk = [...spec.sdk].sort();
+    }
+    if (spec.commands?.length) {
+      for (const name of spec.commands) {
+        if (!commandNames.has(name)) errors.push(`feature '${key}': command '${name}' does not exist`);
+      }
+      feature.commands = [...spec.commands].sort();
+    }
+    features.push(feature);
+  }
+  if (errors.length) throw new CatalogError(`catalog-status.json is invalid:\n  ${errors.join('\n  ')}`);
+  return features.sort(byKey((f) => f.key));
+}
+
+// ─── Diff ───
+
+function stableStringify(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(stableStringify).join(',')}]`;
+  if (value && typeof value === 'object') {
+    return `{${Object.keys(value as Record<string, unknown>)
+      .sort()
+      .filter((k) => (value as Record<string, unknown>)[k] !== undefined)
+      .map((k) => `${JSON.stringify(k)}:${stableStringify((value as Record<string, unknown>)[k])}`)
+      .join(',')}}`;
+  }
+  return JSON.stringify(value);
+}
+
+/** Flattens a catalogue into stable ids → comparable JSON. */
+export function catalogIndex(catalog: PlatformCatalog): Map<string, string> {
+  const index = new Map<string, string>();
+  for (const e of catalog.sdk ?? []) index.set(`sdk:${e.name}`, stableStringify(e));
+  for (const c of catalog.commands ?? []) {
+    const { flags, ...rest } = c;
+    index.set(`command:${c.name}`, stableStringify(rest));
+    for (const f of flags ?? []) index.set(`flag:${c.name} ${f.name}`, stableStringify(f));
+  }
+  for (const g of catalog.argumentValues ?? []) index.set(`args:${g.group}`, stableStringify(g));
+  for (const p of catalog.primitives ?? []) index.set(`primitive:${p.name}`, stableStringify(p));
+  for (const l of catalog.limits ?? []) index.set(`limit:${l.key}`, stableStringify(l));
+  for (const f of catalog.features ?? []) index.set(`feature:${f.key}`, stableStringify(f));
+  return index;
+}
+
+export function diffCatalogs(previous: PlatformCatalog | null, next: PlatformCatalog): PlatformCatalogDiff {
+  const before = previous ? catalogIndex(previous) : new Map<string, string>();
+  const after = catalogIndex(next);
+  const added: string[] = [];
+  const removed: string[] = [];
+  const changed: string[] = [];
+  for (const [id, value] of after) {
+    if (!before.has(id)) added.push(id);
+    else if (before.get(id) !== value) changed.push(id);
+  }
+  for (const id of before.keys()) if (!after.has(id)) removed.push(id);
+  return {
+    fromVersion: previous?.cliVersion ?? '',
+    toVersion: next.cliVersion,
+    added: added.sort(),
+    removed: removed.sort(),
+    changed: changed.sort(),
+  };
+}
+
+export function renderDiffMarkdown(diff: PlatformCatalogDiff, maxPerSection = 200): string {
+  const lines = [
+    `### Platform catalogue: ${diff.fromVersion ? `v${diff.fromVersion}` : '(no previous catalogue)'} → v${diff.toVersion}`,
+    '',
+    `${diff.added.length} added, ${diff.removed.length} removed, ${diff.changed.length} changed.`,
+  ];
+  for (const [title, ids] of [
+    ['Added', diff.added],
+    ['Removed', diff.removed],
+    ['Changed', diff.changed],
+  ] as const) {
+    if (!ids.length) continue;
+    lines.push('', `#### ${title}`, '');
+    for (const id of ids.slice(0, maxPerSection)) lines.push(`- \`${id}\``);
+    if (ids.length > maxPerSection) lines.push(`- … and ${ids.length - maxPerSection} more`);
+  }
+  return `${lines.join('\n')}\n`;
+}