@cosmicdrift/kumiko-guards 0.397.0 → 0.399.0

package/src/_lib/agent-docs-feature-imports.ts

@@ -0,0 +1,175 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join, relative, sep } from "node:path";
+import {
+  type FunctionDeclaration,
+  Node,
+  type Project,
+  type SourceFile,
+  SyntaxKind,
+} from "ts-morph";
+import { exportedFunctions, importedVariable } from "./agent-docs-module-walk";
+import { compareCodepoint, isRecord, parseJsonFile } from "./agent-docs-shared";
+
+const PACKAGES_DIR = "packages";
+const FEATURE_FACTORY_RE = /^create\w*Feature$/;
+const SOURCE_FILE_RE = /\.tsx?$/;
+const TEST_PATH_RE = /(__tests__|\.test\.tsx?$|\.d\.ts$)/;
+
+export type FeatureImport =
+  | {
+      readonly kind: "resolved";
+      readonly importPath: string;
+      readonly exportNames: readonly string[];
+      readonly call?: string;
+    }
+  | { readonly kind: "unresolved" };
+
+type FeatureDefinitionSite = {
+  readonly packageDir: string;
+  readonly srcSegment: string;
+  readonly factoryName: string | undefined;
+};
+
+function sourceFilesUnder(dir: string): string[] {
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir, { recursive: true, encoding: "utf-8" })
+    .filter((rel) => SOURCE_FILE_RE.test(rel) && !TEST_PATH_RE.test(rel))
+    .map((rel) => join(dir, rel));
+}
+
+function stringValue(project: Project, node: Node | undefined): string | undefined {
+  if (node === undefined) return undefined;
+  if (Node.isStringLiteral(node)) return node.getLiteralValue();
+  if (Node.isAsExpression(node)) return stringValue(project, node.getExpression());
+  if (!Node.isIdentifier(node)) return undefined;
+  const file = node.getSourceFile();
+  const name = node.getText();
+  const declaration = file.getVariableDeclaration(name) ?? importedVariable(project, file, name);
+  return stringValue(project, declaration?.getInitializer());
+}
+
+function isTopLevelVariable(node: Node): boolean {
+  return (
+    Node.isVariableDeclaration(node) && Node.isSourceFile(node.getVariableStatement()?.getParent())
+  );
+}
+
+// The factory is the enclosing function, or a module-level constant; a local
+// `const feature = defineFeature(…)` inside a factory is not one.
+function enclosingFactoryName(node: Node): string | undefined {
+  const owner =
+    node.getFirstAncestor(Node.isFunctionDeclaration) ?? node.getFirstAncestor(isTopLevelVariable);
+  return Node.isFunctionDeclaration(owner) || Node.isVariableDeclaration(owner)
+    ? owner.getName()
+    : undefined;
+}
+
+// Where each feature name is passed to defineFeature in a package source. A
+// name defined only outside packages/ (a sample app) has no import path.
+function featureDefinitionSites(
+  repoRoot: string,
+  project: Project,
+): ReadonlyMap<string, FeatureDefinitionSite[]> {
+  const sites = new Map<string, FeatureDefinitionSite[]>();
+  for (const packageName of readdirSync(join(repoRoot, PACKAGES_DIR)).sort(compareCodepoint)) {
+    const packageDir = `${PACKAGES_DIR}/${packageName}`;
+    const srcDir = join(repoRoot, packageDir, "src");
+    for (const path of sourceFilesUnder(srcDir)) {
+      if (!readFileSync(path, "utf-8").includes("defineFeature(")) continue;
+      const calls = project
+        .addSourceFileAtPath(path)
+        .getDescendantsOfKind(SyntaxKind.CallExpression)
+        .filter((call) => call.getExpression().getText() === "defineFeature");
+      for (const call of calls) {
+        const name = stringValue(project, call.getArguments()[0]);
+        if (name === undefined) continue;
+        const srcSegment = relative(srcDir, path).split(sep)[0] ?? "";
+        const list = sites.get(name) ?? [];
+        list.push({ packageDir, srcSegment, factoryName: enclosingFactoryName(call) });
+        sites.set(name, list);
+      }
+    }
+  }
+  return sites;
+}
+
+type ExportEntry = { readonly importPath: string; readonly file: SourceFile };
+
+function exportEntries(repoRoot: string, project: Project, site: FeatureDefinitionSite) {
+  const rel = `${site.packageDir}/package.json`;
+  const parsed = parseJsonFile(rel, readFileSync(join(repoRoot, rel), "utf-8"));
+  const name = isRecord(parsed) ? parsed["name"] : undefined;
+  const exportsField = isRecord(parsed) ? parsed["exports"] : undefined;
+  if (typeof name !== "string" || !isRecord(exportsField)) return [];
+  const entries: ExportEntry[] = [];
+  for (const subpath of [`./${site.srcSegment.replace(SOURCE_FILE_RE, "")}`, "."]) {
+    const target = exportsField[subpath];
+    const path = isRecord(target) ? target["types"] : target;
+    if (typeof path !== "string" || !SOURCE_FILE_RE.test(path)) continue;
+    entries.push({
+      importPath: subpath === "." ? name : `${name}/${subpath.slice(2)}`,
+      file: project.addSourceFileAtPath(join(repoRoot, site.packageDir, path)),
+    });
+  }
+  return entries;
+}
+
+// `options.<flag> === true ? <factory>() : …` inside an exported factory means
+// that factory with `{ <flag>: true }` builds the feature.
+function flagCall(name: string, fn: FunctionDeclaration, factoryName: string): string | undefined {
+  const body = (fn.getImplementation() ?? fn).getBody();
+  for (const conditional of body?.getDescendantsOfKind(SyntaxKind.ConditionalExpression) ?? []) {
+    const whenTrue = conditional.getWhenTrue();
+    const condition = conditional.getCondition();
+    if (!Node.isCallExpression(whenTrue) || whenTrue.getExpression().getText() !== factoryName) {
+      continue;
+    }
+    if (!Node.isBinaryExpression(condition) || condition.getRight().getText() !== "true") continue;
+    const flag = condition.getLeft();
+    if (Node.isPropertyAccessExpression(flag)) return `${name}({ ${flag.getName()}: true })`;
+  }
+  return undefined;
+}
+
+function resolveAt(
+  project: Project,
+  entry: ExportEntry,
+  factoryName: string | undefined,
+): FeatureImport | undefined {
+  const functions = exportedFunctions(project, entry.file);
+  const importPath = entry.importPath;
+  if (factoryName !== undefined && functions.has(factoryName)) {
+    return { kind: "resolved", importPath, exportNames: [factoryName] };
+  }
+  const factories = [...functions.keys()]
+    .filter((name) => FEATURE_FACTORY_RE.test(name))
+    .sort(compareCodepoint);
+  for (const name of factories) {
+    const fn = functions.get(name);
+    const call =
+      fn === undefined || factoryName === undefined ? undefined : flagCall(name, fn, factoryName);
+    if (call !== undefined) return { kind: "resolved", importPath, exportNames: [name], call };
+  }
+  return factories.length === 0
+    ? undefined
+    : { kind: "resolved", importPath, exportNames: factories };
+}
+
+// undefined: the feature is not defined in a package, so an app cannot import it.
+export function createFeatureImportResolver(
+  repoRoot: string,
+  project: Project,
+): (featureName: string) => FeatureImport | undefined {
+  const sites = featureDefinitionSites(repoRoot, project);
+  return (featureName) => {
+    const candidates = sites.get(featureName);
+    if (candidates === undefined) return undefined;
+    for (const site of candidates) {
+      for (const entry of exportEntries(repoRoot, project, site)) {
+        const resolved = resolveAt(project, entry, site.factoryName);
+        if (resolved !== undefined) return resolved;
+      }
+    }
+    return { kind: "unresolved" };
+  };
+}

