@cosmicdrift/kumiko-guards 0.398.0 → 0.400.0

package/src/_lib/agent-docs.ts

@@ -9,201 +9,26 @@ import {
   writeFileSync,
 } from "node:fs";
 import { dirname, join } from "node:path";
-import { type ExportedDeclarations, type JSDocableNode, Node, Project, ts } from "ts-morph";
+import { type ExportedDeclarations, type JSDocableNode, Node, type Project } from "ts-morph";
+import { renderApiDocs } from "./agent-docs-api";
+import { renderFeatureDocs } from "./agent-docs-features";
+import {
+  compareCodepoint,
+  createAgentDocsProject,
+  finishFile,
+  firstSentence,
+  isRecord,
+  parseJsonFile,
+  table,
+} from "./agent-docs-shared";
 
 export const AGENT_DOCS_DIR = "packages/framework/agents";
 
-const FEATURE_MANIFEST_REL = "samples/apps/use-all-bundled/feature-manifest.json";
 const RENDERER_WEB_INDEX_REL = "packages/renderer/src/web/index.ts";
 const RECIPES_REL = "samples/recipes";
 const RECIPE_SLUG_RE = /^[a-z0-9-]+$/;
 const SOURCE_EXTENSIONS = [".ts", ".tsx"];
 
-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 isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
-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 parseJsonFile(relPath: string, raw: string): unknown {
-  try {
-    return JSON.parse(raw);
-  } catch (error) {
-    throw new Error(`${relPath}: invalid JSON`, { cause: error });
-  }
-}
-
-function parseFeatureManifest(raw: string): readonly ManifestFeatureDoc[] {
-  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`);
-  }
-  return 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;
-  });
-}
-
-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. -->`;
-}
-
-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, "\\|");
-}
-
-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");
-}
-
-function codeList(values: readonly string[]): string {
-  return values.map((value) => `\`${value}\``).join(", ");
-}
-
-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");
-}
-
-function renderFeatures(repoRoot: string): string {
-  const raw = readFileSync(join(repoRoot, FEATURE_MANIFEST_REL), "utf-8");
-  const sections = [...parseFeatureManifest(raw)]
-    .sort((left, right) => compareCodepoint(left.name, right.name))
-    .map(renderFeatureSection);
-  return finishFile(FEATURE_MANIFEST_REL, `# Bundled features\n\n${sections.join("\n\n")}`);
-}
-
 type WidgetGroup = "Components" | "Hooks" | "Functions" | "Constants" | "Classes";
 const WIDGET_GROUP_ORDER: readonly WidgetGroup[] = [
   "Components",
@@ -241,13 +66,6 @@ function jsDocOwnerOf(declaration: ExportedDeclarations): JSDocableNode | undefi
   return Node.isJSDocable(declaration) ? declaration : undefined;
 }
 
