Documentation
¶
Overview ¶
Package sourcemap provides utilities for working with source code locations, snippet extraction, and line-based operations.
This package bridges BuildKit's AST positions with our output requirements (snippets for diagnostics, comment extraction for inline directives).
Index ¶
- type Comment
- type SourceMap
- func (sm *SourceMap) Comments() []Comment
- func (sm *SourceMap) CommentsForLine(line int) []Comment
- func (sm *SourceMap) EffectiveStartLine(startLine int, prevComments []string) int
- func (sm *SourceMap) Line(line int) string
- func (sm *SourceMap) LineCount() int
- func (sm *SourceMap) LineOffset(line int) int
- func (sm *SourceMap) Lines() []string
- func (sm *SourceMap) ResolveEndLine(endLine int) int
- func (sm *SourceMap) ResolveEndLineWithEscape(endLine int, escapeToken rune) int
- func (sm *SourceMap) Snippet(startLine, endLine int) string
- func (sm *SourceMap) SnippetAround(line, before, after int) string
- func (sm *SourceMap) Source() []byte
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Comment ¶
type Comment struct {
// Line is the 0-based line number where the comment appears.
Line int
// Text is the comment text including the # prefix.
// Leading whitespace before # is trimmed.
Text string
// IsDirective indicates if this looks like a directive comment.
// True if the comment matches patterns like:
// # tally ignore=...
// # hadolint ignore=...
// # check=skip=...
// # syntax=...
// # escape=...
IsDirective bool
}
Comment represents a comment extracted from source. Comments in Dockerfiles start with # and extend to end of line.
type SourceMap ¶
type SourceMap struct {
// contains filtered or unexported fields
}
SourceMap provides efficient access to source code by line. It precomputes line boundaries for fast snippet extraction.
All line numbers are 0-based (matching BuildKit/LSP conventions).
func New ¶
New creates a SourceMap from source content. Lines are split on \n (handles both \n and \r\n).
func (*SourceMap) Comments ¶
Comments extracts all comments from the source. This includes both standalone comment lines and comments associated with AST nodes. Comments are returned in line order.
Note: This only extracts top-level comments (lines starting with #). Comments within instruction arguments are not extracted.
func (*SourceMap) CommentsForLine ¶
CommentsForLine returns all comments that appear immediately before a line. This matches BuildKit's PrevComment behavior where comments are associated with the following instruction.
Example: For line 5, this returns comments from lines 3-4 if:
- Line 3: # comment one
- Line 4: # comment two
- Line 5: FROM alpine
func (*SourceMap) EffectiveStartLine ¶ added in v0.15.0
EffectiveStartLine returns the actual 1-based source line where an instruction's associated comment block begins. BuildKit's PrevComment may span blank lines that the simple formula (StartLine − len(PrevComment)) does not account for; this method scans the source to find the real position of each PrevComment entry.
startLine is the 1-based instruction start line (parser.Node.StartLine). prevComments is the PrevComment slice from the AST node. BuildKit stores each entry as TrimSpace(rawLine[1:]), which means the first byte of the raw source line is dropped before trimming. This makes the stored text format depend on the source indentation:
"# foo" → "foo" (first byte is #) " # foo" → "# foo" (first byte is space)
If prevComments is empty, returns startLine unchanged.
func (*SourceMap) Line ¶
Line returns the text of a specific line (0-based). Returns empty string if line is out of range.
func (*SourceMap) LineOffset ¶
LineOffset returns the byte offset where a line starts (0-based). Returns -1 if line is out of range.
func (*SourceMap) Lines ¶
Lines returns all lines (without line endings). The returned slice should not be modified.
func (*SourceMap) ResolveEndLine ¶ added in v0.11.0
ResolveEndLine returns the actual end line of an instruction, accounting for backslash continuations that extend beyond the parser-reported end line. endLine is the 1-based line number (e.g., parser.Node.EndLine).
func (*SourceMap) ResolveEndLineWithEscape ¶ added in v0.17.0
ResolveEndLineWithEscape returns the actual end line of an instruction, accounting for line continuations that extend beyond the parser-reported end line. endLine is the 1-based line number (e.g., parser.Node.EndLine).
func (*SourceMap) Snippet ¶
Snippet extracts a range of lines as a single string. Both startLine and endLine are 0-based and inclusive. Returns empty string if range is invalid.
Example:
sm.Snippet(2, 4) // Returns lines 2, 3, and 4 joined with newlines
func (*SourceMap) SnippetAround ¶
SnippetAround extracts context lines around a target line. Returns (contextBefore + target + contextAfter) lines as a single string. The before/after counts are clamped to available lines.
Example:
sm.SnippetAround(5, 2, 2) // Returns lines 3-7 (5 ± 2)
Source Files