@descent-vtt/spec-brief 0.2.2 → 0.2.4

package/CHANGELOG.md

@@ -2,6 +2,68 @@
 
 Notable changes, newest first. Versions follow [semver](https://semver.org).
 
+## 0.2.4
+
+spec-core at 65ef842. Archival rewrites a link reference definition only
+where CommonMark reads one, so text shaped like a definition - under a
+paragraph's text, in alt text, in a wiki link's text - stays as written.
+
+### Changed
+
+- spec-core at 65ef842. Its Markdown scanner reads a link reference
+  definition as CommonMark does. A definition cannot interrupt a paragraph:
+  `[r]: r.md` on the line under a paragraph's text, a lazy line in a block
+  quote or a list item included, is that text, and `archive` and
+  `unarchive` leave it as written, where they rewrote `r.md`. A label holds
+  no unescaped bracket and at most 999 characters: `[[r]: r.md](z.md)` is a
+  link to `z.md`, which they rewrite, where they rewrote `r.md](z.md)` as
+  the destination of a definition, and `[a\]b]: x.md` is a definition,
+  whose `x.md` they now rewrite.
+- References follow the definitions. With `[r]: r.md` written under text,
+  `[x][r](y.md)` is a link to `y.md`, which archival now rewrites. A second
+  bracket holding a bracket is no label, so with `[r]` defined,
+  `[x [r][a[b]c] y](o.md)` holds the reference `[r]`, and `(o.md)` is text
+  and stays as written, as around any link inside a link.
+
+### Fixed
+
+- Text shaped like a definition at the start of an image's alt text or a
+  wiki link's text, `![[r]: r.md](z.png)` or `[[[r]: r.md]]`, is no longer
+  rewritten by `archive`. spec-brief reads those texts again on their own,
+  where such text opens a document and reads as a definition; CommonMark
+  reads none there. `z.png` is rewritten as before.
+
+## 0.2.3
+
+spec-core at 119345e. A link inside a link now counts only the inner one, as
+CommonMark and a renderer read it, so archival leaves the outer destination
+as written. The refusal of `**` inside a name suggests patterns built from
+the one written.
+
+### Changed
+
+- spec-core at 119345e. Its Markdown scanner reads a link inside a link's
+  text as CommonMark does: in `[a [b](inner.md) c](outer.md)` the inner pair
+  is the link, and the outer brackets and `(outer.md)` are text. `archive`
+  and `unarchive` rewrite `inner.md` and leave `(outer.md)` as written,
+  where they rewrote both; a renderer links nothing to `outer.md`, so it
+  does not move with the brief. spec-brief no longer reads a link's text
+  again to find the inner link. It still reads an image's alt text and a
+  wiki link's text, which the scanner leaves unread, and keeps each
+  destination once.
+- The `glob` error for `**` inside a name suggests the pattern written,
+  spelled both ways it may have meant: `docs/**.md` is told `docs/**/*.md`
+  for any depth or `docs/*.md` for one level, and `src/a**` `src/a*/**` or
+  `src/a*`, where every such pattern was told `docs/**/*.md` or `*.md`. The
+  message's first clause is as it was.
+
+### Fixed
+
+- Text shaped like a reference definition at the start of a link's text,
+  `see [[r]: r.md](z.md)`, is no longer rewritten by `archive`. spec-brief
+  read the link's text on its own, where that text starts a line and reads
+  as a definition.
+
 ## 0.2.2
 
 A packaging fix: the tarball no longer carries spec-core's internal README.

package/README.md

@@ -200,7 +200,7 @@ A repository whose briefs have eight ordered sections, `proposed` and `archived`
 
 Section names compare without case, typographic quotes, emphasis, a leading number or a trailing colon, and a heading may add a qualifier after a separator: `## 2. Commander’s Intent:` fills `Commander's Intent`, and `## Invariants (must hold)` fills `Invariants`.
 
-A brief is read as CommonMark reads it wherever that decides what is code or a comment - fenced and indented code, `<pre>`, `<script>`, `<style>` and `<textarea>` blocks, code spans, HTML comments - and nothing inside those is structure. A section, and the title, is an ATX heading, `## Name`, outside a block quote: prose over a `---` line is prose and a rule, and a heading quoted from another document is not one of the brief's sections. A task is a list item outside a block quote with `[ ]`, `[x]` or `[X]`. The links archival rewrites are the ones that write a destination: `[text](dest)`, `![alt](dest)` - one inside a link's text too - and a definition, `[label]: dest`, through which a reference is rewritten once.
+A brief is read as CommonMark reads it wherever that decides what is code or a comment - fenced and indented code, `<pre>`, `<script>`, `<style>` and `<textarea>` blocks, code spans, HTML comments - and nothing inside those is structure. A section, and the title, is an ATX heading, `## Name`, outside a block quote: prose over a `---` line is prose and a rule, and a heading quoted from another document is not one of the brief's sections. A task is a list item outside a block quote with `[ ]`, `[x]` or `[X]`. The links archival rewrites are the ones that write a destination: `[text](dest)`, `![alt](dest)` - one inside a link's text too - and a definition, `[label]: dest`, through which a reference is rewritten once. A definition is one where CommonMark reads it, opening a paragraph or under another: the shape of one under a paragraph's text, or in alt text, is text and stays as written.
 
 ## Rules
 

package/dist/markdown.d.ts

@@ -13,8 +13,11 @@
  *   space, `x` or `X`. The scanner reads `[~]`, `[?]` and others as well,
  *   which a brief does not write.
  * - A link destination is one written in the link or in a definition: the
- *   inline form and the definition, images included, an image or a link inside
- *   a link's text too, each once. A reference is rewritten through its
+ *   inline form and the definition, images included, an image inside a link's
+ *   text, and a link or an image in an image's alt text or a wiki link's text
+ *   too, each once, but no definition there, where CommonMark reads none. A
+ *   link inside a link's text is the link, as CommonMark reads it, and the
+ *   brackets around it are text. A reference is rewritten through its
  *   definition, once.
  *
  * Everything here is in 0-based lines of the brief's `lines`, and columns

package/dist/markdown.js

@@ -13,8 +13,11 @@
  *   space, `x` or `X`. The scanner reads `[~]`, `[?]` and others as well,
  *   which a brief does not write.
  * - A link destination is one written in the link or in a definition: the
- *   inline form and the definition, images included, an image or a link inside
- *   a link's text too, each once. A reference is rewritten through its
+ *   inline form and the definition, images included, an image inside a link's
+ *   text, and a link or an image in an image's alt text or a wiki link's text
+ *   too, each once, but no definition there, where CommonMark reads none. A
+ *   link inside a link's text is the link, as CommonMark reads it, and the
+ *   brackets around it are text. A reference is rewritten through its
  *   definition, once.
  *
  * Everything here is in 0-based lines of the brief's `lines`, and columns
@@ -29,23 +32,29 @@ function isBox(checkbox) {
 /**
  * The links that write their destination - inline links and images, and
  * definitions - with offsets into the text scanned `at` that offset, added to
- * `found` by the offset of the destination.
+ * `found`.
  *
- * A link's text may hold an image, `[![diagram](d.png)](d.md)`, whose
- * destination moves with the brief as the link's does. spec-core lists it
- * after the link, and reads nothing else there: not a link in the text,
- * `[a [b](b.md)](c.md)`, which CommonMark takes as the link where spec-core
- * takes the outer pair, nor an image in an image's alt text or a wiki link's.
- * So each text is read again here, which finds spec-core's image a second
- * time. It is one destination, kept once, because two rewrites of the same
- * columns would write the second over the first. Each text is shorter than
- * the one it came from, so the reading ends.
+ * spec-core reads a link's text as CommonMark does: a link inside it is the
+ * link, so `[a [b](b.md)](c.md)` gives `b.md` alone, and an image inside it,
+ * `[![diagram](d.png)](d.md)`, is listed after the link. It reads nothing in
+ * an image's alt text or a wiki link's text, where a destination still moves
+ * with the brief, so those two are read again here, as `inText`. Each is
+ * shorter than the text it came from, so the reading ends. Nor does spec-core
+ * list a definition inside one, since a bracket pairs across no definition's
+ * line, so each destination is found once, and no two rewrites meet on the
+ * same columns.
+ *
+ * Read on its own, such a text is a document, where `[r]: r.md` at its start
+ * is a definition. CommonMark reads none inside a paragraph's text, and a
+ * renderer shows `![[r]: r.md](z.png)` with that alt text as written, so a
+ * definition found there writes no destination.
  */
-function written(core, at, found) {
+function written(core, at, inText, found) {
     for (const link of core.links) {
-        written(scanMarkdown(link.text), at + core.text.indexOf(link.text, link.start), found);
-        if (link.form === 'inline' || link.form === 'definition') {
-            found.set(at + link.targetStart, { ...link, targetStart: at + link.targetStart, targetEnd: at + link.targetEnd });
+        if (link.image || link.form === 'wiki')
+            written(scanMarkdown(link.text), at + core.text.indexOf(link.text, link.start), true, found);
+        if (link.form === 'inline' || (link.form === 'definition' && !inText)) {
+            found.push({ ...link, targetStart: at + link.targetStart, targetEnd: at + link.targetEnd });
         }
     }
     return found;
@@ -64,7 +73,7 @@ export function scan(lines) {
         tasks: core.listItems
             .filter((item) => isBox(item.checkbox) && item.quoteDepth === 0)
             .map((item) => ({ line: item.line - 1, end: item.endLine, checked: item.checkbox !== ' ', text: item.firstLine })),
-        links: [...written(core, 0, new Map()).values()]
+        links: written(core, 0, false, [])
             .map((link) => {
             // A link's text may run over lines; its destination is on the last.
             const at = core.index.positionAt(link.targetStart);

package/dist/markdown.js.map

@@ -1 +1 @@
-{"version":3,"file":"markdown.js","sourceRoot":"","sources":["../src/markdown.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * A brief's Markdown: spec-core's scanner, copied into `src/vendor/spec-core/`,\n * read in spec-brief's dialect.\n *\n * The scanner is exact about what is code and what is a comment, as CommonMark\n * has it, and reports every heading, list item and link it finds. What of that\n * is a brief's structure is decided here (ADR-0001, amended 2026-09-26):\n *\n * - A heading is an ATX heading outside a block quote. Prose over a `---` is a\n *   setext heading to a renderer, and a brief that separates its parts that way\n *   must not grow a section from it; a heading in a block quote is quoted.\n * - A task is a list item outside a block quote with a box GFM renders: a\n *   space, `x` or `X`. The scanner reads `[~]`, `[?]` and others as well,\n *   which a brief does not write.\n * - A link destination is one written in the link or in a definition: the\n *   inline form and the definition, images included, an image or a link inside\n *   a link's text too, each once. A reference is rewritten through its\n *   definition, once.\n *\n * Everything here is in 0-based lines of the brief's `lines`, and columns\n * within them.\n */\n\nimport { type Link, linesOf, type MarkdownScan, scanMarkdown, type ScannedLine } from './vendor/spec-core/markdown/index.js';\nimport { textOfLines } from './text.js';\n\nexport interface Heading {\n  /** 0-based line. */\n  readonly line: number;\n  readonly level: number;\n  /** As a reader sees it: without a closing sequence or a comment. */\n  readonly text: string;\n}\n\nexport interface Section {\n  readonly heading: Heading;\n  /** 0-based line after the section's last line. The body starts on the line after the heading. */\n  readonly end: number;\n}\n\nexport interface TaskItem {\n  /** 0-based line of the box. */\n  readonly line: number;\n  /** 0-based line after the item's last line: its continuations and what is nested under it. */\n  readonly end: number;\n  readonly checked: boolean;\n  readonly text: string;\n}\n\nexport interface LinkDestination {\n  /** 0-based line. */\n  readonly line: number;\n  /** Columns of the destination within the line, end exclusive. */\n  readonly start: number;\n  readonly end: number;\n  readonly target: string;\n}\n\nexport interface Scan {\n  readonly lines: readonly string[];\n  /** Lines with front matter and comments blanked, and code kept: what counts as content. */\n  readonly prose: readonly string[];\n  /** Lines with front matter, code, raw-text HTML and comments blanked: what counts as structure. */\n  readonly masked: readonly string[];\n  readonly headings: readonly Heading[];\n  readonly tasks: readonly TaskItem[];\n  /** Destinations outside code and comments, each once, in the order of their lines and columns. */\n  readonly links: readonly LinkDestination[];\n}\n\n/** Whether a checkbox is one a task is written with. */\nfunction isBox(checkbox: string | null): boolean {\n  return checkbox === ' ' || checkbox === 'x' || checkbox === 'X';\n}\n\n/**\n * The links that write their destination - inline links and images, and\n * definitions - with offsets into the text scanned `at` that offset, added to\n * `found` by the offset of the destination.\n *\n * A link's text may hold an image, `[![diagram](d.png)](d.md)`, whose\n * destination moves with the brief as the link's does. spec-core lists it\n * after the link, and reads nothing else there: not a link in the text,\n * `[a [b](b.md)](c.md)`, which CommonMark takes as the link where spec-core\n * takes the outer pair, nor an image in an image's alt text or a wiki link's.\n * So each text is read again here, which finds spec-core's image a second\n * time. It is one destination, kept once, because two rewrites of the same\n * columns would write the second over the first. Each text is shorter than\n * the one it came from, so the reading ends.\n */\nfunction written(core: MarkdownScan, at: number, found: Map<number, Link>): Map<number, Link> {\n  for (const link of core.links) {\n    written(scanMarkdown(link.text), at + core.text.indexOf(link.text, link.start), found);\n    if (link.form === 'inline' || link.form === 'definition') {\n      found.set(at + link.targetStart, { ...link, targetStart: at + link.targetStart, targetEnd: at + link.targetEnd });\n    }\n  }\n  return found;\n}\n\n/** Scans a brief's lines, which carry no byte-order mark. */\nexport function scan(lines: readonly string[]): Scan {\n  const core = scanMarkdown(textOfLines(lines));\n  const unquoted = (line: number): boolean => (core.lines[line - 1] as ScannedLine).quoteDepth === 0;\n  return {\n    lines,\n    prose: linesOf(core, 'prose'),\n    masked: linesOf(core, 'structure'),\n    headings: core.headings\n      .filter((h) => h.form === 'atx' && unquoted(h.line))\n      .map((h) => ({ line: h.line - 1, level: h.level, text: h.text })),\n    tasks: core.listItems\n      .filter((item) => isBox(item.checkbox) && item.quoteDepth === 0)\n      .map((item) => ({ line: item.line - 1, end: item.endLine, checked: item.checkbox !== ' ', text: item.firstLine })),\n    links: [...written(core, 0, new Map()).values()]\n      .map((link) => {\n        // A link's text may run over lines; its destination is on the last.\n        const at = core.index.positionAt(link.targetStart);\n        const start = at.column - 1;\n        return { line: at.line - 1, start, end: start + link.targetEnd - link.targetStart, target: link.target };\n      })\n      .sort((a, b) => a.line - b.line || a.start - b.start),\n  };\n}\n\n/** Sections: every heading below the title, running to the next heading at its level or above. */\nexport function sectionsOf(result: Scan): Section[] {\n  const sections: Section[] = [];\n  const { headings } = result;\n  for (let h = 0; h < headings.length; h += 1) {\n    const heading = headings[h] as Heading;\n    if (heading.level < 2) continue;\n    let end = result.lines.length;\n    for (let k = h + 1; k < headings.length; k += 1) {\n      const next = headings[k] as Heading;\n      if (next.level <= heading.level) {\n        end = next.line;\n        break;\n      }\n    }\n    sections.push({ heading, end });\n  }\n  return sections;\n}\n\n/** The first level-one heading, which is what a reader takes as the title. */\nexport function titleOf(result: Scan): Heading | undefined {\n  return result.headings.find((h) => h.level === 1);\n}\n\n/** Whether a line carries anything once comments are removed. */\nexport function hasContent(proseLine: string): boolean {\n  return proseLine.trim().length > 0;\n}\n"]}
+{"version":3,"file":"markdown.js","sourceRoot":"","sources":["../src/markdown.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * A brief's Markdown: spec-core's scanner, copied into `src/vendor/spec-core/`,\n * read in spec-brief's dialect.\n *\n * The scanner is exact about what is code and what is a comment, as CommonMark\n * has it, and reports every heading, list item and link it finds. What of that\n * is a brief's structure is decided here (ADR-0001, amended 2026-09-26):\n *\n * - A heading is an ATX heading outside a block quote. Prose over a `---` is a\n *   setext heading to a renderer, and a brief that separates its parts that way\n *   must not grow a section from it; a heading in a block quote is quoted.\n * - A task is a list item outside a block quote with a box GFM renders: a\n *   space, `x` or `X`. The scanner reads `[~]`, `[?]` and others as well,\n *   which a brief does not write.\n * - A link destination is one written in the link or in a definition: the\n *   inline form and the definition, images included, an image inside a link's\n *   text, and a link or an image in an image's alt text or a wiki link's text\n *   too, each once, but no definition there, where CommonMark reads none. A\n *   link inside a link's text is the link, as CommonMark reads it, and the\n *   brackets around it are text. A reference is rewritten through its\n *   definition, once.\n *\n * Everything here is in 0-based lines of the brief's `lines`, and columns\n * within them.\n */\n\nimport { type Link, linesOf, type MarkdownScan, scanMarkdown, type ScannedLine } from './vendor/spec-core/markdown/index.js';\nimport { textOfLines } from './text.js';\n\nexport interface Heading {\n  /** 0-based line. */\n  readonly line: number;\n  readonly level: number;\n  /** As a reader sees it: without a closing sequence or a comment. */\n  readonly text: string;\n}\n\nexport interface Section {\n  readonly heading: Heading;\n  /** 0-based line after the section's last line. The body starts on the line after the heading. */\n  readonly end: number;\n}\n\nexport interface TaskItem {\n  /** 0-based line of the box. */\n  readonly line: number;\n  /** 0-based line after the item's last line: its continuations and what is nested under it. */\n  readonly end: number;\n  readonly checked: boolean;\n  readonly text: string;\n}\n\nexport interface LinkDestination {\n  /** 0-based line. */\n  readonly line: number;\n  /** Columns of the destination within the line, end exclusive. */\n  readonly start: number;\n  readonly end: number;\n  readonly target: string;\n}\n\nexport interface Scan {\n  readonly lines: readonly string[];\n  /** Lines with front matter and comments blanked, and code kept: what counts as content. */\n  readonly prose: readonly string[];\n  /** Lines with front matter, code, raw-text HTML and comments blanked: what counts as structure. */\n  readonly masked: readonly string[];\n  readonly headings: readonly Heading[];\n  readonly tasks: readonly TaskItem[];\n  /** Destinations outside code and comments, each once, in the order of their lines and columns. */\n  readonly links: readonly LinkDestination[];\n}\n\n/** Whether a checkbox is one a task is written with. */\nfunction isBox(checkbox: string | null): boolean {\n  return checkbox === ' ' || checkbox === 'x' || checkbox === 'X';\n}\n\n/**\n * The links that write their destination - inline links and images, and\n * definitions - with offsets into the text scanned `at` that offset, added to\n * `found`.\n *\n * spec-core reads a link's text as CommonMark does: a link inside it is the\n * link, so `[a [b](b.md)](c.md)` gives `b.md` alone, and an image inside it,\n * `[![diagram](d.png)](d.md)`, is listed after the link. It reads nothing in\n * an image's alt text or a wiki link's text, where a destination still moves\n * with the brief, so those two are read again here, as `inText`. Each is\n * shorter than the text it came from, so the reading ends. Nor does spec-core\n * list a definition inside one, since a bracket pairs across no definition's\n * line, so each destination is found once, and no two rewrites meet on the\n * same columns.\n *\n * Read on its own, such a text is a document, where `[r]: r.md` at its start\n * is a definition. CommonMark reads none inside a paragraph's text, and a\n * renderer shows `![[r]: r.md](z.png)` with that alt text as written, so a\n * definition found there writes no destination.\n */\nfunction written(core: MarkdownScan, at: number, inText: boolean, found: Link[]): Link[] {\n  for (const link of core.links) {\n    if (link.image || link.form === 'wiki') written(scanMarkdown(link.text), at + core.text.indexOf(link.text, link.start), true, found);\n    if (link.form === 'inline' || (link.form === 'definition' && !inText)) {\n      found.push({ ...link, targetStart: at + link.targetStart, targetEnd: at + link.targetEnd });\n    }\n  }\n  return found;\n}\n\n/** Scans a brief's lines, which carry no byte-order mark. */\nexport function scan(lines: readonly string[]): Scan {\n  const core = scanMarkdown(textOfLines(lines));\n  const unquoted = (line: number): boolean => (core.lines[line - 1] as ScannedLine).quoteDepth === 0;\n  return {\n    lines,\n    prose: linesOf(core, 'prose'),\n    masked: linesOf(core, 'structure'),\n    headings: core.headings\n      .filter((h) => h.form === 'atx' && unquoted(h.line))\n      .map((h) => ({ line: h.line - 1, level: h.level, text: h.text })),\n    tasks: core.listItems\n      .filter((item) => isBox(item.checkbox) && item.quoteDepth === 0)\n      .map((item) => ({ line: item.line - 1, end: item.endLine, checked: item.checkbox !== ' ', text: item.firstLine })),\n    links: written(core, 0, false, [])\n      .map((link) => {\n        // A link's text may run over lines; its destination is on the last.\n        const at = core.index.positionAt(link.targetStart);\n        const start = at.column - 1;\n        return { line: at.line - 1, start, end: start + link.targetEnd - link.targetStart, target: link.target };\n      })\n      .sort((a, b) => a.line - b.line || a.start - b.start),\n  };\n}\n\n/** Sections: every heading below the title, running to the next heading at its level or above. */\nexport function sectionsOf(result: Scan): Section[] {\n  const sections: Section[] = [];\n  const { headings } = result;\n  for (let h = 0; h < headings.length; h += 1) {\n    const heading = headings[h] as Heading;\n    if (heading.level < 2) continue;\n    let end = result.lines.length;\n    for (let k = h + 1; k < headings.length; k += 1) {\n      const next = headings[k] as Heading;\n      if (next.level <= heading.level) {\n        end = next.line;\n        break;\n      }\n    }\n    sections.push({ heading, end });\n  }\n  return sections;\n}\n\n/** The first level-one heading, which is what a reader takes as the title. */\nexport function titleOf(result: Scan): Heading | undefined {\n  return result.headings.find((h) => h.level === 1);\n}\n\n/** Whether a line carries anything once comments are removed. */\nexport function hasContent(proseLine: string): boolean {\n  return proseLine.trim().length > 0;\n}\n"]}

package/dist/vendor/spec-core/markdown/index.d.ts

@@ -2,4 +2,4 @@ export { linesOf, scanMarkdown } from './scan.js';
 export { sectionsOf, slugify, titleOf } from './headings.js';
 export { findEntry, frontMatterCloses, frontMatterKind, isNull, keyName, parseInline, readFrontMatter, removeEntry, renderScalar, setEntry, } from './frontmatter.js';
 export type { FrontMatter, FrontMatterEntry, FrontMatterProblem, ReadOptions, YamlScalar, YamlValue, } from './frontmatter.js';
-export type { Block, BlockKind, FrontMatterBlock, FrontMatterKind, Heading, HeadingForm, HtmlComment, Link, LinkForm, ListItem, MarkdownScan, MaskKind, Masks, ScannedLine, Section, Table, TableCell, TableRow, } from './types.js';
+export type { Block, BlockKind, FrontMatterBlock, FrontMatterKind, Heading, HeadingForm, HtmlComment, Link, LinkForm, ListItem, MarkdownScan, MaskKind, Masks, ScannedLine, Section, Table, TableCell, TableRow, UnclosedFrontMatter, } from './types.js';

package/dist/vendor/spec-core/markdown/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/vendor/spec-core/markdown/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAClD,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAC7D,OAAO,EACL,SAAS,EACT,iBAAiB,EACjB,eAAe,EACf,MAAM,EACN,OAAO,EACP,WAAW,EACX,eAAe,EACf,WAAW,EACX,YAAY,EACZ,QAAQ,GACT,MAAM,kBAAkB,CAAC","sourcesContent":["export { linesOf, scanMarkdown } from './scan.js';\nexport { sectionsOf, slugify, titleOf } from './headings.js';\nexport {\n  findEntry,\n  frontMatterCloses,\n  frontMatterKind,\n  isNull,\n  keyName,\n  parseInline,\n  readFrontMatter,\n  removeEntry,\n  renderScalar,\n  setEntry,\n} from './frontmatter.js';\nexport type {\n  FrontMatter,\n  FrontMatterEntry,\n  FrontMatterProblem,\n  ReadOptions,\n  YamlScalar,\n  YamlValue,\n} from './frontmatter.js';\nexport type {\n  Block,\n  BlockKind,\n  FrontMatterBlock,\n  FrontMatterKind,\n  Heading,\n  HeadingForm,\n  HtmlComment,\n  Link,\n  LinkForm,\n  ListItem,\n  MarkdownScan,\n  MaskKind,\n  Masks,\n  ScannedLine,\n  Section,\n  Table,\n  TableCell,\n  TableRow,\n} from './types.js';\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/vendor/spec-core/markdown/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAClD,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAC7D,OAAO,EACL,SAAS,EACT,iBAAiB,EACjB,eAAe,EACf,MAAM,EACN,OAAO,EACP,WAAW,EACX,eAAe,EACf,WAAW,EACX,YAAY,EACZ,QAAQ,GACT,MAAM,kBAAkB,CAAC","sourcesContent":["export { linesOf, scanMarkdown } from './scan.js';\nexport { sectionsOf, slugify, titleOf } from './headings.js';\nexport {\n  findEntry,\n  frontMatterCloses,\n  frontMatterKind,\n  isNull,\n  keyName,\n  parseInline,\n  readFrontMatter,\n  removeEntry,\n  renderScalar,\n  setEntry,\n} from './frontmatter.js';\nexport type {\n  FrontMatter,\n  FrontMatterEntry,\n  FrontMatterProblem,\n  ReadOptions,\n  YamlScalar,\n  YamlValue,\n} from './frontmatter.js';\nexport type {\n  Block,\n  BlockKind,\n  FrontMatterBlock,\n  FrontMatterKind,\n  Heading,\n  HeadingForm,\n  HtmlComment,\n  Link,\n  LinkForm,\n  ListItem,\n  MarkdownScan,\n  MaskKind,\n  Masks,\n  ScannedLine,\n  Section,\n  Table,\n  TableCell,\n  TableRow,\n  UnclosedFrontMatter,\n} from './types.js';\n"]}

package/dist/vendor/spec-core/markdown/links.d.ts

@@ -10,6 +10,12 @@
  * badge wrapped in a link has two destinations - and for nothing else; each
  * is listed after the link it lies in.
  *
+ * Links may not contain links, as CommonMark has it: in
+ * `[a [b](inner.md) c](outer.md)` the inner pair is the link, and the outer
+ * brackets and `(outer.md)` are text. So before a paragraph is read its pairs
+ * are read innermost first, as CommonMark reads them, to learn which `[`
+ * holds a link at any depth.
+ *
  * Brackets are paired once per paragraph with a stack, and the tables that
  * say where a destination or a title ends are built once per paragraph, so
  * no bracket searches the text again for its partner. A document of nothing
@@ -21,5 +27,5 @@
  * move a bound onto those places change no answer, and are equivalent.
  */
 import { type Layout } from './layout.js';
-import type { Link } from './types.js';
-export declare function findLinks(layout: Layout): Link[];
+import type { Heading, Link } from './types.js';
+export declare function findLinks(layout: Layout, headings: readonly Heading[]): Link[];

package/dist/vendor/spec-core/markdown/links.js

@@ -10,6 +10,12 @@
  * badge wrapped in a link has two destinations - and for nothing else; each
  * is listed after the link it lies in.
  *
+ * Links may not contain links, as CommonMark has it: in
+ * `[a [b](inner.md) c](outer.md)` the inner pair is the link, and the outer
+ * brackets and `(outer.md)` are text. So before a paragraph is read its pairs
+ * are read innermost first, as CommonMark reads them, to learn which `[`
+ * holds a link at any depth.
+ *
  * Brackets are paired once per paragraph with a stack, and the tables that
  * say where a destination or a title ends are built once per paragraph, so
  * no bracket searches the text again for its partner. A document of nothing
@@ -21,7 +27,8 @@
  * move a bound onto those places change no answer, and are equivalent.
  */
 import { inRanges, mergeRanges } from '../text/index.js';
-import { isMarkdown, isSpaceOrTab, visibleLead } from './layout.js';
+import { isMarkdown, isSpaceOrTab, leadOffset, visibleLead } from './layout.js';
+import { atxLevel, isThematicBreak, listMarker } from './syntax.js';
 const BANG = 33;
 const DOUBLE_QUOTE = 34;
 const SINGLE_QUOTE = 39;
@@ -36,13 +43,17 @@ const LF = 10;
 const CR = 13;
 /** CommonMark: a link label holds at most 999 characters. */
 const MAX_LABEL = 999;
-const DEFINITION = /^ {0,3}\[(?!\^)([^\]]+)\]:[ \t]*(<[^<>]*>|\S+)/;
+/**
+ * A label holds no bracket but an escaped one. Its two alternatives never
+ * start on the same character, so a label is read without backtracking.
+ */
+const DEFINITION = /^ {0,3}\[(?!\^)((?:[^[\]\\]|\\.)+)\]:[ \t]*(<[^<>]*>|\S+)/;
 /** What may follow a definition's destination: nothing, or a title after whitespace. */
 const TITLE_ONLY = /^(?:[ \t]+(?:"[^"]*"|'[^']*'|\([^)]*\)))?[ \t]*$/;
 const AUTOLINK = /<((?:https?|ftp|mailto):[^<>\s]+)>/g;
-export function findLinks(layout) {
+export function findLinks(layout, headings) {
     const definitions = new Map();
-    const defined = readDefinitions(layout, definitions);
+    const defined = readDefinitions(layout, headings, definitions);
     const bracketed = readBrackets(layout, definitions, new Set(defined.map((d) => d.line)));
     // `<https://x>` as a link's destination or text is part of that link.
     const taken = mergeRanges([...defined, ...bracketed]);
@@ -64,20 +75,31 @@ function normalizeLabel(label) {
  *
  * `[Note]: this matters` is prose that looks like one, so a definition has
  * nothing after its destination but a title. `[^1]: text` is a footnote.
+ *
+ * A definition cannot interrupt a paragraph, as CommonMark has it: one
+ * written on the line under a paragraph's text is that text. It opens a
+ * paragraph, or follows a definition that did.
  */
-function readDefinitions(layout, definitions) {
-    const { text, structure } = layout;
+function readDefinitions(layout, headings, definitions) {
+    const { text, structure, lines, continues } = layout;
+    const closed = closingLines(layout, headings);
     const out = [];
-    for (const line of layout.lines) {
+    for (const line of lines) {
         if (!isMarkdown(line) || !visibleLead(layout, line))
             continue;
         const masked = structure.slice(line.contentStart, line.end);
         const match = DEFINITION.exec(masked);
         if (match === null || !TITLE_ONLY.test(masked.slice(match[0].length)))
             continue;
+        // Under a definition the paragraph holds nothing else yet. `continues`
+        // holds no first line, so there is a line above whenever it is asked about.
+        const follows = out[out.length - 1]?.line === line.line - 1;
+        if (!follows && continues.has(line.line) && paragraphOpen(lines[line.line - 2], closed))
+            continue;
+        const between = match[1].length;
         const start = line.contentStart + match[0].indexOf('[');
-        const label = text.slice(start + 1, start + 1 + match[1].length).trim();
-        if (label.length === 0)
+        const label = text.slice(start + 1, start + 1 + between).trim();
+        if (label.length === 0 || between > MAX_LABEL)
             continue;
         const written = match[2];
         const end = line.contentStart + match[0].length;
@@ -92,6 +114,40 @@ function readDefinitions(layout, definitions) {
     }
     return out;
 }
+/**
+ * The lines after which no paragraph is open, though the line under one
+ * would go on with a paragraph written there: the last line of a heading,
+ * and of an HTML block a comment opens. Such a block starts where a comment
+ * opens a line, after at most three columns, and ends on the line the
+ * comment closes on.
+ */
+function closingLines(layout, headings) {
+    const closed = new Set();
+    for (const heading of headings)
+        closed.add(heading.endLine);
+    for (const comment of layout.comments) {
+        const opened = layout.lines[comment.line - 1];
+        if (opened.indent <= 3 && comment.start === leadOffset(opened))
+            closed.add(layout.index.positionAt(comment.end).line);
+    }
+    return closed;
+}
+/**
+ * Whether a paragraph is open after a line, for the line under it to go on
+ * with. None is after a blank line, code, a thematic break or a closing
+ * line, and none is open in a list item whose marker has nothing after it,
+ * or a heading or a thematic break.
+ */
+function paragraphOpen(line, closed) {
+    if (!isMarkdown(line) || line.blank || closed.has(line.line) || isThematicBreak(line.content))
+        return false;
+    const marker = listMarker(line.content);
+    if (marker === null)
+        return true;
+    // The marker takes every space after it, so what is left is empty or text.
+    const rest = line.content.slice(marker.offset + marker.width);
+    return rest.length > 0 && atxLevel(rest) === 0 && !isThematicBreak(rest);
+}
 function readAutolinks(layout) {
     const out = [];
     for (const match of layout.structure.matchAll(AUTOLINK)) {
@@ -112,26 +168,39 @@ function readAutolinks(layout) {
     }
     return out;
 }
-/** Pairs `[` with `]` inside a paragraph, innermost first, skipping escaped ones. */
 function pairBrackets(structure, from, to) {
-    const pairs = new Map();
+    const brackets = { pairs: new Map(), outer: new Map(), before: new Map(), images: new Set(), nested: new Set() };
+    const { pairs } = brackets;
     const open = [];
+    let escaped = -1;
     for (let at = from; at < to; at += 1) {
         const ch = structure.charCodeAt(at);
-        if (ch === BACKSLASH)
+        if (ch === BACKSLASH) {
+            escaped = at + 1;
             at += 1;
-        else if (ch === OPEN_BRACKET)
-            open.push(at);
+        }
+        else if (ch === OPEN_BRACKET) {
+            open.push({ at, before: pairs.size });
+            if (structure.charCodeAt(at - 1) === BANG && escaped !== at - 1)
+                brackets.images.add(at);
+        }
         else if (ch === CLOSE_BRACKET) {
             // A `]` with nothing to close pairs with nothing; recorded under
             // `undefined` it would not be found either, so this test changes no
-            // answer, only what the map holds.
+            // answer, only what the maps hold.
             const opened = open.pop();
-            if (opened !== undefined)
-                pairs.set(opened, at);
+            if (opened !== undefined) {
+                pairs.set(opened.at, at);
+                brackets.before.set(opened.at, opened.before);
+                const around = open[open.length - 1];
+                if (around !== undefined) {
+                    brackets.outer.set(opened.at, around.at);
+                    brackets.nested.add(around.at);
+                }
+            }
         }
     }
-    return pairs;
+    return brackets;
 }
 function endsOf(structure, from, to) {
     const length = to - from;
@@ -167,8 +236,9 @@ function endsOf(structure, from, to) {
 }
 /**
  * The bracket forms, a paragraph at a time. A paragraph here is a run of
- * Markdown lines, none blank, each continuing the one above: a bracket never
- * pairs across a blank line, a heading, or the start of another block.
+ * Markdown lines, none blank or a definition, each continuing the one above:
+ * a bracket never pairs across a blank line, a heading, a definition, or the
+ * start of another block.
  */
 function readBrackets(layout, definitions, defined) {
     const { lines, continues, structure, text } = layout;
@@ -178,10 +248,13 @@ function readBrackets(layout, definitions, defined) {
     let doubleClose = -2;
     const lookup = (from, to) => to - from > MAX_LABEL ? undefined : definitions.get(normalizeLabel(text.slice(from, to)));
     // A blank or code line let into a paragraph would bring only characters the
-    // structure mask blanks, so this test shapes the runs and changes no link.
+    // structure mask blanks, so those two tests shape the runs and change no
+    // link. A definition's line is no paragraph's: it holds a label, a
+    // destination and a title, none of them a link, and the text after it is a
+    // paragraph of its own, whose brackets pair with nothing before it.
     const inParagraph = (i) => {
         const line = lines[i];
-        return line !== undefined && isMarkdown(line) && !line.blank;
+        return line !== undefined && isMarkdown(line) && !line.blank && !defined.has(i + 1);
     };
     for (let first = 0; first < lines.length; first += 1) {
         if (!inParagraph(first))
@@ -191,7 +264,10 @@ function readBrackets(layout, definitions, defined) {
             last += 1;
         const from = lines[first].start;
         const to = lines[last].end;
-        const pairs = pairBrackets(structure, from, to);
+        const brackets = pairBrackets(structure, from, to);
+        const { pairs } = brackets;
+        // Each `[` with a link inside it, at any depth.
+        const holding = new Set();
         let ends = null;
         // Spaces and tabs, and at most one line ending inside the paragraph. The
         // character at `to` ends the paragraph's last line and is none of these.
@@ -300,7 +376,8 @@ function readBrackets(layout, definitions, defined) {
         };
         const bracket = (at, start, image, line) => {
             const close = pairs.get(at);
-            if (close === undefined)
+            // A link holding a link is text; an image holding one is still an image.
+            if (close === undefined || (!image && holding.has(at)))
                 return null;
             const label = () => text.slice(at + 1, close).trim();
             if (structure.charCodeAt(close + 1) === OPEN_PAREN) {
@@ -311,11 +388,14 @@ function readBrackets(layout, definitions, defined) {
                 }
             }
             else {
-                // Only a `[` is paired, so a second label follows exactly when this finds one.
+                // Only a `[` is paired, so a second bracket follows exactly when this
+                // finds one. It is a label unless it holds a bracket, which it does
+                // when a pair lies inside it, or more than 999 characters; one that is
+                // not leaves the first bracket to be read as a shortcut.
                 const refClose = pairs.get(close + 1);
-                if (refClose !== undefined) {
+                if (refClose !== undefined && refClose - close - 2 <= MAX_LABEL && !brackets.nested.has(close + 1)) {
                     // `[text][]` is read through its text; `[text][label]` through its label.
-                    const collapsed = refClose - close - 2 <= MAX_LABEL && text.slice(close + 2, refClose).trim() === '';
+                    const collapsed = text.slice(close + 2, refClose).trim() === '';
                     const found = collapsed ? lookup(at + 1, close) : lookup(close + 2, refClose);
                     if (found === undefined)
                         return null;
@@ -329,10 +409,32 @@ function readBrackets(layout, definitions, defined) {
                 return null;
             return { form: 'shortcut', image, text: label(), label: label(), start, end: close + 1, line: line.line, ...found };
         };
-        let escaped = -1;
+        const lineAt = (at) => lines[layout.index.positionAt(at).line - 1];
+        // CommonMark reads each pair at its `]`, so the pairs inside a `[` are
+        // read before it, and a link among them makes it text, and every `[`
+        // open around it: the pairs come innermost first, and fill `holding` on
+        // the way out. An image among them does not; a link may hold one. What a
+        // link or an image reads past its `]` - a destination, a title, a second
+        // label - is not read for links again: `reach` is the furthest any of the
+        // first so many pairs read to, and a `[` short of it opens nothing.
+        const reach = [from];
+        for (const at of pairs.keys()) {
+            const line = lineAt(at);
+            const image = brackets.images.has(at);
+            const passed = reach[brackets.before.get(at)] > at;
+            const link = passed ? null : bracket(at, at, image, line);
+            reach.push(Math.max(reach[reach.length - 1], link === null ? from : link.end));
+            const around = brackets.outer.get(at);
+            if (around !== undefined && (holding.has(at) || (link !== null && !image)))
+                holding.add(around);
+        }
         let at = from;
         // Inside a link's text, up to its `]`, where CommonMark reads an image -
         // a badge wrapped in a link - but no other link; then on past the link.
+        // `textEnd` is -1 or a `]` that closes a `[`, so never 0, and the `]` is
+        // read as no link. Leaving one step later, past it, resumes at the same
+        // place, or ends the paragraph where a shortcut link ended it anyway: the
+        // test below reads the same with `textEnd > 0` or `at > textEnd`.
         let textEnd = -1;
         let resume = -1;
         while (at < to) {
@@ -343,7 +445,6 @@ function readBrackets(layout, definitions, defined) {
             }
             const ch = structure.charCodeAt(at);
             if (ch === BACKSLASH) {
-                escaped = at + 1;
                 at += 2;
                 continue;
             }
@@ -351,14 +452,8 @@ function readBrackets(layout, definitions, defined) {
                 at += 1;
                 continue;
             }
-            const line = lines[layout.index.positionAt(at).line - 1];
-            // A definition's line holds its label, its destination and its title,
-            // and none of them is a link.
-            if (defined.has(line.line)) {
-                at = line.end;
-                continue;
-            }
-            const image = structure.charCodeAt(at - 1) === BANG && escaped !== at - 1;
+            const line = lineAt(at);
+            const image = brackets.images.has(at);
             const start = image ? at - 1 : at;
             const link = wiki(at, start, image, line) ?? bracket(at, start, image, line);
             if (textEnd >= 0) {