joist-codegen 2.3.0-next.41 → 2.3.0-next.43

package/build/docs/index.d.cts

@@ -0,0 +1,16 @@
+import { ParsedDoc } from "./markdown.cjs";
+import { generateMetadataDocsFile } from "./generate-metadata-docs.cjs";
+import { buildJSDocBlock, generatedTag } from "./parsing.cjs";
+//#region src/docs/index.d.ts
+/** Loads each entity's parsed `.md` doc, i.e. for injecting into codegen JSDocs & runtime metadata. */
+declare function loadEntityDocs(entitiesDir: string, entityNames: string[]): Promise<Record<string, ParsedDoc>>;
+/**
+ * Run the full docs sync pipeline with mtime-based caching:
+ * 1. backfill .md from .ts JSDocs
+ * 2. sync .md back into .ts JSDocs
+ * 3. save the cache
+ */
+declare function syncDocs(entitiesDir: string, entityNames: string[]): Promise<void>;
+//#endregion
+export { type ParsedDoc, buildJSDocBlock, generateMetadataDocsFile, generatedTag, loadEntityDocs, syncDocs };
+//# sourceMappingURL=index.d.cts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.cts","names":[],"sources":["../../src/docs/index.ts"],"mappings":";;;;;iBAWsB,eAAe,qBAAqB,wBAAwB,QAAQ,eAAe;;;;;;;iBAiBnF,SAAS,qBAAqB,wBAAwB"}

package/build/docs/index.d.mts

@@ -0,0 +1,16 @@
+import { ParsedDoc } from "./markdown.mjs";
+import { generateMetadataDocsFile } from "./generate-metadata-docs.mjs";
+import { buildJSDocBlock, generatedTag } from "./parsing.mjs";
+//#region src/docs/index.d.ts
+/** Loads each entity's parsed `.md` doc, i.e. for injecting into codegen JSDocs & runtime metadata. */
+declare function loadEntityDocs(entitiesDir: string, entityNames: string[]): Promise<Record<string, ParsedDoc>>;
+/**
+ * Run the full docs sync pipeline with mtime-based caching:
+ * 1. backfill .md from .ts JSDocs
+ * 2. sync .md back into .ts JSDocs
+ * 3. save the cache
+ */
+declare function syncDocs(entitiesDir: string, entityNames: string[]): Promise<void>;
+//#endregion
+export { type ParsedDoc, buildJSDocBlock, generateMetadataDocsFile, generatedTag, loadEntityDocs, syncDocs };
+//# sourceMappingURL=index.d.mts.map

package/build/docs/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../../src/docs/index.ts"],"mappings":";;;;;iBAWsB,eAAe,qBAAqB,wBAAwB,QAAQ,eAAe;;;;;;;iBAiBnF,SAAS,qBAAqB,wBAAwB"}

package/build/docs/index.js