package/src/_lib/agent-docs-features.ts

@@ -0,0 +1,196 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { Project } from "ts-morph";
+import { createFeatureImportResolver, type FeatureImport } from "./agent-docs-feature-imports";
+import {
+  codeList,
+  compareCodepoint,
+  finishFile,
+  firstSentence,
+  isRecord,
+  parseJsonFile,
+  table,
+} from "./agent-docs-shared";
+
+const FEATURE_MANIFEST_REL = "samples/apps/use-all-bundled/feature-manifest.json";
+
+type ManifestConfigKeyDoc = {
+  readonly key: string;
+  readonly type: string;
+  readonly scope: string;
+  readonly default: string | number | boolean | null;
+};
+
+type ManifestSecretDoc = {
+  readonly qualifiedName: string;
+  readonly scope: string;
+  readonly label: string | null;
+};
+
+type ManifestFeatureDoc = {
+  readonly name: string;
+  readonly description: string | null;
+  readonly category: string | null;
+  readonly requires: readonly string[];
+  readonly optionalRequires: readonly string[];
+  readonly exposesApis: readonly string[];
+  readonly usesApis: readonly string[];
+  readonly configKeys: readonly ManifestConfigKeyDoc[];
+  readonly secrets: readonly ManifestSecretDoc[];
+};
+
+function isStringArray(value: unknown): value is readonly string[] {
+  return Array.isArray(value) && value.every((item) => typeof item === "string");
+}
+
+function isNullableString(value: unknown): value is string | null {
+  return value === null || typeof value === "string";
+}
+
+function isConfigKeyDoc(value: unknown): value is ManifestConfigKeyDoc {
+  if (!isRecord(value)) return false;
+  const fallback = value["default"];
+  return (
+    typeof value["key"] === "string" &&
+    typeof value["type"] === "string" &&
+    typeof value["scope"] === "string" &&
+    (fallback === null ||
+      typeof fallback === "string" ||
+      typeof fallback === "number" ||
+      typeof fallback === "boolean")
+  );
+}
+
+function isSecretDoc(value: unknown): value is ManifestSecretDoc {
+  return (
+    isRecord(value) &&
+    typeof value["qualifiedName"] === "string" &&
+    typeof value["scope"] === "string" &&
+    isNullableString(value["label"])
+  );
+}
+
+function parseFeatureDoc(value: unknown): ManifestFeatureDoc | undefined {
+  if (!isRecord(value) || typeof value["name"] !== "string") return undefined;
+  const description = value["description"];
+  const configKeys = value["configKeys"];
+  const secrets = value["secrets"];
+  const uiHints = value["uiHints"];
+  const category = isRecord(uiHints) ? uiHints["category"] : undefined;
+  if (
+    !isNullableString(description) ||
+    !isStringArray(value["requires"]) ||
+    !isStringArray(value["optionalRequires"]) ||
+    !isStringArray(value["exposesApis"]) ||
+    !isStringArray(value["usesApis"]) ||
+    !Array.isArray(configKeys) ||
+    !configKeys.every(isConfigKeyDoc) ||
+    !Array.isArray(secrets) ||
+    !secrets.every(isSecretDoc)
+  ) {
+    return undefined;
+  }
+  return {
+    name: value["name"],
+    description,
+    category: typeof category === "string" ? category : null,
+    requires: value["requires"],
+    optionalRequires: value["optionalRequires"],
+    exposesApis: value["exposesApis"],
+    usesApis: value["usesApis"],
+    configKeys,
+    secrets,
+  };
+}
+
+function readFeatureManifest(repoRoot: string): readonly ManifestFeatureDoc[] {
+  const raw = readFileSync(join(repoRoot, FEATURE_MANIFEST_REL), "utf-8");
+  const parsed = parseJsonFile(FEATURE_MANIFEST_REL, raw);
+  const features = isRecord(parsed) ? parsed["features"] : undefined;
+  if (!Array.isArray(features)) {
+    throw new Error(`${FEATURE_MANIFEST_REL}: "features" must be an array`);
+  }
+  const docs = features.map((entry, index) => {
+    const feature = parseFeatureDoc(entry);
+    if (feature === undefined) {
+      throw new Error(`${FEATURE_MANIFEST_REL}: features[${index}] has an unexpected shape`);
+    }
+    return feature;
+  });
+  return docs.sort((left, right) => compareCodepoint(left.name, right.name));
+}
+
+function renderFeatureSection(feature: ManifestFeatureDoc): string {
+  const parts = [`## ${feature.name}`];
+  if (feature.description !== null) parts.push(feature.description.replace(/\s+/g, " ").trim());
+  if (feature.category !== null) parts.push(`Category: ${feature.category}`);
+  if (feature.requires.length > 0) parts.push(`Requires: ${codeList(feature.requires)}`);
+  if (feature.optionalRequires.length > 0) {
+    parts.push(`Optional requires: ${codeList(feature.optionalRequires)}`);
+  }
+  if (feature.configKeys.length > 0) {
+    const rows = feature.configKeys.map((configKey) => [
+      `\`${configKey.key}\``,
+      configKey.type,
+      configKey.scope,
+      configKey.default === null ? "" : `\`${String(configKey.default)}\``,
+    ]);
+    parts.push(`Config keys:\n\n${table(["Key", "Type", "Scope", "Default"], rows)}`);
+  }
+  if (feature.secrets.length > 0) {
+    const rows = feature.secrets.map((secret) => [
+      `\`${secret.qualifiedName}\``,
+      secret.scope,
+      secret.label ?? "",
+    ]);
+    parts.push(`Secrets:\n\n${table(["Secret", "Scope", "Label"], rows)}`);
+  }
+  if (feature.exposesApis.length > 0) parts.push(`Exposes APIs: ${codeList(feature.exposesApis)}`);
+  if (feature.usesApis.length > 0) parts.push(`Uses APIs: ${codeList(feature.usesApis)}`);
+  return parts.join("\n\n");
+}
+
+export type FeatureDocs = {
+  readonly features: string;
+  readonly featuresIndex: string;
+};
+
+function importLine(found: FeatureImport): string {
+  if (found.kind === "unresolved") return "Import: no factory found in the package exports";
+  const statement = `\`import { ${found.exportNames.join(", ")} } from "${found.importPath}"\``;
+  return found.call === undefined ? statement : `${statement}, call \`${found.call}\``;
+}
+
+function renderIndexEntry(feature: ManifestFeatureDoc, found: FeatureImport): string {
+  const purpose = feature.description === null ? "" : ` ${firstSentence(feature.description)}`;
+  const details = [importLine(found)];
+  if (feature.requires.length > 0) details.push(`requires ${codeList(feature.requires)}`);
+  const unset = feature.configKeys.filter((configKey) => configKey.default === null);
+  if (unset.length > 0) {
+    details.push(`config without default ${codeList(unset.map((configKey) => configKey.key))}`);
+  }
+  if (feature.secrets.length > 0) {
+    details.push(`secrets ${codeList(feature.secrets.map((secret) => secret.qualifiedName))}`);
+  }
+  return `- \`${feature.name}\`:${purpose}\n  ${details.join("; ")}`;
+}
+
+const INDEX_INTRO =
+  "One entry per feature a package ships: purpose, import of its factory, required features, config keys without a default and secrets. Factory options: `api/` or the feature's types. Details: `features.md`.";
+
+export function renderFeatureDocs(repoRoot: string, project: Project): FeatureDocs {
+  const manifest = readFeatureManifest(repoRoot);
+  const sections = manifest.map(renderFeatureSection);
+  const resolveImport = createFeatureImportResolver(repoRoot, project);
+  const entries = manifest.flatMap((feature) => {
+    const found = resolveImport(feature.name);
+    return found === undefined ? [] : [renderIndexEntry(feature, found)];
+  });
+  return {
+    features: finishFile(FEATURE_MANIFEST_REL, `# Bundled features\n\n${sections.join("\n\n")}`),
+    featuresIndex: finishFile(
+      FEATURE_MANIFEST_REL,
+      `# Bundled features index\n\n${INDEX_INTRO}\n\n${entries.join("\n")}`,
+    ),
+  };
+}

