parser

package
v0.5.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 7, 2026 License: MIT Imports: 22 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrNotRepo is returned when the path is not inside a git work tree.
	ErrNotRepo = errors.New("not a git repository")
	// ErrBadRef is returned when --since names a ref git cannot resolve.
	ErrBadRef = errors.New("unknown git ref")
)

Functions

func ChangedLines added in v0.3.0 

func ChangedLines(file, ref string) (map[int]bool, error)

ChangedLines returns the set of line numbers in `file` that have been modified since the given git ref. It shells out to `git diff --unified=0` and parses the hunk headers, which in unified-0 mode give exact line ranges in the new (working) file.

Git is always run from the file's repository root, so the caller does not have to be in the work tree (or even in the same directory as the file). Paths are canonicalized with EvalSymlinks so macOS /var vs /private/var (and any other intermediate symlink) still maps onto git's pathspec.

New files (untracked, or added after `ref`) are treated as fully changed. Renames compare against the pre-rename blob so only real edits light up. Binary diffs (no text hunks) light up every current line. Missing git, a path outside any work tree, or an unknown ref return a typed error (ErrNotRepo / ErrBadRef) with an empty set.

func ChangedLinesBatch added in v0.5.0 

func ChangedLinesBatch(root, ref string, files []string) (map[string]map[int]bool, error)

ChangedLinesBatch returns changed line sets for each path in files since ref, keyed by the exact strings passed in. It runs one repo-level `git diff --unified=0 -M ref` (plus one ls-tree for paths absent from the diff) instead of spawning git once per file.

Behavior matches ChangedLines: renames light up only real edits, binaries and new/untracked files mark every current line, and ErrNotRepo / ErrBadRef are returned when the root or ref is invalid.

func EnsureRef added in v0.5.0 

func EnsureRef(dir, ref string) error

EnsureRef reports whether dir is in a git work tree and ref names a commit.

func GitRoot added in v0.5.0 

func GitRoot(dir string) string

GitRoot returns the work tree root that contains dir, or "" if dir is not inside a git repository.

func IsDocPath added in v0.5.0 

func IsDocPath(rel string) bool

IsDocPath reports whether path looks like a documentation file docmap walks.

func RecentFiles added in v0.5.0 

func RecentFiles(dir string, limit int) []string

RecentFiles returns up to `limit` unique paths changed in recent commits under dir, newest first. Paths are relative to dir. Returns nil when git is unavailable or dir is not a work tree.

func Walk added in v0.3.0 

func Walk(root Node, fn func(Node) bool)

Walk invokes fn for every node reachable from root, depth-first. Returning false from fn skips descending into that node's children.

Types 

type AutoLink struct {
	BaseNode
	URL    string
	IsBare bool
	IsMail bool
}

AutoLink is <url> or a GFM bare-URL autolink.

type BaseNode added in v0.3.0 

type BaseNode struct {
	NKind    NodeKind
	Start    int
	End      int
	TokCount int
	Kids     []Node
}

BaseNode holds fields common to every node and is embedded in each concrete type. Its exported fields let constructors populate state without per-type setters.

func (*BaseNode) Children added in v0.3.0 

func (b *BaseNode) Children() []Node

func (*BaseNode) Kind added in v0.3.0 

func (b *BaseNode) Kind() NodeKind

func (*BaseNode) LineEnd added in v0.3.0 

func (b *BaseNode) LineEnd() int

func (*BaseNode) LineStart added in v0.3.0 

func (b *BaseNode) LineStart() int

func (*BaseNode) Tokens added in v0.3.0 

func (b *BaseNode) Tokens() int

type Blockquote added in v0.3.0 

type Blockquote struct {
	BaseNode
}

Blockquote is a > quoted block, possibly nested.

type Callout added in v0.3.0 

type Callout struct {
	BaseNode
	Variant CalloutKind
}

Callout is a GFM alert (> [!NOTE] / [!TIP] / [!IMPORTANT] / [!WARNING] / [!CAUTION]).

type CalloutKind added in v0.3.0 

type CalloutKind string

CalloutKind identifies the variant of a GFM alert (> [!NOTE] etc). 

const (
	CalloutNote      CalloutKind = "note"
	CalloutTip       CalloutKind = "tip"
	CalloutImportant CalloutKind = "important"
	CalloutWarning   CalloutKind = "warning"
	CalloutCaution   CalloutKind = "caution"
)

type CodeBlock added in v0.3.0 

type CodeBlock struct {
	BaseNode
	Language string
	Info     string
	Fenced   bool
	Code     string
}

CodeBlock is a fenced or indented code block.

type CommitRef added in v0.3.0 

