@descent-vtt/spec-graph 0.2.0

package/dist/markdown.d.ts

@@ -0,0 +1,152 @@
+/**
+ * A structural Markdown scanner.
+ *
+ * This is deliberately **not** a CommonMark implementation. spec-graph needs six
+ * things from a document - front matter, headings, list items with their
+ * continuations, HTML comments, links, and a reliable map of what is code - and
+ * a full parser would cost a dependency tree, an AST walk, and a position
+ * mapping layer to get back the offsets we want in the first place.
+ *
+ * What the scanner does guarantee is the part that makes regex-based spec
+ * linters lie:
+ *
+ * - **Code never counts.** Fenced blocks, indented blocks and inline spans are
+ *   masked before a single link is extracted, so an example in a code sample
+ *   never becomes a graph edge.
+ * - **Items are blocks, not lines.** A list item owns its wrapped continuation
+ *   lines and its nested content, so a resolution written on the second line of
+ *   a bullet is found instead of missed.
+ * - **Everything carries absolute offsets.** No re-scanning, no drift between
+ *   the text a rule matched and the position it reports.
+ */
+import { type LineIndex } from './source.js';
+export interface Range {
+    readonly start: number;
+    readonly end: number;
+}
+export interface FrontMatter {
+    /** The body between the delimiters, exclusive. */
+    readonly raw: string;
+    /** Offset of the first character of `raw`. */
+    readonly start: number;
+    readonly end: number;
+    /** Offset just past the closing delimiter line. */
+    readonly bodyStart: number;
+}
+export interface ScannedLine {
+    /** 1-based. */
+    readonly line: number;
+    /** Offset of the raw line start. */
+    readonly start: number;
+    /** Offset just past the line, excluding its terminator. */
+    readonly end: number;
+    /** Offset of the first character after any block-quote markers. */
+    readonly contentStart: number;
+    /** Line text after block-quote markers, indentation intact. */
+    readonly content: string;
+    /** Indentation of `content`, tabs counted as four columns. */
+    readonly indent: number;
+    readonly blank: boolean;
+    readonly quoteDepth: number;
+    /** Inside a fenced or indented code block, fence delimiters included. */
+    readonly code: boolean;
+}
+export interface Heading {
+    readonly level: number;
+    readonly text: string;
+    /** GitHub-compatible anchor slug. */
+    readonly slug: string;
+    readonly start: number;
+    readonly end: number;
+    readonly line: number;
+}
+export interface ListItem {
+    /** The whole block: marker line plus continuations and nested content. */
+    readonly start: number;
+    readonly end: number;
+    /** Offset of the list marker itself. */
+    readonly markerStart: number;
+    readonly marker: string;
+    /** Offset where the item text begins, after marker and any checkbox. */
+    readonly textStart: number;
+    /** The character inside `[ ]`, or `null` when the item has no checkbox. */
+    readonly checkbox: string | null;
+    readonly checkboxStart: number | null;
+    /** First line of item text, trimmed. */
+    readonly firstLine: string;
+    /** Full item text including continuations and nested content. */
+    readonly body: string;
+    /**
+     * `body` with code and comments blanked out, same length and offsets.
+     *
+     * Anything that searches item text for meaning - resolution markers above
+     * all - must read this rather than `body`, or a fenced example nested under
+     * the item will close it.
+     */
+    readonly maskedBody: string;
+    readonly line: number;
+    /** How many list items enclose this one. Top-level items are `0`. */
+    readonly depth: number;
+    readonly indent: number;
+}
+export interface HtmlComment {
+    readonly start: number;
+    readonly end: number;
+    /** Text between `<!--` and `-->`. */
+    readonly inner: string;
+    readonly innerStart: number;
+    readonly line: number;
+}
+export type LinkForm = 'inline' | 'reference' | 'shortcut' | 'autolink' | 'wiki' | 'definition';
+export interface Link {
+    /** Visible label. Empty for autolinks and definitions. */
+    readonly text: string;
+    /** Destination as written: a path, a URL, or a reference label. */
+    readonly target: string;
+    /** Offset of the whole construct. */
+    readonly start: number;
+    readonly end: number;
+    /** Offset of `target` inside the source, for precise diagnostics. */
+    readonly targetStart: number;
+    readonly form: LinkForm;
+    readonly line: number;
+}
+export interface TableCell {
+    /** Cell text as written, trimmed. */
+    readonly text: string;
+    /** Offset of the trimmed text, so a finding can point at the cell itself. */
+    readonly start: number;
+    readonly end: number;
+}
+export interface TableRow {
+    readonly cells: readonly TableCell[];
+    readonly start: number;
+    readonly end: number;
+    readonly line: number;
+}
+export interface Table {
+    readonly start: number;
+    readonly end: number;
+    /** Header cells, trimmed. A table without a header row is not a table. */
+    readonly headers: readonly TableCell[];
+    readonly rows: readonly TableRow[];
+}
+export interface ScannedDocument {
+    readonly text: string;
+    readonly index: LineIndex;
+    readonly frontMatter: FrontMatter | null;
+    /** Offset where the body starts, after any front matter. */
+    readonly bodyStart: number;
+    readonly lines: readonly ScannedLine[];
+    readonly headings: readonly Heading[];
+    readonly listItems: readonly ListItem[];
+    readonly comments: readonly HtmlComment[];
+    readonly links: readonly Link[];
+    readonly tables: readonly Table[];
+    /** Code and comments blanked out, offsets and line breaks preserved. */
+    readonly masked: string;
+    /** True when the offset falls inside code, a comment, or front matter. */
+    isMasked(offset: number): boolean;
+}
+export declare function scanMarkdown(source: string): ScannedDocument;
+export declare function slugify(text: string): string;