@descent-vtt/spec-brief 0.1.0

package/dist/links.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Relative links, and keeping them true when a file moves.
+ *
+ * Both repositories this tool was measured against archive a brief by moving
+ * it one directory down and then adding `../` to its links by hand. A move
+ * that breaks links is a defect the move introduced, so the move repairs them:
+ * the file's own relative links, and the links other live briefs hold to it.
+ */
+import { type Scan } from './markdown.js';
+/** A destination that is a path relative to the file holding it. */
+export declare function isRelativeTarget(target: string): boolean;
+/** The path part of a destination and whatever follows it: `?query` or `#fragment`. */
+export declare function splitTarget(target: string): {
+    readonly path: string;
+    readonly suffix: string;
+};
+/** Normalises a repository-relative path and refuses one that leaves the repository. */
+export declare function normalisePath(path: string): string;
+/** Whether a repository path lies inside a directory. */
+export declare function isInside(path: string, directory: string): boolean;
+export declare function dirOf(path: string): string;
+/** A relative path resolved against a directory, or `null` when it climbs out of the repository. */
+export declare function resolveFrom(directory: string, relative: string): string | null;
+/** The relative path from a directory to a repository path. */
+export declare function relativePath(fromDirectory: string, to: string): string;
+export interface LinkRewrite {
+    readonly lines: string[];
+    readonly count: number;
+}
+/**
+ * Rewrites relative destinations for a file read from `directory` that will
+ * be read from `newDirectory`. `retarget` maps the repository path a
+ * destination resolves to now onto the one it should resolve to afterwards,
+ * which differs only for a file that is itself moving.
+ */
+export declare function rewriteLinks(scanned: Scan, directory: string, newDirectory: string, retarget: (resolved: string) => string): LinkRewrite;
+/** Lines of `scanned` holding a relative link that resolves, from `directory`, to `target`. */
+export declare function linesLinkingTo(scanned: Scan, directory: string, target: string): number[];

package/dist/links.js

