joist-codegen 2.0.3 → 2.1.0-next.2

package/build/docs/index.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.test.d.ts","sourceRoot":"","sources":["../../src/docs/index.test.ts"],"names":[],"mappings":""}

package/build/docs/index.test.js

@@ -0,0 +1,89 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs_1 = require("fs");
+const os_1 = require("os");
+const path_1 = require("path");
+const index_1 = require("./index");
+let testDir;
+beforeEach(async () => {
+    testDir = await fs_1.promises.mkdtemp((0, path_1.join)((0, os_1.tmpdir)(), "joist-docs-test-"));
+});
+afterEach(async () => {
+    await fs_1.promises.rm(testDir, { recursive: true, force: true });
+});
+describe("syncDocs", () => {
+    it("syncs markdown overview into ts file with @generated tag", async () => {
+        await fs_1.promises.writeFile((0, path_1.join)(testDir, "Author.ts"), "export class Author extends AuthorCodegen {}", "utf-8");
+        await fs_1.promises.writeFile((0, path_1.join)(testDir, "Author.md"), "## Overview\nThe Author entity.\n", "utf-8");
+        await (0, index_1.syncDocs)(testDir, ["Author"]);
+        const result = await fs_1.promises.readFile((0, path_1.join)(testDir, "Author.ts"), "utf-8");
+        expect(result).toContain("The Author entity.");
+        expect(result).toContain("@generated Author.md");
+    });
+    it("syncs field docs into ts file", async () => {
+        const ts = ["export class Author extends AuthorCodegen {", '  readonly firstName: string = "";', "}"].join("\n");
+        const md = ["## Overview", "", "## Fields", "", "### firstName", "", "The first name.", ""].join("\n");
+        await fs_1.promises.writeFile((0, path_1.join)(testDir, "Author.ts"), ts, "utf-8");
+        await fs_1.promises.writeFile((0, path_1.join)(testDir, "Author.md"), md, "utf-8");
+        await (0, index_1.syncDocs)(testDir, ["Author"]);
+        const result = await fs_1.promises.readFile((0, path_1.join)(testDir, "Author.ts"), "utf-8");
+        expect(result).toContain("The first name.");
+        expect(result).toContain("@generated Author.md");
+    });
+    it("backfills md from ts jsdoc when md does not exist", async () => {
+        const ts = ["/** The Author entity. */", "export class Author extends AuthorCodegen {}"].join("\n");
+        await fs_1.promises.writeFile((0, path_1.join)(testDir, "Author.ts"), ts, "utf-8");
+        await (0, index_1.syncDocs)(testDir, ["Author"]);
+        const md = await fs_1.promises.readFile((0, path_1.join)(testDir, "Author.md"), "utf-8");
+        expect(md).toContain("The Author entity.");
+    });
+    it("skips entities on second run when files are unchanged", async () => {
+        const bare = "export class Author extends AuthorCodegen {}";
+        await fs_1.promises.writeFile((0, path_1.join)(testDir, "Author.ts"), bare, "utf-8");
+        await fs_1.promises.writeFile((0, path_1.join)(testDir, "Author.md"), "## Overview\nThe Author entity.\n", "utf-8");
+        // First run — processes, writes JSDoc into .ts, and caches the resulting mtimes
+        await (0, index_1.syncDocs)(testDir, ["Author"]);
+        const firstResult = await fs_1.promises.readFile((0, path_1.join)(testDir, "Author.ts"), "utf-8");
+        expect(firstResult).toContain("The Author entity.");
+        // Snapshot the post-run mtimes (these are what the cache recorded)
+        const tsPath = (0, path_1.join)(testDir, "Author.ts");
+        const mdPath = (0, path_1.join)(testDir, "Author.md");
+        const tsStat = await fs_1.promises.stat(tsPath);
+        const mdStat = await fs_1.promises.stat(mdPath);
+        // Revert .ts to the bare version (no JSDoc) but restore the post-run mtime
+        // so the cache thinks nothing changed. If syncDocs re-processes, the overview
+        // would be re-injected; if it correctly skips, the bare content survives.
+        await fs_1.promises.writeFile(tsPath, bare, "utf-8");
+        await fs_1.promises.utimes(tsPath, tsStat.atimeMs / 1000, tsStat.mtimeMs / 1000);
+        await fs_1.promises.utimes(mdPath, mdStat.atimeMs / 1000, mdStat.mtimeMs / 1000);
+        // Second run — should skip because mtimes haven't changed
+        await (0, index_1.syncDocs)(testDir, ["Author"]);
+        const secondResult = await fs_1.promises.readFile((0, path_1.join)(testDir, "Author.ts"), "utf-8");
+        // If the cache correctly skipped, the bare content is still there (no JSDoc injected)
+        expect(secondResult).toBe(bare);
+    });
+    it("re-processes entity when md file changes", async () => {
+        const ts = ["export class Author extends AuthorCodegen {", '  readonly firstName: string = "";', "}"].join("\n");
+        await fs_1.promises.writeFile((0, path_1.join)(testDir, "Author.ts"), ts, "utf-8");
+        await fs_1.promises.writeFile((0, path_1.join)(testDir, "Author.md"), "## Overview\nVersion one.\n", "utf-8");
+        await (0, index_1.syncDocs)(testDir, ["Author"]);
+        const first = await fs_1.promises.readFile((0, path_1.join)(testDir, "Author.ts"), "utf-8");
+        expect(first).toContain("Version one.");
+        // Wait a tick to ensure mtime differs
+        await new Promise((r) => setTimeout(r, 50));
+        await fs_1.promises.writeFile((0, path_1.join)(testDir, "Author.md"), "## Overview\nVersion two.\n", "utf-8");
+        await (0, index_1.syncDocs)(testDir, ["Author"]);
+        const second = await fs_1.promises.readFile((0, path_1.join)(testDir, "Author.ts"), "utf-8");
+        expect(second).toContain("Version two.");
+        expect(second).not.toContain("Version one.");
+    });
+    it("handles entities with no md file", async () => {
+        await fs_1.promises.writeFile((0, path_1.join)(testDir, "Author.ts"), "export class Author extends AuthorCodegen {}", "utf-8");
+        // Should not throw
+        await (0, index_1.syncDocs)(testDir, ["Author"]);
+        // No md created since there's no jsdoc to backfill
+        const files = await fs_1.promises.readdir(testDir);
+        expect(files).toMatchObject(["Author.ts"]);
+    });
+});
+//# sourceMappingURL=index.test.js.map