@@ -1,104 +1,85 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.generatedTag = exports.buildJSDocBlock = exports.generateMetadataDocsFile = void 0;
-exports.loadEntityDocs = loadEntityDocs;
-exports.syncDocs = syncDocs;
-const fs_1 = require("fs");
-const path_1 = require("path");
-const cache_1 = require("./cache");
-const markdown_1 = require("./markdown");
-const parsing_1 = require("./parsing");
-var generate_metadata_docs_1 = require("./generate-metadata-docs");
-Object.defineProperty(exports, "generateMetadataDocsFile", { enumerable: true, get: function () { return generate_metadata_docs_1.generateMetadataDocsFile; } });
-var parsing_2 = require("./parsing");
-Object.defineProperty(exports, "buildJSDocBlock", { enumerable: true, get: function () { return parsing_2.buildJSDocBlock; } });
-Object.defineProperty(exports, "generatedTag", { enumerable: true, get: function () { return parsing_2.generatedTag; } });
+import { DocsCache, getMtime } from "./cache.js";
+import { getMarkdownFilePath, maybeReadMarkdownFile, updateMarkdownDoc } from "./markdown.js";
+import { applyEdits, buildJSDocBlock, buildJSDocEdit, generatedTag, parseEntityJSDocs } from "./parsing.js";
+import { generateMetadataDocsFile } from "./generate-metadata-docs.js";
+import { promises } from "fs";
+import { join } from "path";
+//#region src/docs/index.ts
 /** Loads each entity's parsed `.md` doc, i.e. for injecting into codegen JSDocs & runtime metadata. */
 async function loadEntityDocs(entitiesDir, entityNames) {
-    const result = {};
-    await Promise.all(entityNames.map(async (entityName) => {
-        const doc = await (0, markdown_1.maybeReadMarkdownFile)((0, markdown_1.getMarkdownFilePath)(entitiesDir, entityName));
-        if (doc)
-            result[entityName] = doc;
-    }));
-    return result;
+	const result = {};
+	await Promise.all(entityNames.map(async (entityName) => {
+		const doc = await maybeReadMarkdownFile(getMarkdownFilePath(entitiesDir, entityName));
+		if (doc) result[entityName] = doc;
+	}));
+	return result;
 }
 /**
- * Run the full docs sync pipeline with mtime-based caching:
- * 1. backfill .md from .ts JSDocs
- * 2. sync .md back into .ts JSDocs
- * 3. save the cache
- */
+* Run the full docs sync pipeline with mtime-based caching:
+* 1. backfill .md from .ts JSDocs
+* 2. sync .md back into .ts JSDocs
+* 3. save the cache
+*/
 async function syncDocs(entitiesDir, entityNames) {
-    const cache = await cache_1.DocsCache.load();
-    // Stat all files upfront in parallel to determine which entities need processing
-    const stats = await Promise.all(entityNames.map(async (entityName) => {
-        const tsPath = (0, path_1.join)(entitiesDir, `${entityName}.ts`);
-        const mdPath = (0, markdown_1.getMarkdownFilePath)(entitiesDir, entityName);
-        const [tsMtime, mdMtime] = await Promise.all([(0, cache_1.getMtime)(tsPath), (0, cache_1.getMtime)(mdPath)]);
-        return { entityName, tsPath, mdPath, tsMtime, mdMtime };
-    }));
-    const dirty = stats.filter((s) => s.tsMtime !== -1 && !cache.isUpToDate(s.entityName, s.tsMtime, s.mdMtime));
-    if (dirty.length > 0) {
-        // Step 1: backfill .md from .ts
-        await Promise.all(dirty.map((s) => backfillMarkdownFromJsdoc(s.tsPath, s.mdPath)));
-        // Step 2: sync .md into .ts (re-read .md mtimes since backfill may have written them)
-        await Promise.all(dirty.map((s) => syncMarkdownToJsdoc(s.entityName, s.tsPath, s.mdPath)));
-        // Record final mtimes after both passes
-        await Promise.all(dirty.map(async (s) => {
-            const [tsMtime, mdMtime] = await Promise.all([(0, cache_1.getMtime)(s.tsPath), (0, cache_1.getMtime)(s.mdPath)]);
-            cache.update(s.entityName, tsMtime, mdMtime);
-        }));
-    }
-    await cache.save();
+	const cache = await DocsCache.load();
+	const dirty = (await Promise.all(entityNames.map(async (entityName) => {
+		const tsPath = join(entitiesDir, `${entityName}.ts`);
+		const mdPath = getMarkdownFilePath(entitiesDir, entityName);
+		const [tsMtime, mdMtime] = await Promise.all([getMtime(tsPath), getMtime(mdPath)]);
+		return {
+			entityName,
+			tsPath,
+			mdPath,
+			tsMtime,
+			mdMtime
+		};
+	}))).filter((s) => s.tsMtime !== -1 && !cache.isUpToDate(s.entityName, s.tsMtime, s.mdMtime));
+	if (dirty.length > 0) {
+		await Promise.all(dirty.map((s) => backfillMarkdownFromJsdoc(s.tsPath, s.mdPath)));
+		await Promise.all(dirty.map((s) => syncMarkdownToJsdoc(s.entityName, s.tsPath, s.mdPath)));
+		await Promise.all(dirty.map(async (s) => {
+			const [tsMtime, mdMtime] = await Promise.all([getMtime(s.tsPath), getMtime(s.mdPath)]);
+			cache.update(s.entityName, tsMtime, mdMtime);
+		}));
+	}
+	await cache.save();
 }
 /** Sync a single entity's Markdown docs into its .ts file. */
 async function syncMarkdownToJsdoc(entityName, tsPath, mdPath) {
-    const doc = await (0, markdown_1.maybeReadMarkdownFile)(mdPath);
-    if (!doc || (!doc.overview && Object.keys(doc.fields).length === 0))
-        return;
-    const source = await fs_1.promises.readFile(tsPath, "utf-8");
-    const { classNode, members } = (0, parsing_1.parseEntityJSDocs)(source);
-    const tag = (0, parsing_1.generatedTag)(entityName);
-    const edits = [];
-    if (doc.overview && classNode) {
-        edits.push((0, parsing_1.buildJSDocEdit)(classNode, `${doc.overview}\n${tag}`));
-    }
-    for (const [fieldName, fieldDoc] of Object.entries(doc.fields)) {
-        if (!fieldDoc)
-            continue;
-        for (const member of members.filter((m) => m.name === fieldName && m.kind !== "method")) {
-            edits.push((0, parsing_1.buildJSDocEdit)(member.node, `${fieldDoc}\n${tag}`));
-        }
-    }
-    if (edits.length > 0) {
-        const updated = (0, parsing_1.applyEdits)(source, edits);
-        if (updated !== source) {
-            await fs_1.promises.writeFile(tsPath, updated, "utf-8");
-        }
-    }
+	const doc = await maybeReadMarkdownFile(mdPath);
+	if (!doc || !doc.overview && Object.keys(doc.fields).length === 0) return;
+	const source = await promises.readFile(tsPath, "utf-8");
+	const { classNode, members } = parseEntityJSDocs(source);
+	const tag = generatedTag(entityName);
+	const edits = [];
+	if (doc.overview && classNode) edits.push(buildJSDocEdit(classNode, `${doc.overview}\n${tag}`));
+	for (const [fieldName, fieldDoc] of Object.entries(doc.fields)) {
+		if (!fieldDoc) continue;
+		for (const member of members.filter((m) => m.name === fieldName && m.kind !== "method")) edits.push(buildJSDocEdit(member.node, `${fieldDoc}\n${tag}`));
+	}
+	if (edits.length > 0) {
+		const updated = applyEdits(source, edits);
+		if (updated !== source) await promises.writeFile(tsPath, updated, "utf-8");
+	}
 }
 /**
- * Backfill a single entity's .md file from JSDocs in its .ts file.
- *
- * If the .md doesn't exist, creates it. If it does exist, merges in any
- * fields that are documented in .ts but missing from the .md.
- */
+* Backfill a single entity's .md file from JSDocs in its .ts file.
+*
+* If the .md doesn't exist, creates it. If it does exist, merges in any
+* fields that are documented in .ts but missing from the .md.
+*/
 async function backfillMarkdownFromJsdoc(tsPath, mdPath) {
-    const source = await fs_1.promises.readFile(tsPath, "utf-8");
-    const { classDoc, fieldDocs } = (0, parsing_1.parseEntityJSDocs)(source);
-    if (!classDoc && Object.keys(fieldDocs).length === 0)
-        return;
-    const existingDoc = await (0, markdown_1.maybeReadMarkdownFile)(mdPath);
-    const newFields = {};
-    for (const [name, doc] of Object.entries(fieldDocs)) {
-        if (!existingDoc?.fields[name]) {
-            newFields[name] = doc;
-        }
-    }
-    const newOverview = !existingDoc ? classDoc : existingDoc.overview ? undefined : classDoc;
-    if (!newOverview && Object.keys(newFields).length === 0)
-        return;
-    await (0, markdown_1.updateMarkdownDoc)(mdPath, newOverview, newFields);
+	const source = await promises.readFile(tsPath, "utf-8");
+	const { classDoc, fieldDocs } = parseEntityJSDocs(source);
+	if (!classDoc && Object.keys(fieldDocs).length === 0) return;
+	const existingDoc = await maybeReadMarkdownFile(mdPath);
+	const newFields = {};
+	for (const [name, doc] of Object.entries(fieldDocs)) if (!existingDoc?.fields[name]) newFields[name] = doc;
+	const newOverview = !existingDoc ? classDoc : existingDoc.overview ? void 0 : classDoc;
+	if (!newOverview && Object.keys(newFields).length === 0) return;
+	await updateMarkdownDoc(mdPath, newOverview, newFields);
 }