@@ -0,0 +1,142 @@
+/**
+ * Relative links, and keeping them true when a file moves.
+ *
+ * Both repositories this tool was measured against archive a brief by moving
+ * it one directory down and then adding `../` to its links by hand. A move
+ * that breaks links is a defect the move introduced, so the move repairs them:
+ * the file's own relative links, and the links other live briefs hold to it.
+ */
+import { linksOf } from './markdown.js';
+/** A destination that is a path relative to the file holding it. */
+export function isRelativeTarget(target) {
+    if (target === '' || target.startsWith('#') || target.startsWith('/') || target.startsWith('\\'))
+        return false;
+    return !/^[A-Za-z][A-Za-z0-9+.-]*:/.test(target);
+}
+/** The path part of a destination and whatever follows it: `?query` or `#fragment`. */
+export function splitTarget(target) {
+    const cut = target.search(/[?#]/);
+    return cut < 0 ? { path: target, suffix: '' } : { path: target.slice(0, cut), suffix: target.slice(cut) };
+}
+/** Normalises a repository-relative path and refuses one that leaves the repository. */
+export function normalisePath(path) {
+    const out = [];
+    for (const part of path.replace(/\\/g, '/').split('/')) {
+        if (part === '' || part === '.')
+            continue;
+        if (part === '..') {
+            if (out.length === 0)
+                throw new Error(`"${path}" is outside the repository`);
+            out.pop();
+            continue;
+        }
+        out.push(part);
+    }
+    return out.join('/');
+}
+/** Whether a repository path lies inside a directory. */
+export function isInside(path, directory) {
+    const dir = normalisePath(directory);
+    return dir === '' || path === dir || path.startsWith(`${dir}/`);
+}
+export function dirOf(path) {
+    const slash = path.lastIndexOf('/');
+    return slash < 0 ? '' : path.slice(0, slash);
+}
+function parts(path) {
+    return path.split('/').filter((p) => p !== '' && p !== '.');
+}
+/** A relative path resolved against a directory, or `null` when it climbs out of the repository. */
+export function resolveFrom(directory, relative) {
+    const out = parts(directory);
+    for (const part of parts(relative)) {
+        if (part === '..') {
+            if (out.length === 0)
+                return null;
+            out.pop();
+        }
+        else {
+            out.push(part);
+        }
+    }
+    return out.join('/');
+}
+/** The relative path from a directory to a repository path. */
+export function relativePath(fromDirectory, to) {
+    const from = parts(fromDirectory);
+    const target = parts(to);
+    let common = 0;
+    while (common < from.length && from[common] === target[common])
+        common += 1;
+    const up = from.slice(common).map(() => '..');
+    const rest = target.slice(common);
+    const joined = [...up, ...rest].join('/');
+    return joined === '' ? '.' : joined;
+}
+function decode(path) {
+    try {
+        return decodeURIComponent(path);
+    }
+    catch {
+        return path;
+    }
+}
+/** Writes a path back in the encoding its original destination used. */
+function encodeLike(original, path) {
+    if (!original.includes('%'))
+        return path;
+    // encodeURIComponent leaves "." and ".." as they are.
+    return path.split('/').map(encodeURIComponent).join('/');
+}
+/**
+ * Rewrites relative destinations for a file read from `directory` that will
+ * be read from `newDirectory`. `retarget` maps the repository path a
+ * destination resolves to now onto the one it should resolve to afterwards,
+ * which differs only for a file that is itself moving.
+ */
+export function rewriteLinks(scanned, directory, newDirectory, retarget) {
+    const lines = [...scanned.lines];
+    let count = 0;
+    const byLine = new Map();
+    for (const link of linksOf(scanned)) {
+        if (!isRelativeTarget(link.target))
+            continue;
+        const { path, suffix } = splitTarget(link.target);
+        if (path === '')
+            continue;
+        const resolved = resolveFrom(directory, decode(path));
+        if (resolved === null)
+            continue;
+        const destination = retarget(resolved);
+        // A destination that still resolves where it should keeps its spelling.
+        if (resolveFrom(newDirectory, decode(path)) === destination)
+            continue;
+        const relative = relativePath(newDirectory, destination);
+        const trailing = path.endsWith('/') && relative !== '.' ? '/' : '';
+        const replacement = `${encodeLike(path, relative)}${trailing}${suffix}`;
+        byLine.set(link.line, [...(byLine.get(link.line) ?? []), { start: link.start, end: link.end, replacement }]);
+        count += 1;
+    }
+    for (const [line, edits] of byLine) {
+        let text = lines[line];
+        for (const edit of [...edits].sort((a, b) => b.start - a.start)) {
+            text = text.slice(0, edit.start) + edit.replacement + text.slice(edit.end);
+        }
+        lines[line] = text;
+    }
+    return { lines, count };
+}
+/** Lines of `scanned` holding a relative link that resolves, from `directory`, to `target`. */
+export function linesLinkingTo(scanned, directory, target) {
+    const found = new Set();
+    for (const link of linksOf(scanned)) {
+        if (!isRelativeTarget(link.target))
+            continue;
+        const { path } = splitTarget(link.target);
+        if (path !== '' && resolveFrom(directory, decode(path)) === target)
+            found.add(link.line);
+    }
+    // Lines are scanned in order, so the set is already ascending.
+    return [...found];
+}
+//# sourceMappingURL=links.js.map

package/dist/links.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"links.js","sourceRoot":"","sources":["../src/links.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Relative links, and keeping them true when a file moves.\n *\n * Both repositories this tool was measured against archive a brief by moving\n * it one directory down and then adding `../` to its links by hand. A move\n * that breaks links is a defect the move introduced, so the move repairs them:\n * the file's own relative links, and the links other live briefs hold to it.\n */\n\nimport { linksOf, type Scan } from './markdown.js';\n\n/** A destination that is a path relative to the file holding it. */\nexport function isRelativeTarget(target: string): boolean {\n  if (target === '' || target.startsWith('#') || target.startsWith('/') || target.startsWith('\\\\')) return false;\n  return !/^[A-Za-z][A-Za-z0-9+.-]*:/.test(target);\n}\n\n/** The path part of a destination and whatever follows it: `?query` or `#fragment`. */\nexport function splitTarget(target: string): { readonly path: string; readonly suffix: string } {\n  const cut = target.search(/[?#]/);\n  return cut < 0 ? { path: target, suffix: '' } : { path: target.slice(0, cut), suffix: target.slice(cut) };\n}\n\n/** Normalises a repository-relative path and refuses one that leaves the repository. */\nexport function normalisePath(path: string): string {\n  const out: string[] = [];\n  for (const part of path.replace(/\\\\/g, '/').split('/')) {\n    if (part === '' || part === '.') continue;\n    if (part === '..') {\n      if (out.length === 0) throw new Error(`\"${path}\" is outside the repository`);\n      out.pop();\n      continue;\n    }\n    out.push(part);\n  }\n  return out.join('/');\n}\n\n/** Whether a repository path lies inside a directory. */\nexport function isInside(path: string, directory: string): boolean {\n  const dir = normalisePath(directory);\n  return dir === '' || path === dir || path.startsWith(`${dir}/`);\n}\n\nexport function dirOf(path: string): string {\n  const slash = path.lastIndexOf('/');\n  return slash < 0 ? '' : path.slice(0, slash);\n}\n\nfunction parts(path: string): string[] {\n  return path.split('/').filter((p) => p !== '' && p !== '.');\n}\n\n/** A relative path resolved against a directory, or `null` when it climbs out of the repository. */\nexport function resolveFrom(directory: string, relative: string): string | null {\n  const out = parts(directory);\n  for (const part of parts(relative)) {\n    if (part === '..') {\n      if (out.length === 0) return null;\n      out.pop();\n    } else {\n      out.push(part);\n    }\n  }\n  return out.join('/');\n}\n\n/** The relative path from a directory to a repository path. */\nexport function relativePath(fromDirectory: string, to: string): string {\n  const from = parts(fromDirectory);\n  const target = parts(to);\n  let common = 0;\n  while (common < from.length && from[common] === target[common]) common += 1;\n  const up = from.slice(common).map(() => '..');\n  const rest = target.slice(common);\n  const joined = [...up, ...rest].join('/');\n  return joined === '' ? '.' : joined;\n}\n\nfunction decode(path: string): string {\n  try {\n    return decodeURIComponent(path);\n  } catch {\n    return path;\n  }\n}\n\n/** Writes a path back in the encoding its original destination used. */\nfunction encodeLike(original: string, path: string): string {\n  if (!original.includes('%')) return path;\n  // encodeURIComponent leaves \".\" and \"..\" as they are.\n  return path.split('/').map(encodeURIComponent).join('/');\n}\n\nexport interface LinkRewrite {\n  readonly lines: string[];\n  readonly count: number;\n}\n\n/**\n * Rewrites relative destinations for a file read from `directory` that will\n * be read from `newDirectory`. `retarget` maps the repository path a\n * destination resolves to now onto the one it should resolve to afterwards,\n * which differs only for a file that is itself moving.\n */\nexport function rewriteLinks(\n  scanned: Scan,\n  directory: string,\n  newDirectory: string,\n  retarget: (resolved: string) => string,\n): LinkRewrite {\n  const lines = [...scanned.lines];\n  let count = 0;\n  const byLine = new Map<number, { start: number; end: number; replacement: string }[]>();\n  for (const link of linksOf(scanned)) {\n    if (!isRelativeTarget(link.target)) continue;\n    const { path, suffix } = splitTarget(link.target);\n    if (path === '') continue;\n    const resolved = resolveFrom(directory, decode(path));\n    if (resolved === null) continue;\n    const destination = retarget(resolved);\n    // A destination that still resolves where it should keeps its spelling.\n    if (resolveFrom(newDirectory, decode(path)) === destination) continue;\n    const relative = relativePath(newDirectory, destination);\n    const trailing = path.endsWith('/') && relative !== '.' ? '/' : '';\n    const replacement = `${encodeLike(path, relative)}${trailing}${suffix}`;\n    byLine.set(link.line, [...(byLine.get(link.line) ?? []), { start: link.start, end: link.end, replacement }]);\n    count += 1;\n  }\n  for (const [line, edits] of byLine) {\n    let text = lines[line] as string;\n    for (const edit of [...edits].sort((a, b) => b.start - a.start)) {\n      text = text.slice(0, edit.start) + edit.replacement + text.slice(edit.end);\n    }\n    lines[line] = text;\n  }\n  return { lines, count };\n}\n\n/** Lines of `scanned` holding a relative link that resolves, from `directory`, to `target`. */\nexport function linesLinkingTo(scanned: Scan, directory: string, target: string): number[] {\n  const found = new Set<number>();\n  for (const link of linksOf(scanned)) {\n    if (!isRelativeTarget(link.target)) continue;\n    const { path } = splitTarget(link.target);\n    if (path !== '' && resolveFrom(directory, decode(path)) === target) found.add(link.line);\n  }\n  // Lines are scanned in order, so the set is already ascending.\n  return [...found];\n}\n"]}

package/dist/lint.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Running rules: severities from the configuration, plugins beside the
+ * built-in rules, findings in a stable order.
+ */
+import type { Brief } from './brief.js';
+import type { Corpus } from './corpus.js';
+import { type Rule } from './rules.js';
+import type { Finding, SeveritySetting } from './types.js';
+export interface Plugin {
+    /** Prefixes the plugin's rule ids: `<name>/<rule>`. */
+    readonly name: string;
+    readonly rules: readonly Rule[];
+    /** The plugin's entry in the configuration, handed to each rule. */
+    readonly options?: unknown;
+}
+export interface LintOptions {
+    readonly plugins?: readonly Plugin[];
+    /** Tracked files, for the rules that read the tree. */
+    readonly repoFiles?: readonly string[] | null;
+    /** Limit the findings to these briefs. The whole corpus is still read. */
+    readonly only?: readonly Brief[];
+}
+/** Every rule id a run knows: built-in, collision and plugin. */
+export declare function ruleIds(plugins?: readonly Plugin[]): string[];
+/** The severity configuration assigns a rule, or its own. */
+export declare function severityOf(corpus: Corpus, id: string, fallback: SeveritySetting): SeveritySetting;
+/** Refuses a configuration that names a rule nobody defines: a typo there silences nothing. */
+export declare function checkRuleIds(corpus: Corpus, plugins?: readonly Plugin[]): void;
+export declare function lint(corpus: Corpus, options?: LintOptions): Promise<Finding[]>;
+export declare function sortFindings(findings: readonly Finding[]): Finding[];
+export interface Summary {
+    readonly errors: number;
+    readonly warnings: number;
+    readonly notes: number;
+}
+export declare function summarise(findings: readonly Finding[]): Summary;
+/** Whether findings fail a run: any error, or any warning under `--strict`. */
+export declare function failing(findings: readonly Finding[], strict: boolean): boolean;

package/dist/lint.js

@@ -0,0 +1,90 @@
+/**
+ * Running rules: severities from the configuration, plugins beside the
+ * built-in rules, findings in a stable order.
+ */
+import { ConfigError } from './config.js';
+import { analyse, COLLISION_RULES, RULES } from './rules.js';
+const RANK = { note: 0, warning: 1, error: 2 };
+function lower(a, b) {
+    return RANK[a] <= RANK[b] ? a : b;
+}
+/** Every rule id a run knows: built-in, collision and plugin. */
+export function ruleIds(plugins = []) {
+    return [
+        ...RULES.map((r) => r.id),
+        ...COLLISION_RULES.map((r) => r.id),
+        ...plugins.flatMap((p) => p.rules.map((r) => `${p.name}/${r.id}`)),
+    ];
+}
+/** The severity configuration assigns a rule, or its own. */
+export function severityOf(corpus, id, fallback) {
+    return corpus.config.rules[id] ?? fallback;
+}
+/** Refuses a configuration that names a rule nobody defines: a typo there silences nothing. */
+export function checkRuleIds(corpus, plugins = []) {
+    const known = new Set(ruleIds(plugins));
+    const unknown = Object.keys(corpus.config.rules).filter((id) => !known.has(id));
+    if (unknown.length > 0) {
+        throw new ConfigError('configuration', unknown.map((id) => `"rules.${id}" names no rule`));
+    }
+}
+export async function lint(corpus, options = {}) {
+    const plugins = options.plugins ?? [];
+    checkRuleIds(corpus, plugins);
+    const active = [
+        ...RULES.map((rule) => ({ id: rule.id, rule, severity: severityOf(corpus, rule.id, rule.severity), options: undefined })),
+        ...plugins.flatMap((plugin) => plugin.rules.map((rule) => {
+            const id = `${plugin.name}/${rule.id}`;
+            return { id, rule, severity: severityOf(corpus, id, rule.severity), options: plugin.options };
+        })),
+    ].filter((r) => r.severity !== 'off');
+    const shared = analyse(corpus);
+    const targets = options.only ?? corpus.briefs;
+    const findings = [];
+    for (const brief of targets) {
+        for (const { id, rule, severity, options: ruleOptions } of active) {
+            const results = await rule.check({
+                brief,
+                corpus,
+                config: corpus.config,
+                repoFiles: options.repoFiles ?? null,
+                shared,
+                options: ruleOptions,
+            });
+            for (const result of results) {
+                const configured = severity;
+                findings.push({
+                    rule: id,
+                    severity: result.severity === undefined ? configured : lower(result.severity, configured),
+                    message: result.message,
+                    file: brief.file,
+                    line: Math.max(1, Math.trunc(result.line)),
+                    brief: brief.id ?? undefined,
+                    hint: result.hint,
+                });
+            }
+        }
+    }
+    return sortFindings(findings);
+}
+/** Strings by code unit, which is the same order on every host and in every locale. */
+function order(a, b) {
+    if (a === b)
+        return 0;
+    return a < b ? -1 : 1;
+}
+export function sortFindings(findings) {
+    return [...findings].sort((a, b) => order(a.file, b.file) || a.line - b.line || order(a.rule, b.rule) || order(a.message, b.message));
+}
+export function summarise(findings) {
+    return {
+        errors: findings.filter((f) => f.severity === 'error').length,
+        warnings: findings.filter((f) => f.severity === 'warning').length,
+        notes: findings.filter((f) => f.severity === 'note').length,
+    };
+}
+/** Whether findings fail a run: any error, or any warning under `--strict`. */
+export function failing(findings, strict) {
+    return findings.some((f) => f.severity === 'error' || (strict && f.severity === 'warning'));
+}
+//# sourceMappingURL=lint.js.map

package/dist/lint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lint.js","sourceRoot":"","sources":["../src/lint.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Running rules: severities from the configuration, plugins beside the\n * built-in rules, findings in a stable order.\n */\n\nimport type { Brief } from './brief.js';\nimport { ConfigError } from './config.js';\nimport type { Corpus } from './corpus.js';\nimport { analyse, COLLISION_RULES, type Rule, RULES } from './rules.js';\nimport type { Finding, Severity, SeveritySetting } from './types.js';\n\nexport interface Plugin {\n  /** Prefixes the plugin's rule ids: `<name>/<rule>`. */\n  readonly name: string;\n  readonly rules: readonly Rule[];\n  /** The plugin's entry in the configuration, handed to each rule. */\n  readonly options?: unknown;\n}\n\nexport interface LintOptions {\n  readonly plugins?: readonly Plugin[];\n  /** Tracked files, for the rules that read the tree. */\n  readonly repoFiles?: readonly string[] | null;\n  /** Limit the findings to these briefs. The whole corpus is still read. */\n  readonly only?: readonly Brief[];\n}\n\nconst RANK: Readonly<Record<Severity, number>> = { note: 0, warning: 1, error: 2 };\n\nfunction lower(a: Severity, b: Severity): Severity {\n  return RANK[a] <= RANK[b] ? a : b;\n}\n\ninterface ActiveRule {\n  readonly id: string;\n  readonly rule: Rule;\n  readonly severity: SeveritySetting;\n  readonly options: unknown;\n}\n\n/** Every rule id a run knows: built-in, collision and plugin. */\nexport function ruleIds(plugins: readonly Plugin[] = []): string[] {\n  return [\n    ...RULES.map((r) => r.id),\n    ...COLLISION_RULES.map((r) => r.id),\n    ...plugins.flatMap((p) => p.rules.map((r) => `${p.name}/${r.id}`)),\n  ];\n}\n\n/** The severity configuration assigns a rule, or its own. */\nexport function severityOf(corpus: Corpus, id: string, fallback: SeveritySetting): SeveritySetting {\n  return corpus.config.rules[id] ?? fallback;\n}\n\n/** Refuses a configuration that names a rule nobody defines: a typo there silences nothing. */\nexport function checkRuleIds(corpus: Corpus, plugins: readonly Plugin[] = []): void {\n  const known = new Set(ruleIds(plugins));\n  const unknown = Object.keys(corpus.config.rules).filter((id) => !known.has(id));\n  if (unknown.length > 0) {\n    throw new ConfigError('configuration', unknown.map((id) => `\"rules.${id}\" names no rule`));\n  }\n}\n\nexport async function lint(corpus: Corpus, options: LintOptions = {}): Promise<Finding[]> {\n  const plugins = options.plugins ?? [];\n  checkRuleIds(corpus, plugins);\n  const active: ActiveRule[] = [\n    ...RULES.map((rule) => ({ id: rule.id, rule, severity: severityOf(corpus, rule.id, rule.severity), options: undefined })),\n    ...plugins.flatMap((plugin) =>\n      plugin.rules.map((rule) => {\n        const id = `${plugin.name}/${rule.id}`;\n        return { id, rule, severity: severityOf(corpus, id, rule.severity), options: plugin.options };\n      }),\n    ),\n  ].filter((r) => r.severity !== 'off');\n\n  const shared = analyse(corpus);\n  const targets = options.only ?? corpus.briefs;\n  const findings: Finding[] = [];\n  for (const brief of targets) {\n    for (const { id, rule, severity, options: ruleOptions } of active) {\n      const results = await rule.check({\n        brief,\n        corpus,\n        config: corpus.config,\n        repoFiles: options.repoFiles ?? null,\n        shared,\n        options: ruleOptions,\n      });\n      for (const result of results) {\n        const configured = severity as Severity;\n        findings.push({\n          rule: id,\n          severity: result.severity === undefined ? configured : lower(result.severity, configured),\n          message: result.message,\n          file: brief.file,\n          line: Math.max(1, Math.trunc(result.line)),\n          brief: brief.id ?? undefined,\n          hint: result.hint,\n        });\n      }\n    }\n  }\n  return sortFindings(findings);\n}\n\n/** Strings by code unit, which is the same order on every host and in every locale. */\nfunction order(a: string, b: string): number {\n  if (a === b) return 0;\n  return a < b ? -1 : 1;\n}\n\nexport function sortFindings(findings: readonly Finding[]): Finding[] {\n  return [...findings].sort(\n    (a, b) => order(a.file, b.file) || a.line - b.line || order(a.rule, b.rule) || order(a.message, b.message),\n  );\n}\n\nexport interface Summary {\n  readonly errors: number;\n  readonly warnings: number;\n  readonly notes: number;\n}\n\nexport function summarise(findings: readonly Finding[]): Summary {\n  return {\n    errors: findings.filter((f) => f.severity === 'error').length,\n    warnings: findings.filter((f) => f.severity === 'warning').length,\n    notes: findings.filter((f) => f.severity === 'note').length,\n  };\n}\n\n/** Whether findings fail a run: any error, or any warning under `--strict`. */\nexport function failing(findings: readonly Finding[], strict: boolean): boolean {\n  return findings.some((f) => f.severity === 'error' || (strict && f.severity === 'warning'));\n}\n"]}

package/dist/markdown.d.ts

@@ -0,0 +1,65 @@
+/**
+ * A structural Markdown scanner: code, comments, headings, task items and link
+ * destinations, each with its line.
+ *
+ * Not a CommonMark parser, and it does not need to be. Nothing here renders.
+ * What must be exactly right is knowing what is code or a comment, because a
+ * heading inside a fenced block is not a section and a template hint inside
+ * `<!-- -->` is not content. Everything else is deliberately simple: ATX
+ * headings only (a setext underline and a front-matter delimiter are the same
+ * three characters), fences at any indentation, and no indented code blocks,
+ * because inside a list four spaces of indentation is a continuation far more
+ * often than code.
+ */
+export interface Heading {
+    /** 0-based line. */
+    readonly line: number;
+    readonly level: number;
+    readonly text: string;
+}
+export interface Section {
+    readonly heading: Heading;
+    /** 0-based line after the section's last line. The body starts on the line after the heading. */
+    readonly end: number;
+}
+export interface TaskItem {
+    /** 0-based line of the box. */
+    readonly line: number;
+    /** 0-based line after the item's last continuation line. */
+    readonly end: number;
+    readonly checked: boolean;
+    readonly text: string;
+}
+export interface LinkDestination {
+    /** 0-based line. */
+    readonly line: number;
+    /** Columns of the destination within the line, end exclusive. */
+    readonly start: number;
+    readonly end: number;
+    readonly target: string;
+}
+export interface Scan {
+    readonly lines: readonly string[];
+    /** Lines with comments blanked and code kept: what counts as content. */
+    readonly prose: readonly string[];
+    /** Lines with comments, code spans and fenced blocks blanked: what counts as structure. */
+    readonly masked: readonly string[];
+    readonly headings: readonly Heading[];
+    readonly tasks: readonly TaskItem[];
+}
+/**
+ * Scans `lines` from line `from`; earlier lines (front matter) are blanked in
+ * both masks and contribute nothing.
+ */
+export declare function scan(lines: readonly string[], from?: number): Scan;
+/** Sections: every heading below the title, running to the next heading at its level or above. */
+export declare function sectionsOf(result: Scan): Section[];
+/** The first level-one heading, which is what a reader takes as the title. */
+export declare function titleOf(result: Scan): Heading | undefined;
+/**
+ * Link and image destinations outside code and comments: `[text](dest)`,
+ * `![alt](dest)`, and reference definitions `[label]: dest`.
+ */
+export declare function linksOf(result: Scan): LinkDestination[];
+/** Whether a line carries anything once comments are removed. */
+export declare function hasContent(proseLine: string): boolean;