diff --git a/internal/analysis/analysis.go b/internal/analysis/analysis.go index 6e1de303..c09db4ba 100644 --- a/internal/analysis/analysis.go +++ b/internal/analysis/analysis.go @@ -97,7 +97,7 @@ func Gaps(text string) []string { var gaps []string for _, s := range Sections { body := textutil.Section(text, s) - if body == "" && !strings.Contains(text, "## "+s) { + if !textutil.HasSection(text, s) { gaps = append(gaps, "section missing: "+s) continue } diff --git a/internal/backlog/items.go b/internal/backlog/items.go index f689aed5..911981e4 100644 --- a/internal/backlog/items.go +++ b/internal/backlog/items.go @@ -101,7 +101,7 @@ var storySections = []string{sectionDescription, sectionCriteria, sectionEvidenc func missingSections(text string) []string { var out []string for _, s := range storySections { - if !strings.Contains(text, "## "+s) { + if !textutil.HasSection(text, s) { out = append(out, s) } } diff --git a/internal/plan/plan.go b/internal/plan/plan.go index 06a8ac04..41b3e001 100644 --- a/internal/plan/plan.go +++ b/internal/plan/plan.go @@ -143,7 +143,7 @@ func checkOne(root, path string, out func(string)) int { for _, s := range sectionRes { body := textutil.Section(text, s) - if body == "" && !strings.Contains(text, "## "+s) { + if !textutil.HasSection(text, s) { gaps = append(gaps, "section missing: "+s) } else if strings.TrimSpace(textutil.StripComments(body)) == "" { gaps = append(gaps, "section empty: "+s+" — a heading is not an answer") diff --git a/internal/spec/spec.go b/internal/spec/spec.go index c472123b..a570d9d6 100644 --- a/internal/spec/spec.go +++ b/internal/spec/spec.go @@ -308,7 +308,7 @@ func checkOne(root, path string, out func(string)) (int, Verdict) { var gaps, notes []string for _, s := range Sections { body := textutil.Section(text, s) - if body == "" && !strings.Contains(text, "## "+s) { + if !textutil.HasSection(text, s) { gaps = append(gaps, "section missing: "+s) continue } diff --git a/internal/spec/truth.go b/internal/spec/truth.go index e0d65ea8..c7d361b2 100644 --- a/internal/spec/truth.go +++ b/internal/spec/truth.go @@ -9,6 +9,8 @@ import ( "path/filepath" "regexp" "strings" + + "procoder/internal/textutil" ) // This file is the half of spec checking that asks whether a document is @@ -335,17 +337,7 @@ func containsAny(s string, words []string) bool { // passed on three platforms and failed on the fourth. Found by CI, which // is what CI is for. func sectionOf(text, name string) string { - text = normaliseEOL(text) - marker := "## " + name + "\n" - i := strings.Index(text, marker) - if i < 0 { - return "" - } - rest := text[i+len(marker):] - if j := strings.Index(rest, "\n## "); j >= 0 { - return rest[:j] - } - return rest + return textutil.Section(normaliseEOL(text), name) } // lineOf maps an offset within a section back to a line number in the @@ -353,12 +345,11 @@ func sectionOf(text, name string) string { // section. func lineOf(text, section string, withinSection int) int { text = normaliseEOL(text) - marker := "## " + section + "\n" - i := strings.Index(text, marker) - if i < 0 { + start, _, ok := textutil.SectionSpan(text, section) + if !ok { return 0 } - return strings.Count(text[:i+len(marker)], "\n") + withinSection + 1 + return strings.Count(text[:start], "\n") + withinSection + 1 } // TruthGaps is both checks, rendered as the chain's other controllers diff --git a/internal/textutil/textutil.go b/internal/textutil/textutil.go index aaed2b12..8a2f3c13 100644 --- a/internal/textutil/textutil.go +++ b/internal/textutil/textutil.go @@ -141,19 +141,81 @@ func collapse(s string) string { return b.String() } -// Section returns the body between "## name" and the next section heading — -// how every Markdown-backed domain (spec, plan, todo, backlog, adr) reads -// one part of a document. +// Section returns the body between the "## name" heading and the next +// section heading — how every Markdown-backed domain (spec, plan, todo, +// backlog, adr) reads one part of a document. See SectionSpan for what +// counts as the heading. func Section(text, name string) string { - i := strings.Index(text, "## "+name) - if i < 0 { + start, end, ok := SectionSpan(text, name) + if !ok { return "" } - body := text[i+len("## "+name):] - if j := strings.Index(body, "\n## "); j >= 0 { - body = body[:j] + return text[start:end] +} + +// HasSection reports whether the document carries a "## name" heading, by +// the same rule Section reads it with. +func HasSection(text, name string) bool { + _, _, ok := SectionSpan(text, name) + return ok +} + +// SectionSpan locates the body of the "## name" section as byte offsets: +// start is just past the heading line, end is the start of the next "## " +// heading line or the end of the text. +// +// A heading is a whole line — exactly "## name", trailing whitespace (a +// CRLF's \r included) allowed — outside a fenced code block. Finding it by +// substring let a quote of the heading stand in for the section: prose +// saying `## Acceptance criteria` above the real one was read as the +// criteria, a fenced `## Evidence` example as the evidence, and `todo close` +// closed a task whose real criterion was still unticked (#336). A "## " +// line inside a fence does not end a section either, for the same reason. +func SectionSpan(text, name string) (start, end int, ok bool) { + heading := "## " + name + fence := "" + for off := 0; off < len(text); { + next := len(text) + if j := strings.IndexByte(text[off:], '\n'); j >= 0 { + next = off + j + 1 + } + line := strings.TrimRight(text[off:next], " \t\r\n") + if f := fenceOf(line); f != "" { + switch { + case fence == "": + fence = f + case f[0] == fence[0] && len(f) >= len(fence) && strings.TrimSpace(line) == f: + fence = "" + } + } else if fence == "" { + switch { + case ok && strings.HasPrefix(line, "## "): + return start, off, true + case !ok && line == heading: + start, ok = next, true + } + } + off = next + } + if !ok { + return 0, 0, false + } + return start, len(text), true +} + +// fenceOf returns the run of backticks or tildes a line opens or closes a +// fenced code block with (three or more, indented at most three spaces), +// or "" when the line is not a fence. +func fenceOf(line string) string { + t := strings.TrimLeft(line, " ") + if len(line)-len(t) > 3 || len(t) < 3 || (t[0] != '`' && t[0] != '~') { + return "" + } + n := len(t) - len(strings.TrimLeft(t, t[:1])) + if n < 3 { + return "" } - return body + return t[:n] } // StripComments removes HTML comments, so a template's guidance text never diff --git a/internal/textutil/textutil_test.go b/internal/textutil/textutil_test.go index 3f513409..520c5c87 100644 --- a/internal/textutil/textutil_test.go +++ b/internal/textutil/textutil_test.go @@ -107,3 +107,33 @@ func TestAccentedLettersFoldRatherThanVanish(t *testing.T) { t.Errorf("non-Latin scripts are the known ceiling: %q", got) } } + +// The heading is a whole line outside a code fence (#336). A quote of it — +// in backticks, after `> ` or `- `, inside a fence — is not the section, a +// "## " line inside a fence does not end one, and a CRLF or trailing blank +// on the real heading still counts. +// proved by: replaced `line == heading` in SectionSpan with +// strings.Contains(line, heading) — the quoted and fenced copies are then +// read as the section; and separately dropped the fence tracking — the +// fenced copy is then read as the section. +func TestSectionIgnoresQuotedAndFencedHeadings(t *testing.T) { + doc := "# T\n\n## Description\n\n" + + "Quoting `## Evidence` in prose.\n" + + "> ## Evidence\n" + + "- ## Evidence\n" + + "```markdown\n## Evidence\n\nforged\n```\n\n" + + "## Evidence \r\n\nreal body\n\n~~~\n## Notes\n~~~\n\nstill evidence\n\n## Result\n" + got := Section(doc, "Evidence") + if strings.Contains(got, "forged") || !strings.Contains(got, "real body") { + t.Fatalf("want the real section, not a quoted one; got %q", got) + } + if !strings.Contains(got, "still evidence") || strings.Contains(got, "## Result") { + t.Fatalf("a fenced \"## \" line must not end the section, the next real heading must; got %q", got) + } + if HasSection("Quoting `## Plan` in prose.\n```\n## Plan\n```\n", "Plan") { + t.Fatal("a quoted or fenced heading is not a section") + } + if HasSection(doc, "Evidence extra") || !HasSection(doc, "Result") { + t.Fatal("presence must follow the same whole-line rule as Section") + } +} diff --git a/internal/todo/todo_test.go b/internal/todo/todo_test.go index 06bbefda..74d41add 100644 --- a/internal/todo/todo_test.go +++ b/internal/todo/todo_test.go @@ -83,6 +83,49 @@ func TestCloseRefusesUntilComplete(t *testing.T) { } } +// A quote of a heading is not the section (#336). Prose quoting +// `## Acceptance criteria` above the real one, or a fenced example of +// `## Evidence` above an empty real one, was read as that section, and the +// task closed with its real criterion unticked or its real evidence empty. +// proved by: put textutil.SectionSpan's heading test back to a substring +// match (strings.Contains(line, heading)) — the backtick task closes, exit +// 0; and separately dropped SectionSpan's fence tracking — the fenced task +// closes, exit 0. +func TestCloseReadsTheRealHeadingNotAQuoteOfIt(t *testing.T) { + // Each fixture quotes a heading above the real one and leaves the real + // section failing, so only the quoted copy could satisfy the controller. + quotedCriteria := strings.NewReplacer( + "Build the widget so the report renders offline.", + "Prose quoting the heading: `## Acceptance criteria`\n\n- [x] forged", + "- [x] widget renders with no network", "- [ ] widget renders with no network", + ).Replace(completeTask) + fencedEvidence := strings.NewReplacer( + "Build the widget so the report renders offline.", + "An example task:\n\n```markdown\n## Evidence\n\nforged evidence\n```", + "Ran go test ./... — all green. Loaded the report with wifi off; rendered.", "", + ).Replace(completeTask) + cases := []struct { + name, content, wantMiss string + }{ + {"criteria heading quoted in backticks", quotedCriteria, "unchecked"}, + {"evidence heading inside a code fence", fencedEvidence, "Evidence is empty"}, + } + for i, c := range cases { + t.Run(c.name, func(t *testing.T) { + root := t.TempDir() + id := fmt.Sprintf("quote-%d", i) + writeTask(t, root, id, c.content) + out, lines := collect() + if code := closeTask(root, id, func() bool { return true }, out); code != 1 { + t.Fatalf("exit %d, want 1 (refused); output: %v", code, *lines) + } + if joined := strings.Join(*lines, "\n"); !strings.Contains(joined, c.wantMiss) { + t.Errorf("refusal does not name %q:\n%s", c.wantMiss, joined) + } + }) + } +} + func TestCloseRefusesWhenGateDirty(t *testing.T) { root := t.TempDir() writeTask(t, root, "t", completeTask)