From efae7a77c9b73b3682ddaf4956ebffae39d74cf6 Mon Sep 17 00:00:00 2001 From: Lilleman auf Larv Date: Fri, 9 Oct 2026 18:59:42 +0200 Subject: [PATCH] Answer prose round 1: the comments say why, items 95, 96, 91 and 34 read in one pass, the floor's decision drops the rule CLAUDE.md holds, and item 97 files the changelog's order --- docs/decisions.md | 8 ++--- src/markdown/directive-syntax.ts | 2 +- src/markdown/emit/line-escaping.ts | 7 ++--- src/markdown/inline-tokens.ts | 2 +- src/markdown/parse/inline-content.ts | 2 +- todo.md | 46 ++++++++++++++++------------ 6 files changed, 35 insertions(+), 32 deletions(-) diff --git a/docs/decisions.md b/docs/decisions.md index cd75242..3ad0fbb 100644 --- a/docs/decisions.md +++ b/docs/decisions.md @@ -573,13 +573,11 @@ exits 0 on. ## The project ships under the comprehension floor until items 59, 60, 62 and 95 land 2026-10-03, the maintainer; item 95 in place of item 61, 2026-10-09, the maintainer. KISS, a -technical principle, and its comprehension floor of 7. Valid while `todo.md` items 59, 60, 62 and -95 are open. +technical principle, and its comprehension floor of 7. +Valid while `todo.md` items 59, 60, 62 and 95 are open. A four-seat comprehension panel scored the project under the floor of 7. Its scoring run of -2026-10-08 is the baseline. Since 2026-10-04, a chunk whose panel scores any -dimension lower improves what the seats named and scores again, and after three such rounds asks -the maintainer. +2026-10-08 is the baseline. | Seat | Navigation | Locality | Shape | Self-sufficiency | Overall | |---|---|---|---|---|---| diff --git a/src/markdown/directive-syntax.ts b/src/markdown/directive-syntax.ts index 32d3460..e91da0b 100644 --- a/src/markdown/directive-syntax.ts +++ b/src/markdown/directive-syntax.ts @@ -10,7 +10,7 @@ import { serializeCanonicalJson } from '../canonical-json.ts' export type AttributeReading = { refusal: 'kind' | 'nesting'; value?: undefined } | { refusal?: undefined; value: VocabularyValue } -// An `!adf:` standing at `index`, which only `claimDirectivePrefix` builds. +// Proof that `!adf:` stands at `index`; only `claimDirectivePrefix` builds one. export type ClaimedPrefix = { readonly [claimedPrefix]: true; readonly index: number } export type DirectiveValue = { decoded: string; spelling: string } diff --git a/src/markdown/emit/line-escaping.ts b/src/markdown/emit/line-escaping.ts index a1491c9..941ef81 100644 --- a/src/markdown/emit/line-escaping.ts +++ b/src/markdown/emit/line-escaping.ts @@ -32,7 +32,6 @@ type EmittedDelimiter = { closes: boolean; offset: number; pair: number; width: type EmittedRun = { canClose: boolean; canOpen: boolean; character: string; delimiters: EmittedDelimiter[]; length: number; start: number } -// What stays fixed while one line's escapes are decided. type EscapeWalk = { readonly claims: Claims readonly container: LineContainer @@ -127,7 +126,7 @@ function escapeClaims(scan: string, escapings: readonly InlineEscaping[], contai return escaped } -// A run joining the emitter's own delimiter escapes its text; a run of text escapes from its start while the reader claims what the escapes leave of it. +// A text character beside one of the emitter's delimiters would lengthen that delimiter's run, so every text character in such a run escapes. function runEscapes(walk: EscapeWalk, start: number, end: number, line: ScanLine): number[] { const { escapings, scan } = walk const indexes: number[] = [] @@ -137,7 +136,7 @@ function runEscapes(walk: EscapeWalk, start: number, end: number, line: ScanLine return indexes } for (let index = start; index < end; index += 1) { - // A backtick run escapes whole: a rest left bare would be a raw run of another length for a closer. + // A backtick run escapes whole: a bare rest would be a shorter backtick string, which can close a span an earlier run opens. const claimed = (index > start && scan.charAt(index) === '`') || claimsRunRest(walk, index, end, line) if (!claimed) break indexes.push(index) @@ -323,7 +322,7 @@ function claimsLineStart(line: ScanLine, index: number, container: LineContainer return escapesLineClaim(line.text, index - line.start, line.position) } -// Where the closing sequence an ATX heading would read in the text starts, `undefined` where it reads none. +// The start of the closing sequence an ATX heading would read at the text's end. function closingHashes(scan: string): number | undefined { let start = scan.length while (scan.charAt(start - 1) === '#') start -= 1 diff --git a/src/markdown/inline-tokens.ts b/src/markdown/inline-tokens.ts index 9a401d0..43a1523 100644 --- a/src/markdown/inline-tokens.ts +++ b/src/markdown/inline-tokens.ts @@ -7,7 +7,7 @@ import { delimiterFlags, runLength } from './commonmark/emphasis-matching.ts' import { highlightDelimiter, highlightFlanking } from './portable/conventions.ts' import { readEntityReference } from './commonmark/entity-references.ts' -// What the inline reader reads from a token start, `width` characters on; `text` reads literally, a directive reads by its own grammar, and HTML is refused. +// `directive` and `html` carry no `width`: a directive reads by its own grammar, and the reader refuses HTML. export type InlineToken = | { email: boolean; kind: 'autolink'; width: number } | { image: boolean; kind: 'bracket'; width: number } diff --git a/src/markdown/parse/inline-content.ts b/src/markdown/parse/inline-content.ts index 21a33f6..1721a83 100644 --- a/src/markdown/parse/inline-content.ts +++ b/src/markdown/parse/inline-content.ts @@ -147,7 +147,7 @@ function readToken(scan: Scan, index: number, token: InlineToken): Result` -is quadratic, in the reader and the emitter's escape walk alike. commonmark.js keeps a cache of -backtick runs by length for the first. +in a text of length n, backtick runs of lengths 1 to k with no closers cost about k·n, and `` is quadratic, in the reader and the emitter's escape walk alike. +commonmark.js avoids the backtick cost by caching backtick runs by length. ### 92. Lower the reading cost of the files a chunk reads most before its first commit. @@ -284,22 +290,21 @@ Today `marks="[{\"attrs\":{\"mode\":\"wide\"},\"type\":\"breakout\"}]"`, the mar escaped JSON. Breaking where the panel picks another spelling: `MIGRATION.md`'s Spellings table gains its row. -### 95. Find the code-span closers an escape forms and the mark runs a line cannot spell by reading the line back, in place of `escapeClosedRuns` and `unspellableRuns` predicting them. +### 95. Find the code-span closers an escape forms, the mark runs a line cannot spell and the text `[` that opens link text by reading the line back, in place of `escapeClosedRuns`, `unspellableRuns` and `lastLinkClose` predicting them. -`src/markdown/emit/line-escaping.ts` asks the reader's tokens where text would read as syntax, but -`escapeClosedRuns` still works out which backtick strings an escape leaves, and `unspellableRuns` -rebuilds the reader's emphasis and highlight pairing to pick the run to carry, and `lastLinkClose` -guesses which text `[` opens link text. Reading the line -back costs a parse per line attempt, and the run it picks may differ, changing output. +`escapeClosedRuns` works out which backtick strings an escape leaves, `unspellableRuns` rebuilds the +reader's emphasis and highlight pairing, and `lastLinkClose` guesses which text `[` opens link +text. Only the property tests catch drift between these and the reader, and it holds the project +under the comprehension floor. Reading the line back costs one parse each time a line is tried. The +run it carries may differ from today's, which changes lossless output (§The formats are API). ### 91. Spell an emphasis or link once across the hard breaks between two nodes it marks, in both writers. -No reader marks a hard break, so `*One\` then `Two*` writes back as `_One_\` then -`_Two_`, and a link typed across a line as two links. Joining the run across the break in -`inline-line.ts` ruled worse with two comprehension panels (PR #22): a joined run that cannot be -spelled needs its own fallback, first as a set of parted breaks, then as a flag the first fallback -clears. Lands after item 95, which lets the joined spelling be tried and kept only where it reads -back. +Lands after item 95, which lets the joined spelling be tried and kept only where it reads back. No +reader marks a hard break, so `*One\` then `Two*` writes back as `_One_\` then `_Two_`, and a link +typed across a line as two links. Joining the run across the break in `inline-line.ts` ruled worse +with two comprehension panels (PR #22): a joined run that cannot be spelled needs its own fallback, +first as a set of parted breaks, then as a flag the first fallback clears. ### 73. Announce the package where someone needing an ADF converter already reads: JRACLOUD-77436, the Atlassian developer community and Stack Overflow's ADF-to-markdown questions. @@ -328,9 +333,10 @@ README goal covers the release path. ### 34. Read emphasis flanking by the whole character beside an astral symbol. -Check whether `delimiterRunToken` (`inline-tokens.ts`), which the reader and the escape walk share, -and `emittedRuns` (`line-escaping.ts`) read one UTF-16 unit beside an astral symbol — a lone surrogate is neither punctuation nor symbol, where CommonMark reads `😀` as -punctuation — and, where they do, read the code point, with a fixture per direction. +Check whether `delimiterRunToken` (`inline-tokens.ts`), `emittedRuns` and `resolveEmphasis` +(`line-escaping.ts`) read one UTF-16 unit beside an astral symbol. A lone surrogate is neither +punctuation nor symbol, but CommonMark reads `😀` as punctuation. Where they do, read the code +point, with a fixture per direction. ### 31. Make the branch-coverage figure repeat across runs of an unchanged tree.