@secureport/core 1.0.0 → 2.2.0

package/src/import/nessus.ts

@@ -28,12 +28,15 @@ const NESSUS_SEVERITY: Readonly<Record<string, Severity>> = Object.freeze({
  * fingerprints distinctly per service.
  *
  * The port is also recorded on {@link Finding.port} (**B42**), which is a
- * record and nothing more. The location assembly and the fingerprint inputs are
- * deliberately unchanged: the fingerprint's last component is
- * `parameter ?? port ?? ''`, so a Nessus port is still counted twice — once
- * inside the location and once as that component. That double-count is
- * harmless and **must stay**, because removing it would move every existing
- * Nessus fingerprint and force a re-fingerprint migration.
+ * record and nothing more. **The double-count is gone in `fp_v2`** (6.9c): the
+ * fingerprint's last component was `parameter ?? port ?? ''`, so a Nessus port
+ * was counted twice — once inside the location and once as that component —
+ * and this comment said it had to stay because removing it would force a
+ * re-fingerprint migration. 6.9b built that migration, so it went. The tail is
+ * now `parameter ?? ''`, and the port is carried by the location alone, which
+ * `normaliseLocation` canonicalises: `app.example.com:443` and
+ * `https://app.example.com/` are one endpoint (B102), and a non-default port
+ * stays in the location where it belongs.
  *
  * Severity comes from the CVSS v3 base score where Nessus supplies one, and from
  * its own numeric rating otherwise.

package/src/index.ts

@@ -16,6 +16,15 @@
 
 export type { Finding } from './finding.js';
 export type { FingerprintInput, VulnKeyInput } from './fingerprint.js';
+export type {
+  FingerprintAlgorithm,
+  IssuePlan,
+  IssueWithEvidence,
+  RefingerprintOutcome,
+  RefingerprintPlan,
+} from './refingerprint.js';
+export { currentAlgorithm, planRefingerprint } from './refingerprint.js';
+export { exposureOf } from './reconcile.js';
 export {
   FINGERPRINT_VERSION,
   PATH_PLACEHOLDER,
@@ -44,6 +53,9 @@ export { importGeneric } from './import/generic.js';
 export type { BuildSnapshotInput } from './snapshot-builder.js';
 export { buildSnapshot, parseSnapshot } from './snapshot-builder.js';
 export type {
+  Branding,
+  EvidenceVerbosity,
+  OmittedIssues,
   ReportKind,
   ReportModel,
   ReportOptions,
@@ -53,12 +65,12 @@ export type {
   RetestVerdict,
   TestingBasis,
 } from './report/model.js';
-export { buildReportModel } from './report/model.js';
+export { buildReportModel, VERDICT_LABELS } from './report/model.js';
 export { renderMarkdown } from './report/markdown.js';
 export { renderHtml } from './report/html.js';
 export type { JsonReport } from './report/json.js';
 export { renderJson } from './report/json.js';
-export type { ReconcileInput, ReconcileResult } from './reconcile.js';
+export type { ReconcileInput, ReconcileResult, SuppressionDecision } from './reconcile.js';
 export { reconcile } from './reconcile.js';
 export type {
   Coverage,

package/src/issue.ts

@@ -216,6 +216,7 @@ export type IssueEventType =
   | 'commented'
   | 'assigned'
   | 'merged'
+  | 'retitled'
   | 'exported';
 
 /**

package/src/reconcile.ts

@@ -1,6 +1,6 @@
 import type { Finding } from './finding.js';
 import { FINGERPRINT_VERSION } from './fingerprint.js';
-import type { Issue, IssueEvent } from './issue.js';
+import type { IgnoreReason, IgnoreScope, Issue, IssueEvent } from './issue.js';
 import type { Run, RunKind, RunSummary, SeverityCounts } from './run.js';
 import {
   DEFAULT_SLA_POLICY,
@@ -73,6 +73,56 @@ export interface ReconcileInput {
 
   /** How long the run took, for the summary. */
   readonly durationMs?: number;
+
+  /**
+   * Consulted for each issue this run would newly open, to suppress it at
+   * birth — a standing rule rather than a decision about one issue.
+   *
+   * **It has to live here, and B89 records why the obvious alternative fails.**
+   * `reconcile()` computes the run summary, so an issue it opens is counted
+   * `new`. A caller that suppressed that issue after the fact would produce a
+   * report whose opening line said `new` while its own appendix said
+   * `suppressed`, about the same issue, in the same document. Filtering the
+   * findings before reconciling is no better: the issue then vanishes from the
+   * summary entirely rather than being suppressed, and invariant 7 says a
+   * suppressed issue is never absent from the appendix.
+   *
+   * Return `undefined` to open the issue normally. The suppressed issue is
+   * counted `ignored` in the same pass that counts everything else, which the
+   * summary already does correctly because it tests `status` before it tests
+   * whether the run created the issue.
+   *
+   * **Consulted only for new issues**, never for one that already exists: an
+   * issue a person has looked at is theirs, and a rule written afterwards does
+   * not get to reach back and hide it.
+   */
+  readonly suppress?: (issue: Issue) => SuppressionDecision | undefined;
+}
+
+/**
+ * Why a standing rule suppressed an issue at the moment it was opened.
+ *
+ * @see {@link ReconcileInput.suppress}
+ */
+export interface SuppressionDecision {
+  /** Which of the domain's ignore reasons applies. */
+  readonly reason: IgnoreReason;
+
+  /** The justification an auditor reads in the suppressed appendix. */
+  readonly comment?: string;
+
+  /** How widely the suppression applies. */
+  readonly scope?: IgnoreScope;
+
+  /**
+   * Who accepted the risk. Defaults to {@link ReconcileInput.actor}.
+   *
+   * Worth passing. The appendix is an accepted-risk register, and a register
+   * whose every row says `reconciler` answers "who accepted this?" with "the
+   * clock did" — which `00-DOMAIN.md` §3 is explicit is not an identity. The
+   * rule that matched has an author; this is where to name them.
+   */
+  readonly by?: string;
 }
 
 /**
@@ -146,6 +196,40 @@ function defaultThreshold(kind: RunKind): number {
   return kind === 'upload' ? 1 : 2;
 }
 
+/**
+ * How much a single issue contributes to an exposure score.
+ *
+ * **Severity times age in days, capped at ninety.** The cap is the load-bearing
+ * part: without it a two-year-old advisory eventually outweighs a critical
+ * found this morning, and the number stops being about risk and starts being
+ * about how long you have had the account. Ninety days is where an unfixed
+ * issue stops getting worse and simply *is* bad.
+ *
+ * **Only `open` and `regressed` count.** A resolved issue is not exposure, and
+ * an ignored one is excluded from exposure exactly as it is excluded from
+ * every count but its own (invariant 7) — suppressing an issue is a statement
+ * that it is not currently risk, and a score that disagreed with that would
+ * make the suppression pointless.
+ *
+ * Exported because `reconcile()` is not the only thing that needs it: the
+ * nightly rollup scores a whole organisation across every target, and two
+ * implementations of this would be two definitions of exposure.
+ *
+ * @param issue - The issue to score.
+ * @param now - When the score is being taken. An argument, so the same issue
+ *   and the same clock always give the same number.
+ * @returns The contribution, which is zero for anything not currently open.
+ */
+export function exposureOf(
+  issue: Pick<Issue, 'status' | 'effectiveSeverity' | 'firstSeen'>,
+  now: Date,
+): number {
+  if (issue.status !== 'open' && issue.status !== 'regressed') return 0;
+  return (
+    SEVERITY_WEIGHTS[issue.effectiveSeverity] * Math.min(daysBetween(issue.firstSeen, now), 90)
+  );
+}
+
 /** An all-zero count, so a report never has to decide what a missing key means. */
 function emptyCounts(): Record<string, number> {
   return Object.fromEntries(SEVERITY_ORDER.map((s) => [s, 0]));
@@ -285,8 +369,42 @@ export function reconcile(input: ReconcileInput): ReconcileResult {
         origin: run.kind,
         slaDueAt: slaDueAt(worst.detectedSeverity, now, slaPolicy),
       };
-      updated.set(key, issue);
+      const decision = input.suppress?.(issue);
+      if (decision === undefined) {
+        updated.set(key, issue);
+        emit(id, 'created', { findingIds, severity: worst.detectedSeverity });
+        continue;
+      }
+
+      // Both events, in order. The issue was opened and then suppressed; a
+      // history that recorded only the suppression would have an issue whose
+      // first event is `ignored`, and invariant 2 wants every state change
+      // accounted for rather than the net result.
+      //
+      // `severityAtIgnore` is set deliberately, which is what makes a rule
+      // liftable: the existing branch above un-ignores an issue whose detected
+      // severity rises past what was accepted, and a standing rule should not
+      // be more permanent than a person's own decision. Accepting the risk of
+      // a medium is not accepting the risk of a critical, however the
+      // acceptance was expressed. **A merge survivor is the deliberate
+      // exception and omits it** (P6, B98) — that is a statement about
+      // identity rather than risk, and it has to survive a severity rise.
+      const suppressed: Issue = {
+        ...issue,
+        status: 'ignored',
+        ignoreReason: decision.reason,
+        ...(decision.comment === undefined ? {} : { ignoreComment: decision.comment }),
+        ...(decision.scope === undefined ? {} : { ignoreScope: decision.scope }),
+        ignoredBy: decision.by ?? actor,
+        severityAtIgnore: worst.detectedSeverity,
+      };
+      updated.set(key, suppressed);
       emit(id, 'created', { findingIds, severity: worst.detectedSeverity });
+      emit(id, 'ignored', {
+        reason: decision.reason,
+        ...(decision.comment === undefined ? {} : { comment: decision.comment }),
+        bornSuppressed: true,
+      });
       continue;
     }
 
@@ -446,9 +564,7 @@ export function reconcile(input: ReconcileInput): ReconcileResult {
     else if (regressedNow.has(key)) counts.regressed[severity]++;
     else if (updated.has(key)) counts.stillOpen[severity]++;
 
-    if (issue.status === 'open' || issue.status === 'regressed') {
-      exposureScore += SEVERITY_WEIGHTS[severity] * Math.min(daysBetween(issue.firstSeen, now), 90);
-    }
+    exposureScore += exposureOf(issue, now);
   }
 
   const summary: RunSummary = {

package/src/refingerprint.ts

@@ -0,0 +1,282 @@
+import type { Finding } from './finding.js';
+import type { FingerprintInput, VulnKeyInput } from './fingerprint.js';
+import { FINGERPRINT_VERSION, fingerprint, vulnKey } from './fingerprint.js';
+import type { Issue } from './issue.js';
+
+/**
+ * How to compute a fingerprint. Injected so the dry run can be pointed at a
+ * version that does not exist yet.
+ *
+ * **`@secureport/core` only ever contains one algorithm** — the current one,
+ * named by `FINGERPRINT_VERSION`. So on the day a version bump is being
+ * considered, the way to find out what it would do is to hand this planner
+ * the candidate implementation. Against the shipped algorithm the plan is a
+ * no-op by construction, which is exactly what makes it safe to run at any
+ * time and what lets the tests drive real merges and splits without a
+ * released `fp_v2`.
+ */
+export interface FingerprintAlgorithm {
+  readonly version: string;
+  fingerprintOf(input: FingerprintInput): string;
+  vulnKeyOf(input: VulnKeyInput): string;
+}
+
+/** The algorithm this build ships. */
+export const currentAlgorithm: FingerprintAlgorithm = {
+  version: FINGERPRINT_VERSION,
+  fingerprintOf: fingerprint,
+  vulnKeyOf: vulnKey,
+};
+
+/** An issue and the evidence a re-fingerprint would recompute it from. */
+export interface IssueWithEvidence {
+  readonly issue: Issue;
+  /**
+   * The evidence that **defines** this issue, which is not always every
+   * finding linked to it: `gatherForOrg` excludes what a merge attached from
+   * another issue, because that evidence describes a different weakness and
+   * re-deriving a key from it would split the survivor apart.
+   */
+  readonly findings: readonly Finding[];
+}
+
+/**
+ * What would happen to one issue.
+ *
+ * - `unchanged` — recomputes to the fingerprint it already has.
+ * - `moved` — one new fingerprint, different, and nothing else lands on it.
+ *   The issue keeps its identity and its history; only the key changes.
+ * - `merged` — its new fingerprint is shared with at least one other issue.
+ *   They become one, which is the outcome B39 and B41 are chasing.
+ * - `split` — its findings no longer agree on a fingerprint, so the issue
+ *   would become several. The most disruptive outcome and the one that most
+ *   needs reading before an execution.
+ * - `undecidable` — at least one of its findings cannot be re-keyed at all,
+ *   so no honest answer exists for it. See {@link planRefingerprint}.
+ */
+export type RefingerprintOutcome = 'unchanged' | 'moved' | 'merged' | 'split' | 'undecidable';
+
+export interface IssuePlan {
+  readonly issueId: string;
+  readonly targetId: string;
+  readonly title: string;
+  readonly from: string;
+  readonly fromVersion: string;
+  /** Distinct fingerprints this issue's evidence produces at the new version. */
+  readonly to: readonly string[];
+  readonly outcome: RefingerprintOutcome;
+  /** Other issues that land on one of `to`. Empty unless `outcome` involves a merge. */
+  readonly mergesWith: readonly string[];
+  /**
+   * Findings linked to the issue — **not necessarily the number the recompute
+   * read**. A manual issue is keyed from its own columns however much evidence
+   * is attached to it, and a scanner issue with zero findings falls back to
+   * the same path. Both are reported here as they stand so the count stays a
+   * fact about the data rather than about this function.
+   */
+  readonly evidence: number;
+}
+
+export interface RefingerprintPlan {
+  readonly fromVersion: string;
+  readonly toVersion: string;
+  readonly issues: readonly IssuePlan[];
+  readonly counts: Readonly<Record<RefingerprintOutcome, number>>;
+}
+
+/**
+ * Works out what re-fingerprinting every issue would do, and writes nothing.
+ *
+ * **Recomputed from inputs, never by comparing stored strings.** A stored
+ * `fp_v1` fingerprint and a stored `fp_v2` one are not comparable — that is
+ * the whole reason `reconcile()` refuses to run across versions (B45) — so
+ * the only honest question is "what does the new algorithm say about the same
+ * evidence?". That means re-deriving `vulnKey` too: B39's change was to the
+ * `vulnKey` fallback, and reading the stored value would miss precisely the
+ * class of change this migration exists for.
+ *
+ * **A manual issue is keyed from its own columns, evidence or not.** Findings
+ * can be attached to a human-raised issue after the fact; 24 of the 404 manual
+ * issues in the development database are. Re-deriving those from the evidence
+ * would replace the human's `vulnKey` with the scanner's and merge the issue
+ * into whichever upload-origin issue already holds that key — losing the
+ * issue a person raised, in a migration nobody expected to lose anything.
+ *
+ * **An issue an earlier merge retired keeps the key it has**, and this is what
+ * makes the plan reach a fixed point. A merge copies the duplicate's evidence
+ * to the survivor without removing it from the duplicate (B98), so re-deriving
+ * a retired issue from its evidence produces the survivor's key and proposes
+ * the merge that already happened — every run, forever. Checked before the
+ * manual rule, because an issue can be both and retirement is the later
+ * statement about its identity.
+ *
+ * **Findings are never touched, and this never needs them to be.** A finding
+ * is evidence (invariant 1) and `findings` rejects `UPDATE` at the database
+ * (B66); its `fingerprint_version` records which algorithm produced it and
+ * that stays true forever. Only `issues` are re-keyed. B69, 8 September.
+ *
+ * **A finding whose key cannot be re-derived makes its issue `undecidable`,
+ * and does not stop the report.** `vulnKey()` throws when a finding carries
+ * no mapped rule, CWE, category or engine rule id — so a row that was never
+ * produced by an importer at this version (or was produced by a different
+ * one) has no answer. Reporting that is the useful behaviour: a migration
+ * plan that dies on one row tells an operator nothing about the other
+ * thousand, and guessing a key from the stored value would defeat the whole
+ * purpose, since re-deriving `vulnKey` is the point.
+ */
+export function planRefingerprint(
+  input: readonly IssueWithEvidence[],
+  algorithm: FingerprintAlgorithm = currentAlgorithm,
+): RefingerprintPlan {
+  const recomputed = input.map(({ issue, findings }) => {
+    // Retirement is checked first, and the order is load-bearing. An issue an
+    // earlier merge retired is not re-keyed at all: its identity moved to the
+    // survivor, and its evidence — which the merge copied to that survivor —
+    // would re-derive the survivor's key and propose merging the two all over
+    // again, so the plan would never reach a fixed point. A *manual* issue
+    // that was later merged away is both things at once, and retirement is
+    // the later statement about its identity, so it wins. Measured: with the
+    // branches the other way round, 95 issues reported `moved` on every run
+    // while the executor left them alone on every run, forever.
+    if (issue.status === 'ignored' && issue.ignoreReason === 'duplicate') {
+      return { issue, evidence: findings.length, undecidable: false, to: [issue.fingerprint] };
+    }
+
+    // A manual issue is keyed from its own columns: its `vulnKey` and location
+    // were declared by a person, and evidence linked afterwards corroborates
+    // that issue rather than redefining it. Re-deriving would replace the
+    // human's key with the scanner's and dissolve the issue into whichever
+    // upload-origin issue already holds it.
+    //
+    // A *merge survivor* is deliberately not handled here, though it is also
+    // an identity a person asserted. Keying one from its own columns carries a
+    // stale `vulnKey` — written before the mapping table knew the engine's
+    // rule — so the migrated issue stops matching what the importer now
+    // produces, auto-resolves and comes back as new. `gatherForOrg` excludes
+    // the absorbed evidence instead, so a survivor re-derives correctly from
+    // what was always its own.
+    if (issue.origin === 'manual') {
+      return {
+        issue,
+        evidence: findings.length,
+        undecidable: false,
+        to: [fromOwnColumns(issue, algorithm)],
+      };
+    }
+
+    const keys = findings.map((f) => fingerprintOfFinding(issue, f, algorithm));
+    return {
+      issue,
+      evidence: findings.length,
+      undecidable: keys.some((k) => k === undefined),
+      to: [...new Set(keys.filter((k): k is string => k !== undefined))].sort(),
+    };
+  });
+
+  // A scanner-origin issue whose evidence has since been detached has nothing
+  // left to re-derive from, so it falls back to its own columns rather than
+  // vanishing from the report.
+  for (const row of recomputed) {
+    if (row.to.length === 0 && !row.undecidable) {
+      row.to = [fromOwnColumns(row.issue, algorithm)];
+    }
+  }
+
+  const owners = new Map<string, string[]>();
+  for (const row of recomputed) {
+    if (row.undecidable) continue;
+    for (const fp of row.to) {
+      const list = owners.get(fp);
+      if (list) list.push(row.issue.id);
+      else owners.set(fp, [row.issue.id]);
+    }
+  }
+
+  const counts: Record<RefingerprintOutcome, number> = {
+    unchanged: 0,
+    moved: 0,
+    merged: 0,
+    split: 0,
+    undecidable: 0,
+  };
+
+  const issues = recomputed.map(({ issue, evidence, to, undecidable }): IssuePlan => {
+    const mergesWith = [
+      ...new Set(to.flatMap((fp) => owners.get(fp) ?? []).filter((id) => id !== issue.id)),
+    ].sort();
+
+    // Split first: an issue that fragments is the most disruptive outcome
+    // and stays visible even when one of its fragments also collides.
+    const outcome: RefingerprintOutcome = undecidable
+      ? 'undecidable'
+      : to.length > 1
+        ? 'split'
+        : mergesWith.length > 0
+          ? 'merged'
+          : to[0] === issue.fingerprint
+            ? 'unchanged'
+            : 'moved';
+
+    counts[outcome] += 1;
+    return {
+      issueId: issue.id,
+      targetId: issue.targetId,
+      title: issue.title,
+      from: issue.fingerprint,
+      fromVersion: issue.fingerprintVersion,
+      to,
+      outcome,
+      mergesWith,
+      evidence,
+    };
+  });
+
+  const fromVersions = [...new Set(input.map(({ issue }) => issue.fingerprintVersion))].sort();
+  return {
+    fromVersion: fromVersions.join(', ') || algorithm.version,
+    toVersion: algorithm.version,
+    issues,
+    counts,
+  };
+}
+
+/** An issue's fingerprint at the new version, from the issue's own columns. */
+function fromOwnColumns(issue: Issue, algorithm: FingerprintAlgorithm): string {
+  return algorithm.fingerprintOf({
+    targetId: issue.targetId,
+    vulnKey: issue.vulnKey,
+    location: issue.location,
+    ...(issue.parameter === undefined ? {} : { parameter: issue.parameter }),
+  });
+}
+
+/**
+ * One finding's fingerprint at the new version, `vulnKey` re-derived and all,
+ * or `undefined` when the key cannot be derived from what the finding holds.
+ */
+function fingerprintOfFinding(
+  issue: Issue,
+  finding: Finding,
+  algorithm: FingerprintAlgorithm,
+): string | undefined {
+  let key;
+  try {
+    key = algorithm.vulnKeyOf({
+      sourceEngine: finding.sourceEngine,
+      ...(finding.sourceRuleId === undefined ? {} : { sourceRuleId: finding.sourceRuleId }),
+      ...(finding.cwe === undefined ? {} : { cwe: finding.cwe }),
+      ...(finding.category === undefined ? {} : { category: finding.category }),
+    });
+  } catch {
+    return undefined;
+  }
+  return algorithm.fingerprintOf({
+    // The target is the issue's: a finding records the run it came from, and
+    // every run of an issue's evidence is against the same target anyway.
+    targetId: issue.targetId,
+    vulnKey: key,
+    location: finding.location,
+    ...(finding.parameter === undefined ? {} : { parameter: finding.parameter }),
+    ...(finding.port === undefined ? {} : { port: finding.port }),
+  });
+}

package/src/report/anchors.ts

@@ -0,0 +1,96 @@
+/**
+ * Heading anchors and the contents list, produced together.
+ *
+ * **One pass over the rendered body, not two walks over the document.** A
+ * contents list built separately from the ids it links to is a list that can
+ * point at nothing — the failure is silent, it only shows up when somebody
+ * clicks, and it would appear the moment a heading's wording changed in one
+ * place and not the other. Here the ids and the entries come out of the same
+ * scan, so a heading that exists has an anchor and an entry, and one that does
+ * not exist has neither.
+ *
+ * This post-processes the renderer's **own** output, inside the same function
+ * that produced it. That is a different thing from the string surgery P7.1
+ * rules out: the rule there is against forking a published template, and this
+ * never reads one — every heading it matches was emitted a few lines earlier by
+ * the renderer calling it.
+ */
+
+/** One line of the contents list. */
+export interface TocEntry {
+  /** Heading level, 2 or 3. */
+  readonly level: number;
+
+  /** The anchor it links to, without the `#`. */
+  readonly id: string;
+
+  /** The heading as printed. */
+  readonly text: string;
+}
+
+/**
+ * A heading's anchor: lowercase, punctuation dropped, spaces hyphenated.
+ *
+ * The same rule GitHub and most Markdown renderers use, so a Markdown
+ * report's contents links resolve in the places Markdown is usually read —
+ * which is the only way this can work at all, because Markdown headings carry
+ * no explicit id to point at.
+ */
+function slug(text: string): string {
+  return (
+    text
+      .toLowerCase()
+      // Entities first: a heading rendered as `AT&T` should anchor on the
+      // text a reader sees, not on the escape that produced it.
+      .replace(/&[a-z]+;/gu, ' ')
+      .replace(/[^a-z0-9]+/gu, '-')
+      .replace(/^-+|-+$/gu, '') || 'section'
+  );
+}
+
+/** Makes `id` unique within a document, the way a duplicate heading is usually handled. */
+function unique(id: string, taken: Map<string, number>): string {
+  const seen = taken.get(id) ?? 0;
+  taken.set(id, seen + 1);
+  return seen === 0 ? id : `${id}-${String(seen)}`;
+}
+
+/**
+ * Gives every `<h2>` and `<h3>` an id, and reports what it found.
+ *
+ * `<h4>` is deliberately left alone: it is an individual issue, and a report
+ * with sixty findings would have a contents list longer than its summary.
+ */
+export function anchorHtmlHeadings(html: string): { html: string; toc: TocEntry[] } {
+  const toc: TocEntry[] = [];
+  const taken = new Map<string, number>();
+
+  // Safe over this input because it is this package's own markup rather than
+  // anything from outside: h2 and h3 are emitted with plain escaped text and
+  // never with nested elements.
+  const anchored = html.replace(
+    /<h([23])([^>]*)>([\s\S]*?)<\/h\1>/gu,
+    (_match, level: string, attrs: string, text: string) => {
+      const id = unique(slug(text), taken);
+      toc.push({ level: Number(level), id, text });
+      return `<h${level}${attrs} id="${id}">${text}</h${level}>`;
+    },
+  );
+
+  return { html: anchored, toc };
+}
+
+/** The same, for Markdown, where the anchor is implied by the heading text. */
+export function markdownHeadings(lines: readonly string[]): TocEntry[] {
+  const toc: TocEntry[] = [];
+  const taken = new Map<string, number>();
+
+  for (const line of lines) {
+    const match = /^(#{2,3})\s+(.*)$/u.exec(line);
+    if (!match) continue;
+    const text = match[2];
+    toc.push({ level: match[1].length, id: unique(slug(text), taken), text });
+  }
+
+  return toc;
+}