argsbarg 6.1.2 → 6.1.3

package/src/cli-tool/schemagen/cleanup.ts

@@ -3,9 +3,9 @@ Remove stale __generated__/ directories and files after schemagen runs.
 */
 
 import { existsSync, readdirSync, rmSync, statSync } from "node:fs";
-import { dirname, join, relative } from "node:path";
+import { join, relative } from "node:path";
 import type { SchemaRoot } from "./discover-schema-roots.ts";
-import { GENERATED_DIR, schemaJsonBasename, TYPES_FILE } from "./names.ts";
+import { GENERATED_DIR, schemaJsonBasename } from "./names.ts";
 
 function listGeneratedDirs(srcDir: string, projectRoot: string, out: string[]): void {
   for (const ent of readdirSync(srcDir)) {
@@ -22,11 +22,11 @@ function listGeneratedDirs(srcDir: string, projectRoot: string, out: string[]):
   }
 }
 
-/** Drop orphan `__generated__/` trees and JSON files for removed schema kinds. */
+/** Drop orphan `__generated__/` trees and JSON files for removed schema roots. */
 export function cleanStaleGenerated(
   projectRoot: string,
   srcDir: string,
-  activeBySchemaFile: Map<string, SchemaRoot[]>,
+  activeByGeneratedDir: Map<string, SchemaRoot[]>,
 ): void {
   const srcPath = join(projectRoot, srcDir);
   if (!existsSync(srcPath)) {
@@ -38,8 +38,7 @@ export function cleanStaleGenerated(
 
   for (const relGeneratedDir of generatedDirs) {
     const generatedDir = join(projectRoot, relGeneratedDir);
-    const relTypesPath = relative(projectRoot, join(dirname(generatedDir), TYPES_FILE));
-    const roots = existsSync(join(projectRoot, relTypesPath)) ? (activeBySchemaFile.get(relTypesPath) ?? []) : [];
+    const roots = activeByGeneratedDir.get(generatedDir) ?? [];
 
     if (roots.length === 0) {
       rmSync(generatedDir, { recursive: true, force: true });
@@ -47,7 +46,7 @@ export function cleanStaleGenerated(
       continue;
     }
 
-    const keep = new Set(["index.ts", ...roots.map((root) => schemaJsonBasename(root.kind))]);
+    const keep = new Set(["index.ts", ...roots.map((root) => schemaJsonBasename(root.typeName))]);
     for (const ent of readdirSync(generatedDir)) {
       if (keep.has(ent)) {
         continue;

package/src/cli-tool/schemagen/discover-schema-roots.ts

@@ -1,160 +1,111 @@
 /*
-Discovers schema roots in types.ts files via configType / inputType / outputType exports.
+Discovers schema roots via @sg JSDoc markers on export interface/type declarations.
 */
 
 import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
-import { dirname, join, relative } from "node:path";
-import { TYPES_FILE } from "./names.ts";
+import { join, relative } from "node:path";
 
-export type SchemaRootKind = "config" | "input" | "output";
+/** Directories to scan relative to project root. */
+const SEARCH_DIRS = ["src"] as const;
 
-export type SchemaRole = "configType" | "inputType" | "outputType";
+/** Directory names skipped during walk (any depth). */
+const EXCLUDE_DIRS = ["node_modules", "__generated__"] as const;
+
+/** File basename patterns skipped (basename match only). */
+const EXCLUDE_FILE_PATTERNS = [/\.test\.ts$/];
+
+const SG_JSDOC_RE = /\/\*\*[\s\S]*?@sg[\s\S]*?\*\//g;
+const EXPORT_DECL_RE = /^export\s+(interface|type)\s+(\w+)/;
 
 export interface SchemaRoot {
-  kind: SchemaRootKind;
   typeName: string;
-  /** Path to types.ts relative to project root (anchors __generated__/ output). */
+  /** Path to the file containing `@sg`, relative to project root (anchors `__generated__/`). */
   path: string;
-  /** Path to the file that defines `typeName` (defaults to `path`). */
+  /** Path to the file that defines `typeName` (same as `path` for `@sg`). */
   sourcePath: string;
 }
 
-const ROLE_EXPORT_RE = /export\s+type\s+(configType|inputType|outputType)\s*=\s*(\w+)/g;
-const HAS_ROLE_EXPORT_RE = /export\s+type\s+(configType|inputType|outputType)\s*=/;
-const IMPORT_RE = /import\s+(?:type\s+)?\{([^}]+)\}\s+from\s+["']([^"']+)["']/g;
-
-const ROLE_TO_KIND: Record<SchemaRole, SchemaRootKind> = {
-  configType: "config",
-  inputType: "input",
-  outputType: "output",
-};
+function shouldIncludeFile(basename: string): boolean {
+  if (!basename.endsWith(".ts") || basename.endsWith(".d.ts")) {
+    return false;
+  }
+  return !EXCLUDE_FILE_PATTERNS.some((pattern) => pattern.test(basename));
+}
 
-function listTypesManifestFiles(srcDir: string, baseDir: string, out: string[]): void {
-  for (const ent of readdirSync(srcDir)) {
-    const full = join(srcDir, ent);
+function walkDir(dir: string, baseDir: string, out: string[]): void {
+  for (const ent of readdirSync(dir)) {
+    if ((EXCLUDE_DIRS as readonly string[]).includes(ent)) {
+      continue;
+    }
+    const full = join(dir, ent);
     const st = statSync(full);
     if (st.isDirectory()) {
-      listTypesManifestFiles(full, baseDir, out);
+      walkDir(full, baseDir, out);
       continue;
     }
-    if (ent !== TYPES_FILE) {
+    if (!shouldIncludeFile(ent)) {
       continue;
     }
-    const text = readFileSync(full, "utf8");
-    if (HAS_ROLE_EXPORT_RE.test(text)) {
-      out.push(relative(baseDir, full));
-    }
-  }
-}
-
-/** True when `typeName` is declared in this file (not a schemagen role alias). */
-function isTypeDefinedInFile(text: string, typeName: string): boolean {
-  if (new RegExp(`export\\s+interface\\s+${typeName}\\b`).test(text)) {
-    return true;
-  }
-  if (new RegExp(`export\\s+type\\s+${typeName}\\s*=`).test(text)) {
-    return !["configType", "inputType", "outputType"].includes(typeName);
+    out.push(relative(baseDir, full));
   }
-  return false;
 }
 
-function parseLocalTypeImports(text: string): Map<string, string> {
-  const imports = new Map<string, string>();
-  for (const match of text.matchAll(IMPORT_RE)) {
-    const names = match[1];
-    const from = match[2];
-    if (!names || !from?.startsWith(".")) {
+function listScannableFiles(projectRoot: string): string[] {
+  const files: string[] = [];
+  for (const searchDir of SEARCH_DIRS) {
+    const abs = join(projectRoot, searchDir);
+    if (!existsSync(abs)) {
       continue;
     }
-    for (const part of names.split(",")) {
-      const trimmed = part.trim();
-      const nameMatch = trimmed.match(/^(?:type\s+)?(\w+)(?:\s+as\s+(\w+))?$/);
-      if (!nameMatch?.[1]) {
-        continue;
-      }
-      const localName = nameMatch[2] ?? nameMatch[1];
-      imports.set(localName, from);
-    }
+    walkDir(abs, projectRoot, files);
   }
-  return imports;
+  return files.sort();
 }
 
-function resolveModuleFile(manifestFile: string, specifier: string): string | null {
-  const base = join(dirname(manifestFile), specifier);
-  const candidates = [base, `${base}.ts`, join(base, "index.ts")];
-  for (const candidate of candidates) {
-    if (existsSync(candidate)) {
-      return candidate;
-    }
+function parseTypeNameAfterSgBlock(text: string, blockEndIndex: number, relPath: string): string {
+  const rest = text.slice(blockEndIndex);
+  const sameLine = rest.match(/^([^\n]*)/)?.[1] ?? "";
+  if (sameLine.trim().length > 0) {
+    throw new Error(
+      `${relPath}: @sg JSDoc must be immediately followed by export interface/type (same-line export not supported)`,
+    );
   }
-  return null;
-}
 
-/** Resolve a role alias to the module that defines `typeName`, when imported from a relative path. */
-function resolveAliasedTypeSource(
-  projectRoot: string,
-  manifestRelPath: string,
-  manifestText: string,
-  typeName: string,
-): string | null {
-  const manifestFile = join(projectRoot, manifestRelPath);
-  const specifier = parseLocalTypeImports(manifestText).get(typeName);
-  if (!specifier) {
-    return null;
-  }
-  const moduleFile = resolveModuleFile(manifestFile, specifier);
-  if (!moduleFile) {
-    return null;
-  }
-  const moduleText = readFileSync(moduleFile, "utf8");
-  if (!isTypeDefinedInFile(moduleText, typeName)) {
-    return null;
-  }
-  return relative(projectRoot, moduleFile);
-}
-
-function discoverFromFile(projectRoot: string, path: string, text: string): SchemaRoot[] {
-  const rolesSeen = new Set<SchemaRole>();
-  const roots: SchemaRoot[] = [];
-
-  for (const match of text.matchAll(ROLE_EXPORT_RE)) {
-    const role = match[1] as SchemaRole | undefined;
-    const typeName = match[2];
-    if (!role || !typeName) {
-      continue;
+  const lines = rest.split("\n").slice(1);
+  for (const line of lines) {
+    if (line.trim() === "") {
+      throw new Error(`${relPath}: @sg JSDoc must be immediately followed by export interface/type`);
     }
-    if (rolesSeen.has(role)) {
-      throw new Error(`${path}: duplicate export type ${role}`);
+    const match = line.match(EXPORT_DECL_RE);
+    if (match?.[2]) {
+      return match[2];
     }
-    rolesSeen.add(role);
+    throw new Error(`${relPath}: @sg JSDoc must be immediately followed by export interface/type`);
+  }
 
-    let sourcePath = path;
-    if (!isTypeDefinedInFile(text, typeName)) {
-      const resolved = resolveAliasedTypeSource(projectRoot, path, text, typeName);
-      if (!resolved) {
-        continue;
-      }
-      sourcePath = resolved;
-    }
+  throw new Error(`${relPath}: @sg JSDoc must be immediately followed by export interface/type`);
+}
 
-    roots.push({ kind: ROLE_TO_KIND[role], typeName, path, sourcePath });
+function discoverFromFile(relPath: string, text: string): SchemaRoot[] {
+  const roots: SchemaRoot[] = [];
+  for (const match of text.matchAll(SG_JSDOC_RE)) {
+    const index = match.index ?? 0;
+    const blockEnd = index + match[0].length;
+    const typeName = parseTypeNameAfterSgBlock(text, blockEnd, relPath);
+    roots.push({ typeName, path: relPath, sourcePath: relPath });
   }
-
   return roots;
 }
 
-/** Find all schema roots under `srcDir` in `types.ts` files with role exports. */
-export function discoverSchemaRoots(projectRoot: string, srcDir = "src"): SchemaRoot[] {
-  const srcPath = join(projectRoot, srcDir);
-  const files: string[] = [];
-  listTypesManifestFiles(srcPath, projectRoot, files);
-
+/** Find all `@sg` schema roots under `SEARCH_DIRS`. */
+export function discoverSchemaRoots(projectRoot: string, _srcDir = "src"): SchemaRoot[] {
+  const files = listScannableFiles(projectRoot);
   const roots: SchemaRoot[] = [];
   const typeOwners = new Map<string, string>();
 
-  for (const relPath of files.sort()) {
+  for (const relPath of files) {
     const text = readFileSync(join(projectRoot, relPath), "utf8");
-    for (const root of discoverFromFile(projectRoot, relPath, text)) {
+    for (const root of discoverFromFile(relPath, text)) {
       const prev = typeOwners.get(root.typeName);
       if (prev) {
         throw new Error(`${relPath}: duplicate schema root type ${root.typeName} (already declared in ${prev})`);
@@ -164,10 +115,5 @@ export function discoverSchemaRoots(projectRoot: string, srcDir = "src"): Schema
     }
   }
 
-  const configRoots = roots.filter((r) => r.kind === "config");
-  if (configRoots.length > 1) {
-    throw new Error(`multiple config schema roots: ${configRoots.map((r) => `${r.typeName} (${r.path})`).join(", ")}`);
-  }
-
   return roots;
 }

package/src/cli-tool/schemagen/index.ts

@@ -1,3 +1,3 @@
-export { discoverSchemaRoots, type SchemaRoot, type SchemaRootKind } from "./discover-schema-roots.ts";
-export { GENERATED_DIR, schemaExportName, schemaJsonBasename, TYPES_FILE } from "./names.ts";
+export { discoverSchemaRoots, type SchemaRoot } from "./discover-schema-roots.ts";
+export { GENERATED_DIR, schemaExportName, schemaJsonBasename } from "./names.ts";
 export { type RunSchemagenOptions, type RunSchemagenResult, runSchemagen } from "./run.ts";

package/src/cli-tool/schemagen/names.ts

@@ -1,22 +1,17 @@
-import type { SchemaRootKind } from "./discover-schema-roots.ts";
-
-/** Directory name for generated schema artifacts (next to `types.ts`). */
+/** Directory name for generated schema artifacts (colocated with `@sg` source files). */
 export const GENERATED_DIR = "__generated__";
 
-/** TypeScript schemagen manifest filename under `src/`. */
-export const TYPES_FILE = "types.ts";
-
-/** JSON basename for a schema root kind (`outputSchema.json`, etc.). */
-export function schemaJsonBasename(kind: SchemaRootKind): string {
-  return `${kind}Schema.json`;
+/** JSON basename for a schema root (`RenderJsonInputSchema.json`, etc.). */
+export function schemaJsonBasename(typeName: string): string {
+  return `${typeName}Schema.json`;
 }
 
 /** Export const name wired on leaves or `program.appConfig`. */
-export function schemaExportName(kind: SchemaRootKind): string {
-  return `${kind}Schema`;
+export function schemaExportName(typeName: string): string {
+  return `${typeName}Schema`;
 }
 
 /** Safe import binding for a schema JSON basename. */
-export function schemaJsonImportVar(kind: SchemaRootKind): string {
-  return `${kind}SchemaJson`;
+export function schemaJsonImportVar(typeName: string): string {
+  return `${typeName}SchemaJson`;
 }

package/src/cli-tool/schemagen/run.ts

@@ -6,24 +6,20 @@ import { mkdirSync, writeFileSync } from "node:fs";
 import { dirname, join, relative } from "node:path";
 import { createGenerator } from "ts-json-schema-generator";
 import { cleanStaleGenerated } from "./cleanup.ts";
-import { discoverSchemaRoots, type SchemaRoot, type SchemaRootKind } from "./discover-schema-roots.ts";
+import { discoverSchemaRoots, type SchemaRoot } from "./discover-schema-roots.ts";
 import { GENERATED_DIR, schemaExportName, schemaJsonBasename, schemaJsonImportVar } from "./names.ts";
 
-const KIND_ORDER: SchemaRootKind[] = ["config", "input", "output"];
-
 export interface RunSchemagenOptions {
   /** Project root (default: `process.cwd()`). */
   projectRoot?: string;
-  /** Source tree directory relative to project root (default: `src`). */
+  /** Source tree directory relative to project root (default: `src`). Unused; kept for API compat. */
   srcDir?: string;
   /** Path to tsconfig relative to project root (default: `tsconfig.json`). */
   tsconfig?: string;
 }
 
 export interface RunSchemagenResult {
-  configRoots: number;
-  inputRoots: number;
-  outputRoots: number;
+  schemas: number;
 }
 
 function resolveTsconfig(projectRoot: string, tsconfig: string): string {
@@ -35,6 +31,10 @@ function resolveTsconfig(projectRoot: string, tsconfig: string): string {
   }
 }
 
+function generatedDirForRoot(projectRoot: string, root: SchemaRoot): string {
+  return join(dirname(join(projectRoot, root.path)), GENERATED_DIR);
+}
+
 function generateJson(projectRoot: string, tsconfigPath: string, root: SchemaRoot): Record<string, unknown> {
   const typeFile = join(projectRoot, root.sourcePath);
   const generator = createGenerator({
@@ -44,27 +44,25 @@ function generateJson(projectRoot: string, tsconfigPath: string, root: SchemaRoo
     topRef: false,
     skipTypeCheck: false,
     jsDoc: "extended",
-    additionalProperties: root.kind === "config" ? false : undefined,
+    additionalProperties: false,
   });
   const schema = generator.createSchema(root.typeName) as Record<string, unknown>;
-  if (root.kind === "config") {
-    schema.additionalProperties = false;
-  }
+  schema.additionalProperties = false;
   return schema;
 }
 
 function writeGeneratedIndex(generatedDir: string, roots: SchemaRoot[]): void {
-  const sorted = [...roots].sort((left, right) => KIND_ORDER.indexOf(left.kind) - KIND_ORDER.indexOf(right.kind));
+  const sorted = [...roots].sort((left, right) => left.typeName.localeCompare(right.typeName));
   const lines = ["// Auto-generated by argsbarg schemagen — do not edit by hand.", ""];
   for (const root of sorted) {
-    lines.push(`import ${schemaJsonImportVar(root.kind)} from "./${schemaJsonBasename(root.kind)}";`);
+    lines.push(`import ${schemaJsonImportVar(root.typeName)} from "./${schemaJsonBasename(root.typeName)}";`);
   }
   if (sorted.length > 0) {
     lines.push("");
   }
   for (const root of sorted) {
     lines.push(
-      `export const ${schemaExportName(root.kind)} = ${schemaJsonImportVar(root.kind)} as Record<string, unknown>;`,
+      `export const ${schemaExportName(root.typeName)} = ${schemaJsonImportVar(root.typeName)} as Record<string, unknown>;`,
     );
     lines.push("");
   }
@@ -78,32 +76,27 @@ export function runSchemagen(options: RunSchemagenOptions = {}): RunSchemagenRes
   const tsconfigPath = resolveTsconfig(projectRoot, options.tsconfig ?? "tsconfig.json");
 
   const roots = discoverSchemaRoots(projectRoot, srcDir);
-  const bySchemaFile = new Map<string, SchemaRoot[]>();
+  const byGeneratedDir = new Map<string, SchemaRoot[]>();
 
   for (const root of roots) {
     const schema = generateJson(projectRoot, tsconfigPath, root);
-    const generatedDir = join(dirname(join(projectRoot, root.path)), GENERATED_DIR);
+    const generatedDir = generatedDirForRoot(projectRoot, root);
     mkdirSync(generatedDir, { recursive: true });
-    const jsonPath = join(generatedDir, schemaJsonBasename(root.kind));
+    const jsonPath = join(generatedDir, schemaJsonBasename(root.typeName));
     writeFileSync(jsonPath, `${JSON.stringify(schema, null, 2)}\n`);
     console.log(`wrote ${relative(projectRoot, jsonPath)} (${root.typeName})`);
 
-    const list = bySchemaFile.get(root.path) ?? [];
+    const list = byGeneratedDir.get(generatedDir) ?? [];
     list.push(root);
-    bySchemaFile.set(root.path, list);
+    byGeneratedDir.set(generatedDir, list);
   }
 
-  for (const [relPath, fileRoots] of bySchemaFile) {
-    const generatedDir = join(dirname(join(projectRoot, relPath)), GENERATED_DIR);
-    writeGeneratedIndex(generatedDir, fileRoots);
+  for (const [generatedDir, dirRoots] of byGeneratedDir) {
+    writeGeneratedIndex(generatedDir, dirRoots);
     console.log(`wrote ${relative(projectRoot, join(generatedDir, "index.ts"))}`);
   }
 
-  cleanStaleGenerated(projectRoot, srcDir, bySchemaFile);
+  cleanStaleGenerated(projectRoot, srcDir, byGeneratedDir);
 
-  return {
-    configRoots: roots.filter((r) => r.kind === "config").length,
-    inputRoots: roots.filter((r) => r.kind === "input").length,
-    outputRoots: roots.filter((r) => r.kind === "output").length,
-  };
+  return { schemas: roots.length };
 }