@helping-ai-workflow/md2doc 3.2.0 → 3.3.0

package/lib/editor/blockmap.js

@@ -63,35 +63,123 @@ function indexOfAtLineStart(content, needle, from) {
   return at;
 }
 
+// The search above is a byte-for-byte `indexOf`, and marked does not hand back
+// bytes that match byte-for-byte: a nested list token's `raw` has the trailing
+// spaces stripped off its LAST line while the enclosing `item.text` keeps them.
+// MEASURED on this repo's marked, for '# H\n\n- alpha\n  - beta\n  - \n- gamma\n':
+//
+//   item.text          "alpha\n- beta\n- "      <- trailing space kept
+//   child list tk.raw  "- beta\n-\n"            <- trailing space gone, \n added
+//
+// so `content.indexOf(tk.raw)` was -1, and the guessed offset 0 that followed
+// shifted every descendant's startLine UP one line. That is not a corner: the
+// markdown the CLIENT serialises mid-session contains the shape:
+// '# H\n\n- alpha\n  - beta\n    - \n- gamma\n' was captured coming back from
+// client.js during a test/editor-journey.test.js run and mapped to an inverted
+// range under the old search. Ordinary authored markdown does it too — an
+// everyday flat-plus-nested list corrupts the moment a trailing space lands on
+// its nested line. Neither of those two strings is itself a fixture — they came
+// out of a capture harness and a mutation sweep that are not in the repo. What
+// IS pinned, and what to read instead, is the shape FAMILY — grep 'trailing
+// space' in test/blockmap.test.js for the range assertions, and 'eats the item
+// above' in test/editor-journey.test.js for the gestures that used to do
+// exactly that.
+//
+// Both sides are put through the same normalisation before the search: trailing
+// spaces and tabs are dropped from every line. Two properties are relied on,
+// and they are different from each other:
+//
+//   LINE OFFSETS SURVIVE. The transform only ever removes characters that are
+//   not '\n', so it cannot change a line count — a character offset found in
+//   the normalised copy names the same LINE offset it would have named in the
+//   original, and a line offset is the only thing this function returns.
+//
+//   SUBSTRINGS SURVIVE. If the needle occurred in the content before, the
+//   normalised needle occurs in the normalised content. Every '\n' inside the
+//   needle is the same '\n' in the content, so a space run sitting before it is
+//   stripped identically on both sides; the two can only disagree at the
+//   needle's own END, where the needle may lose a trailing run the content
+//   keeps. That only makes the needle SHORTER, and a prefix of a substring is
+//   still a substring. (Byte identity of two equal strings under a shared
+//   transform is the wrong lemma here — it says nothing about a needle whose
+//   surroundings differ from its own end.)
+//
+// The needle additionally loses its trailing newlines (`\n+$`), because the raw
+// of a token that ends the item carries a terminator `item.text` does not have.
+// That leaves `pos` on the newline (or newlines) that ended the consumed token
+// rather than after them, so both searches below start earlier than they used
+// to and a match could in principle land on one of those bytes. One argument
+// rules that out for both searches at once, so it is the only one stated here:
+// to match at a position occupied by a newline, the NEEDLE would have to begin
+// with a newline. MEASURED over the journey capture plus a synthetic sweep of
+// nested lists (blank lines, fenced code, blockquotes, tab indents, ordered and
+// task markers): no nested list token's `raw` began with '\n'. Labelled
+// MEASURED and not invariant — nothing downstream may assume it.
+function stripTrailingLineSpace(s) {
+  return s.replace(/[ \t]+$/gm, '');
+}
+
+// Returns { offsets, unlocatable }. `offsets` keeps its old contract exactly:
+// one entry per child list token, always, in order. `unlocatable` is true when
+// at least one of those entries is a GUESS rather than a found position —
+// see pushListItemBlocks(), which is what acts on it.
 function childListStartOffsets(item) {
-  const content = typeof item.text === 'string' ? item.text : '';
+  const content = stripTrailingLineSpace(
+    typeof item.text === 'string' ? item.text : ''
+  );
   const offsets = [];
+  let unlocatable = false;
   let pos = 0;
   for (const tk of item.tokens || []) {
+    const needle = stripTrailingLineSpace(typeof tk.raw === 'string' ? tk.raw : '')
+      .replace(/\n+$/, '');
     if (tk.type === 'list') {
-      let at = indexOfAtLineStart(content, tk.raw, pos);
-      if (at < 0) at = content.indexOf(tk.raw, pos);
+      // An empty needle would make `indexOf` answer `pos` for any content, i.e.
+      // report a find that was never made. Treated as not-found instead.
+      let at = needle === '' ? -1 : indexOfAtLineStart(content, needle, pos);
+      if (at < 0 && needle !== '') at = content.indexOf(needle, pos);
       // Unlocatable (a shape this walk does not model): fall back to the line
       // the cursor is already on. Never skip — a missing block desynchronises
       // the render walk and takes the whole document down.
+      if (at < 0) unlocatable = true;
       offsets.push(at < 0 ? lineOffsetAt(content, pos) : lineOffsetAt(content, at));
-      if (at >= 0) pos = at + tk.raw.length;
+      if (at >= 0) pos = at + needle.length;
       continue;
     }
     // `text` raws are synthesised; everything else is a faithful slice and is
     // consumed so later searches start beyond it.
     if (tk.type === 'text') continue;
-    const at = content.indexOf(tk.raw, pos);
-    if (at >= 0) pos = at + tk.raw.length;
+    // BEHAVIOUR CHANGE, small and deliberate: before the trailing-newline trim
+    // above, a `space` token (a blank-line run inside the item) had a needle of
+    // pure newlines and this branch consumed it, advancing `pos` past the blank
+    // run. Trimmed, that needle is '' — and `''.indexOf` answers `pos` for any
+    // content, i.e. a find that was never made — so the token is skipped and
+    // `pos` stays where it was, which means every later search starts earlier
+    // than it used to.
+    //
+    // What establishes that this is harmless is an ABLATION, not an argument: a
+    // copy of this function that still advances `pos` past an empty needle
+    // (using the untrimmed raw) produced block maps identical to these on every
+    // document of the journey capture, of its trailing-space mutations, and of a
+    // synthetic nested-list sweep. The same sweeps also show `space` was the
+    // only token type whose needle ever collapsed to '' — which is the only type
+    // that CAN, its raw being whitespace by construction.
+    if (needle === '') continue;
+    const at = content.indexOf(needle, pos);
+    if (at >= 0) pos = at + needle.length;
   }
-  return offsets;
+  return { offsets, unlocatable };
 }
 
