@greyworld/code-check-core 1.0.0

package/dist/tools/ast-parser/markdown/parser.d.ts

@@ -0,0 +1,271 @@
+import { Node } from "commonmark";
+import type { MarkdownNode, MarkdownNodeType, ParserOptions, NodeVisitor, TypedVisitors } from "./types";
+/**
+ * MarkdownParser - CommonMark compliant markdown AST parser
+ *
+ * This parser uses the official commonmark.js library which is the reference
+ * implementation of the CommonMark specification.
+ *
+ * @example
+ * ```typescript
+ * const parser = new MarkdownParser();
+ * const ast = parser.parse("# Hello World\n\nThis is a paragraph.");
+ *
+ * // Walk the AST
+ * parser.walk(ast, (node, entering) => {
+ *     if (entering && node.type === "heading") {
+ *         console.log(`Found heading level ${node.level}`);
+ *     }
+ * });
+ * ```
+ */
+export declare class MarkdownParser {
+    private parser;
+    private enableFrontmatter;
+    /**
+     * Create a new MarkdownParser instance
+     *
+     * @param options - Parser configuration options
+     */
+    constructor(options?: ParserOptions);
+    /**
+     * Parse markdown text into an AST
+     *
+     * When front-matter parsing is enabled (default), the leading
+     * `---...---` YAML block is extracted, parsed, and inserted as a
+     * "frontmatter" node at the beginning of the document's children.
+     *
+     * @param markdown - The markdown text to parse
+     * @returns The root node of the AST (document node)
+     */
+    parse(markdown: string): MarkdownNode;
+    /**
+     * Parse markdown and return the raw commonmark Node
+     *
+     * This is useful when you need access to the full commonmark API
+     *
+     * @param markdown - The markdown text to parse
+     * @returns The raw commonmark Node
+     */
+    parseRaw(markdown: string): Node;
+    /**
+     * Walk the AST and call the visitor function for each node
+     *
+     * @param ast - The root node to start walking from
+     * @param visitor - Function called for each node (entering and leaving)
+     */
+    walk(ast: MarkdownNode, visitor: NodeVisitor): void;
+    /**
+     * Walk the AST with type-specific visitors
+     *
+     * @param ast - The root node to start walking from
+     * @param visitors - Object mapping node types to visitor functions
+     */
+    walkTyped(ast: MarkdownNode, visitors: TypedVisitors): void;
+    /**
+     * Find all nodes of a specific type
+     *
+     * @param ast - The root node to search from
+     * @param type - The node type to find
+     * @returns Array of matching nodes
+     */
+    findByType(ast: MarkdownNode, type: MarkdownNodeType): MarkdownNode[];
+    /**
+     * Find all nodes matching a predicate
+     *
+     * @param ast - The root node to search from
+     * @param predicate - Function that returns true for matching nodes
+     * @returns Array of matching nodes
+     */
+    findAll(ast: MarkdownNode, predicate: (node: MarkdownNode) => boolean): MarkdownNode[];
+    /**
+     * Find the first node matching a predicate
+     *
+     * @param ast - The root node to search from
+     * @param predicate - Function that returns true for matching nodes
+     * @returns The first matching node, or null if not found
+     */
+    findFirst(ast: MarkdownNode, predicate: (node: MarkdownNode) => boolean): MarkdownNode | null;
+    /**
+     * Get all text content from the AST
+     *
+     * @param ast - The root node to extract text from
+     * @returns Combined text content
+     */
+    getTextContent(ast: MarkdownNode): string;
+    /**
+     * Get all headings from the document
+     *
+     * @param ast - The root node
+     * @returns Array of heading nodes with their text content
+     */
+    getHeadings(ast: MarkdownNode): Array<{
+        level: number;
+        text: string;
+        node: MarkdownNode;
+    }>;
+    /**
+     * Get all links from the document
+     *
+     * @param ast - The root node
+     * @returns Array of link information
+     */
+    getLinks(ast: MarkdownNode): Array<{
+        url: string;
+        title: string | null;
+        text: string;
+        node: MarkdownNode;
+    }>;
+    /**
+     * Get all images from the document
+     *
+     * @param ast - The root node
+     * @returns Array of image information
+     */
+    getImages(ast: MarkdownNode): Array<{
+        src: string;
+        alt: string;
+        title: string | null;
+        node: MarkdownNode;
+    }>;
+    /**
+     * Get all code blocks from the document
+     *
+     * @param ast - The root node
+     * @returns Array of code block information
+     */
+    getCodeBlocks(ast: MarkdownNode): Array<{
+        language: string | null;
+        code: string;
+        node: MarkdownNode;
+    }>;
+    /**
+     * Get the parsed front-matter data from the document AST
+     *
+     * @param ast - The root document node
+     * @returns The parsed YAML data object, or null if no
+     *          front-matter is present
+     */
+    getFrontmatter(ast: MarkdownNode): Record<string, unknown> | null;
+    /**
+     * Return the document body children, excluding the frontmatter node.
+     */
+    getBodyChildren(doc: MarkdownNode): MarkdownNode[];
+    /**
+     * Extract a heading section's content nodes.
+     *
+     * Finds the first heading at `level` whose text matches `title`,
+     * then returns all sibling nodes from that heading up to (but not
+     * including) the next heading at the same or higher level.
+     *
+     * @returns The content nodes, or null if the heading is not found.
+     */
+    getSection(doc: MarkdownNode, level: number, title: string): MarkdownNode[] | null;
+    /**
+     * Text-line variant of getSection for rules that need raw-line
+     * processing (e.g. regex-based bullet validation).
+     *
+     * @returns The lines within the section and the 1-based start line
+     *          number, or null if the heading is not found.
+     */
+    getSectionText(source: string, level: number, title: string): {
+        lines: string[];
+        startLine: number;
+    } | null;
+    /**
+     * Extract the original source lines that correspond to an AST node,
+     * using its `sourceRange`.
+     *
+     * Returns the same shape as `getSectionText` so that rules can switch
+     * seamlessly between section-level and node-level text processing.
+     *
+     * @param source - The full markdown source text
+     * @param node   - An AST node with a non-null `sourceRange`
+     * @returns The source lines spanning the node and the 1-based start
+     *          line number, or null if the node has no `sourceRange`.
+     */
+    getNodeText(source: string, node: MarkdownNode): {
+        lines: string[];
+        startLine: number;
+    } | null;
+    /**
+     * Get the logical text lines of a node by walking its AST.
+     *
+     * Unlike {@link getNodeText}, which returns verbatim source lines,
+     * this method merges soft-break wrapped lines into single logical
+     * lines.  Hard line breaks (trailing double-space or backslash)
+     * still produce separate logical lines.
+     *
+     * For container nodes (list, item, block_quote, document) the
+     * method recurses into block-level children so that each
+     * paragraph / heading yields its own set of logical lines.
+     *
+     * @param source - The full markdown source text
+     * @param node   - An AST node with a non-null `sourceRange`
+     * @returns Logical text lines and the 1-based start line number,
+     *          or null if the node has no `sourceRange`.
+     */
+    getLogicalLines(source: string, node: MarkdownNode): {
+        lines: string[];
+        startLine: number;
+    } | null;
+    /**
+     * Flatten markdown list nodes into their direct item nodes.
+     */
+    getBulletItems(listNodes: MarkdownNode[]): MarkdownNode[];
+    /**
+     * Extract a bullet item's first line in normalized "* " form.
+     */
+    getItemBulletLine(source: string, item: MarkdownNode): {
+        text: string;
+        startLine: number;
+    } | null;
+    /**
+     * Find the next sibling of `anchor` within `parent`'s children.
+     *
+     * If a predicate is given, skips siblings that don't match.
+     * Only looks forward (nodes after `anchor`), returns the first match.
+     */
+    getNextSibling(parent: MarkdownNode, anchor: MarkdownNode, predicate?: (node: MarkdownNode) => boolean): MarkdownNode | null;
+    /**
+     * Filter nodes by type from a flat node list.
+     */
+    filterByType(nodes: MarkdownNode[], type: MarkdownNodeType): MarkdownNode[];
+    /**
+     * Check whether `parent` has a direct child matching the predicate
+     * at the given position.
+     */
+    hasChild(parent: MarkdownNode, predicate: (node: MarkdownNode) => boolean, position?: "first" | "last" | "any"): boolean;
+    /**
+     * Extract front-matter from the beginning of a markdown string.
+     *
+     * @returns An object containing the frontmatter MarkdownNode and
+     *          the remaining body text, or null if no front-matter
+     *          was found.
+     */
+    private extractFrontmatter;
+    /**
+     * Shift all sourceRange line numbers in the subtree by `offset`.
+     * Used after frontmatter extraction so that body-node positions
+     * are absolute with respect to the original document.
+     */
+    private offsetSourceRanges;
+    /**
+     * Merge soft-wrapped source lines into logical lines.
+     *
+     * A line ending with two or more trailing spaces or a backslash is
+     * treated as a CommonMark hard line break — the logical line is
+     * split there.  All other intra-paragraph newlines are soft breaks
+     * and are collapsed into a single space.
+     *
+     * Continuation indentation (leading whitespace on lines after the
+     * first) is stripped before merging so that list-item continuation
+     * and block-quote prefixes do not leak into the logical text.
+     */
+    private mergeSoftWraps;
+    /**
+     * Internal recursive walk implementation
+     */
+    private walkNode;
+}
+//# sourceMappingURL=parser.d.ts.map

package/dist/tools/ast-parser/markdown/parser.d.ts.map

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