+//#endregion
+export { buildJSDocBlock, generateMetadataDocsFile, generatedTag, loadEntityDocs, syncDocs };
+
 //# sourceMappingURL=index.js.map

package/build/docs/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/docs/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","names":["fs"],"sources":["../../src/docs/index.ts"],"sourcesContent":["import { promises as fs } from \"fs\";\nimport { join } from \"path\";\n\nimport { DocsCache, getMtime } from \"./cache.ts\";\nimport { type ParsedDoc, getMarkdownFilePath, maybeReadMarkdownFile, updateMarkdownDoc } from \"./markdown.ts\";\nimport { applyEdits, buildJSDocEdit, generatedTag, parseEntityJSDocs } from \"./parsing.ts\";\nexport { generateMetadataDocsFile } from \"./generate-metadata-docs.ts\";\nexport { type ParsedDoc } from \"./markdown.ts\";\nexport { buildJSDocBlock, generatedTag } from \"./parsing.ts\";\n\n/** Loads each entity's parsed `.md` doc, i.e. for injecting into codegen JSDocs & runtime metadata. */\nexport async function loadEntityDocs(entitiesDir: string, entityNames: string[]): Promise<Record<string, ParsedDoc>> {\n  const result: Record<string, ParsedDoc> = {};\n  await Promise.all(\n    entityNames.map(async (entityName) => {\n      const doc = await maybeReadMarkdownFile(getMarkdownFilePath(entitiesDir, entityName));\n      if (doc) result[entityName] = doc;\n    }),\n  );\n  return result;\n}\n\n/**\n * Run the full docs sync pipeline with mtime-based caching:\n * 1. backfill .md from .ts JSDocs\n * 2. sync .md back into .ts JSDocs\n * 3. save the cache\n */\nexport async function syncDocs(entitiesDir: string, entityNames: string[]): Promise<void> {\n  const cache = await DocsCache.load();\n\n  // Stat all files upfront in parallel to determine which entities need processing\n  const stats = await Promise.all(\n    entityNames.map(async (entityName) => {\n      const tsPath = join(entitiesDir, `${entityName}.ts`);\n      const mdPath = getMarkdownFilePath(entitiesDir, entityName);\n      const [tsMtime, mdMtime] = await Promise.all([getMtime(tsPath), getMtime(mdPath)]);\n      return { entityName, tsPath, mdPath, tsMtime, mdMtime };\n    }),\n  );\n\n  const dirty = stats.filter((s) => s.tsMtime !== -1 && !cache.isUpToDate(s.entityName, s.tsMtime, s.mdMtime));\n\n  if (dirty.length > 0) {\n    // Step 1: backfill .md from .ts\n    await Promise.all(dirty.map((s) => backfillMarkdownFromJsdoc(s.tsPath, s.mdPath)));\n\n    // Step 2: sync .md into .ts (re-read .md mtimes since backfill may have written them)\n    await Promise.all(dirty.map((s) => syncMarkdownToJsdoc(s.entityName, s.tsPath, s.mdPath)));\n\n    // Record final mtimes after both passes\n    await Promise.all(\n      dirty.map(async (s) => {\n        const [tsMtime, mdMtime] = await Promise.all([getMtime(s.tsPath), getMtime(s.mdPath)]);\n        cache.update(s.entityName, tsMtime, mdMtime);\n      }),\n    );\n  }\n\n  await cache.save();\n}\n\n/** Sync a single entity's Markdown docs into its .ts file. */\nasync function syncMarkdownToJsdoc(entityName: string, tsPath: string, mdPath: string): Promise<void> {\n  const doc = await maybeReadMarkdownFile(mdPath);\n  if (!doc || (!doc.overview && Object.keys(doc.fields).length === 0)) return;\n\n  const source = await fs.readFile(tsPath, \"utf-8\");\n  const { classNode, members } = parseEntityJSDocs(source);\n\n  const tag = generatedTag(entityName);\n  const edits = [];\n  if (doc.overview && classNode) {\n    edits.push(buildJSDocEdit(classNode, `${doc.overview}\\n${tag}`));\n  }\n  for (const [fieldName, fieldDoc] of Object.entries(doc.fields)) {\n    if (!fieldDoc) continue;\n    for (const member of members.filter((m) => m.name === fieldName && m.kind !== \"method\")) {\n      edits.push(buildJSDocEdit(member.node, `${fieldDoc}\\n${tag}`));\n    }\n  }\n\n  if (edits.length > 0) {\n    const updated = applyEdits(source, edits);\n    if (updated !== source) {\n      await fs.writeFile(tsPath, updated, \"utf-8\");\n    }\n  }\n}\n\n/**\n * Backfill a single entity's .md file from JSDocs in its .ts file.\n *\n * If the .md doesn't exist, creates it. If it does exist, merges in any\n * fields that are documented in .ts but missing from the .md.\n */\nasync function backfillMarkdownFromJsdoc(tsPath: string, mdPath: string): Promise<void> {\n  const source = await fs.readFile(tsPath, \"utf-8\");\n  const { classDoc, fieldDocs } = parseEntityJSDocs(source);\n\n  if (!classDoc && Object.keys(fieldDocs).length === 0) return;\n\n  const existingDoc = await maybeReadMarkdownFile(mdPath);\n  const newFields: Record<string, string> = {};\n  for (const [name, doc] of Object.entries(fieldDocs)) {\n    if (!existingDoc?.fields[name]) {\n      newFields[name] = doc;\n    }\n  }\n  const newOverview = !existingDoc ? classDoc : existingDoc.overview ? undefined : classDoc;\n\n  if (!newOverview && Object.keys(newFields).length === 0) return;\n\n  await updateMarkdownDoc(mdPath, newOverview, newFields);\n}\n"],"mappings":"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"}

