@descent-vtt/spec-graph 0.7.0 → 0.9.0

package/dist/markdown.d.ts

@@ -1,166 +1,58 @@
 /**
- * A structural Markdown scanner.
+ * What spec-graph reads out of a Markdown document.
  *
- * 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.
+ * The scan is spec-core's, copied into `src/vendor/spec-core/markdown/`: one
+ * pass that is exact about code and comments, as CommonMark is, and simple about
+ * the rest (ADR-0001). It started as this file, and the guarantees it was
+ * written for came with it: code never counts, items are blocks and not lines,
+ * and everything carries absolute offsets.
  *
- * What the scanner does guarantee is the part that makes regex-based spec
- * linters lie:
+ * What stays here is what spec-graph decides about the scan, which no other
+ * tool has to agree with: which links cite something, which anchors a heading
+ * answers to, and which lines are Markdown at all.
+ */
+import type { FrontMatterBlock, Heading, Link, MarkdownScan, ScannedLine } from './vendor/spec-core/markdown/index.js';
+export { scanMarkdown, slugify } from './vendor/spec-core/markdown/index.js';
+export type { Heading, HtmlComment, Link, LinkForm, ListItem, ScannedLine, Table, TableCell, TableRow, } from './vendor/spec-core/markdown/index.js';
+export type { Range } from './vendor/spec-core/text/index.js';
+/** A scanned document, under the name the API has always given it. */
+export type ScannedDocument = MarkdownScan;
+/** The front-matter block at the top of a document, under the name the API has always given it. */
+export type FrontMatter = FrontMatterBlock;
+/**
+ * Whether a line's content is Markdown.
+ *
+ * Code, the four raw-text HTML elements and front matter are not, for the same
+ * reason: a heading, a status or an item written in one is an example or data,
+ * and never a statement the document makes.
+ */
+export declare function isMarkdownLine(line: ScannedLine): boolean;
+/**
+ * Whether a line holds a comment and nothing else.
+ *
+ * For a reader that takes the first line of a section as its value, which is
+ * what a status section is. A template's hint written above the value - `<!--
+ * proposed | accepted -->` - is not the value, and neither is a directive. A
+ * line that goes on past its comment, `<!-- hint --> Accepted`, is still read.
+ */
+export declare function isOnlyComment(scanned: ScannedDocument, line: ScannedLine): boolean;
+/**
+ * The links that cite something.
+ *
+ * An image shows a file and cites nothing: a diagram of a decision is not a
+ * dependency on it, and a missing picture is a broken page, not a broken
+ * relation. So images are not references, as they never were. A wiki embed,
+ * `![[0007-sharding]]`, is the exception - it transcludes the note it names,
+ * which is the strongest citation a wiki can write - and spec-graph has always
+ * read it as one.
+ */
+export declare function referenceLinks(scanned: ScannedDocument): Link[];
+/**
+ * The anchors a set of headings answers to.
  *
- * - **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.
+ * Each heading's slug, and the anchor GitHub gives it, which is the slug with
+ * `-1`, `-2` and so on for the second and later headings that slug alike. A
+ * link written against the rendered page uses the anchor; one written by hand
+ * uses the slug, and for any heading but a repeat the two are one.
  */
-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 or a URL. */
-    readonly target: string;
-    /** Offset of the whole construct. */
-    readonly start: number;
-    readonly end: number;
-    /**
-     * Offset of `target` inside the source, for precise diagnostics.
-     *
-     * For a reference link this is inside the definition, not inside the use:
-     * `[design][one]` has no destination of its own, and the line a human edits
-     * to fix it is the one that says what `one` points at.
-     */
-    readonly targetStart: number;
-    /**
-     * The reference label, for the two forms written with one.
-     *
-     * `null` everywhere else. Kept because `target` is the destination the label
-     * stands for, and a report quoting `[design][docs/gone.md]` would be quoting
-     * something the author never wrote.
-     */
-    readonly label: string | null;
-    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;
+export declare function anchorsOf(headings: readonly Heading[]): Set<string>;