joist-codegen 2.3.0-next.7 → 2.3.0-next.71

package/build/docs/markdown.js

@@ -1,241 +1,173 @@
-"use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.testing = void 0;
-exports.maybeReadMarkdownFile = maybeReadMarkdownFile;
-exports.parseMarkdownContent = parseMarkdownContent;
-exports.writeMarkdownDoc = writeMarkdownDoc;
-exports.updateMarkdownDoc = updateMarkdownDoc;
-exports.getMarkdownFilePath = getMarkdownFilePath;
-const fs_1 = require("fs");
-const path_1 = require("path");
-const prettier_1 = __importStar(require("prettier"));
+import { promises } from "fs";
+import { join } from "path";
+import prettier, { resolveConfig } from "prettier";
+//#region src/docs/markdown.ts
 /** Read and parse a .md file if it exists, returning undefined if it doesn't. */
 async function maybeReadMarkdownFile(filePath) {
-    try {
-        const content = await fs_1.promises.readFile(filePath, "utf-8");
-        return parseMarkdownContent(content);
-    }
-    catch {
-        return undefined;
-    }
+	try {
+		return parseMarkdownContent(await promises.readFile(filePath, "utf-8"));
+	} catch {
+		return;
+	}
 }
 /** Reads a basic `overview` and per-field docs out of md content. */
 function parseMarkdownContent(content) {
-    const lines = content.split("\n");
-    let currentSection = null;
-    let currentField = null;
-    const overviewLines = [];
-    const fields = {};
-    for (const line of lines) {
-        if (/^## Overview\s*$/.test(line)) {
-            currentSection = "overview";
-            currentField = null;
-            continue;
-        }
-        if (/^## Fields\s*$/.test(line)) {
-            currentSection = "fields";
-            currentField = null;
-            continue;
-        }
-        // Any other ## resets us out of known sections
-        if (/^## /.test(line)) {
-            currentSection = null;
-            currentField = null;
-            continue;
-        }
-        if (currentSection === "fields") {
-            const fieldMatch = line.match(/^### (\w+)\s*$/);
-            if (fieldMatch) {
-                currentField = fieldMatch[1];
-                fields[currentField] = [];
-                continue;
-            }
-        }
-        if (currentSection === "overview") {
-            overviewLines.push(line);
-        }
-        else if (currentSection === "fields" && currentField) {
-            fields[currentField].push(line);
-        }
-    }
-    return {
-        overview: trimBlankLines(overviewLines).join("\n"),
-        fields: Object.fromEntries(Object.entries(fields).map(([k, v]) => [k, trimBlankLines(v).join("\n")])),
-    };
+	const lines = content.split("\n");
+	let currentSection = null;
+	let currentField = null;
+	const overviewLines = [];
+	const fields = {};
+	for (const line of lines) {
+		if (/^## Overview\s*$/.test(line)) {
+			currentSection = "overview";
+			currentField = null;
+			continue;
+		}
+		if (/^## Fields\s*$/.test(line)) {
+			currentSection = "fields";
+			currentField = null;
+			continue;
+		}
+		if (line.startsWith("## ")) {
+			currentSection = null;
+			currentField = null;
+			continue;
+		}
+		if (currentSection === "fields") {
+			const fieldMatch = line.match(/^### (\w+)\s*$/);
+			if (fieldMatch) {
+				currentField = fieldMatch[1];
+				fields[currentField] = [];
+				continue;
+			}
+		}
+		if (currentSection === "overview") overviewLines.push(line);
+		else if (currentSection === "fields" && currentField) fields[currentField].push(line);
+	}
+	return {
+		overview: trimBlankLines(overviewLines).join("\n"),
+		fields: Object.fromEntries(Object.entries(fields).map(([k, v]) => [k, trimBlankLines(v).join("\n")]))
+	};
 }
 /** Create a new .md file from scratch (used only for initial backfill when no .md exists). */
 async function writeMarkdownDoc(filePath, overview, fields) {
-    const parts = [];
-    parts.push("## Overview");
-    parts.push(overview || "");
-    parts.push("");
-    if (fields && Object.keys(fields).length > 0) {
-        parts.push("## Fields");
-        parts.push("");
-        for (const [fieldName, fieldDoc] of Object.entries(fields)) {
-            parts.push(`### ${fieldName}`);
-            parts.push("");
-            parts.push(fieldDoc);
-            parts.push("");
-        }
-    }
-    const prettierConfig = await (0, prettier_1.resolveConfig)(filePath);
-    const content = await prettier_1.default.format(parts.join("\n"), {
-        ...prettierConfig,
-        parser: "markdown",
-        plugins: [],
-    });
-    await fs_1.promises.writeFile(filePath, content, "utf-8");
+	const parts = [];
+	parts.push("## Overview");
+	parts.push(overview || "");
+	parts.push("");
+	if (fields && Object.keys(fields).length > 0) {
+		parts.push("## Fields");
+		parts.push("");
+		for (const [fieldName, fieldDoc] of Object.entries(fields)) {
+			parts.push(`### ${fieldName}`);
+			parts.push("");
+			parts.push(fieldDoc);
+			parts.push("");
+		}
+	}
+	const prettierConfig = await resolveConfig(filePath);
+	const content = await prettier.format(parts.join("\n"), {
+		...prettierConfig,
+		parser: "markdown",
+		plugins: []
+	});
+	await promises.writeFile(filePath, content, "utf-8");
 }
 /**
- * Update an existing .md file, merging in new/changed content without stomping user content.
- * If the file doesn't exist, creates it from scratch.
- */
+* Update an existing .md file, merging in new/changed content without stomping user content.
+* If the file doesn't exist, creates it from scratch.
+*/
 async function updateMarkdownDoc(filePath, overview, fields) {
-    let existing = null;
-    try {
-        existing = await fs_1.promises.readFile(filePath, "utf-8");
-    }
-    catch {
-        // File doesn't exist
-    }
-    if (existing !== null) {
-        const updated = mergeMarkdownContent(existing, overview, fields);
-        if (updated !== existing) {
-            await fs_1.promises.writeFile(filePath, updated, "utf-8");
-        }
-    }
-    else {
-        await writeMarkdownDoc(filePath, overview ?? "", Object.keys(fields).length > 0 ? fields : undefined);
-    }
+	let existing = null;
+	try {
+		existing = await promises.readFile(filePath, "utf-8");
+	} catch {}
+	if (existing !== null) {
+		const updated = mergeMarkdownContent(existing, overview, fields);
+		if (updated !== existing) await promises.writeFile(filePath, updated, "utf-8");
+	} else await writeMarkdownDoc(filePath, overview ?? "", Object.keys(fields).length > 0 ? fields : void 0);
 }
 function getMarkdownFilePath(entitiesDir, entityName) {
-    return (0, path_1.join)(entitiesDir, `${entityName}.md`);
+	return join(entitiesDir, `${entityName}.md`);
 }
 /** Trim leading/trailing blank lines but preserve internal blank lines. */
 function trimBlankLines(lines) {
-    let start = 0;
-    while (start < lines.length && lines[start].trim() === "")
-        start++;
-    let end = lines.length - 1;
-    while (end >= start && lines[end].trim() === "")
-        end--;
-    return lines.slice(start, end + 1);
+	let start = 0;
+	while (start < lines.length && lines[start].trim() === "") start++;
+	let end = lines.length - 1;
+	while (end >= start && lines[end].trim() === "") end--;
+	return lines.slice(start, end + 1);
 }
 /**
- * Merge updates into an existing .md file, preserving all user content.
- *
- * - If `overview` is provided and the file has `## Overview`, replaces its body
- * - For each field in `fields`, if `### fieldName` exists, replaces its body;
- *   otherwise appends it to the `## Fields` section (creating the section if needed)
- * - All other content (custom sections, tables, etc.) is preserved verbatim
- */
+* Merge updates into an existing .md file, preserving all user content.
+*
+* - If `overview` is provided and the file has `## Overview`, replaces its body
+* - For each field in `fields`, if `### fieldName` exists, replaces its body;
+*   otherwise appends it to the `## Fields` section (creating the section if needed)
+* - All other content (custom sections, tables, etc.) is preserved verbatim
+*/
 function mergeMarkdownContent(existing, overview, fields) {
-    const lines = existing.split("\n");
-    const result = [];
-    // Track which fields we've already merged so we know what to append
-    const mergedFields = new Set();
-    let fieldsEndIndex = -1;
-    let i = 0;
-    while (i < lines.length) {
-        const line = lines[i];
-        // Replace ## Overview body
-        if (/^## Overview\s*$/.test(line) && overview !== undefined) {
-            result.push(line);
-            i++;
-            // Skip over old overview body (until next ## or EOF)
-            while (i < lines.length && !/^## /.test(lines[i]))
-                i++;
-            // Write new overview body
-            result.push(overview || "");
-            result.push("");
-            continue;
-        }
-        // Track where ## Fields section ends (for appending new fields)
-        if (/^## Fields\s*$/.test(line)) {
-            result.push(line);
-            i++;
-            // Process the fields section line by line
-            while (i < lines.length && !/^## /.test(lines[i])) {
-                const fieldMatch = lines[i].match(/^### (\w+)\s*$/);
-                if (fieldMatch && fieldMatch[1] in fields) {
-                    const fieldName = fieldMatch[1];
-                    mergedFields.add(fieldName);
-                    result.push(lines[i]); // ### fieldName
-                    i++;
-                    // Skip old field body (until next ### or ## or EOF)
-                    while (i < lines.length && !/^###? /.test(lines[i]) && !/^## /.test(lines[i]))
-                        i++;
-                    // Write new field body
-                    result.push("");
-                    result.push(fields[fieldName]);
-                    result.push("");
-                }
-                else {
-                    // Keep any line that isn't a field we're replacing (other ### fields, blank lines, etc.)
-                    result.push(lines[i]);
-                    i++;
-                }
-            }
-            fieldsEndIndex = result.length;
-            continue;
-        }
-        result.push(line);
-        i++;
-    }
-    // Append any fields that weren't already in the file
-    const newFields = Object.entries(fields).filter(([name]) => !mergedFields.has(name));
-    if (newFields.length > 0) {
-        if (fieldsEndIndex === -1) {
-            // No ## Fields section existed, create one
-            result.push("");
-            result.push("## Fields");
-            result.push("");
-            fieldsEndIndex = result.length;
-        }
-        const toInsert = [];
-        for (const [fieldName, fieldDoc] of newFields) {
-            toInsert.push(`### ${fieldName}`);
-            toInsert.push("");
-            toInsert.push(fieldDoc);
-            toInsert.push("");
-        }
-        result.splice(fieldsEndIndex, 0, ...toInsert);
-    }
-    return result.join("\n");
+	const lines = existing.split("\n");
+	const result = [];
+	const mergedFields = /* @__PURE__ */ new Set();
+	let fieldsEndIndex = -1;
+	let i = 0;
+	while (i < lines.length) {
+		const line = lines[i];
+		if (/^## Overview\s*$/.test(line) && overview !== void 0) {
+			result.push(line);
+			i++;
+			while (i < lines.length && !lines[i].startsWith("## ")) i++;
+			result.push(overview || "");
+			result.push("");
+			continue;
+		}
+		if (/^## Fields\s*$/.test(line)) {
+			result.push(line);
+			i++;
+			while (i < lines.length && !lines[i].startsWith("## ")) {
+				const fieldMatch = lines[i].match(/^### (\w+)\s*$/);
+				if (fieldMatch && fieldMatch[1] in fields) {
+					const fieldName = fieldMatch[1];
+					mergedFields.add(fieldName);
+					result.push(lines[i]);
+					i++;
+					while (i < lines.length && !/^###? /.test(lines[i]) && !lines[i].startsWith("## ")) i++;
+					result.push("");
+					result.push(fields[fieldName]);
+					result.push("");
+				} else {
+					result.push(lines[i]);
+					i++;
+				}
+			}
+			fieldsEndIndex = result.length;
+			continue;
+		}
+		result.push(line);
+		i++;
+	}
+	const newFields = Object.entries(fields).filter(([name]) => !mergedFields.has(name));
+	if (newFields.length > 0) {
+		if (fieldsEndIndex === -1) {
+			result.push("");
+			result.push("## Fields");
+			result.push("");
+			fieldsEndIndex = result.length;
+		}
+		const toInsert = [];
+		for (const [fieldName, fieldDoc] of newFields) {
+			toInsert.push(`### ${fieldName}`);
+			toInsert.push("");
+			toInsert.push(fieldDoc);
+			toInsert.push("");
+		}
+		result.splice(fieldsEndIndex, 0, ...toInsert);
+	}
+	return result.join("\n");
 }
-exports.testing = { mergeMarkdownContent };
+const testing = { mergeMarkdownContent };
+//#endregion
+export { getMarkdownFilePath, maybeReadMarkdownFile, parseMarkdownContent, testing, updateMarkdownDoc, writeMarkdownDoc };
+
 //# sourceMappingURL=markdown.js.map

package/build/docs/markdown.js.map

@@ -1 +1 @@
-{"version":3,"file":"markdown.js","sourceRoot":"","sources":["../../src/docs/markdown.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"markdown.js","names":["fs"],"sources":["../../src/docs/markdown.ts"],"sourcesContent":["import { promises as fs } from \"fs\";\nimport { join } from \"path\";\n\nimport prettier, { resolveConfig } from \"prettier\";\n\nexport interface ParsedDoc {\n  overview: string;\n  fields: Record<string, string>;\n}\n\n/** Read and parse a .md file if it exists, returning undefined if it doesn't. */\nexport async function maybeReadMarkdownFile(filePath: string): Promise<ParsedDoc | undefined> {\n  try {\n    const content = await fs.readFile(filePath, \"utf-8\");\n    return parseMarkdownContent(content);\n  } catch {\n    return undefined;\n  }\n}\n\n/** Reads a basic `overview` and per-field docs out of md content. */\nexport function parseMarkdownContent(content: string): ParsedDoc {\n  const lines = content.split(\"\\n\");\n  let currentSection: \"overview\" | \"fields\" | null = null;\n  let currentField: string | null = null;\n\n  const overviewLines: string[] = [];\n  const fields: Record<string, string[]> = {};\n\n  for (const line of lines) {\n    if (/^## Overview\\s*$/.test(line)) {\n      currentSection = \"overview\";\n      currentField = null;\n      continue;\n    }\n    if (/^## Fields\\s*$/.test(line)) {\n      currentSection = \"fields\";\n      currentField = null;\n      continue;\n    }\n    // Any other ## resets us out of known sections\n    if (line.startsWith(\"## \")) {\n      currentSection = null;\n      currentField = null;\n      continue;\n    }\n\n    if (currentSection === \"fields\") {\n      const fieldMatch = line.match(/^### (\\w+)\\s*$/);\n      if (fieldMatch) {\n        currentField = fieldMatch[1];\n        fields[currentField] = [];\n        continue;\n      }\n    }\n\n    if (currentSection === \"overview\") {\n      overviewLines.push(line);\n    } else if (currentSection === \"fields\" && currentField) {\n      fields[currentField].push(line);\n    }\n  }\n\n  return {\n    overview: trimBlankLines(overviewLines).join(\"\\n\"),\n    fields: Object.fromEntries(Object.entries(fields).map(([k, v]) => [k, trimBlankLines(v).join(\"\\n\")])),\n  };\n}\n\n/** Create a new .md file from scratch (used only for initial backfill when no .md exists). */\nexport async function writeMarkdownDoc(\n  filePath: string,\n  overview: string,\n  fields?: Record<string, string>,\n): Promise<void> {\n  const parts: string[] = [];\n\n  parts.push(\"## Overview\");\n  parts.push(overview || \"\");\n  parts.push(\"\");\n\n  if (fields && Object.keys(fields).length > 0) {\n    parts.push(\"## Fields\");\n    parts.push(\"\");\n    for (const [fieldName, fieldDoc] of Object.entries(fields)) {\n      parts.push(`### ${fieldName}`);\n      parts.push(\"\");\n      parts.push(fieldDoc);\n      parts.push(\"\");\n    }\n  }\n\n  const prettierConfig = await resolveConfig(filePath);\n  const content = await prettier.format(parts.join(\"\\n\"), {\n    ...prettierConfig,\n    parser: \"markdown\",\n    plugins: [],\n  });\n\n  await fs.writeFile(filePath, content, \"utf-8\");\n}\n\n/**\n * Update an existing .md file, merging in new/changed content without stomping user content.\n * If the file doesn't exist, creates it from scratch.\n */\nexport async function updateMarkdownDoc(\n  filePath: string,\n  overview: string | undefined,\n  fields: Record<string, string>,\n): Promise<void> {\n  let existing: string | null = null;\n  try {\n    existing = await fs.readFile(filePath, \"utf-8\");\n  } catch {\n    // File doesn't exist\n  }\n\n  if (existing !== null) {\n    const updated = mergeMarkdownContent(existing, overview, fields);\n    if (updated !== existing) {\n      await fs.writeFile(filePath, updated, \"utf-8\");\n    }\n  } else {\n    await writeMarkdownDoc(filePath, overview ?? \"\", Object.keys(fields).length > 0 ? fields : undefined);\n  }\n}\n\nexport function getMarkdownFilePath(entitiesDir: string, entityName: string): string {\n  return join(entitiesDir, `${entityName}.md`);\n}\n\n/** Trim leading/trailing blank lines but preserve internal blank lines. */\nfunction trimBlankLines(lines: string[]): string[] {\n  let start = 0;\n  while (start < lines.length && lines[start].trim() === \"\") start++;\n  let end = lines.length - 1;\n  while (end >= start && lines[end].trim() === \"\") end--;\n  return lines.slice(start, end + 1);\n}\n\n/**\n * Merge updates into an existing .md file, preserving all user content.\n *\n * - If `overview` is provided and the file has `## Overview`, replaces its body\n * - For each field in `fields`, if `### fieldName` exists, replaces its body;\n *   otherwise appends it to the `## Fields` section (creating the section if needed)\n * - All other content (custom sections, tables, etc.) is preserved verbatim\n */\nfunction mergeMarkdownContent(existing: string, overview: string | undefined, fields: Record<string, string>): string {\n  const lines = existing.split(\"\\n\");\n  const result: string[] = [];\n\n  // Track which fields we've already merged so we know what to append\n  const mergedFields = new Set<string>();\n  let fieldsEndIndex = -1;\n\n  let i = 0;\n  while (i < lines.length) {\n    const line = lines[i];\n\n    // Replace ## Overview body\n    if (/^## Overview\\s*$/.test(line) && overview !== undefined) {\n      result.push(line);\n      i++;\n      // Skip over old overview body (until next ## or EOF)\n      while (i < lines.length && !lines[i].startsWith(\"## \")) i++;\n      // Write new overview body\n      result.push(overview || \"\");\n      result.push(\"\");\n      continue;\n    }\n\n    // Track where ## Fields section ends (for appending new fields)\n    if (/^## Fields\\s*$/.test(line)) {\n      result.push(line);\n      i++;\n      // Process the fields section line by line\n      while (i < lines.length && !lines[i].startsWith(\"## \")) {\n        const fieldMatch = lines[i].match(/^### (\\w+)\\s*$/);\n        if (fieldMatch && fieldMatch[1] in fields) {\n          const fieldName = fieldMatch[1];\n          mergedFields.add(fieldName);\n          result.push(lines[i]); // ### fieldName\n          i++;\n          // Skip old field body (until next ### or ## or EOF)\n          while (i < lines.length && !/^###? /.test(lines[i]) && !lines[i].startsWith(\"## \")) i++;\n          // Write new field body\n          result.push(\"\");\n          result.push(fields[fieldName]);\n          result.push(\"\");\n        } else {\n          // Keep any line that isn't a field we're replacing (other ### fields, blank lines, etc.)\n          result.push(lines[i]);\n          i++;\n        }\n      }\n      fieldsEndIndex = result.length;\n      continue;\n    }\n\n    result.push(line);\n    i++;\n  }\n\n  // Append any fields that weren't already in the file\n  const newFields = Object.entries(fields).filter(([name]) => !mergedFields.has(name));\n  if (newFields.length > 0) {\n    if (fieldsEndIndex === -1) {\n      // No ## Fields section existed, create one\n      result.push(\"\");\n      result.push(\"## Fields\");\n      result.push(\"\");\n      fieldsEndIndex = result.length;\n    }\n    const toInsert: string[] = [];\n    for (const [fieldName, fieldDoc] of newFields) {\n      toInsert.push(`### ${fieldName}`);\n      toInsert.push(\"\");\n      toInsert.push(fieldDoc);\n      toInsert.push(\"\");\n    }\n    result.splice(fieldsEndIndex, 0, ...toInsert);\n  }\n\n  return result.join(\"\\n\");\n}\n\nexport const testing = { mergeMarkdownContent };\n"],"mappings":";;;;;AAWA,eAAsB,sBAAsB,UAAkD;CAC5F,IAAI;EAEF,OAAO,qBAAqB,MADNA,SAAG,SAAS,UAAU,OAAO,CAChB;CACrC,QAAQ;EACN;CACF;AACF;;AAGA,SAAgB,qBAAqB,SAA4B;CAC/D,MAAM,QAAQ,QAAQ,MAAM,IAAI;CAChC,IAAI,iBAA+C;CACnD,IAAI,eAA8B;CAElC,MAAM,gBAA0B,CAAC;CACjC,MAAM,SAAmC,CAAC;CAE1C,KAAK,MAAM,QAAQ,OAAO;EACxB,IAAI,mBAAmB,KAAK,IAAI,GAAG;GACjC,iBAAiB;GACjB,eAAe;GACf;EACF;EACA,IAAI,iBAAiB,KAAK,IAAI,GAAG;GAC/B,iBAAiB;GACjB,eAAe;GACf;EACF;EAEA,IAAI,KAAK,WAAW,KAAK,GAAG;GAC1B,iBAAiB;GACjB,eAAe;GACf;EACF;EAEA,IAAI,mBAAmB,UAAU;GAC/B,MAAM,aAAa,KAAK,MAAM,gBAAgB;GAC9C,IAAI,YAAY;IACd,eAAe,WAAW;IAC1B,OAAO,gBAAgB,CAAC;IACxB;GACF;EACF;EAEA,IAAI,mBAAmB,YACrB,cAAc,KAAK,IAAI;OAClB,IAAI,mBAAmB,YAAY,cACxC,OAAO,aAAa,CAAC,KAAK,IAAI;CAElC;CAEA,OAAO;EACL,UAAU,eAAe,aAAa,CAAC,CAAC,KAAK,IAAI;EACjD,QAAQ,OAAO,YAAY,OAAO,QAAQ,MAAM,CAAC,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,GAAG,eAAe,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC;CACtG;AACF;;AAGA,eAAsB,iBACpB,UACA,UACA,QACe;CACf,MAAM,QAAkB,CAAC;CAEzB,MAAM,KAAK,aAAa;CACxB,MAAM,KAAK,YAAY,EAAE;CACzB,MAAM,KAAK,EAAE;CAEb,IAAI,UAAU,OAAO,KAAK,MAAM,CAAC,CAAC,SAAS,GAAG;EAC5C,MAAM,KAAK,WAAW;EACtB,MAAM,KAAK,EAAE;EACb,KAAK,MAAM,CAAC,WAAW,aAAa,OAAO,QAAQ,MAAM,GAAG;GAC1D,MAAM,KAAK,OAAO,WAAW;GAC7B,MAAM,KAAK,EAAE;GACb,MAAM,KAAK,QAAQ;GACnB,MAAM,KAAK,EAAE;EACf;CACF;CAEA,MAAM,iBAAiB,MAAM,cAAc,QAAQ;CACnD,MAAM,UAAU,MAAM,SAAS,OAAO,MAAM,KAAK,IAAI,GAAG;EACtD,GAAG;EACH,QAAQ;EACR,SAAS,CAAC;CACZ,CAAC;CAED,MAAMA,SAAG,UAAU,UAAU,SAAS,OAAO;AAC/C;;;;;AAMA,eAAsB,kBACpB,UACA,UACA,QACe;CACf,IAAI,WAA0B;CAC9B,IAAI;EACF,WAAW,MAAMA,SAAG,SAAS,UAAU,OAAO;CAChD,QAAQ,CAER;CAEA,IAAI,aAAa,MAAM;EACrB,MAAM,UAAU,qBAAqB,UAAU,UAAU,MAAM;EAC/D,IAAI,YAAY,UACd,MAAMA,SAAG,UAAU,UAAU,SAAS,OAAO;CAEjD,OACE,MAAM,iBAAiB,UAAU,YAAY,IAAI,OAAO,KAAK,MAAM,CAAC,CAAC,SAAS,IAAI,SAAS,KAAA,CAAS;AAExG;AAEA,SAAgB,oBAAoB,aAAqB,YAA4B;CACnF,OAAO,KAAK,aAAa,GAAG,WAAW,IAAI;AAC7C;;AAGA,SAAS,eAAe,OAA2B;CACjD,IAAI,QAAQ;CACZ,OAAO,QAAQ,MAAM,UAAU,MAAM,MAAM,CAAC,KAAK,MAAM,IAAI;CAC3D,IAAI,MAAM,MAAM,SAAS;CACzB,OAAO,OAAO,SAAS,MAAM,IAAI,CAAC,KAAK,MAAM,IAAI;CACjD,OAAO,MAAM,MAAM,OAAO,MAAM,CAAC;AACnC;;;;;;;;;AAUA,SAAS,qBAAqB,UAAkB,UAA8B,QAAwC;CACpH,MAAM,QAAQ,SAAS,MAAM,IAAI;CACjC,MAAM,SAAmB,CAAC;CAG1B,MAAM,+BAAe,IAAI,IAAY;CACrC,IAAI,iBAAiB;CAErB,IAAI,IAAI;CACR,OAAO,IAAI,MAAM,QAAQ;EACvB,MAAM,OAAO,MAAM;EAGnB,IAAI,mBAAmB,KAAK,IAAI,KAAK,aAAa,KAAA,GAAW;GAC3D,OAAO,KAAK,IAAI;GAChB;GAEA,OAAO,IAAI,MAAM,UAAU,CAAC,MAAM,EAAE,CAAC,WAAW,KAAK,GAAG;GAExD,OAAO,KAAK,YAAY,EAAE;GAC1B,OAAO,KAAK,EAAE;GACd;EACF;EAGA,IAAI,iBAAiB,KAAK,IAAI,GAAG;GAC/B,OAAO,KAAK,IAAI;GAChB;GAEA,OAAO,IAAI,MAAM,UAAU,CAAC,MAAM,EAAE,CAAC,WAAW,KAAK,GAAG;IACtD,MAAM,aAAa,MAAM,EAAE,CAAC,MAAM,gBAAgB;IAClD,IAAI,cAAc,WAAW,MAAM,QAAQ;KACzC,MAAM,YAAY,WAAW;KAC7B,aAAa,IAAI,SAAS;KAC1B,OAAO,KAAK,MAAM,EAAE;KACpB;KAEA,OAAO,IAAI,MAAM,UAAU,CAAC,SAAS,KAAK,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC,WAAW,KAAK,GAAG;KAEpF,OAAO,KAAK,EAAE;KACd,OAAO,KAAK,OAAO,UAAU;KAC7B,OAAO,KAAK,EAAE;IAChB,OAAO;KAEL,OAAO,KAAK,MAAM,EAAE;KACpB;IACF;GACF;GACA,iBAAiB,OAAO;GACxB;EACF;EAEA,OAAO,KAAK,IAAI;EAChB;CACF;CAGA,MAAM,YAAY,OAAO,QAAQ,MAAM,CAAC,CAAC,QAAQ,CAAC,UAAU,CAAC,aAAa,IAAI,IAAI,CAAC;CACnF,IAAI,UAAU,SAAS,GAAG;EACxB,IAAI,mBAAmB,IAAI;GAEzB,OAAO,KAAK,EAAE;GACd,OAAO,KAAK,WAAW;GACvB,OAAO,KAAK,EAAE;GACd,iBAAiB,OAAO;EAC1B;EACA,MAAM,WAAqB,CAAC;EAC5B,KAAK,MAAM,CAAC,WAAW,aAAa,WAAW;GAC7C,SAAS,KAAK,OAAO,WAAW;GAChC,SAAS,KAAK,EAAE;GAChB,SAAS,KAAK,QAAQ;GACtB,SAAS,KAAK,EAAE;EAClB;EACA,OAAO,OAAO,gBAAgB,GAAG,GAAG,QAAQ;CAC9C;CAEA,OAAO,OAAO,KAAK,IAAI;AACzB;AAEA,MAAa,UAAU,EAAE,qBAAqB"}

package/build/docs/parsing.cjs

@@ -0,0 +1,117 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_runtime = require("../_virtual/_rolldown/runtime.cjs");
+let jscodeshift = require("jscodeshift");
+jscodeshift = require_runtime.__toESM(jscodeshift, 1);
+//#region src/docs/parsing.ts
+const j = jscodeshift.default.withParser("ts");
+/** Parse an entity .ts file and extract class + member JSDoc. */
+function parseEntityJSDocs(source) {
+	const root = j(source);
+	let classDoc;
+	let classNode;
+	const members = [];
+	root.find(j.ExportNamedDeclaration).forEach((p) => {
+		if (p.node.declaration?.type === "ClassDeclaration") {
+			classDoc = extractJSDoc(p.node);
+			classNode = p.node;
+		}
+	});
+	root.find(j.ClassProperty).forEach((p) => {
+		const name = p.node.key?.name;
+		if (name) members.push({
+			name,
+			kind: "property",
+			doc: extractJSDoc(p.node),
+			node: p.node
+		});
+	});
+	root.find(j.ClassMethod).forEach((p) => {
+		const name = p.node.key?.name;
+		if (name) members.push({
+			name,
+			kind: classMethodKind(p.node),
+			doc: extractJSDoc(p.node),
+			node: p.node
+		});
+	});
+	return {
+		classDoc,
+		classNode,
+		members,
+		fieldDocs: collectFieldDocs(members)
+	};
+}
+/**
+* Collect field docs from members for backfill.
+* When a getter and setter share the same name, prefer the getter's doc.
+*/
+function collectFieldDocs(members) {
+	const result = {};
+	for (const m of members) {
+		if (!m.doc || m.kind === "method") continue;
+		if (result[m.name] && m.kind === "setter") continue;
+		result[m.name] = m.doc;
+	}
+	return result;
+}
+/**
+* Build a source edit that sets the JSDoc on a node (replacing existing or inserting new).
+*
+* (This is bizarre, but this `SourceEdit` + `applyEdits` leaves all existing formatting
+* alone better than doing a `node.toSource()` or other AST-based updates. :grimmacing:)
+*/
+function buildJSDocEdit(node, text) {
+	const column = node.loc.start.column;
+	const existingComment = node.comments?.find((c) => c.leading && "value" in c && c.value.startsWith("*"));
+	if (existingComment) return {
+		start: existingComment.start,
+		end: existingComment.end,
+		text: buildJSDocBlock(text, column)
+	};
+	const indent = " ".repeat(column);
+	return {
+		start: node.start,
+		end: node.start,
+		text: buildJSDocBlock(text, column) + "\n" + indent
+	};
+}
+/** Apply edits to source by splicing in reverse order. */
+function applyEdits(source, edits) {
+	const sorted = [...edits].sort((a, b) => b.start - a.start);
+	let result = source;
+	for (const edit of sorted) result = result.slice(0, edit.start) + edit.text + result.slice(edit.end);
+	return result;
+}
+/** Build a JSDoc block comment string from plain text. */
+function buildJSDocBlock(text, indent) {
+	const pad = " ".repeat(indent);
+	const lines = text.split("\n");
+	if (lines.length === 1) return `/** ${lines[0]} */`;
+	return `/**\n` + lines.map((l) => l ? `${pad} * ${l}` : `${pad} *`).join("\n") + `\n${pad} */`;
+}
+/** The `@generated Entity.md` marker, i.e. so readers know a JSDoc is sourced from (and edited in) the `.md`. */
+function generatedTag(entityName) {
+	return `@generated ${entityName}.md`;
+}
+/** Extract text from a JSDoc-style leading block comment (i.e. one starting with `*`). */
+function extractJSDoc(node) {
+	const block = node.comments?.find((c) => c.leading && "value" in c && c.value.startsWith("*"));
+	if (!block || !("value" in block)) return void 0;
+	const lines = block.value.split("\n").map((l) => l.replace(/^\s*\*\s?/, "").trimEnd());
+	while (lines.length > 0 && lines[0].trim() === "") lines.shift();
+	while (lines.length > 0 && lines[lines.length - 1].trim() === "") lines.pop();
+	return lines.join("\n") || void 0;
+}
+function classMethodKind(node) {
+	if (node.kind === "get") return "getter";
+	if (node.kind === "set") return "setter";
+	return "method";
+}
+//#endregion
+exports.applyEdits = applyEdits;
+exports.buildJSDocBlock = buildJSDocBlock;
+exports.buildJSDocEdit = buildJSDocEdit;
+exports.generatedTag = generatedTag;
+exports.parseEntityJSDocs = parseEntityJSDocs;
+
+//# sourceMappingURL=parsing.cjs.map

package/build/docs/parsing.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"parsing.cjs","names":[],"sources":["../../src/docs/parsing.ts"],"sourcesContent":["import type { namedTypes } from \"ast-types\";\nimport jscodeshift, { type ASTNode } from \"jscodeshift\";\n\nconst j = jscodeshift.withParser(\"ts\");\n\ntype CommentKind = (namedTypes.CommentBlock | namedTypes.CommentLine | namedTypes.Block | namedTypes.Line) & {\n  start?: number;\n  end?: number;\n};\nj;\ntype Commented = ASTNode & {\n  comments?: CommentKind[] | null;\n  start?: number;\n  end?: number;\n  loc?: namedTypes.SourceLocation | null;\n};\n\nexport type MemberKind = \"property\" | \"getter\" | \"setter\" | \"method\";\n\nexport interface MemberInfo {\n  kind: MemberKind;\n  name: string;\n  doc: string | undefined;\n  node: Commented;\n}\n\nexport interface SourceEdit {\n  start: number;\n  end: number;\n  text: string;\n}\n\n/** Parse an entity .ts file and extract class + member JSDoc. */\nexport function parseEntityJSDocs(source: string) {\n  const root = j(source);\n  let classDoc: string | undefined;\n  let classNode: Commented | undefined;\n  const members: MemberInfo[] = [];\n\n  root.find(j.ExportNamedDeclaration).forEach((p) => {\n    if (p.node.declaration?.type === \"ClassDeclaration\") {\n      classDoc = extractJSDoc(p.node as Commented);\n      classNode = p.node as Commented;\n    }\n  });\n\n  root.find(j.ClassProperty).forEach((p) => {\n    const name = (p.node.key as namedTypes.Identifier)?.name;\n    if (name) {\n      members.push({ name, kind: \"property\", doc: extractJSDoc(p.node as Commented), node: p.node as Commented });\n    }\n  });\n\n  root.find(j.ClassMethod).forEach((p) => {\n    const name = (p.node.key as namedTypes.Identifier)?.name;\n    if (name) {\n      members.push({\n        name,\n        kind: classMethodKind(p.node),\n        doc: extractJSDoc(p.node as Commented),\n        node: p.node as Commented,\n      });\n    }\n  });\n\n  return { classDoc, classNode, members, fieldDocs: collectFieldDocs(members) };\n}\n\n/**\n * Collect field docs from members for backfill.\n * When a getter and setter share the same name, prefer the getter's doc.\n */\nfunction collectFieldDocs(members: MemberInfo[]): Record<string, string> {\n  const result: Record<string, string> = {};\n  for (const m of members) {\n    if (!m.doc || m.kind === \"method\") continue;\n    if (result[m.name] && m.kind === \"setter\") continue;\n    result[m.name] = m.doc;\n  }\n  return result;\n}\n\n/**\n * Build a source edit that sets the JSDoc on a node (replacing existing or inserting new).\n *\n * (This is bizarre, but this `SourceEdit` + `applyEdits` leaves all existing formatting\n * alone better than doing a `node.toSource()` or other AST-based updates. :grimmacing:)\n */\nexport function buildJSDocEdit(node: Commented, text: string): SourceEdit {\n  const column = node.loc!.start.column;\n  const existingComment = node.comments?.find((c) => c.leading && \"value\" in c && c.value.startsWith(\"*\"));\n  if (existingComment) {\n    return { start: existingComment.start!, end: existingComment.end!, text: buildJSDocBlock(text, column) };\n  }\n  const indent = \" \".repeat(column);\n  return { start: node.start!, end: node.start!, text: buildJSDocBlock(text, column) + \"\\n\" + indent };\n}\n\n/** Apply edits to source by splicing in reverse order. */\nexport function applyEdits(source: string, edits: SourceEdit[]): string {\n  const sorted = [...edits].sort((a, b) => b.start - a.start);\n  let result = source;\n  for (const edit of sorted) {\n    result = result.slice(0, edit.start) + edit.text + result.slice(edit.end);\n  }\n  return result;\n}\n\n/** Build a JSDoc block comment string from plain text. */\nexport function buildJSDocBlock(text: string, indent: number): string {\n  const pad = \" \".repeat(indent);\n  const lines = text.split(\"\\n\");\n  if (lines.length === 1) return `/** ${lines[0]} */`;\n  return `/**\\n` + lines.map((l) => (l ? `${pad} * ${l}` : `${pad} *`)).join(\"\\n\") + `\\n${pad} */`;\n}\n\n/** The `@generated Entity.md` marker, i.e. so readers know a JSDoc is sourced from (and edited in) the `.md`. */\nexport function generatedTag(entityName: string): string {\n  return `@generated ${entityName}.md`;\n}\n\n/** Extract text from a JSDoc-style leading block comment (i.e. one starting with `*`). */\nfunction extractJSDoc(node: Commented): string | undefined {\n  const block = node.comments?.find((c) => c.leading && \"value\" in c && c.value.startsWith(\"*\"));\n  if (!block || !(\"value\" in block)) return undefined;\n  const lines = block.value.split(\"\\n\").map((l) => l.replace(/^\\s*\\*\\s?/, \"\").trimEnd());\n  while (lines.length > 0 && lines[0].trim() === \"\") lines.shift();\n  while (lines.length > 0 && lines[lines.length - 1].trim() === \"\") lines.pop();\n  return lines.join(\"\\n\") || undefined;\n}\n\nfunction classMethodKind(node: namedTypes.ClassMethod): MemberKind {\n  if (node.kind === \"get\") return \"getter\";\n  if (node.kind === \"set\") return \"setter\";\n  return \"method\";\n}\n"],"mappings":"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"}

package/build/docs/parsing.d.cts

@@ -0,0 +1,48 @@
+import { ASTNode } from "jscodeshift";
+import { namedTypes } from "ast-types";
+//#region src/docs/parsing.d.ts
+type CommentKind = (namedTypes.CommentBlock | namedTypes.CommentLine | namedTypes.Block | namedTypes.Line) & {
+  start?: number;
+  end?: number;
+};
+type Commented = ASTNode & {
+  comments?: CommentKind[] | null;
+  start?: number;
+  end?: number;
+  loc?: namedTypes.SourceLocation | null;
+};
+type MemberKind = "property" | "getter" | "setter" | "method";
+interface MemberInfo {
+  kind: MemberKind;
+  name: string;
+  doc: string | undefined;
+  node: Commented;
+}
+interface SourceEdit {
+  start: number;
+  end: number;
+  text: string;
+}
+/** Parse an entity .ts file and extract class + member JSDoc. */
+declare function parseEntityJSDocs(source: string): {
+  classDoc: string | undefined;
+  classNode: Commented | undefined;
+  members: MemberInfo[];
+  fieldDocs: Record<string, string>;
+};
+/**
+ * Build a source edit that sets the JSDoc on a node (replacing existing or inserting new).
+ *
+ * (This is bizarre, but this `SourceEdit` + `applyEdits` leaves all existing formatting
+ * alone better than doing a `node.toSource()` or other AST-based updates. :grimmacing:)
+ */
+declare function buildJSDocEdit(node: Commented, text: string): SourceEdit;
+/** Apply edits to source by splicing in reverse order. */
+declare function applyEdits(source: string, edits: SourceEdit[]): string;
+/** Build a JSDoc block comment string from plain text. */
+declare function buildJSDocBlock(text: string, indent: number): string;
+/** The `@generated Entity.md` marker, i.e. so readers know a JSDoc is sourced from (and edited in) the `.md`. */
+declare function generatedTag(entityName: string): string;
+//#endregion
+export { MemberInfo, MemberKind, SourceEdit, applyEdits, buildJSDocBlock, buildJSDocEdit, generatedTag, parseEntityJSDocs };
+//# sourceMappingURL=parsing.d.cts.map

package/build/docs/parsing.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parsing.d.cts","names":[],"sources":["../../src/docs/parsing.ts"],"mappings":";;;KAKK,eAAe,WAAW,eAAe,WAAW,cAAc,WAAW,QAAQ,WAAW;EACnG;EACA;;KAGG,YAAY;EACf,WAAW;EACX;EACA;EACA,MAAM,WAAW;;KAGP;UAEK;EACf,MAAM;EACN;EACA;EACA,MAAM;;UAGS;EACf;EACA;EACA;;;iBAIc,kBAAkB;;;;;;;;;;;;iBAuDlB,eAAe,MAAM,WAAW,eAAe;;iBAW/C,WAAW,gBAAgB,OAAO;;iBAUlC,gBAAgB,cAAc;;iBAQ9B,aAAa"}