package/build/docs/markdown.cjs

@@ -0,0 +1,181 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_runtime = require("../_virtual/_rolldown/runtime.cjs");
+let fs = require("fs");
+let path = require("path");
+let prettier = require("prettier");
+prettier = require_runtime.__toESM(prettier, 1);
+//#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 {
+		return parseMarkdownContent(await fs.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;
+		}
+		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.resolveConfig)(filePath);
+	const content = await prettier.default.format(parts.join("\n"), {
+		...prettierConfig,
+		parser: "markdown",
+		plugins: []
+	});
+	await fs.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.
+*/
+async function updateMarkdownDoc(filePath, overview, fields) {
+	let existing = null;
+	try {
+		existing = await fs.promises.readFile(filePath, "utf-8");
+	} catch {}
+	if (existing !== null) {
+		const updated = mergeMarkdownContent(existing, overview, fields);
+		if (updated !== existing) await fs.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.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);
+}
+/**
+* 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 = [];
+	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");
+}
+const testing = { mergeMarkdownContent };
+//#endregion
+exports.getMarkdownFilePath = getMarkdownFilePath;
+exports.maybeReadMarkdownFile = maybeReadMarkdownFile;
+exports.parseMarkdownContent = parseMarkdownContent;
+exports.testing = testing;
+exports.updateMarkdownDoc = updateMarkdownDoc;
+exports.writeMarkdownDoc = writeMarkdownDoc;
+
+//# sourceMappingURL=markdown.cjs.map

package/build/docs/markdown.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdown.cjs","names":["resolveConfig","join"],"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":"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"}

package/build/docs/{markdown.d.ts → markdown.d.cts}

@@ -1,19 +1,20 @@
-export interface ParsedDoc {
-    overview: string;
-    fields: Record<string, string>;
+//#region src/docs/markdown.d.ts
+interface ParsedDoc {
+  overview: string;
+  fields: Record<string, string>;
 }
 /** Read and parse a .md file if it exists, returning undefined if it doesn't. */
