fix(archive): read a wrapped scenario bullet as one bullet

.changeset/wrapped-scenario-bullets-retire.md

@@ -0,0 +1,5 @@
+---
+"@fission-ai/openspec": patch
+---
+
+Fix `retire_capabilities` refusing any spec whose scenario bullets wrap onto a second line. The continuation line was counted as content the merge could not account for, which blocked the retirement and suppressed the hint that names the marker (#1780). A spec bulleted with `+` is covered too: naming only `-` and `*` as list markers reported every one of its scenario bullets as unaccounted content, so that capability could not be retired at all either.

src/core/specs-apply.ts

@@ -618,6 +618,78 @@ function firstForeignTail(raw: string): { heading: string; raw: string } | undef
   return undefined;
 }
 
+/**
+ * The column a line's content starts at, tabs expanded to a four-column stop.
+ * `prefix` is the text that precedes the content: a line's indentation, or a
+ * list item's indentation together with its marker.
+ */
+function contentColumn(prefix: string): number {
+  let column = 0;
+  for (const char of prefix) column += char === '\t' ? 4 - (column % 4) : 1;
+  return column;
+}
+
+/**
+ * A line that opens a block of its own: a blockquote, a thematic break, a list
+ * item, a table row, or raw HTML. CommonMark lets each of these interrupt a
+ * paragraph, so one written flush against a bullet starts something new rather
+ * than continuing it - and the audit has to name it rather than let it be
+ * deleted with the file. Headings interrupt too and are checked separately,
+ * since they are refused however they are indented.
+ */
+const INTERRUPTS_PARAGRAPH =
+  /^ {0,3}(?:>|(?:[-*_][ \t]*){3,}$|(?:[-*+]|\d{1,9}[.)])(?:[ \t]|$)|[<|])/;
+
+/**
+ * A list item, spelled the way CommonMark spells one, with its marker and the
+ * space after it captured so a caller can measure the item's content column.
+ *
+ * Every marker, and only those. `+` is a list marker like `-` and `*`: a spec
+ * bulleted that way validates like any other, and naming only two of the three
+ * made every one of its scenario bullets unaccounted content, so such a
+ * capability could not be retired at all.
+ *
+ * The nine-digit cap is the other half of "only those": CommonMark stops an
+ * ordered marker at nine digits, so `1234567890.` opens a paragraph, not a
+ * list. It changes no verdict here, because a line this pattern rejects is
+ * weighed by the same rules either way; it is here so the audit and
+ * INTERRUPTS_PARAGRAPH cannot disagree about what a marker is. A line one of
+ * them calls a bullet and the other does not is read as both at once, and that
+ * disagreement is what a shared definition removes.
+ *
+ * Content after the marker is not required, so an empty `- ` still reads as
+ * the bullet it is rather than falling through to the leftovers. The captured
+ * group is the indent plus the marker plus its trailing space, which is the
+ * item's content column.
+ */
+const LIST_ITEM = /^(\s*(?:[-*+]|\d{1,9}[.)])\s+)/;
+
+/**
+ * Drop up to `columns` visual columns of leading whitespace, so a line inside a
+ * list item is classified by what it is *within* that item. A `## Retention`
+ * indented under `100. Step` is a heading; measured against the file's left
+ * margin instead, it reads as five spaces of nothing and was absorbed as
+ * continuation. A tab straddling the boundary is consumed whole, which can only
+ * make a line look more like a construct - the direction that refuses.
+ */
+function dropIndent(line: string, columns: number): string {
+  let column = 0;
+  let index = 0;
+  while (index < line.length && column < columns) {
+    const char = line[index];
+    if (char === ' ') column += 1;
+    else if (char === '\t') column += 4 - (column % 4);
+    else break;
+    index++;
+  }
+  return line.slice(index);
+}
+
+/** A heading in any form a spec can write one, ATX or raw HTML. */
+function isHeadingLine(line: string): boolean {
+  return /^ {0,3}#{1,6}(?:[ \t]|$)/.test(line) || /^\s*<h[1-6]\b/i.test(line);
+}
+
 /**
  * The non-blank lines of a spec that are not part of what a retirement is able
  * to name: the title, the `## Purpose` section, the `## Requirements` header,
@@ -704,35 +776,101 @@ function contentTheMergeCannotName(parts: RequirementsSectionParts): string[] {
     // operational note below the last scenario be deleted unmentioned.
     let inScenarioBullets = false;
     let bulletsSeen = false;
+    // The content column of the list item the previous line opened or
+    // continued, or null when the last line was not part of one. A line
+    // indented to that column continues the item it sits under (#1780) - a
+    // repository that wraps its prose at a column limit writes most scenario
+    // bullets over two lines, and counting the second line as loose content
+    // made every such capability unretirable. Reset by a blank line, so an
+    // indented note written below the scenarios is still the author's own.
+    let listContentIndent: number | null = null;
+    // Whether the bullet's paragraph is still open, so a line that does not
+    // indent can still be continuing it. Closed by anything that ends a
+    // paragraph: a blank line, a fence, a heading, or a block of its own.
+    let paragraphOpen = false;
     for (let index = 0; index < lines.length; index++) {
       const line = lines[index];
       if (!line.trim()) {
         // Only a blank that follows actual bullets closes the run, so a blank
         // between a scenario header and its first bullet is not a boundary.
         if (bulletsSeen) inScenarioBullets = false;
+        listContentIndent = null;
+        paragraphOpen = false;
         continue;
       }
       if (index === 0) continue; // the `### Requirement:` header itself
+      const indent = contentColumn(/^[ \t]*/.exec(line)![0]);
+      // Indented to the item's content column: inside the item, whatever it
+      // holds - a nested list, a table, an indented quote.
+      const insideItem = listContentIndent !== null && indent >= listContentIndent;
+      // Every syntax test below reads the line as the item sees it. A wide
+      // marker (`100. `) pushes its content past the three columns Markdown
+      // constructs are allowed, so measuring from the file's left margin missed
+      // headings and block starts written inside such an item.
+      const withinItem = insideItem ? dropIndent(line, listContentIndent!) : line;
+      // Not indented at all, but continuing the bullet's own paragraph inside a
+      // scenario's unbroken bullet run - how a hand-wrapped bullet is usually
+      // written. Absorbing it widens nothing: a sibling bullet in that same
+      // position is already read as the scenario's own, and a lazy line is part
+      // of the bullet above it where a sibling is merely next to it. Outside
+      // the run the indent is required, so a note bulleted below the scenarios
+      // and its own wrapped lines stay the author's.
+      const lazilyContinuesBullet =
+        paragraphOpen && inScenarioBullets && !INTERRUPTS_PARAGRAPH.test(withinItem);
+      // A heading is a heading wherever it sits, so neither form absorbs one:
+      // `firstForeignTail` names the ATX spelling and the `before` pass names
+      // the raw HTML, and indenting a section under a bullet must not smuggle
+      // it past the audit.
+      const continuesListItem = (insideItem || lazilyContinuesBullet) && !isHeadingLine(withinItem);
       // Fenced lines render as a code block inside the requirement, so they are
       // its own content however they are spelled - a `### Requirement:` in an
       // example is not a heading to any reader. Flagging them made a spec that
       // merely documents a command unretirable.