package/src/_lib/agent-docs-module-walk.ts

@@ -0,0 +1,103 @@
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import type {
+  ExportDeclaration,
+  FunctionDeclaration,
+  ImportDeclaration,
+  Project,
+  SourceFile,
+  VariableDeclaration,
+} from "ts-morph";
+
+// Syntactic module walk over relative specifiers. Asking ts-morph to resolve a
+// specifier rebuilds the program after every added file, which made one
+// generator run take seconds per package; package specifiers stay unresolved.
+export function relativeModuleFile(
+  project: Project,
+  declaration: ImportDeclaration | ExportDeclaration,
+): SourceFile | undefined {
+  const specifier = declaration.getModuleSpecifierValue();
+  if (specifier === undefined || !specifier.startsWith(".")) return undefined;
+  const base = join(dirname(declaration.getSourceFile().getFilePath()), specifier);
+  const withoutJs = base.replace(/\.js$/, "");
+  const candidates = [base, `${withoutJs}.ts`, `${withoutJs}.tsx`, join(base, "index.ts")];
+  const path = candidates.find((candidate) => /\.tsx?$/.test(candidate) && existsSync(candidate));
+  if (path === undefined) return undefined;
+  return project.getSourceFile(path) ?? project.addSourceFileAtPath(path);
+}
+
+function reExportTargets(
+  project: Project,
+  file: SourceFile,
+  name: string,
+): { target: SourceFile; name: string }[] {
+  const targets: { target: SourceFile; name: string }[] = [];
+  for (const declaration of file.getExportDeclarations()) {
+    const target = relativeModuleFile(project, declaration);
+    if (declaration.isTypeOnly() || target === undefined) continue;
+    const named = declaration.getNamedExports();
+    if (named.length === 0) targets.push({ target, name });
+    for (const spec of named) {
+      const exported = (spec.getAliasNode() ?? spec.getNameNode()).getText();
+      if (exported === name) targets.push({ target, name: spec.getName() });
+    }
+  }
+  return targets;
+}
+
+export function exportedVariable(
+  project: Project,
+  file: SourceFile,
+  name: string,
+  seen = new Set<SourceFile>(),
+): VariableDeclaration | undefined {
+  seen.add(file);
+  const local = file.getVariableDeclaration(name);
+  if (local !== undefined) return local;
+  for (const hop of reExportTargets(project, file, name)) {
+    if (seen.has(hop.target)) continue;
+    const found = exportedVariable(project, hop.target, hop.name, seen);
+    if (found !== undefined) return found;
+  }
+  return undefined;
+}
+
+export function importedVariable(
+  project: Project,
+  file: SourceFile,
+  name: string,
+): VariableDeclaration | undefined {
+  const declaration = file
+    .getImportDeclarations()
+    .find((candidate) => candidate.getNamedImports().some((spec) => spec.getName() === name));
+  const spec = declaration?.getNamedImports().find((candidate) => candidate.getName() === name);
+  const target = declaration === undefined ? undefined : relativeModuleFile(project, declaration);
+  if (spec === undefined || target === undefined) return undefined;
+  const original = spec.getNameNode().getText();
+  return exportedVariable(project, target, original);
+}
+
+export function exportedFunctions(
+  project: Project,
+  file: SourceFile,
+  seen = new Set<SourceFile>(),
+): Map<string, FunctionDeclaration> {
+  seen.add(file);
+  const found = new Map<string, FunctionDeclaration>();
+  for (const fn of file.getFunctions()) {
+    const name = fn.getName();
+    if (fn.isExported() && name !== undefined) found.set(name, fn);
+  }
+  for (const declaration of file.getExportDeclarations()) {
+    const target = relativeModuleFile(project, declaration);
+    if (declaration.isTypeOnly() || target === undefined || seen.has(target)) continue;
+    const targetFunctions = exportedFunctions(project, target, seen);
+    const named = declaration.getNamedExports();
+    if (named.length === 0) for (const [name, fn] of targetFunctions) found.set(name, fn);
+    for (const spec of named) {
+      const fn = targetFunctions.get(spec.getName());
+      if (fn !== undefined) found.set((spec.getAliasNode() ?? spec.getNameNode()).getText(), fn);
+    }
+  }
+  return found;
+}

