Documentation
¶
Overview ¶
Package identity defines DocumentID — a document's canonical, repository- relative identity (ADR 0001) — and its validating constructor. It is the lowest leaf of the domain: it depends only on the standard library so that every other domain package (corpus, reference, graphmodel, analysis) can import it without creating cycles. Keeping identity here lets the reference package carry typed DocumentIDs even though corpus depends on reference.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var MarkdownExts = []string{".md", ".markdown"}
MarkdownExts are the recognized markdown file extensions (lowercase, with leading dot). It is the single source of truth shared by the scanner (discovery) and the resolver (note vs. asset classification).
Functions ¶
func Contains ¶
Contains joins relPath (a slash-or-OS-separated, root-relative path) under the absolute root absRoot, cleans it, and verifies the result stays within the root. It returns the cleaned OS-separator path and true when contained, or ("", false) when the joined path escapes the root (via "..", an absolute component, etc.). It is the single root-containment join used by every filesystem boundary in the codebase (the scanner's asset check, the llms-full body reader, the artifact writer) so they cannot diverge on the guard (ADR 0003). It is a pure path computation — it performs no I/O and (like the scanner's separate symlink resolution) does not itself resolve symlinks.
An ABSOLUTE relPath is always rejected: filepath.Join(absRoot, "/etc/passwd") silently treats the absolute path as a relative component and would otherwise report it as contained. Callers pass root-relative paths; an absolute one is a containment violation by definition.
func EscapesRoot ¶
EscapesRoot reports whether a cleaned, slash-separated, root-relative path escapes its root — i.e. it is "..", begins with "../", or is empty/".". It is the single root-containment predicate shared across the codebase (ADR 0003); OS-separator callers convert with filepath.ToSlash first. Note: it expects an already-cleaned path (e.g. from path.Clean or filepath.Rel+ToSlash).
func IDSet ¶
func IDSet(ids []DocumentID) map[DocumentID]struct{}
IDSet turns a slice of DocumentIDs into a membership set. It is the ONE shared helper for the many "have I seen this ID?" / "is this ID in this list?" lookups across the emitters and graph model, so they cannot hand-roll the slice→set loop subtly differently. Order is irrelevant for a set, so determinism of consuming code is unaffected: callers that emit must still sort their output (e.g. via IDStrings or slices.Sort) when iterating the set.
func IDStrings ¶
func IDStrings(ids []DocumentID) []string
IDStrings turns a slice of DocumentIDs into a non-nil, sorted slice of plain strings. It is the ONE shared helper used by every emitter that projects an ID list into JSON/MCP output (graph.json, the MCP server) so the two cannot drift on nil-vs-empty or sort order. The result is always non-nil (an empty input yields an empty, allocated slice) so JSON renders `[]` rather than `null`.
func IsDirectoryIndex ¶
IsDirectoryIndex reports whether base (a path basename) is a conventional directory-index file (README.md / index.md), matched case-insensitively. It is the ONE shared predicate used by both the root-set resolver and the hierarchy builder so the two never diverge on case handling (ADR 0007).
func IsMarkdownPath ¶
IsMarkdownPath reports whether p has a recognized markdown extension. The comparison is case-insensitive.
Types ¶
type DocumentID ¶
type DocumentID string
DocumentID is a document's identity: its canonical repository-relative path, cleaned and slash-separated, relative to the scan root (see ADR 0001). It is never a basename — duplicate basenames in different directories are distinct identities.
func NewDocumentID ¶
func NewDocumentID(root, p string) (DocumentID, error)
NewDocumentID derives a canonical DocumentID for path p, interpreted relative to root. Both root and p may be absolute or relative; the result is always a cleaned, forward-slash, root-relative path. It returns an error if p escapes root (e.g. via ".." or an absolute path outside root), enforcing the root-containment boundary of ADR 0003 at the identity layer.
func (DocumentID) Base ¶
func (id DocumentID) Base() string
Base returns the final path element of the identity. It is a resolution hint only and is never used as identity (see ADR 0001).
func (DocumentID) Dir ¶
func (id DocumentID) Dir() string
Dir returns the slash-separated directory portion of the identity, or "." for a top-level document.
func (DocumentID) String ¶
func (id DocumentID) String() string
String returns the identifier as a plain string.
Source Files