markdown

Overview ¶

Package markdown parses *.md / *.markdown files into heading-level SymbolSpans so docs/ADR content becomes searchable alongside source code.

Strategy: line-based scan, no external dependency. Why direct rather than goldmark?

• The transformation we need ("split at ATX headings, keep body including code fences") is ~80 LOC and easier to reason about than walking an AST node graph.
• go.mod stays small; the user-global security rule asks us to justify every new dependency. A heading splitter is well below that bar.
• Edge cases we DO need to handle (code-fence-internal hashes that look like headings, setext-style underlined headings) are local enough that line-scanning is precise.

Output contract:

• Each ATX heading (`#`, `##`, ..., `######`) starts a SymbolSpan.
• SymbolSpan.Text covers the heading line through the line BEFORE the next heading (or EOF).
• SymbolSpan.Name is the heading text normalized via slugify (lowercase, runs of non-alphanumerics → "-", trimmed).
• SymbolSpan.Kind is KindADRSection when the file path matches an ADR convention (ADR-*.md, docs/adr/*.md, etc.), otherwise KindDocSection.
• A file with NO headings returns ONE SymbolSpan covering the whole file with Name="untitled" (the chunker labels it "FileHeader"-ish via DocSection so retrieval still works).