@forge-ts/gen 0.7.1 → 0.8.0

package/dist/index.d.ts

@@ -395,6 +395,269 @@ interface MarkdownOptions {
  */
 declare function generateMarkdown(symbols: ForgeSymbol[], config: ForgeConfig, options?: MarkdownOptions): string;
 
+/**
+ * Mdast AST node builders and markdown serialization.
+ *
+ * Provides concise factory functions for constructing mdast trees
+ * and a serializer that produces well-formed markdown via remark-stringify.
+ *
+ * @internal
+ */
+/** Inline leaf node: literal text. */
+interface MdText {
+    type: "text";
+    value: string;
+}
+/** Inline leaf node: code span. */
+interface MdInlineCode {
+    type: "inlineCode";
+    value: string;
+}
+/** Inline container: strong emphasis (bold). */
+interface MdStrong {
+    type: "strong";
+    children: MdPhrasing[];
+}
+/** Inline container: emphasis (italic). */
+interface MdEmphasis {
+    type: "emphasis";
+    children: MdPhrasing[];
+}
+/** Inline container: hyperlink. */
+interface MdLink {
+    type: "link";
+    url: string;
+    children: MdPhrasing[];
+}
+/** Union of all inline (phrasing) content types. */
+type MdPhrasing = MdText | MdInlineCode | MdStrong | MdEmphasis | MdLink;
+/** Block node: heading (depth 1-6). */
+interface MdHeading {
+    type: "heading";
+    depth: 1 | 2 | 3 | 4 | 5 | 6;
+    children: MdPhrasing[];
+}
+/** Block node: paragraph. */
+interface MdParagraph {
+    type: "paragraph";
+    children: MdPhrasing[];
+}
+/** Block node: fenced code block. */
+interface MdCode {
+    type: "code";
+    lang?: string | null;
+    value: string;
+}
+/** Block node: blockquote. */
+interface MdBlockquote {
+    type: "blockquote";
+    children: MdBlock[];
+}
+/** Block node: raw HTML (including comments). */
+interface MdHtml {
+    type: "html";
+    value: string;
+}
+/** Block node: horizontal rule. */
+interface MdThematicBreak {
+    type: "thematicBreak";
+}
+/** List item container. */
+interface MdListItem {
+    type: "listItem";
+    spread?: boolean;
+    children: MdBlock[];
+}
+/** Block node: ordered or unordered list. */
+interface MdList {
+    type: "list";
+    ordered?: boolean;
+    spread?: boolean;
+    children: MdListItem[];
+}
+/** GFM table cell. */
+interface MdTableCell {
+    type: "tableCell";
+    children: MdPhrasing[];
+}
+/** GFM table row. */
+interface MdTableRow {
+    type: "tableRow";
+    children: MdTableCell[];
+}
+/** GFM table. */
+interface MdTable {
+    type: "table";
+    align?: ("left" | "center" | "right" | null)[];
+    children: MdTableRow[];
+}
+/** Union of all block content types. */
+type MdBlock = MdHeading | MdParagraph | MdCode | MdBlockquote | MdHtml | MdThematicBreak | MdList | MdTable;
+/** Document root. */
+interface MdRoot {
+    type: "root";
+    children: MdBlock[];
+}
+/**
+ * Concise factory functions for building mdast nodes.
+ *
+ * Usage:
+ * ```typescript
+ * const tree = md.root(
+ *   md.heading(2, md.text("API")),
+ *   md.table(null,
+ *     md.tableRow(md.tableCell(md.text("Name")), md.tableCell(md.text("Type"))),
+ *     md.tableRow(md.tableCell(md.inlineCode("id")), md.tableCell(md.text("string"))),
+ *   ),
+ * );
+ * ```
+ */
+declare const md: {
+    text: (value: string) => MdText;
+    inlineCode: (value: string) => MdInlineCode;
+    strong: (...children: MdPhrasing[]) => MdStrong;
+    emphasis: (...children: MdPhrasing[]) => MdEmphasis;
+    link: (url: string, ...children: MdPhrasing[]) => MdLink;
+    heading: (depth: 1 | 2 | 3 | 4 | 5 | 6, ...children: MdPhrasing[]) => MdHeading;
+    paragraph: (...children: MdPhrasing[]) => MdParagraph;
+    code: (lang: string, value: string) => MdCode;
+    blockquote: (...children: MdBlock[]) => MdBlockquote;
+    html: (value: string) => MdHtml;
+    thematicBreak: () => MdThematicBreak;
+    listItem: (...children: MdBlock[]) => MdListItem;
+    list: (items: MdListItem[], ordered?: boolean) => MdList;
+    tableCell: (...children: MdPhrasing[]) => MdTableCell;
+    tableRow: (...cells: MdTableCell[]) => MdTableRow;
+    table: (align: ("left" | "center" | "right" | null)[] | null, ...rows: MdTableRow[]) => MdTable;
+    root: (...children: MdBlock[]) => MdRoot;
+};
+/**
+ * Serialize an mdast tree to a well-formed markdown string.
+ *
+ * Uses remark-stringify with GFM table support. The serializer handles
+ * all escaping (pipes in table cells, special characters in text, etc.)
+ * so callers never need manual escape functions.
+ *
+ * @param tree - The mdast root node to serialize.
+ * @returns The serialized markdown string.
+ */
+declare function serializeMarkdown(tree: MdRoot): string;
+/**
+ * Truncate a string to at most maxLen chars.
+ * Avoids cutting inside backtick-delimited code spans to prevent
+ * broken inline code that would cause escaping issues.
+ */
+declare function truncate(text: string, maxLen?: number): string;
+/** Convert a label to a GitHub-compatible anchor slug. */
+declare function toAnchor(text: string): string;
+/**
+ * Strip extension from a link path and normalize to a slug.
+ * Produces bare slug links compatible with Mintlify and most SSGs.
+ */
+declare function slugLink(path: string): string;
+
+/**
+ * Shared markdown/MDX utilities powered by gray-matter and the unified/remark ecosystem.
+ *
+ * Provides:
+ * - Frontmatter parsing and serialization (gray-matter)
+ * - AST-aware MDX sanitization (remark-parse + position-based transforms)
+ * - AST-aware FORGE:AUTO section updates (remark-parse + position-based splicing)
+ *
+ * @internal
+ */
+
+/**
+ * Result of parsing frontmatter from markdown/MDX content.
+ * @public
+ */
+interface FrontmatterResult {
+    /** The body content without the frontmatter block. */
+    body: string;
+    /** The parsed frontmatter data as a key-value map. */
+    data: Record<string, unknown>;
+}
+/**
+ * Parse frontmatter from markdown/MDX content.
+ *
+ * Uses gray-matter for robust YAML parsing — handles multi-line values,
+ * quoted strings, and edge cases that regex-based stripping misses.
+ *
+ * @param content - The full file content including frontmatter.
+ * @returns The body (without frontmatter) and the parsed data object.
+ * @public
+ */
+declare function parseFrontmatter(content: string): FrontmatterResult;
+/**
+ * Serialize content with frontmatter prepended.
+ *
+ * Produces the standard format:
+ * ```
+ * ---
+ * key: value
+ * ---
+ *
+ * body
+ * ```
+ *
+ * @param body - The markdown body content (without frontmatter).
+ * @param data - The frontmatter fields to serialize.
+ * @returns The combined frontmatter + body string.
+ * @public
+ */
+declare function stringifyWithFrontmatter(body: string, data: Record<string, string | number | boolean>): string;
+/**
+ * Strip frontmatter from content, returning only the body.
+ *
+ * @param content - The full file content including frontmatter.
+ * @returns The body content without the frontmatter block.
+ * @public
+ */
+declare function stripFrontmatter(content: string): string;
+/**
+ * Parse a markdown string and extract inline (phrasing) content.
+ *
+ * Use for TSDoc text that may contain backtick code, bold, links, etc.
+ * The returned nodes can be spread into paragraphs, table cells, or
+ * any other context that accepts inline content.
+ *
+ * This prevents double-escaping: backticks become proper `inlineCode`
+ * nodes instead of text that gets escaped by the serializer.
+ *
+ * @param markdown - The TSDoc content string (may contain markdown).
+ * @returns Array of inline mdast nodes.
+ * @public
+ */
+declare function parseInline(markdown: string): MdPhrasing[];
+/**
+ * Parse a markdown string and extract block-level content.
+ *
+ * Use for multi-line TSDoc content that may contain headings,
+ * lists, blockquotes, code blocks, etc.
+ *
+ * @param markdown - The markdown string to parse.
+ * @returns Array of block-level mdast nodes.
+ * @public
+ */
+declare function parseBlocks(markdown: string): MdBlock[];
+/**
+ * Sanitize markdown content for MDX compatibility using AST-aware processing.
+ *
+ * Parses the document with remark to understand its structure, then applies
+ * targeted string replacements only to text and HTML comment nodes —
+ * code blocks, inline code, and frontmatter are automatically preserved.
+ *
+ * Transformations applied outside code:
+ * - HTML comments to MDX comments
+ * - Curly braces in text escaped (prevents MDX expression parsing)
+ * - Angle brackets around word chars escaped (prevents JSX tag parsing)
+ *
+ * @param content - The markdown content to sanitize.
+ * @returns The sanitized content safe for MDX consumption.
+ * @public
+ */
+declare function sanitizeForMdx(content: string): string;
+
 /** Options controlling README sync behaviour. */
 interface ReadmeSyncOptions {
     /** Include a "Documented with forge-ts" badge above the API table. */
@@ -555,4 +818,4 @@ interface GenerateOptions {
  */
 declare function generate(config: ForgeConfig, options?: GenerateOptions): Promise<ForgeResult>;
 
-export { type AdapterContext, DEFAULT_TARGET, type DevServerCommand, type DocPage, type GenerateOptions, type GeneratedFile, type MarkdownOptions, type ReadmeSyncOptions, type SSGAdapter, type SSGConfigFile, type SSGStyleGuide, type SSGTarget, type ScaffoldManifest, type SiteGeneratorOptions, type SkillPackage, escapeMdx, generate, generateDocSite, generateLlmsFullTxt, generateLlmsTxt, generateMarkdown, generateSSGConfigs, generateSkillMd, generateSkillPackage, getAdapter, getAvailableTargets, groupSymbolsByPackage, registerAdapter, syncReadme };
+export { type AdapterContext, DEFAULT_TARGET, type DevServerCommand, type DocPage, type FrontmatterResult, type GenerateOptions, type GeneratedFile, type MarkdownOptions, type ReadmeSyncOptions, type SSGAdapter, type SSGConfigFile, type SSGStyleGuide, type SSGTarget, type ScaffoldManifest, type SiteGeneratorOptions, type SkillPackage, escapeMdx, generate, generateDocSite, generateLlmsFullTxt, generateLlmsTxt, generateMarkdown, generateSSGConfigs, generateSkillMd, generateSkillPackage, getAdapter, getAvailableTargets, groupSymbolsByPackage, md, parseBlocks, parseFrontmatter, parseInline, registerAdapter, sanitizeForMdx, serializeMarkdown, slugLink, stringifyWithFrontmatter, stripFrontmatter, syncReadme, toAnchor, truncate };