package/src/_lib/agent-docs-shared.ts

@@ -0,0 +1,76 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { Project, ts } from "ts-morph";
+
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export function parseJsonFile(relPath: string, raw: string): unknown {
+  try {
+    return JSON.parse(raw);
+  } catch (error) {
+    throw new Error(`${relPath}: invalid JSON`, { cause: error });
+  }
+}
+
+export function compareCodepoint(left: string, right: string): number {
+  if (left < right) return -1;
+  return left > right ? 1 : 0;
+}
+
+function generatedHeader(source: string): string {
+  return `<!-- Generated by \`bun run gen:agent-docs\` from ${source}. Do not edit. -->`;
+}
+
+export function finishFile(source: string, body: string): string {
+  const normalized = body.replace(/\r\n/g, "\n").trim();
+  return `${generatedHeader(source)}\n\n${normalized}\n`;
+}
+
+function escapeCell(text: string): string {
+  return text.replace(/\s+/g, " ").trim().replace(/\|/g, "\\|");
+}
+
+export function table(headers: readonly string[], rows: readonly (readonly string[])[]): string {
+  const lines = [
+    `| ${headers.join(" | ")} |`,
+    `| ${headers.map(() => "---").join(" | ")} |`,
+    ...rows.map((row) => `| ${row.map(escapeCell).join(" | ")} |`),
+  ];
+  return lines.join("\n");
+}
+
+export function codeList(values: readonly string[]): string {
+  return values.map((value) => `\`${value}\``).join(", ");
+}
+
+const FIRST_SENTENCE_RE = /^(.+?(?<!\be\.g|\bi\.e)[.!?])(?:\s|$)/;
+
+export function firstSentence(text: string): string {
+  const flattened = text.replace(/\s+/g, " ").trim();
+  return FIRST_SENTENCE_RE.exec(flattened)?.[1] ?? flattened;
+}
+
+const FALLBACK_COMPILER_OPTIONS: ts.CompilerOptions = {
+  module: ts.ModuleKind.ESNext,
+  moduleResolution: ts.ModuleResolutionKind.Bundler,
+  target: ts.ScriptTarget.ES2022,
+  jsx: ts.JsxEmit.ReactJSX,
+  allowImportingTsExtensions: true,
+  noEmit: true,
+};
+
+// The repo tsconfig carries the workspace `paths`, so re-exports from sibling
+// packages resolve to their sources instead of a published dist.
+export function createAgentDocsProject(repoRoot: string): Project {
+  const tsConfigFilePath = join(repoRoot, "tsconfig.json");
+  if (!existsSync(tsConfigFilePath)) {
+    return new Project({ compilerOptions: FALLBACK_COMPILER_OPTIONS });
+  }
+  return new Project({
+    tsConfigFilePath,
+    skipAddingFilesFromTsConfig: true,
+    compilerOptions: { jsx: ts.JsxEmit.ReactJSX, noEmit: true },
+  });
+}