type CommitRef struct {
	BaseNode
	SHA string
}

CommitRef is a SHA autolink (GFM).

type ContentSummary added in v0.3.0 

type ContentSummary struct {
	Callouts     int
	Tables       int
	CodeBlocks   int
	MathBlocks   int
	HTMLBlocks   int
	Footnotes    int
	DefLists     int
	LinkRefDefs  int
	Tasks        int
	TasksChecked int
	WikiLinks    int
	WikiEmbeds   int
	Mentions     int
	IssueRefs    int
	CommitRefs   int
	Emojis       int
}

ContentSummary is an at-a-glance inventory of notable constructs across an entire Document. Used by the renderer to draw the file header.

type Definition added in v0.3.0 

type Definition struct {
	BaseNode
}

Definition is a single definition for a term.

type DefinitionList added in v0.3.0 

type DefinitionList struct {
	BaseNode
}

DefinitionList is a Pandoc-style definition list.

type DefinitionTerm added in v0.3.0 

type DefinitionTerm struct {
	BaseNode
	Term string
}

DefinitionTerm is the term being defined.

type Delete added in v0.3.0 

type Delete struct {
	BaseNode
}

Delete is ~~text~~ (GFM strikethrough).

type Document 

type Document struct {
	Filename    string
	Source      string // original file text; used by --expand to dump real markdown
	TotalTokens int
	Sections    []*Section
	References  []Reference // Links to other .md files
	Nodes       []Node      // Typed AST (populated by the new parser)
	// contains filtered or unexported fields
}

Document represents a parsed markdown document.

The legacy Sections tree is heading-only and is what the renderer currently consumes. Nodes holds the richer typed AST produced by the new goldmark-based parser (frontmatter, tables, callouts, code blocks, Obsidian wiki links, etc.) once it lands. Both exist side-by-side during the migration so existing callers keep working.

func Parse 

func Parse(content string) *Document

Parse parses markdown content into a Document using goldmark (CommonMark + GFM + Obsidian extensions) and derives the legacy Section tree and cross-file Reference list from the resulting typed AST.

func ParseFile added in v0.5.0 

func ParseFile(path string) (*Document, error)

ParseFile reads path, optionally consults the on-disk mtime parse cache under .docmap/cache, parses, and stores a fresh entry. PDF files are parsed without caching. Set DOCMAP_NO_CACHE=1 to skip the cache entirely. Cache I/O errors are ignored.

func ParsePDF added in v0.1.0 

func ParsePDF(filepath string) (*Document, error)

ParsePDF parses a PDF file into a Document structure

func ParseYAML added in v0.2.0 

func ParseYAML(content string) (*Document, error)

ParseYAML parses YAML content into a Document structure

func (*Document) GetAllSections 

func (d *Document) GetAllSections() []*Section

GetAllSections returns a flat list of all sections

func (*Document) GetSection 

func (d *Document) GetSection(name string) *Section

GetSection finds a section by name (case-insensitive partial match)

func (*Document) SourceSpan added in v0.5.0 

func (d *Document) SourceSpan(start, end int) string

SourceSpan returns the original source for the inclusive 1-based line range. Empty when Source was not captured (PDF) or the range is invalid. Lines are split once per document and reused across calls.

func (*Document) Summary added in v0.3.0 

func (d *Document) Summary() ContentSummary

Summary walks the typed AST once and returns inventory counts for every notable construct in the document. Used by the renderer to draw the file header's content summary.

type Emoji added in v0.3.0 

type Emoji struct {
	BaseNode
	Name string
}

Emoji is :name: (GFM).

type Emphasis added in v0.3.0 

type Emphasis struct {
	BaseNode
}

Emphasis is *text* or _text_.

type Entity added in v0.3.0 

type Entity struct {
	BaseNode
	Raw     string
	Decoded string
}

