corestack/go
2
0 Fork 0
Code Issues 3 Pull Requests Actions Packages Projects Releases 2 Wiki Activity

fix: address docs checker review findings

Browse Source 
Check every link reference definition, decode destinations per CommonMark,
report correct lines for empty headings, autolinks and nested definitions,
reject symlinked record directories and wrong-case path components, and
refuse titles that cannot pass. Only top-level headings count (spec section 6).

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
endandClaude Sonnet 5.5 committed 2026-10-23 14:57:21 -07:00
1 parent 789931d90f
commit d579e38ba5
8 files changed
+146 -27
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

internal/docs/body.go
+85 -20
View File
@@ -3,12 +3,14 @@ package docs
import (
"bytes"
"regexp"
"slices"
"strings"
"github.com/yuin/goldmark"
"github.com/yuin/goldmark/ast"
"github.com/yuin/goldmark/parser"
"github.com/yuin/goldmark/text"
"github.com/yuin/goldmark/util"
)
var (
@@ -16,6 +18,8 @@ var (
planSections = []string{"Scope", "Steps", "Validation"}
)
var atxRe = regexp.MustCompile(`(?m)^ {0,3}#{1,6}(?:[ \t]|$)`)
type heading struct {
level int
text string
@@ -36,8 +40,35 @@ func (d *doc) lineAt(off int) int {
return d.startLine + bytes.Count(d.src[:min(off, len(d.src))], []byte("\n"))
}
// lineOf is the line of the first text under n, or of the nearest block that has lines.
func (d *doc) lineOf(n ast.Node) int {
// headingLine is the line of h. An empty ATX heading has no lines, so it is the first
// `#` line after the end of the previous top-level block.
func (d *doc) headingLine(h *ast.Heading, prev ast.Node) int {
if h.Lines().Len() > 0 {
return d.lineAt(h.Lines().At(0).Start)
}
from := 0
if prev != nil {
_ = ast.Walk(prev, func(c ast.Node, enter bool) (ast.WalkStatus, error) {
if enter {
for i := range c.Lines().Len() {
from = max(from, c.Lines().At(i).Stop)
}
if t, ok := c.(*ast.Text); ok {
from = max(from, t.Segment.Stop)
}
}
return ast.WalkContinue, nil
})
}
if m := atxRe.FindIndex(d.src[from:]); m != nil {
return d.lineAt(from + m[0])
}
return d.startLine
}
// lineOf is the line of the first text under n. Without text (an autolink, an image with
// no alt text) it is the line where needle appears in the enclosing block, else the block's first line.
func (d *doc) lineOf(n ast.Node, needle string) int {
var off = -1
_ = ast.Walk(n, func(c ast.Node, enter bool) (ast.WalkStatus, error) {
if t, ok := c.(*ast.Text); ok && enter {
@@ -49,6 +80,9 @@ func (d *doc) lineOf(n ast.Node) int {
for p := n; off < 0 && p != nil; p = p.Parent() {
if p.Type() == ast.TypeBlock && p.Lines().Len() > 0 {
off = p.Lines().At(0).Start
if i := bytes.Index(d.src[off:p.Lines().At(p.Lines().Len()-1).Stop], []byte(needle)); needle != "" && i >= 0 {
off += i
}
}
}
if off < 0 {
@@ -59,15 +93,12 @@ func (d *doc) lineOf(n ast.Node) int {
func (c *checker) body(r *record, src string, startLine int, title string, titleOK bool) {
b := []byte(src)
ctx := parser.NewContext()
ctx := &refCtx{Context: parser.NewContext()}
root := goldmark.DefaultParser().Parse(text.NewReader(b), parser.WithContext(ctx))
d := &doc{c: c, r: r, src: b, startLine: startLine}
for n := root.FirstChild(); n != nil; n = n.NextSibling() {
if h, ok := n.(*ast.Heading); ok {
line := d.startLine
if h.Lines().Len() > 0 {
line = d.lineAt(h.Lines().At(0).Start)
}
line := d.headingLine(h, n.PreviousSibling())
d.heads = append(d.heads, heading{h.Level, strings.TrimSpace(string(h.Lines().Value(b))), line, len(d.kids)})
}
d.kids = append(d.kids, n)
@@ -161,7 +192,7 @@ func (d *doc) decisionOutcome() {
// Prose before the first subsection is the decision itself.
pre := nodes
for i, n := range nodes {
if _, ok := n.(*ast.Heading); ok {
if h, ok := n.(*ast.Heading); ok && h.Level == 3 {
pre = nodes[:i]
break
}
@@ -223,9 +254,8 @@ func (d *doc) inlineText(n ast.Node) string {
return s.String()
}
// placeholders reports every marker outside code.
func (d *doc) placeholders(root ast.Node) {
var code [][2]int
// codeRanges returns the source ranges of code blocks and code spans.
func codeRanges(root ast.Node) (code [][2]int) {
_ = ast.Walk(root, func(n ast.Node, enter bool) (ast.WalkStatus, error) {
switch n.(type) {
case *ast.FencedCodeBlock, *ast.CodeBlock:
@@ -242,6 +272,12 @@ func (d *doc) placeholders(root ast.Node) {
}
return ast.WalkContinue, nil
})
return code
}
// placeholders reports every marker outside code.
func (d *doc) placeholders(root ast.Node) {
code := codeRanges(root)
for off := 0; ; {
i := strings.Index(string(d.src[off:]), marker)
if i < 0 {
@@ -259,27 +295,56 @@ func (d *doc) placeholders(root ast.Node) {
}
}
// refCtx records every link reference definition; the parser keeps only the first of a label.
type refCtx struct {
parser.Context
all []parser.Reference
}
func (c *refCtx) AddReference(r parser.Reference) {
c.all = append(c.all, r)
c.Context.AddReference(r)
}
// defRe finds a definition's label at the start of a line, allowing blockquote and list prefixes.
var defRe = regexp.MustCompile(`(?m)^[ \t>]*(?:(?:[*+-]|\d+[.)])[ \t]+)*\[([^\]\n]+)\]:`)
// dest decodes a link destination as CommonMark does before it is used.
func dest(b []byte) string {
return string(util.ResolveEntityNames(util.ResolveNumericReferences(util.UnescapePunctuations(b))))
}
// links checks every link, image and autolink destination and every reference definition.
func (d *doc) links(root ast.Node, ctx parser.Context) {
func (d *doc) links(root ast.Node, ctx *refCtx) {
_ = ast.Walk(root, func(n ast.Node, enter bool) (ast.WalkStatus, error) {
if !enter {
return ast.WalkContinue, nil
}
switch t := n.(type) {
case *ast.Link:
d.c.checkLink(d.r, d.lineOf(n), string(t.Destination))
d.c.checkLink(d.r, d.lineOf(n, "]("+string(t.Destination)), dest(t.Destination))
case *ast.Image:
d.c.checkLink(d.r, d.lineOf(n), string(t.Destination))
d.c.checkLink(d.r, d.lineOf(n, "]("+string(t.Destination)), dest(t.Destination))
case *ast.AutoLink:
d.c.checkLink(d.r, d.lineOf(n), string(t.URL(d.src)))
d.c.checkLink(d.r, d.lineOf(n, "<"+string(t.Label(d.src))), string(t.URL(d.src)))
}
return ast.WalkContinue, nil
})
for _, ref := range ctx.References() {
line := d.startLine
if m := regexp.MustCompile(`(?im)^ {0,3}\[` + regexp.QuoteMeta(string(ref.Label())) + `\]:`).FindIndex(d.src); m != nil {
line = d.lineAt(m[0])
// shortcut: a definition's line is its label's nth match outside code; a multi-line
// definition inside a container may be located by label only. Upgrade by tracking offsets.
code := codeRanges(root)
lines := map[string][]int{}
for _, m := range defRe.FindAllSubmatchIndex(d.src, -1) {
if !slices.ContainsFunc(code, func(r [2]int) bool { return m[0] >= r[0] && m[0] < r[1] }) {
k := util.ToLinkReference(d.src[m[2]:m[3]])
lines[k] = append(lines[k], d.lineAt(m[0]))
}
d.c.checkLink(d.r, line, string(ref.Destination()))
}
for _, ref := range ctx.all {
line, k := d.startLine, util.ToLinkReference(ref.Label())
if len(lines[k]) > 0 {
line, lines[k] = lines[k][0], lines[k][1:]
}
d.c.checkLink(d.r, line, dest(ref.Destination()))
}
}