-const FIRST_SENTENCE_RE = /^(.+?(?<!\be\.g|\bi\.e)[.!?])(?:\s|$)/;
-
-function firstSentence(text: string): string {
-  const flattened = text.replace(/\s+/g, " ").trim();
-  return FIRST_SENTENCE_RE.exec(flattened)?.[1] ?? flattened;
-}
-
 function descriptionOf(declarations: readonly ExportedDeclarations[]): string {
   for (const declaration of declarations) {
     const docs = jsDocOwnerOf(declaration)?.getJsDocs() ?? [];
@@ -257,15 +75,7 @@ function descriptionOf(declarations: readonly ExportedDeclarations[]): string {
   return "";
 }
 
-function renderWidgets(repoRoot: string): string {
-  const project = new Project({
-    compilerOptions: {
-      module: ts.ModuleKind.ESNext,
-      moduleResolution: ts.ModuleResolutionKind.Bundler,
-      target: ts.ScriptTarget.ES2022,
-      jsx: ts.JsxEmit.ReactJSX,
-    },
-  });
+function renderWidgets(repoRoot: string, project: Project): string {
   const indexFile = project.addSourceFileAtPath(join(repoRoot, RENDERER_WEB_INDEX_REL));
   const grouped = new Map<WidgetGroup, [string, string][]>(
     WIDGET_GROUP_ORDER.map((group) => [group, []]),
@@ -381,9 +191,13 @@ function renderRecipe(recipe: Recipe): string {
 
 export function renderAgentDocs(repoRoot: string): ReadonlyMap<string, string> {
   const recipes = readRecipes(repoRoot);
+  const project = createAgentDocsProject(repoRoot);
+  const featureDocs = renderFeatureDocs(repoRoot, project);
   const files = new Map<string, string>();
-  files.set("features.md", renderFeatures(repoRoot));
-  files.set("widgets.md", renderWidgets(repoRoot));
+  files.set("features-index.md", featureDocs.featuresIndex);
+  files.set("features.md", featureDocs.features);
+  files.set("widgets.md", renderWidgets(repoRoot, project));
+  for (const [rel, content] of renderApiDocs(repoRoot, project)) files.set(rel, content);
   files.set("examples.md", renderExamplesIndex(recipes));
   for (const recipe of recipes) files.set(`examples/${recipe.slug}.md`, renderRecipe(recipe));
   return files;

package/src/guard-agent-docs-drift.ts

@@ -2,7 +2,8 @@
 /**
  * Guard: the generated agent docs under `packages/framework/agents/` must
  * match what `bun run gen:agent-docs` renders from the current sources
- * (feature manifest, renderer web exports, sample recipes), and every
+ * (feature manifest, public entry-point signatures, renderer web exports,
+ * sample recipes), and every
  * `agents/<file>.md` path the hand-written `packages/framework/AGENTS.md`
  * points at must exist in that generated set.
  *

package/src/guard-screen-conventions.ts

@@ -48,6 +48,14 @@ function stringLiteralValue(obj: ObjectLiteralExpression, name: string): string
   return init?.isKind(SyntaxKind.StringLiteral) ? init.getLiteralValue() : undefined;
 }
 
+function booleanLiteralValue(obj: ObjectLiteralExpression, name: string): boolean | undefined {
+  const prop = obj.getProperty(name);
+  if (!prop?.isKind(SyntaxKind.PropertyAssignment)) return undefined;
+  const init = prop.getInitializer();
+  if (init?.isKind(SyntaxKind.TrueKeyword)) return true;
+  return init?.isKind(SyntaxKind.FalseKeyword) ? false : undefined;
+}
+
 function hasDeclaredProperty(obj: ObjectLiteralExpression, name: string): boolean {
   const prop = obj.getProperty(name);
   if (!prop?.isKind(SyntaxKind.PropertyAssignment)) return false;
@@ -55,7 +63,7 @@ function hasDeclaredProperty(obj: ObjectLiteralExpression, name: string): boolea
   return init !== undefined && init.getKind() !== SyntaxKind.UndefinedKeyword;
 }
 
-// R2: a relatedList section with neither rowClick nor rowActions renders a
+// R2: a relatedList section with neither rowClick, rowActions nor readOnly renders a
 // list nobody can act on.
 function checkRelatedListSections(
   root: ObjectLiteralExpression,
@@ -65,6 +73,7 @@ function checkRelatedListSections(
   for (const obj of root.getDescendantsOfKind(SyntaxKind.ObjectLiteralExpression)) {
     if (stringLiteralValue(obj, "kind") !== "relatedList") continue;
     if (hasIgnoreTag(obj, IGNORE_TAG)) continue;
+    if (booleanLiteralValue(obj, "readOnly") === true) continue;
     if (hasDeclaredProperty(obj, "rowClick") || hasDeclaredProperty(obj, "rowActions")) continue;
     violations.push({
       file: sf.getFilePath(),
@@ -107,7 +116,7 @@ export const guard: AstGuard = {
   name: "Screen-Conventions Guard",
   scan: SCAN,
   hint:
-    "relatedList sections need `rowClick` or `rowActions`; a rowAction label " +
+    "relatedList sections need `rowClick`, `rowActions` or `readOnly: true`; a rowAction label " +
     'must not end in ".action.edit" ' +
     'when the `id` is not "edit". ' +
     `Justified exception: // ${IGNORE_TAG} <reason>`,