Entity is an HTML entity (&copy;, &#169;, &#x2665;).

type FootnoteDef added in v0.3.0 

type FootnoteDef struct {
	BaseNode
	ID string
}

FootnoteDef is a footnote definition ([^id]: content).

type FootnoteRef added in v0.3.0 

type FootnoteRef struct {
	BaseNode
	ID string
}

FootnoteRef is [^id] in flowing text.

type Frontmatter added in v0.3.0 

type Frontmatter struct {
	BaseNode
	Format FrontmatterFormat
	Raw    string
}

Frontmatter is a YAML/TOML/JSON header block at the top of a file.

type FrontmatterFormat added in v0.3.0 

type FrontmatterFormat string

FrontmatterFormat is the serialization format of a frontmatter block. 

const (
	FrontmatterYAML FrontmatterFormat = "yaml"
	FrontmatterTOML FrontmatterFormat = "toml"
	FrontmatterJSON FrontmatterFormat = "json"
)

type HTMLBlock added in v0.3.0 

type HTMLBlock struct {
	BaseNode
	Raw string
}

HTMLBlock is a raw HTML block (includes <details>, <div>, comments).

type Heading added in v0.3.0 

type Heading struct {
	BaseNode
	Level    int
	Title    string
	RawTitle string
	IsSetext bool
	ID       string
}

Heading is an ATX (# Title) or Setext (underline) heading.

type Image added in v0.3.0 

type Image struct {
	BaseNode
	URL   string
	Alt   string
	Title string
	RefID string
}

Image is an inline or reference image.

type InlineCode added in v0.3.0 

type InlineCode struct {
	BaseNode
	Code string
}

InlineCode is `text`.

type InlineHTML added in v0.3.0 

type InlineHTML struct {
	BaseNode
	Raw string
}

InlineHTML is raw inline HTML like <kbd>.

type InlineMath added in v0.3.0 

type InlineMath struct {
	BaseNode
	TeX string
}

InlineMath is $...$.

type IssueRef added in v0.3.0 

type IssueRef struct {
	BaseNode
	Repo   string
	Number int
}

IssueRef is #123 / GH-123 / user/repo#123 (GFM).

type LineBreak added in v0.3.0 

type LineBreak struct {
	BaseNode
	Hard bool
}

LineBreak is a hard (two-space / backslash) or soft line break. 

type Link struct {
	BaseNode
	URL   string
	Title string
	Text  string
	RefID string
}

Link is an inline or reference link.

type LinkRefDef added in v0.3.0 

type LinkRefDef struct {
	BaseNode
	Label string
	URL   string
	Title string
}

LinkRefDef is a reference link definition ([label]: url "title").

type List added in v0.3.0 

type List struct {
	BaseNode
	Ordered bool
	Tight   bool
	Start   int
	Marker  rune
}

List is an ordered or unordered list.

type ListItem added in v0.3.0 

type ListItem struct {
	BaseNode
}

ListItem is a regular item inside a list.

type MathBlock added in v0.3.0 

type MathBlock struct {
	BaseNode
	TeX   string
	Fence string
}

MathBlock is a block-level math expression ($$...$$ or \[...\]).

type Mention added in v0.3.0 

type Mention struct {
	BaseNode
	User string
}

Mention is @user (GFM).

type Node added in v0.3.0 

type Node interface {
	Kind() NodeKind
	LineStart() int
	LineEnd() int
	Tokens() int
	Children() []Node
}

Node is the common interface every markdown construct implements. Concrete types embed BaseNode to satisfy it.

func FindByKind added in v0.3.0 

func FindByKind(root Node, kind NodeKind) []Node

FindByKind returns every descendant of root whose Kind matches kind.

type NodeKind added in v0.3.0 

type NodeKind string

NodeKind enumerates every markdown construct docmap recognizes. The taxonomy covers CommonMark + GFM + Obsidian wiki links/embeds. 

const (
	KindFrontmatter    NodeKind = "frontmatter"
	KindHeading        NodeKind = "heading"
	KindParagraph      NodeKind = "paragraph"
	KindBlockquote     NodeKind = "blockquote"
	KindCallout        NodeKind = "callout"
	KindList           NodeKind = "list"
	KindListItem       NodeKind = "list_item"
	KindTaskItem       NodeKind = "task_item"
	KindTable          NodeKind = "table"
	KindTableRow       NodeKind = "table_row"
	KindTableCell      NodeKind = "table_cell"
	KindCodeBlock      NodeKind = "code_block"
	KindMathBlock      NodeKind = "math_block"
	KindThematicBreak  NodeKind = "thematic_break"
	KindHTMLBlock      NodeKind = "html_block"
	KindDefinitionList NodeKind = "definition_list"
	KindDefTerm        NodeKind = "definition_term"
	KindDefinition     NodeKind = "definition"
	KindFootnoteDef    NodeKind = "footnote_def"
	KindLinkRefDef     NodeKind = "link_ref_def"

	KindText        NodeKind = "text"
	KindEmphasis    NodeKind = "emphasis"
	KindStrong      NodeKind = "strong"
	KindDelete      NodeKind = "delete"
	KindInlineCode  NodeKind = "inline_code"
	KindLink        NodeKind = "link"
	KindAutoLink    NodeKind = "autolink"
	KindImage       NodeKind = "image"
	KindWikiLink    NodeKind = "wiki_link"
	KindWikiEmbed   NodeKind = "wiki_embed"
	KindFootnoteRef NodeKind = "footnote_ref"
	KindMention     NodeKind = "mention"
	KindIssueRef    NodeKind = "issue_ref"
	KindCommitRef   NodeKind = "commit_ref"
	KindEmoji       NodeKind = "emoji"
	KindLineBreak   NodeKind = "line_break"
	KindEntity      NodeKind = "entity"
	KindInlineMath  NodeKind = "inline_math"
	KindInlineHTML  NodeKind = "inline_html"
)

type NotableStats added in v0.3.0 

type NotableStats struct {
	Tasks        int
	TasksChecked int
	WikiLinks    int
	WikiEmbeds   int
	Mentions     int
	IssueRefs    int
	CommitRefs   int
	Emojis       int
}

NotableStats aggregates counts of constructs that would be noisy if listed per-instance under a section.

type Paragraph added in v0.3.0 

type Paragraph struct {
	BaseNode
	Text string
	Raw  string
}

Paragraph is a block of flowing text. Text is the inline-rendered form (newlines collapsed); Raw preserves the original multi-line source so post-passes (math fences, etc.) can operate on real line boundaries.

type PathChange added in v0.5.0 

type PathChange struct {
	Path    string // relative to the directory passed to ChangedPaths
	OldPath string // set for renames (R) / copies (C)
	Status  string // A, M, D, R, C (untracked files are A)
}

PathChange is one path git reports as different from ref.

func ChangedPaths added in v0.5.0 

func ChangedPaths(dir, ref string) ([]PathChange, error)

ChangedPaths lists documentation files that differ from ref under dir, including deletions, renames, and untracked files. Paths are slash- separated and relative to dir. Non-doc paths are omitted.

func ChangedPathsAll added in v0.5.0 

func ChangedPathsAll(dir, ref string) ([]PathChange, error)

ChangedPathsAll lists every path that differs from ref under dir, including non-doc files (e.g. .go), deletions, renames, and untracked files. Paths are slash-separated and relative to dir.

type Reference 

type Reference struct {
	Text   string // Link text
	Target string // Target file path
	Line   int    // Line number where reference appears
}

Reference represents a link to another markdown file

type Section 

type Section struct {
	Level     int // 1 = #, 2 = ##, etc.
	Title     string
	Content   string   // raw content (excluding children)
	Tokens    int      // estimated tokens for this section
	KeyTerms  []string // extracted key concepts
	Children  []*Section
	Parent    *Section
	LineStart int
	LineEnd   int
	Notables  []Node
	Stats     NotableStats
}

Section represents a heading and the content that follows it up to the next same-or-higher heading.

Notables lists the discoverable block nodes inside this section that an agent might want to jump to directly — callouts, tables, code blocks, math blocks, HTML blocks, footnote definitions, definition lists. It is populated one-per-instance so the renderer can print each as its own line.

Stats aggregates counts of things that would be noisy per-instance (task list items, Obsidian wiki links, Obsidian embeds). They are rendered as a single summary line per section.

type Strong added in v0.3.0 

type Strong struct {
	BaseNode
}

Strong is **text** or __text__.

type Table added in v0.3.0 

type Table struct {
	BaseNode
	Headers []string
	Aligns  []TableAlign
}

Table is a GFM table.

type TableAlign added in v0.3.0 

type TableAlign string

TableAlign specifies a column's alignment in a GFM table. 

const (
	AlignNone   TableAlign = ""
	AlignLeft   TableAlign = "left"
	AlignCenter TableAlign = "center"
	AlignRight  TableAlign = "right"
)

type TableCell added in v0.3.0 

type TableCell struct {
	BaseNode
	Align TableAlign
}

TableCell is one cell within a row.

type TableRow added in v0.3.0 

type TableRow struct {
	BaseNode
	IsHeader bool
}

TableRow is a single row of a table.

type TaskItem added in v0.3.0 

type TaskItem struct {
	BaseNode
	Checked bool
}

TaskItem is a GFM task list item ([ ] or [x]).

type Text added in v0.3.0 

type Text struct {
	BaseNode
	Value string
}

Text is a plain run of characters.

type ThematicBreak added in v0.3.0 

type ThematicBreak struct {
	BaseNode
}

ThematicBreak is --- / *** / ___.

type WikiEmbed added in v0.3.0 

type WikiEmbed struct {
	BaseNode
	Target string
	Width  int
	Height int
}

WikiEmbed is ![[file]] / ![[file|200]] / ![[file|200x100]] (Obsidian). 

type WikiLink struct {
	BaseNode
	Target string
	Alias  string
	Anchor string
	Block  string
}

WikiLink is [[Page]] / [[Page|alias]] / [[Page#header]] / [[Page#^block]] (Obsidian).

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.