package/build/docs/index.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.test.js","sourceRoot":"","sources":["../../src/docs/index.test.ts"],"names":[],"mappings":"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"}

package/build/docs/markdown.d.ts

@@ -0,0 +1,30 @@
+export 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>;
+/** Reads a basic `overview` and per-field docs out of md content. */
+export 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>;
+/**
+ * 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;
+/**
+ * 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;
+export declare const testing: {
+    mergeMarkdownContent: typeof mergeMarkdownContent;
+};
+export {};
+//# sourceMappingURL=markdown.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"markdown.d.ts","sourceRoot":"","sources":["../../src/docs/markdown.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,SAAS;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAChC;AAED,iFAAiF;AACjF,wBAAsB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC,CAO5F;AAED,qEAAqE;AACrE,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CA8C/D;AAED,8FAA8F;AAC9F,wBAAsB,gBAAgB,CACpC,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC9B,OAAO,CAAC,IAAI,CAAC,CAmBf;AAED;;;GAGG;AACH,wBAAsB,iBAAiB,CACrC,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC7B,OAAO,CAAC,IAAI,CAAC,CAgBf;AAED,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAEnF;AAWD;;;;;;;GAOG;AACH,iBAAS,oBAAoB,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CA6EpH;AAED,eAAO,MAAM,OAAO;;CAA2B,CAAC"}

package/build/docs/markdown.js

@@ -0,0 +1,201 @@
+"use strict";
+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");
+/** 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;
+    }
+}
+/** 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")])),
+    };
+}
+/** 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("");
+        }
+    }
+    await fs_1.promises.writeFile(filePath, parts.join("\n"), "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_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);
+    }
+}
+function getMarkdownFilePath(entitiesDir, entityName) {
+    return (0, path_1.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 = [];
+    // 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");
+}
+exports.testing = { mergeMarkdownContent };
+//# sourceMappingURL=markdown.js.map

package/build/docs/markdown.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdown.js","sourceRoot":"","sources":["../../src/docs/markdown.ts"],"names":[],"mappings":"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"}

package/build/docs/markdown.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=markdown.test.d.ts.map

package/build/docs/markdown.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdown.test.d.ts","sourceRoot":"","sources":["../../src/docs/markdown.test.ts"],"names":[],"mappings":""}

package/build/docs/markdown.test.js

@@ -0,0 +1,240 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const markdown_1 = require("./markdown");
+const { mergeMarkdownContent } = markdown_1.testing;
+describe("markdown", () => {
+    describe("parseMarkdownContent", () => {
+        it("parses overview and fields", () => {
+            const md = [
+                "## Overview",
+                "This is the Author entity.",
+                "",
+                "## Fields",
+                "",
+                "### firstName",
+                "",
+                "The author's first name.",
+                "",
+                "### lastName",
+                "",
+                "The author's last name.",
+                "",
+            ].join("\n");
+            expect((0, markdown_1.parseMarkdownContent)(md)).toEqual({
+                overview: "This is the Author entity.",
+                fields: {
+                    firstName: "The author's first name.",
+                    lastName: "The author's last name.",
+                },
+            });
+        });
+        it("handles multi-line overview", () => {
+            const md = ["## Overview", "Line one.", "", "Line two after blank.", "", "## Fields", ""].join("\n");
+            expect((0, markdown_1.parseMarkdownContent)(md)).toEqual({
+                overview: "Line one.\n\nLine two after blank.",
+                fields: {},
+            });
+        });
+        it("handles multi-line field docs", () => {
+            const md = [
+                "## Overview",
+                "Entity doc.",
+                "",
+                "## Fields",
+                "",
+                "### notes",
+                "First paragraph.",
+                "",
+                "Second paragraph.",
+                "",
+            ].join("\n");
+            expect((0, markdown_1.parseMarkdownContent)(md)).toEqual({
+                overview: "Entity doc.",
+                fields: {
+                    notes: "First paragraph.\n\nSecond paragraph.",
+                },
+            });
+        });
+        it("returns empty strings when sections are empty", () => {
+            const md = "## Overview\n\n## Fields\n";
+            expect((0, markdown_1.parseMarkdownContent)(md)).toEqual({
+                overview: "",
+                fields: {},
+            });
+        });
+        it("ignores unknown sections", () => {
+            const md = [
+                "## Overview",
+                "The overview.",
+                "",
+                "## SomeOtherSection",
+                "Should be ignored.",
+                "",
+                "## Fields",
+                "",
+                "### name",
+                "The name.",
+                "",
+            ].join("\n");
+            expect((0, markdown_1.parseMarkdownContent)(md)).toEqual({
+                overview: "The overview.",
+                fields: { name: "The name." },
+            });
+        });
+        it("parses field docs with markdown tables", () => {
+            const md = [
+                "## Overview",
+                "Entity.",
+                "",
+                "## Fields",
+                "",
+                "### status",
+                "",
+                "The current status. Possible values:",
+                "",
+                "| Value | Meaning |",
+                "|-------|---------|",
+                "| ACTIVE | Currently active |",
+                "| INACTIVE | No longer active |",
+                "",
+            ].join("\n");
+            expect((0, markdown_1.parseMarkdownContent)(md)).toMatchObject({
+                fields: {
+                    status: [
+                        "The current status. Possible values:",
+                        "",
+                        "| Value | Meaning |",
+                        "|-------|---------|",
+                        "| ACTIVE | Currently active |",
+                        "| INACTIVE | No longer active |",
+                    ].join("\n"),
+                },
+            });
+        });
+    });
+    describe("mergeMarkdownContent", () => {
+        it("preserves custom sections between Overview and Fields", () => {
+            const existing = [
+                "## Overview",
+                "Old overview.",
+                "",
+                "## Business Rules",
+                "",
+                "| Rule | Description |",
+                "|------|-------------|",
+                "| no nulls | Name is required |",
+                "",
+                "## Fields",
+                "",
+                "### name",
+                "",
+                "The name.",
+                "",
+            ].join("\n");
+            const result = mergeMarkdownContent(existing, "New overview.", {});
+            expect(result).toBe([
+                "## Overview",
+                "New overview.",
+                "",
+                "## Business Rules",
+                "",
+                "| Rule | Description |",
+                "|------|-------------|",
+                "| no nulls | Name is required |",
+                "",
+                "## Fields",
+                "",
+                "### name",
+                "",
+                "The name.",
+                "",
+            ].join("\n"));
+        });
+        it("preserves custom sections after Fields", () => {
+            const existing = [
+                "## Overview",
+                "The overview.",
+                "",
+                "## Fields",
+                "",
+                "### name",
+                "",
+                "The name.",
+                "",
+                "## Notes",
+                "",
+                "```typescript",
+                "const a = 1;",
+                "```",
+                "",
+            ].join("\n");
+            const result = mergeMarkdownContent(existing, undefined, { age: "The age." });
+            expect(result).toBe([
+                "## Overview",
+                "The overview.",
+                "",
+                "## Fields",
+                "",
+                "### name",
+                "",
+                "The name.",
+                "",
+                "### age",
+                "",
+                "The age.",
+                "",
+                "## Notes",
+                "",
+                "```typescript",
+                "const a = 1;",
+                "```",
+                "",
+            ].join("\n"));
+        });
+        it("appends new fields without touching existing ones", () => {
+            const existing = [
+                "## Overview",
+                "The overview.",
+                "",
+                "## Fields",
+                "",
+                "### name",
+                "",
+                "User-written name doc with **bold** text.",
+                "",
+            ].join("\n");
+            const result = mergeMarkdownContent(existing, undefined, { age: "The age." });
+            expect(result).toBe([
+                "## Overview",
+                "The overview.",
+                "",
+                "## Fields",
+                "",
+                "### name",
+                "",
+                "User-written name doc with **bold** text.",
+                "",
+                "### age",
+                "",
+                "The age.",
+                "",
+            ].join("\n"));
+        });
+        it("replaces an existing field's doc", () => {
+            const existing = ["## Overview", "The overview.", "", "## Fields", "", "### name", "", "Old name doc.", ""].join("\n");
+            const result = mergeMarkdownContent(existing, undefined, { name: "New name doc." });
+            expect(result).toBe(["## Overview", "The overview.", "", "## Fields", "", "### name", "", "New name doc.", ""].join("\n"));
+        });
+        it("creates Fields section if it doesn't exist", () => {
+            const existing = ["## Overview", "The overview.", ""].join("\n");
+            const result = mergeMarkdownContent(existing, undefined, { name: "The name." });
+            expect(result).toBe(["## Overview", "The overview.", "", "", "## Fields", "", "### name", "", "The name.", ""].join("\n"));
+        });
+        it("does not modify content when nothing to merge", () => {
+            const existing = ["## Overview", "The overview.", "", "## Fields", "", "### name", "", "The name.", ""].join("\n");
+            const result = mergeMarkdownContent(existing, undefined, {});
+            expect(result).toBe(existing);
+        });
+    });
+});
+//# sourceMappingURL=markdown.test.js.map

package/build/docs/markdown.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdown.test.js","sourceRoot":"","sources":["../../src/docs/markdown.test.ts"],"names":[],"mappings":"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"}

package/build/docs/parsing.d.ts

@@ -0,0 +1,42 @@
+import type { namedTypes } from "ast-types";
+import { ASTNode } from "jscodeshift";
+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;
+};
+export type MemberKind = "property" | "getter" | "setter" | "method";
+export interface MemberInfo {
+    kind: MemberKind;
+    name: string;
+    doc: string | undefined;
+    node: Commented;
+}
+export interface SourceEdit {
+    start: number;
+    end: number;
+    text: string;
+}
+/** Parse an entity .ts file and extract class + member JSDoc. */
+export 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:)
+ */
+export declare function buildJSDocEdit(node: Commented, text: string): SourceEdit;
+/** Apply edits to source by splicing in reverse order. */
+export declare function applyEdits(source: string, edits: SourceEdit[]): string;
+export {};
+//# sourceMappingURL=parsing.d.ts.map