-export declare function maybeReadMarkdownFile(filePath: string): Promise<ParsedDoc | undefined>;
+declare function maybeReadMarkdownFile(filePath: string): Promise<ParsedDoc | undefined>;
 /** Reads a basic `overview` and per-field docs out of md content. */
-export declare function parseMarkdownContent(content: string): ParsedDoc;
+declare function parseMarkdownContent(content: string): ParsedDoc;
 /** Create a new .md file from scratch (used only for initial backfill when no .md exists). */
-export declare function writeMarkdownDoc(filePath: string, overview: string, fields?: Record<string, string>): Promise<void>;
+declare function writeMarkdownDoc(filePath: string, overview: string, fields?: Record<string, string>): Promise<void>;
 /**
  * Update an existing .md file, merging in new/changed content without stomping user content.
  * If the file doesn't exist, creates it from scratch.
  */
-export declare function updateMarkdownDoc(filePath: string, overview: string | undefined, fields: Record<string, string>): Promise<void>;
-export declare function getMarkdownFilePath(entitiesDir: string, entityName: string): string;
+declare function updateMarkdownDoc(filePath: string, overview: string | undefined, fields: Record<string, string>): Promise<void>;
+declare function getMarkdownFilePath(entitiesDir: string, entityName: string): string;
 /**
  * Merge updates into an existing .md file, preserving all user content.
  *
@@ -23,7 +24,9 @@ export declare function getMarkdownFilePath(entitiesDir: string, entityName: str
  * - All other content (custom sections, tables, etc.) is preserved verbatim
  */
 declare function mergeMarkdownContent(existing: string, overview: string | undefined, fields: Record<string, string>): string;
