@0dep/toc 1.0.1 → 2.0.0

package/index.js

@@ -1,64 +1,67 @@
 export const TOC_START = '<!-- toc -->';
 export const TOC_END = '<!-- /toc -->';
 const DEFAULT_SUMMARY = 'Table of contents';
-const KNOWN_OPTIONS = ['collapsible', 'collapsed'];
+const KNOWN_OPTIONS = ['collapsible', 'collapsed', 'levels'];
+const LEVELS = /^(?:([1-6])|([1-6])-([1-6])|([1-6])-|-([1-6]))$/;
 const NUL = String.fromCharCode(0);
+/** @type {Map<string, ReturnType<typeof analyse>>} */
+const cache = new Map();
+const LINK = /\[([^\]]*)\]\(#([^)\s]+)/g;
 
 /**
- * Return the markdown with the toc between every `<!-- toc -->` and `<!-- /toc -->` pair regenerated. Each
- * pair lists every heading below its own start marker. A pair is left alone when it is unbalanced, has a
- * problem on its start marker, or has no headings below it, and nothing outside the pairs is ever touched.
- * The start marker line is kept as written, options included.
+ * The markdown with the toc between every `<!-- toc -->` and `<!-- /toc -->` pair regenerated.
  * @param {string} source
  * @returns {string}
  */
 export function buildToc(source) {
-  const { lines, eol } = splitLines(source);
-  const { headlines, markers } = scan(lines);
+  const { bom, lines, eol, headlines, markers } = analyse(source);
   /** @type {string[]} */
   const out = [];
   let cursor = 0;
   for (const { start, end, options, problem } of markers) {
     if (start === -1 || end === -1 || problem) continue;
-    const listed = headlines.filter((h) => h.line > start);
+    const listed = headingsBelow(headlines, start, options);
     if (listed.length === 0) continue;
     out.push(...lines.slice(cursor, start), renderBlock(listed, lines[start], options, eol));
     cursor = end + 1;
   }
   out.push(...lines.slice(cursor));
-  return out.join(eol);
+  return bom + out.join(eol);
 }
 
 /**
- * Return the toc block, markers included, for the headings below `fromLine`, by default every heading so the
- * block can be pasted into a document without markers. Returns an empty string when there is nothing to list.
+ * The toc block, markers included, for the headings below `fromLine`, empty when there is nothing to list.
  * @param {string} source
- * @param {number} [fromLine] zero based line number, typically the start marker's
- * @param {TocOptions} [options] rendered into the start marker, e.g. `{ collapsed: 'Contents' }`
+ * @param {number} [fromLine] zero based
+ * @param {TocOptions} [options]
  * @returns {string}
  */
 export function renderToc(source, fromLine = -1, options = {}) {
-  const { lines, eol } = splitLines(source);
-  const listed = scan(lines).headlines.filter((h) => h.line > fromLine);
+  const { eol, headlines } = analyse(source);
+  const listed = headingsBelow(headlines, fromLine, options);
   return listed.length === 0 ? '' : renderBlock(listed, formatMarker(options), options, eol);
 }
 
 /**
- * Every marker pair in document order as zero based line numbers, outside fenced code blocks. A start marker
- * pairs with the first end marker after it. A missing side is -1: a start marker without an end marker, or an
- * end marker with no open start marker before it. `options` holds the recognised options written on the start
- * marker and `problem`, only present when there is one, says why the marker cannot be used.
+ * Every marker pair in document order, shared with later calls for the same source.
  * @param {string} source
  * @returns {Marker[]}
  */
 export function findMarkers(source) {
-  return scan(splitLines(source).lines).markers;
+  return analyse(source).markers;
 }
 
 /**
- * Slug a heading's rendered text the way github-slugger does: lowercase, drop everything that is not a
- * letter, number, mark, space, hyphen or underscore, then turn each space into a hyphen. Nothing is trimmed
- * or collapsed.
+ * Every link to an anchor in the document, in order, shared with later calls for the same source.
+ * @param {string} source
+ * @returns {Anchor[]}
+ */
+export function findAnchors(source) {
+  return analyse(source).anchors;
+}
+
+/**
+ * The GitHub anchor slug of a heading's rendered text.
  * @param {string} text
  * @returns {string}
  */
@@ -70,7 +73,7 @@ export function slugify(text) {
 }
 
 /**
- * Reduce a heading's inline markdown to the text GitHub renders and slugs.
+ * The text GitHub renders for a heading's inline markdown.
  * @param {string} markdown
  * @returns {string}
  */
@@ -85,33 +88,51 @@ export function headingText(markdown) {
 }
 
 /**
- * Split the source into lines and remember its line ending, CRLF when the source has any, so the toc is
- * written the way the rest of the file is and a Windows authored file does not end up with mixed endings.
+ * The lines and the scan of the source.
  * @param {string} source
- * @returns {{ lines: string[], eol: string }}
+ * @returns {{ bom: string, lines: string[], eol: string, headlines: Headline[], markers: Marker[], anchors: Anchor[] }}
+ */
+function analyse(source) {
+  let result = cache.get(source);
+  if (!result) {
+    const { bom, lines, eol } = splitLines(source);
+    result = { bom, lines, eol, ...scan(lines) };
+    cache.clear();
+    cache.set(source, result);
+  }
+  return result;
+}
+
+/**
+ * The lines of the source, its byte order mark if any, and its line ending.
+ * @param {string} source
+ * @returns {{ bom: string, lines: string[], eol: string }}
  */
 function splitLines(source) {
-  return { lines: source.split(/\r?\n/), eol: source.includes('\r\n') ? '\r\n' : '\n' };
+  const bom = source.startsWith('\uFEFF') ? '\uFEFF' : '';
+  return { bom, lines: source.slice(bom.length).split(/\r?\n/), eol: source.includes('\r\n') ? '\r\n' : '\n' };
 }
 
 /**
- * Scan the lines for every marker pair and every ATX and setext heading, all outside fenced code blocks. A
- * marker is a line holding nothing but the comment, indented at most three spaces like a heading, since four
- * make an indented code block. A start marker, `<!-- toc -->` with optional options before the closing `-->`,
- * opens a pair that the first end marker after it closes; a start marker inside an open pair is content and an end marker outside a pair is
- * reported with start -1.
+ * The headings, marker pairs and anchor links of the lines.
  * @param {string[]} lines
- * @returns {{ headlines: Array<{ line: number, level: number, markdown: string }>, markers: Marker[] }}
+ * @returns {{ headlines: Headline[], markers: Marker[], anchors: Anchor[] }}
  */
 function scan(lines) {
-  /** @type {Array<{ line: number, level: number, markdown: string }>} */
+  /** @type {Headline[]} */
   const headlines = [];
   /** @type {Marker[]} */
   const markers = [];
+  /** @type {Array<{ line: number, text: string, anchor: string }>} */
+  const links = [];
+  /** @type {Set<string>} */
+  const ids = new Set();
   /** @type {{ char: string, length: number } | null} */
   let fence = null;
   /** @type {Marker | null} */
   let open = null;
+  let paragraph = false;
+  let comment = false;
 
   for (const [i, line] of lines.entries()) {
     const fenceMatch = /^ {0,3}(`{3,}|~{3,})(.*)$/.exec(line);
@@ -123,8 +144,32 @@ function scan(lines) {
     }
     if (fenceMatch && !(fenceMatch[1][0] === '`' && fenceMatch[2].includes('`'))) {
       fence = { char: fenceMatch[1][0], length: fenceMatch[1].length };
+      paragraph = false;
       continue;
     }
+    if (!paragraph && /^(?: {4}|\t)/.test(line)) continue;
+    paragraph = line.trim() !== '';
+
+    const { text: inline, restore } = protect(line);
+    let visible = inline;
+    if (comment) {
+      const close = visible.indexOf('-->');
+      if (close === -1) continue;
+      visible = visible.slice(close + 3);
+      comment = false;
+    }
+    visible = visible.replace(/<!--[\s\S]*?-->/g, '');
+    const start = visible.indexOf('<!--');
+    if (start !== -1) {
+      visible = visible.slice(0, start);
+      comment = true;
+    }
+    for (const [, tag, attributes] of visible.matchAll(/<([a-zA-Z][a-zA-Z0-9-]*)\b([^>]*)>/g)) {
+      for (const [, name, quoted, single] of attributes.matchAll(/(?:^|\s)(id|name)=(?:"([^"]*)"|'([^']*)')/g)) {
+        if (name === 'id' || tag.toLowerCase() === 'a') ids.add(quoted ?? single);
+      }
+    }
+    for (const [, text, anchor] of visible.matchAll(LINK)) links.push({ line: i, text: restore(text), anchor: restore(anchor) });
 
     const startMatch = /^ {0,3}<!--\s*toc(?:\s+(.*?))?\s*-->\s*$/.exec(line);
     if (startMatch) {
@@ -140,42 +185,102 @@ function scan(lines) {
 
     const atx = /^ {0,3}(#{1,6})\s+(.+?)\s*$/.exec(line);
     if (atx) {
-      headlines.push({ line: i, level: atx[1].length, markdown: atx[2] });
+      headlines.push({ line: i, level: atx[1].length, markdown: atx[2], slug: '' });
       continue;
     }
 
     const setext = /^ {0,3}(=+|-+)\s*$/.exec(line);
     if (setext && i > 0 && isParagraphText(lines[i - 1])) {
-      headlines.push({ line: i - 1, level: setext[1][0] === '=' ? 1 : 2, markdown: lines[i - 1].trim() });
+      headlines.push({ line: i - 1, level: setext[1][0] === '=' ? 1 : 2, markdown: lines[i - 1].trim(), slug: '' });
     }
   }
-  return { headlines, markers };
+  assignSlugs(headlines);
+  return { headlines, markers, anchors: resolveAnchors(links, headlines, ids) };
 }
 
 /**
- * The toc block for the given headings, wrapped in the given start marker line and the end marker. Indentation
- * is relative to the shallowest level listed so far, so the list never starts indented, which markdown would
- * render flat anyway, and duplicate slugs get github style `-1`, `-2` suffixes. With
- * `collapsible` or `collapsed` the list goes inside a details element, open or closed to start with, blank
- * lines around it so it renders as markdown, and any other attributes from the marker on the summary element.
- * @param {Array<{ level: number, markdown: string }>} headlines
- * @param {string} startLine the start marker as written in the document
- * @param {TocOptions} options
- * @param {string} [eol] line ending, LF by default
+ * @param {Array<{ line: number, text: string, anchor: string }>} links
+ * @param {Headline[]} headlines
+ * @param {Set<string>} ids
+ * @returns {Anchor[]}
  */
-function renderBlock(headlines, startLine, options, eol = '\n') {
+function resolveAnchors(links, headlines, ids) {
+  const targets = new Set([...headlines.map((h) => h.slug), ...ids]);
+  return links.map(({ line, text, anchor }) => {
+    const decoded = decodeAnchor(anchor);
+    if (targets.has(anchor) || targets.has(decoded)) return { line, text, anchor, valid: true };
+    const candidates = new Set([slugify(headingText(decoded)), slugify(headingText(text))].filter((c) => targets.has(c)));
+    if (candidates.size !== 1) return { line, text, anchor, valid: false };
+    return { line, text, anchor, valid: false, suggestion: [...candidates][0] };
+  });
+}
+
+/** @param {string} anchor */
+function decodeAnchor(anchor) {
+  try {
+    return decodeURIComponent(anchor);
+  } catch {
+    return anchor;
+  }
+}
+
+/**
+ * Set the slug of every heading.
+ * @param {Headline[]} headlines
+ */
+function assignSlugs(headlines) {
   /** @type {Record<string, number>} */
   const occurrences = {};
-  let minLevel = Infinity;
-  const tocLines = headlines.map(({ level, markdown }) => {
-    minLevel = Math.min(minLevel, level);
-    const base = slugify(headingText(markdown));
+  for (const headline of headlines) {
+    const base = slugify(headingText(headline.markdown));
     let slug = base;
     while (Object.hasOwn(occurrences, slug)) {
       occurrences[base]++;
       slug = `${base}-${occurrences[base]}`;
     }
     occurrences[slug] = 0;
+    headline.slug = slug;
+  }
+}
+
+/**
+ * The headings after `fromLine` within the levels the options allow.
+ * @param {Headline[]} headlines
+ * @param {number} fromLine
+ * @param {TocOptions} options
+ * @returns {Headline[]}
+ */
+function headingsBelow(headlines, fromLine, options) {
+  const [min, max] = levelRange(options.levels) ?? [1, 6];
+  return headlines.filter((h) => h.line > fromLine && h.level >= min && h.level <= max);
+}
+
+/**
+ * The lowest and highest heading level a levels option allows, every level when absent, undefined when broken.
+ * @param {string} [levels]
+ * @returns {[number, number] | undefined}
+ */
+function levelRange(levels) {
+  if (levels === undefined) return [1, 6];
+  const match = LEVELS.exec(levels);
+  if (!match) return undefined;
+  const [, only, from, to, fromOpen, toOpen] = match;
+  const min = Number(only ?? from ?? fromOpen ?? 1);
+  const max = Number(only ?? to ?? toOpen ?? 6);
+  return min <= max ? [min, max] : undefined;
+}
+
+/**
+ * The toc block for the headings, between the start marker line and the end marker.
+ * @param {Headline[]} headlines
+ * @param {string} startLine
+ * @param {TocOptions} options
+ * @param {string} [eol]
+ */
+function renderBlock(headlines, startLine, options, eol = '\n') {
+  let minLevel = Infinity;
+  const tocLines = headlines.map(({ level, markdown, slug }) => {
+    minLevel = Math.min(minLevel, level);
     return `${'  '.repeat(level - minLevel)}- [${headingLabel(markdown)}](#${slug})`;
   });
   const details = options.collapsible ?? options.collapsed;
@@ -189,12 +294,9 @@ function renderBlock(headlines, startLine, options, eol = '\n') {
 }
 
 /**
- * Parse what is written on a start marker: the options as bare names (`collapsed`) or quoted values
- * (`collapsed="Contents"`), and any other well-formed `name="value"` as an attribute for the summary element.
- * Anything else, bare names that are not options, unquoted values, malformed names, is a problem, as is a
- * combination that makes no sense. A marker with a problem is never used.
+ * The options written on a start marker, with a problem when they cannot be used and a warning when one is ignored.
  * @param {string | undefined} text
- * @returns {{ options: TocOptions, problem?: string }}
+ * @returns {{ options: TocOptions, problem?: string, warning?: string }}
  */
 function parseOptions(text) {
   /** @type {TocOptions} */
@@ -204,24 +306,29 @@ function parseOptions(text) {
   /** @type {string[]} */
   const unknown = [];
   for (const [token, name, value] of (text ?? '').matchAll(/([^\s="]+)(?:="([^"]*)")?(?=\s|$)|\S+/g)) {
-    if (name && KNOWN_OPTIONS.includes(name)) options[/** @type {'collapsible' | 'collapsed'} */ (name)] = value ?? true;
+    if (name === 'levels') options.levels = value ?? '';
+    else if (name && KNOWN_OPTIONS.includes(name)) options[/** @type {'collapsible' | 'collapsed'} */ (name)] = value ?? true;
     else if (name && value !== undefined && /^[a-zA-Z][\w:.-]*$/.test(name)) attributes[name] = value;
     else unknown.push(token);
   }
   const names = Object.keys(attributes);
   if (names.length) options.attributes = attributes;
-  if (unknown.length) return { options, problem: `unknown TOC option ${unknown.join(' ')}` };
-  if (options.collapsible !== undefined && options.collapsed !== undefined) {
-    return { options, problem: 'TOC options collapsible and collapsed exclude each other' };
+  /** @type {{ options: TocOptions, problem?: string, warning?: string }} */
+  const parsed = { options };
+  if (options.levels !== undefined && !levelRange(options.levels)) {
+    parsed.warning = `TOC option levels "${options.levels}" is not a level or a range like 2-3, ignored`;
   }
-  if (names.length && options.collapsible === undefined && options.collapsed === undefined) {
-    return { options, problem: `TOC attributes ${names.join(', ')} need collapsible or collapsed` };
+  if (unknown.length) parsed.problem = `unknown TOC option ${unknown.join(' ')}`;
+  else if (options.collapsible !== undefined && options.collapsed !== undefined) {
+    parsed.problem = 'TOC options collapsible and collapsed exclude each other';
+  } else if (names.length && options.collapsible === undefined && options.collapsed === undefined) {
+    parsed.problem = `TOC attributes ${names.join(', ')} need collapsible or collapsed`;
   }
-  return { options };
+  return parsed;
 }
 
 /**
- * The start marker line for the given options, the inverse of `parseOptions`: options first, then attributes.
+ * The start marker line for the options.
  * @param {TocOptions} options
  */
 function formatMarker(options) {
@@ -235,15 +342,14 @@ function formatMarker(options) {
 
 /**
  * @param {Record<string, string>} attributes
- * @returns {string[]} `name="value"` in the order given
+ * @returns {string[]}
  */
 function formatAttributes(attributes) {
   return Object.entries(attributes).map(([name, value]) => `${name}="${value}"`);
 }
 
 /**
- * The label used in the toc: the heading's own markdown, except that links become their text since a link
- * cannot nest inside the toc link.
+ * The link text used in the toc for a heading.
  * @param {string} markdown
  * @returns {string}
  */
@@ -253,8 +359,7 @@ function headingLabel(markdown) {
 }
 
 /**
- * Replace code spans (with their content, or the whole span when `keepCodeSpans` is set) and backslash escapes
- * (with the escaped character) by placeholders so the inline markdown passes leave them alone.
+ * The markdown with code spans and backslash escapes swapped for placeholders, and a function to put them back.
  * @param {string} markdown
  * @param {{ keepCodeSpans?: boolean }} [options]
  */
@@ -274,8 +379,7 @@ function protect(markdown, { keepCodeSpans = false } = {}) {
 }
 
 /**
- * Strip one leading and one trailing space from code span content when both are present and the content is
- * not only spaces, as CommonMark does.
+ * The code span content unpadded as CommonMark renders it.
  * @param {string} code
  */
 function unpadCodeSpan(code) {
@@ -289,8 +393,7 @@ function stripClosingHashes(markdown) {
 }
 
 /**
- * Links, images and reference links become their text, autolinks their url. Used for both the slug text and
- * the toc label since a link cannot nest inside the toc link.
+ * The text with links, images and autolinks flattened to their text or url.
  * @param {string} text
  */
 function stripLinks(text) {
@@ -308,15 +411,22 @@ function isParagraphText(line) {
 }
 
 /**
- * Options written on a start marker. `collapsible` wraps the list in a details element that starts open,
- * `collapsed` in one that starts closed. Each is `true` for the default summary "Table of contents" or a
- * string for a custom one. `attributes` are the other `name="value"` pairs on the marker, rendered on the
- * summary element in the order written, only present when there are any.
- * @typedef {{ collapsible?: true | string, collapsed?: true | string, attributes?: Record<string, string> }} TocOptions
+ * Options written on a start marker, each `true` or a summary text, and the other attributes for the summary element.
+ * @typedef {{ collapsible?: true | string, collapsed?: true | string, levels?: string, attributes?: Record<string, string> }} TocOptions
+ */
+
+/**
+ * A heading with its zero based line, level, inline markdown and GitHub slug.
+ * @typedef {{ line: number, level: number, markdown: string, slug: string }} Headline
+ */
+
+/**
+ * A link to an anchor with its zero based line, text, anchor as written, whether it has a target and, when it
+ * has none and one heading clearly matches, a suggestion.
+ * @typedef {{ line: number, text: string, anchor: string, valid: boolean, suggestion?: string }} Anchor
  */
 
 /**
- * A marker pair. `start` and `end` are zero based line numbers, -1 when that side is missing. `problem` is
- * only present when the start marker cannot be used: an unknown option or an impossible combination.
- * @typedef {{ start: number, end: number, options: TocOptions, problem?: string }} Marker
+ * A marker pair as zero based lines, -1 for a missing side, with its options, a problem when they cannot be used and a warning when one is ignored.
+ * @typedef {{ start: number, end: number, options: TocOptions, problem?: string, warning?: string }} Marker
  */

package/package.json

@@ -1,36 +1,34 @@
 {
   "name": "@0dep/toc",
-  "version": "1.0.1",
+  "version": "2.0.0",
   "description": "Generate a GitHub flavoured markdown table of contents",
   "type": "module",
   "sideEffects": false,
   "module": "./index.js",
-  "main": "./index.cjs",
   "types": "./types/index.d.ts",
   "exports": {
     ".": {
       "types": "./types/index.d.ts",
-      "require": "./index.cjs",
-      "import": "./index.js"
+      "default": "./index.js"
     }
   },
   "bin": {
     "toc": "bin/toc.js"
   },
   "engines": {
-    "node": ">=20"
+    "node": ">=22.12"
   },
   "scripts": {
-    "pretest": "npm run toc && npm run dist",
+    "pretest": "npm run toc && npm run types",
     "test": "mocha",
     "posttest": "npm run lint && npm run tsc && npm run test:md",
     "test:md": "texample",
-    "toc": "node bin/toc.js README.md",
-    "posttoc": "prettier --write README.md",
+    "toc": "node bin/toc.js --check README.md CHANGELOG.md",
+    "posttoc": "prettier --write README.md CHANGELOG.md",
     "lint": "eslint . --cache && prettier . --check --cache",
     "tsc": "tsc -p test",
-    "dist": "rollup -c && dts-buddy",
-    "prepack": "npm run dist",
+    "types": "tsc",
+    "prepack": "npm run types",
     "cov:html": "c8 -r html -r text mocha",
     "test:lcov": "c8 -r lcov mocha && npm run lint"
   },
@@ -46,7 +44,8 @@
     "markdown",
     "readme",
     "github",
-    "slug"
+    "slug",
+    "glob"
   ],
   "author": {
     "name": "Zerodep AB",
@@ -63,26 +62,22 @@
   "license": "MIT",
   "devDependencies": {
     "@eslint/js": "^10.0.1",
-    "@rollup/plugin-commonjs": "^29.0.3",
     "@types/chai": "^5.2.3",
     "@types/mocha": "^10.0.10",
     "@types/node": "^22.20.2",
     "c8": "^12.0.0",
     "chai": "^6.2.2",
-    "dts-buddy": "^0.8.3",
     "eslint": "^10.10.0",
     "globals": "^17.12.0",
     "mocha": "^12.0.0",
     "prettier": "^3.9.6",
-    "rollup": "^4.63.1",
     "texample": "^1.0.2",
     "typescript": "^6.0.3"
   },
   "files": [
     "bin/",
     "index.js",
-    "index.cjs",
-    "types/index.d.ts*",
+    "types/",
     "CHANGELOG.md"
   ]
 }