README
¶
pkg/sourceref
specscore: annotation parsing and source-to-spec linking. Detects and parses references from source code comments.
Outstanding Questions
sourceref.gohardcodes"github.com","synchestra-io","synchestra"as the "current" repo defaults used byparseExpandedURLto determine whether a cross-repo suffix is needed. Should these be configurable via a parameter or context struct so the library works for any project? For now, these match the original synchestra behavior.
Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
var DetectionRegex = regexp.MustCompile(`^\s*(//|#|--|/\*|\*|%|;)\s*(synchestra:|https://synchestra\.io/)`)
DetectionRegex matches source references preceded by recognized comment prefixes.
Functions ¶
func DetectReference ¶
DetectReference checks if a line contains a source reference.
func ExpandGlobPattern ¶
ExpandGlobPattern expands a glob pattern to a list of file paths. Returns sorted file paths.
Supported patterns:
- "**/*" or "**" — matches all files recursively (special-cased)
- Standard filepath.Match patterns (e.g. "*.go", "src/*.txt")
Note: arbitrary recursive glob patterns like "src/**/*.go" are NOT supported. Only the exact literals "**" and "**/*" trigger recursive matching; all other patterns are matched per-segment via filepath.Match.
func ExtractReference ¶
ExtractReference extracts the reference string from a line.
func FormatOutput ¶
func FormatOutput(result *ScanResult, singleFile bool, typeFilter string) string
FormatOutput formats the scan results for output. If singleFile is true, returns a flat list. Otherwise, groups by file with headers.
Types ¶
type Reference ¶
type Reference struct {
// ResolvedPath is the repo-root-relative path after type-prefix expansion
ResolvedPath string
// CrossRepoSuffix is the optional @host/org/repo (empty string if same-repo)
CrossRepoSuffix string
// Type is the inferred resource type: "feature", "plan", "doc", or "" if unknown
Type string
}
Reference represents a parsed source reference found in source code.
func GetUniqueReferences ¶
func GetUniqueReferences(result *ScanResult, typeFilter string) []*Reference
GetUniqueReferences extracts unique references from a ScanResult, optionally filtered by type. Returns references sorted by (resolved_path, cross_repo_suffix).
func ParseReference ¶
ParseReference parses an extracted reference string and returns a Reference.
type ScanResult ¶
type ScanResult struct {
// FileRefs maps file path to list of references found in that file
FileRefs map[string][]*Reference
}
ScanResult represents the references found in a set of files.
func ScanFiles ¶
func ScanFiles(filePaths []string) (*ScanResult, error)
ScanFiles scans a list of files for source references. Returns a ScanResult with all references grouped by file. The result may be partial if some files fail; errors are accumulated and returned alongside whatever refs were successfully scanned.
Source Files