-export declare const testing: {
-    mergeMarkdownContent: typeof mergeMarkdownContent;
+declare const testing: {
+  mergeMarkdownContent: typeof mergeMarkdownContent;
 };
-export {};
+//#endregion
+export { ParsedDoc, getMarkdownFilePath, maybeReadMarkdownFile, parseMarkdownContent, testing, updateMarkdownDoc, writeMarkdownDoc };
+//# sourceMappingURL=markdown.d.cts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"markdown.d.cts","names":[],"sources":["../../src/docs/markdown.ts"],"mappings":";UAKiB;EACf;EACA,QAAQ;;;iBAIY,sBAAsB,mBAAmB,QAAQ;;iBAUvD,qBAAqB,kBAAkB;;iBAiDjC,iBACpB,kBACA,kBACA,SAAS,yBACR;;;;;iBAgCmB,kBACpB,kBACA,8BACA,QAAQ,yBACP;iBAkBa,oBAAoB,qBAAqB;;;;;;;;;iBAqBhD,qBAAqB,kBAAkB,8BAA8B,QAAQ;cA+EzE;+BAAA"}

package/build/docs/markdown.d.mts

@@ -0,0 +1,32 @@
+//#region src/docs/markdown.d.ts
+interface ParsedDoc {
+  overview: string;
+  fields: Record<string, string>;
+}
+/** Read and parse a .md file if it exists, returning undefined if it doesn't. */
+declare function maybeReadMarkdownFile(filePath: string): Promise<ParsedDoc | undefined>;
+/** Reads a basic `overview` and per-field docs out of md content. */
+declare function parseMarkdownContent(content: string): ParsedDoc;
+/** Create a new .md file from scratch (used only for initial backfill when no .md exists). */
+declare function writeMarkdownDoc(filePath: string, overview: string, fields?: Record<string, string>): Promise<void>;
+/**
+ * Update an existing .md file, merging in new/changed content without stomping user content.
+ * If the file doesn't exist, creates it from scratch.
+ */
+declare function updateMarkdownDoc(filePath: string, overview: string | undefined, fields: Record<string, string>): Promise<void>;
+declare function getMarkdownFilePath(entitiesDir: string, entityName: string): string;
+/**
+ * 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
+ */
+declare function mergeMarkdownContent(existing: string, overview: string | undefined, fields: Record<string, string>): string;
+declare const testing: {
+  mergeMarkdownContent: typeof mergeMarkdownContent;
+};
+//#endregion
+export { ParsedDoc, getMarkdownFilePath, maybeReadMarkdownFile, parseMarkdownContent, testing, updateMarkdownDoc, writeMarkdownDoc };
+//# sourceMappingURL=markdown.d.mts.map

package/build/docs/markdown.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdown.d.mts","names":[],"sources":["../../src/docs/markdown.ts"],"mappings":";UAKiB;EACf;EACA,QAAQ;;;iBAIY,sBAAsB,mBAAmB,QAAQ;;iBAUvD,qBAAqB,kBAAkB;;iBAiDjC,iBACpB,kBACA,kBACA,SAAS,yBACR;;;;;iBAgCmB,kBACpB,kBACA,8BACA,QAAQ,yBACP;iBAkBa,oBAAoB,qBAAqB;;;;;;;;;iBAqBhD,qBAAqB,kBAAkB,8BAA8B,QAAQ;cA+EzE;+BAAA"}