-function pushListItemBlocks(listToken, cursor, indent, blocks, nextId) {
+// `inheritedUnlocatable` is how an item degrades its whole subtree: see the
+// `degraded` note below the block literal.
+function pushListItemBlocks(listToken, cursor, indent, blocks, nextId, inheritedUnlocatable) {
   for (const item of listToken.items) {
     const childListTokens = item.tokens.filter((t) => t.type === 'list');
     const totalSpan = trimmedLineCount(item.raw);
-    const childLineOffsets = childListStartOffsets(item);
+    const located = childListStartOffsets(item);
+    const childLineOffsets = located.offsets;
+    const degraded = !!inheritedUnlocatable || located.unlocatable;
 
     // The item's OWN block covers its contiguous leading lines only — up to its
     // first child.
@@ -136,12 +224,58 @@ function pushListItemBlocks(listToken, cursor, indent, blocks, nextId) {
     // is never editable and no commit path can start on it. If you add a
     // consumer that walks block ranges, either honour that emptiness or check
     // for it; do not assume `startLine <= endLine`.
+    //
+    // DEGRADED SUBTREE. When childListStartOffsets() could not FIND a child
+    // list and had to guess its line, every line number computed from that
+    // guess is fiction, and the fiction does not stop at the parent: the guess
+    // is the offset each descendant's cursor is built from, so an entire nested
+    // run gets addresses belonging to the lines ABOVE it. That is not an
+    // abstract risk — it is the shape a user is in between typing a nested
+    // marker and typing its first character, and the observed result was that
+    // client.js's bystanderCarryOver() replayed the WRONG source line over a
+    // sibling: '- alpha\n  - beta\n  - \n' committed back as
+    // '- alpha\n  - alpha\n-\n', with beta gone from the file.
+    //
+    // So the whole subtree — this item and, via `inheritedUnlocatable`, every
+    // item below it — is given an EMPTY range (endLine === startLine - 1)
+    // rather than a wrong one. Empty is a shape this codebase already defines
+    // and already defends: client.js's blockOwnsNoLine() is `endLine <
+    // startLine`, and the functions that call it directly are
+    // canWysiwygForLi() (arming), openRawEditor() (the raw textarea),
+    // insertBlockBelow() (the ＋ paths, twice — anchor and subtree tail),
+    // resolveGutterOperands() (twice — where the ⠿ menu's 刪除 and every other
+    // grip operation resolves its targets, reached from deleteBlockViaGutter()
+    // through deleteBlockViaGutterBody()) and bystanderCarryOver() (the replay
+    // of untouched siblings). So an empty range refuses at every arming and
+    // commit boundary instead of writing somebody else's line.
+    //
+    // Every block is still PUSHED. lib/md2doc.js's edit-mode render walk
+    // consumes blocks[] in lockstep and throws on `biRef.v !== blocks.length`,
+    // so a skipped block takes the whole document down; an empty range costs
+    // that check nothing, and server.js's assertBlockRangesFit() only rejects
+    // `endLine > lines.length`, which a shortened range can never trip.
+    //
+    // `unlocatable` marks these records so the client can say WHY it refused.
+    // Same-line nesting ('- - a') produces an empty range too, and it is a
+    // legitimate, fully-modelled shape — it does not get the flag, and it
+    // keeps its own existing wording.
+    //
+    // ACCEPTED RESIDUAL: the degraded subtree's source lines end up owned by no
+    // block at all. lib/editor/selection.js's `ownsALine()` is
+    // `b.endLine >= b.startLine`, and membersOf() filters on it, so those lines
+    // fall out of every block selection — a drag across them selects the blocks
+    // either side and nothing in between. That is the price of emptying the
+    // subtree instead of corrupting it, and it is the right trade: a wrong
+    // range writes over somebody else's line, an absent one only cannot be
+    // selected. Unreachable as this is written (no markdown found so far makes
+    // the search fail); recorded here so whoever first reaches it meets this
+    // in the code rather than in the field.
     const ownSpan = childLineOffsets.length ? childLineOffsets[0] : totalSpan;
     const block = {
       id: nextId.v++,
       type: 'li',
       startLine: cursor,
-      endLine: cursor + ownSpan - 1,
+      endLine: degraded ? cursor - 1 : cursor + ownSpan - 1,
       // Two independent axes (RULING F-N): GFM allows `1. [ ] a`, so
       // ordered-ness and task-ness cannot share one field. `listType` is the
       // LIST's type; `task` is the ITEM's.
@@ -150,12 +284,13 @@ function pushListItemBlocks(listToken, cursor, indent, blocks, nextId) {
       indent,
     };
     if (item.task) block.checked = !!item.checked;
+    if (degraded) block.unlocatable = true;
     blocks.push(block);
     // Every child is emitted, unconditionally: blocks[] is consumed in lockstep
     // by lib/md2doc.js's render walk, so a skipped child desynchronises the two
     // and the render runs off the end of the array.
     childListTokens.forEach((ct, k) => {
-      pushListItemBlocks(ct, cursor + childLineOffsets[k], indent + 1, blocks, nextId);
+      pushListItemBlocks(ct, cursor + childLineOffsets[k], indent + 1, blocks, nextId, degraded);
     });
     // advance cursor by full item raw newlines; fall back to totalSpan if raw
     // has no trailing newline (EOF item).

package/lib/editor/cli.js

@@ -5,11 +5,28 @@ const { createEditorServer } = require('./server.js');
 
 const CLIENT_SRC = fs.readFileSync(path.join(__dirname, 'client.js'), 'utf8');
 
-async function startEditSession({ files, port = null, open = true, quiet = false }) {
+// F13: each exit path prints its own line. The tab-closed (idle) and
+// never-opened lines come from a listener on server.js's
+// 'md2doc-auto-close' event, since that side is what decides why the
+// server is closing. The SIGINT line is printed here instead, because the
+// signal lands on the process itself — server.js has no way to observe it.
+const AUTO_CLOSE_MESSAGES = {
+  idle: 'md2doc: no browser activity for a while — closing this editor session.\n',
+  'never-opened': 'md2doc: the editor link was never opened — closing this editor session.\n',
+};
+
+async function startEditSession({
+  files, port = null, open = true, quiet = false, idleTimeoutMs, neverOpenedGraceMs,
+}) {
   const srv = await createEditorServer({
     files,
     clientJs: CLIENT_SRC,
     listenPort: port === null ? 0 : port,
+    // Included when the caller supplies a value; otherwise omitted so
+    // createEditorServer's own default applies, rather than a duplicated
+    // default here that could drift out of sync with it.
+    ...(idleTimeoutMs === undefined ? {} : { idleTimeoutMs }),
+    ...(neverOpenedGraceMs === undefined ? {} : { neverOpenedGraceMs }),
   });
   const urls = files.map((f) => srv.urlFor(f));
   for (const u of urls) process.stdout.write(u + '\n');
@@ -17,6 +34,38 @@ async function startEditSession({ files, port = null, open = true, quiet = false
     const { openViewer } = require('./open.js');
     for (const u of urls) openViewer(u);
   }
+  srv.server.on('md2doc-auto-close', (reason) => {
+    const msg = AUTO_CLOSE_MESSAGES[reason];
+    if (msg) process.stdout.write(msg);
+  });
+  // SIGINT previously had no handler: Node's default action kills the
+  // process before srv.server's 'close' listener below ever runs. Driven
+  // directly by spawning a child and sending it SIGINT before this fix:
+  // it exited with signal=SIGINT, code=null, and stdout held only the
+  // earlier URL line — no closing message. Printing here and driving the
+  // close through srv.close() (rather than letting the signal's default
+  // action finish the job) routes this exit through the same 'close'
+  // listener that already handles the idle and never-opened exits.
+  //
+  // T21 item 3: this handler REPLACES Node's default action, and the default
+  // action was the escape route — with a handler installed, a Ctrl+C that
+  // does not lead to an exit leaves the user with no way out but another
+  // terminal. Two things answer that here. srv.close() now lands the open
+  // sockets rather than waiting on them (see shutdownServer() in server.js
+  // for the preconnect measurement that made the default invocation hang
+  // where --no-open did not), and a SECOND SIGINT exits on the spot. The
+  // second one does not reprint the line: driven before this guard existed,
+  // two Ctrl+C's printed 'interrupted' twice and the process was still alive
+  // 12 s after the first. 130 is the conventional code for a process ending
+  // on SIGINT; the ordinary path still exits 0 through the 'close' listener
+  // below.
+  let interrupted = false;
+  process.on('SIGINT', () => {
+    if (interrupted) process.exit(130);
+    interrupted = true;
+    process.stdout.write('md2doc: interrupted — closing this editor session.\n');
+    srv.close();
+  });
   srv.server.on('close', () => process.exit(0));
   return srv;
 }