-      if (mask[index]) continue;
+      if (mask[index]) {
+        // A fence that starts left of the item's content column has ended it,
+        // and a fence ends the paragraph wherever it sits - so what follows is
+        // not a lazy continuation of anything.
+        if (!insideItem) listContentIndent = null;
+        paragraphOpen = false;
+        continue;
+      }
+      // Checked ahead of the continuation branch: a setext underline turns the
+      // line above it into a heading, and indenting the pair under a bullet
+      // must not absorb them any more than an indented `#` line is absorbed.
       if (
         index > 1 &&
-        /^ {0,3}(?:=+|-+)\s*$/.test(line) &&
+        /^ {0,3}(?:=+|-+)\s*$/.test(withinItem) &&
         lines[index - 1].trim()
       ) {
         leftovers.push(lines[index - 1].trim());
+        listContentIndent = null;
+        paragraphOpen = false;
+        continue;
+      }
+      // A continuation of the list item above: indented to its content column
+      // with no blank line between. Whatever the item is, this line is part of
+      // it - accounted for when the item was, and already reported when it was
+      // not, so nothing is deleted unmentioned either way.
+      if (continuesListItem) {
+        // An indented nested list or quote is still inside the item, but it
+        // ended the bullet's paragraph - so a later unindented line is not
+        // continuing that paragraph either.
+        paragraphOpen = !INTERRUPTS_PARAGRAPH.test(withinItem);
         continue;
       }
+      // Any other line closes the item; a bullet opens the next one. The
+      // content column is the marker's own indent plus the marker itself, so a
+      // nested list and its own wrapped lines stay inside the item too.
+      const bullet = line.match(LIST_ITEM);
+      listContentIndent = bullet ? contentColumn(bullet[1]) : null;
+      paragraphOpen = bullet !== null;
       if (/^ {0,3}####\s+Scenario:/i.test(line)) {
         seenScenario = true;
         inScenarioBullets = true;
         bulletsSeen = false;
         continue;
       }
-      if (/^\s*(?:[-*]|\d+[.)])\s/.test(line)) {
+      if (bullet) {
         if (inScenarioBullets) {
           bulletsSeen = true;
           continue;