@ttsc/lint 0.30.3 → 0.31.0

package/rule/astutil/astutil.go

@@ -12,6 +12,7 @@
 package astutil
 
 import (
+  "sort"
   "strings"
 
   shimast "github.com/microsoft/typescript-go/shim/ast"
@@ -21,7 +22,7 @@ import (
 // NodeText returns the source text under `node` with leading trivia
 // (whitespace + comments) stripped AND trailing ASCII whitespace
 // (` `, `\t`, `\r`, `\n`) trimmed. Mirrors `nodeText` in the built-in
-// engine — useful for rules that compare textual identity (the
+// engine. Useful for rules that compare textual identity (the
 // `no-self-assign` / `no-self-compare` shape) or that splice a
 // sub-node's text into a fix string.
 //
@@ -32,14 +33,25 @@ import (
 // directly.
 //
 // Returns "" when `file` or `node` is nil, or when the computed range
-// falls outside the file (defensive — shouldn't happen for engine-supplied
-// nodes).
+// falls outside the file, including malformed nodes supplied by callers.
+//
+// @evidence contracts/common.md#principled-implementation Compiler trivia skipping and ASCII trailing trimming preserve the documented source-text boundary; invalid node ranges yield an empty result.
+// @evidence contracts/common.md#clear-and-simple-design One helper owns the text extraction used by contributor comparisons and edits.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Source extraction uses the supported compiler scanner rather than comment-pattern special cases.
+// @evidence contracts/common.md#meaningful-documentation Native prose explains trimmed versus literal ranges and defensive results; paragraphs and tags follow documentation guidance.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation NodeText performs no filesystem or process operation of its own.
+// @evidence contracts/performance.md#efficient-algorithms Bounds checks are fixed work; compiler SkipTrivia scans l leading-trivia bytes and the fixed ASCII TrimRight scans t trailing bytes, giving O(1+l+t) boundary work without copying the selected source text. Trivia can extend beyond the node end before the post-scan range guard rejects it; delegation does not make scanning fixed-cost.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work This pure extraction helper coordinates no requests or shared state. The caller owns source/node snapshot validity and reuse of extracted text; this operation introduces no cross-Program cache keyed only by mutable AST pointers or ranges.
+// @evidence contracts/performance.md#bound-retention-and-release-resources The returned string is a view into the supplied source bytes, not an independent copy, so retaining it can retain the complete source allocation. The caller owns that retention and can copy when a separate lifetime is needed; this helper stores no historical results and acquires no native handle or task.
 func NodeText(file *shimast.SourceFile, node *shimast.Node) string {
   if file == nil || node == nil {
     return ""
   }
   src := file.Text()
   end := node.End()
+  if node.Pos() < 0 || node.Pos() > len(src) {
+    return ""
+  }
   pos := shimscanner.SkipTrivia(src, node.Pos())
   if pos < 0 || end > len(src) || pos >= end {
     return ""
@@ -49,7 +61,10 @@ func NodeText(file *shimast.SourceFile, node *shimast.Node) string {
 
 // KeywordStart returns the source offset of a declaration keyword such as
 // `var`, `let`, `const`, `module`, `namespace`, or `function` that lives
-// at the start of `node` (after leading trivia). Returns -1 if not found.
+// in the declaration prefix of `node` (after leading trivia and modifiers).
+// Names, type syntax, parameters and bodies end that prefix. Decorator
+// expressions do not supply the declaration keyword. Returns -1 if not found.
+// Comments, literal contents and identifier prefixes are not keyword tokens.
 //
 // Use this to anchor TextEdits that swap a leading keyword:
 //
@@ -58,46 +73,83 @@ func NodeText(file *shimast.SourceFile, node *shimast.Node) string {
 //    ctx.ReportFix(node, "use const",
 //      rule.TextEdit{Pos: start, End: start + len("let"), Text: "const"})
 //  }
+//
+// @evidence contracts/common.md#principled-implementation Parser header boundaries and token search locate the declaration keyword without mistaking nested bodies or parameter initializers for the declaration.
+// @evidence contracts/common.md#clear-and-simple-design Node-based search shares the same token-location implementation as arbitrary-range search.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Compiler tokens replace the guessed 32-byte prefix and raw substring workaround.
+// @evidence contracts/common.md#meaningful-documentation Native prose explains modifier handling, token exclusions, missing results and an edit example; separated tags follow documentation guidance.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation KeywordStart scans source text positions and touches no filesystem path or process.
+// @evidence contracts/performance.md#efficient-algorithms Header-bound selection inspects h declarations and parameters before constructing the scanner. A matching first token avoids opaque-span collection; otherwise a child walk visits a nodes, collects s opaque spans and sorts them in O(s log s), followed by forward lexical search. Delegated trivia/token decoding costs depend on bytes consumed, not just token count; the grammar boundary excludes body traversal while preserving modifier and decorator distinctions.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work This pure lookup helper coordinates no requests or shared memo. Source/node identity and positions belong to the caller snapshot; scanner state is fresh for the requested grammar boundary, and any caller reuse must remain valid for that snapshot rather than AST pointer equality across Programs.
+// @evidence contracts/performance.md#bound-retention-and-release-resources The call owns a temporary scanner, up to s collected spans and recursive walk depth. The scanner borrows the source and may allocate decoded token values or per-scan numeric caches proportional to scanned data; none survives through the returned integer. Inputs remain caller-owned, and this helper retains no history, native handle or running task.
 func KeywordStart(file *shimast.SourceFile, node *shimast.Node, keyword string) int {
   if file == nil || node == nil || keyword == "" {
     return -1
   }
-  src := file.Text()
-  pos := shimscanner.SkipTrivia(src, node.Pos())
-  end := pos + len(keyword)
-  if pos < 0 || end > len(src) {
+  pos, end := node.Pos(), node.End()
+  if pos < 0 || pos >= end || end > len(file.Text()) {
     return -1
   }
-  if strings.HasPrefix(src[pos:], keyword) && (end == len(src) || !isIdentifierPart(src[end])) {
-    return pos
-  }
-  limit := node.End()
-  if limit > len(src) {
-    limit = len(src)
-  }
-  // Scan at most 32 bytes past the trivia-adjusted start. Declaration keywords
-  // ("var", "let", "const", etc.) always appear within the first few bytes of
-  // a node's token range; the cap avoids runaway scanning on malformed nodes.
-  for i := pos; i+len(keyword) <= limit && i < pos+32; i++ {
-    end = i + len(keyword)
-    if strings.HasPrefix(src[i:], keyword) &&
-      (i == 0 || !isIdentifierPart(src[i-1])) &&
-      (end == len(src) || !isIdentifierPart(src[end])) {
-      return i
+  limit := func(child *shimast.Node) {
+    if child != nil && child.Pos() >= pos && child.Pos() < end {
+      end = child.Pos()
     }
   }
-  return -1
+  limit(node.Name())
+  limit(node.Body())
+  declarations := node
+  if node.Kind == shimast.KindVariableStatement {
+    if statement := node.AsVariableStatement(); statement != nil {
+      declarations = statement.DeclarationList
+    }
+  }
+  if declarations != nil && declarations.Kind == shimast.KindVariableDeclarationList {
+    if list := declarations.AsVariableDeclarationList(); list != nil && list.Declarations != nil {
+      for _, declaration := range list.Declarations.Nodes {
+        limit(declaration)
+      }
+    }
+  }
+  if function := node.FunctionLikeData(); function != nil {
+    limit(function.Type)
+    if function.TypeParameters != nil {
+      for _, parameter := range function.TypeParameters.Nodes {
+        limit(parameter)
+      }
+    }
+    if function.Parameters != nil {
+      for _, parameter := range function.Parameters.Nodes {
+        limit(parameter)
+      }
+    }
+  }
+  scan := shimscanner.GetScannerForSourceFile(file, pos)
+  if keywordMatches(scan, pos, end, keyword) {
+    return scan.TokenStart()
+  }
+  return searchKeyword(scan, pos, end, keyword, opaqueSpans(file, node, end, true))
 }
 
 // FindKeyword scans `[pos, end)` for a keyword token whose lexeme is
 // `keyword` and returns its first-byte offset, or -1 if not found.
 // Differs from KeywordStart in that it works on an arbitrary byte range
-// instead of a node's leading-trivia-adjusted start — use this for fixes
-// that need to splice text after `import` or before `from`.
+// instead of a declaration header. Scanning starts at the file beginning to
+// preserve lexical context, but matches must lie inside the range. Use this
+// for fixes that splice text after `import` or before `from`.
+//
+// The compiler scanner handles Unicode identifier boundaries and trivia.
+// Parser-classified strings, regex literals, template text and JSX text are
+// excluded so a matching word inside literal content is never returned.
+// The entire keyword token must lie within the requested range.
 //
-// The match is identifier-aware: a hit must be flanked by non-identifier
-// bytes (or file edges) so that searching for `import` does not match
-// the `import` prefix of `importMap`.
+// @evidence contracts/common.md#principled-implementation Parser opaque spans prevent context-sensitive literal contents from entering lexical search; the compiler scanner then recognizes complete keyword tokens and their original byte ranges.
+// @evidence contracts/common.md#clear-and-simple-design One search implementation owns literal exclusion, lexical matching and range bounds for public and host callers.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Language tokens replace ASCII flank guesses and raw text matches, without fixture-specific exceptions or foreign scanner mutation.
+// @evidence contracts/common.md#meaningful-documentation Native prose states Unicode, literal and complete-range behavior; paragraphs and tags follow documentation guidance.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation FindKeyword performs no filesystem or process operation of its own.
+// @evidence contracts/performance.md#efficient-algorithms The parser child walk visits a nodes, pruning descent at the requested end or an opaque literal, then sorts s spans in O(s log s). Forward scanning begins at file byte zero to preserve lexical context and can consume a complete boundary token before rejecting it; token/trivia decoding is driven by scanned bytes and values. This may read the prefix before pos, and temporary span storage grows with s; no fixed-cost claim follows from delegation.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work This pure range lookup owns no request coordinator or shared memo. The caller owns source snapshot identity, byte-range validity and any reuse across repeated queries; a fresh scanner preserves lexical context for this range instead of reusing a position under a changed Program.
+// @evidence contracts/performance.md#bound-retention-and-release-resources The call owns a temporary scanner, s opaque-span slots and recursive walk stack. Scanner token values and numeric caches can allocate according to scanned data while borrowing the source; only one integer leaves the function, so those temporary owners become unreachable on return. No cross-call history, native handle or task is retained.
 func FindKeyword(file *shimast.SourceFile, pos, end int, keyword string) int {
   if file == nil || keyword == "" {
     return -1
@@ -109,38 +161,69 @@ func FindKeyword(file *shimast.SourceFile, pos, end int, keyword string) int {
   if end > len(src) {
     end = len(src)
   }
-  limit := end - len(keyword)
-  for i := pos; i <= limit; i++ {
-    if src[i] != keyword[0] {
-      continue
-    }
-    tail := i + len(keyword)
-    if src[i:tail] != keyword {
-      continue
+  if pos >= end {
+    return -1
+  }
+  scan := shimscanner.GetScannerForSourceFile(file, 0)
+  return searchKeyword(scan, pos, end, keyword, opaqueSpans(file, file.AsNode(), end, false))
+}
+
+// keywordMatches accepts complete language keyword tokens within the range.
+func keywordMatches(scan *shimscanner.Scanner, pos, end int, keyword string) bool {
+  kind := scan.Token()
+  return scan.TokenStart() >= pos && scan.TokenEnd() <= end &&
+    kind >= shimast.KindFirstKeyword && kind <= shimast.KindLastKeyword &&
+    scan.TokenText() == keyword
+}
+
+// searchKeyword skips parser-classified opaque text before lexical matching.
+// Node callers start at their grammar boundary; arbitrary ranges start at the
+// source beginning so a range inside a string or comment cannot create tokens.
+func searchKeyword(scan *shimscanner.Scanner, pos, end int, keyword string, spans []opaqueSpan) int {
+  spanIndex := 0
+  for scan.Token() != shimast.KindEndOfFile && scan.TokenStart() < end {
+    start := scan.TokenStart()
+    for spanIndex < len(spans) && spans[spanIndex].end <= start {
+      spanIndex++
     }
-    if i > 0 && isIdentifierPart(src[i-1]) {
+    if spanIndex < len(spans) && spans[spanIndex].pos <= start {
+      scan.ResetTokenState(spans[spanIndex].end)
+      scan.Scan()
       continue
     }
-    if tail < len(src) && isIdentifierPart(src[tail]) {
-      continue
+    if keywordMatches(scan, pos, end, keyword) {
+      return start
     }
-    return i
+    scan.Scan()
   }
   return -1
 }
 
-// TokenRange returns the `[pos, end)` range of a node's primary token
-// with leading trivia stripped from the start. Useful for rules that
+// TokenRange returns the node's `[pos, end)` range with leading trivia
+// stripped from the start and its original End preserved. It covers the
+// complete node, not only its first lexical token. Useful for rules that
 // want their diagnostic and fix range aligned to the token rather than
 // the surrounding whitespace.
 //
 // Returns `(-1, -1)` when `file` or `node` is nil or when the computed
 // range is malformed.
+//
+// @evidence contracts/common.md#principled-implementation Compiler trivia skipping produces the token start while node End remains the half-open bound; malformed ranges return the documented sentinel pair.
+// @evidence contracts/common.md#clear-and-simple-design One range helper separates untrimmed byte coordinates from NodeText's trailing trim.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Range extraction uses supported compiler trivia semantics without guessed whitespace or consumer-specific offsets.
+// @evidence contracts/common.md#meaningful-documentation Native prose describes byte-range alignment and invalid sentinels; paragraphs and tags follow documentation guidance.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation TokenRange performs no filesystem or process operation of its own.
+// @evidence contracts/performance.md#efficient-algorithms Bounds checks and two coordinate returns are fixed work; compiler SkipTrivia scans l leading-trivia bytes, giving O(1+l) boundary work without copying source text or traversing the node body. Malformed trivia can reach beyond the node end before the post-scan guard rejects the range.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work This pure coordinate helper coordinates no requests or shared state. The caller owns the source/node snapshot whose positions establish validity and any reuse of these coordinates; this operation adds no cross-Program memo based on AST pointers alone.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Only two integer coordinates leave this function; they retain no source string, AST pointer or allocation. The caller owns the input Program lifetime, and this helper stores no historical results or acquires any native handle or task.
 func TokenRange(file *shimast.SourceFile, node *shimast.Node) (int, int) {
   if file == nil || node == nil {
     return -1, -1
   }
   src := file.Text()
+  if node.Pos() < 0 || node.Pos() > len(src) {
+    return -1, -1
+  }
   pos := shimscanner.SkipTrivia(src, node.Pos())
   end := node.End()
   if pos < 0 || pos > len(src) || end < pos || end > len(src) {
@@ -149,19 +232,42 @@ func TokenRange(file *shimast.SourceFile, node *shimast.Node) (int, int) {
   return pos, end
 }
 
-// isIdentifierPart reports whether the ASCII byte ch can appear inside a
-// JavaScript/TypeScript identifier (letters, digits, underscore, dollar sign).
-// Used to detect word boundaries when searching for keyword tokens so that
-// a search for "let" does not match "letters".
-// Note: this is a byte-level check; non-ASCII identifier characters (e.g.
-// Unicode letters) are treated as non-identifier bytes, which is conservative
-// — the keyword boundary check may produce a false positive only for source
-// files that use non-ASCII characters immediately adjacent to a keyword,
-// an extremely rare pattern in practice.
-func isIdentifierPart(ch byte) bool {
-  return (ch >= 'a' && ch <= 'z') ||
-    (ch >= 'A' && ch <= 'Z') ||
-    (ch >= '0' && ch <= '9') ||
-    ch == '_' ||
-    ch == '$'
+type opaqueSpan struct {
+  pos int
+  end int
+}
+
+// opaqueSpans uses parser classification because scanning alone cannot
+// distinguish regex bodies, template continuations and JSX text from code.
+func opaqueSpans(file *shimast.SourceFile, root *shimast.Node, end int, declarationPrefix bool) []opaqueSpan {
+  spans := make([]opaqueSpan, 0)
+  var walk func(*shimast.Node)
+  walk = func(node *shimast.Node) {
+    if node == nil || node.Pos() >= end {
+      return
+    }
+    kind := node.Kind
+    if kind >= shimast.KindStringLiteral && kind <= shimast.KindLastLiteralToken ||
+      kind >= shimast.KindFirstTemplateToken && kind <= shimast.KindLastTemplateToken ||
+      kind == shimast.KindJsxText || kind == shimast.KindJsxTextAllWhiteSpaces ||
+      declarationPrefix && kind == shimast.KindDecorator {
+      start := shimscanner.GetTokenPosOfNode(node, file, false)
+      if start >= 0 && node.End() > start && node.End() <= len(file.Text()) {
+        spans = append(spans, opaqueSpan{pos: start, end: node.End()})
+      }
+      return
+    }
+    node.ForEachChild(func(child *shimast.Node) bool {
+      walk(child)
+      return false
+    })
+  }
+  walk(root)
+  sort.Slice(spans, func(i, j int) bool {
+    if spans[i].pos != spans[j].pos {
+      return spans[i].pos < spans[j].pos
+    }
+    return spans[i].end < spans[j].end
+  })
+  return spans
 }

package/rule/context_decode_options_preserves_defaults_and_decoder_errors_test.go

@@ -0,0 +1,87 @@
+package rule_test
+
+import (
+  "encoding/json"
+  "errors"
+  "testing"
+
+  "github.com/samchon/ttsc/packages/lint/rule"
+)
+
+// TestContextDecodeOptionsPreservesDefaultsAndDecoderErrors verifies all five
+// public context helpers preserve absence and standard JSON decoding semantics.
+//
+// Present options update a caller-owned destination rather than constructing a
+// cached replacement. Invalid input returns the standard decoder's error; JSON
+// type errors do not promise transactional rollback of all destination fields.
+//
+//  1. Exercise nil receivers and absent payloads without changing defaults.
+//  2. Decode a partial object into distinct defaults, preserving omitted fields.
+//  3. Check syntax, type and invalid-destination errors plus JSON null behavior.
+//
+// @evidence contracts/testing.md#behavioral-verification The actual Context, ProjectContext, ProjectInputContext, HintContext and GraphContext DecodeOptions methods preserve caller defaults for absent input, decode present fields without replacing omitted defaults, and return standard JSON errors rather than swallowing them.
+// @evidence contracts/testing.md#independent-expectations Authored default values and literal JSON specify destination updates independently of the helpers. Standard encoding/json documents SyntaxError, UnmarshalTypeError, InvalidUnmarshalError and null-to-scalar behavior; assertions use those public error types without reproducing decoder logic or assuming rollback after a type error.
+// @evidence contracts/testing.md#distinguishing-cases Each named context runs nil receiver, nil and empty options, populated partial object with an unknown member, distinct destination defaults, malformed syntax, wrong field type, nil destination and JSON null cases. Custom unmarshaler effects and filesystem path interpretation are not claimed by these ordinary destination cases.
+// @evidence contracts/testing.md#execution-ownership One direct external-package unit registers five separately named context subcases and calls the public option-decoding operations with raw JSON. It needs no Program, registry, filesystem fixture, native artifact or installed consumer.
+func TestContextDecodeOptionsPreservesDefaultsAndDecoderErrors(t *testing.T) {
+  contexts := []struct {
+    name   string
+    decode func(json.RawMessage) func(interface{}) error
+    absent func(interface{}) error
+  }{
+    {"file", func(raw json.RawMessage) func(interface{}) error { return (&rule.Context{Options: raw}).DecodeOptions }, (*rule.Context)(nil).DecodeOptions},
+    {"project", func(raw json.RawMessage) func(interface{}) error {
+      return (&rule.ProjectContext{Options: raw}).DecodeOptions
+    }, (*rule.ProjectContext)(nil).DecodeOptions},
+    {"input", func(raw json.RawMessage) func(interface{}) error {
+      return (&rule.ProjectInputContext{Options: raw}).DecodeOptions
+    }, (*rule.ProjectInputContext)(nil).DecodeOptions},
+    {"hint", func(raw json.RawMessage) func(interface{}) error {
+      return (&rule.HintContext{Options: raw}).DecodeOptions
+    }, (*rule.HintContext)(nil).DecodeOptions},
+    {"graph", func(raw json.RawMessage) func(interface{}) error {
+      return (&rule.GraphContext{Options: raw}).DecodeOptions
+    }, (*rule.GraphContext)(nil).DecodeOptions},
+  }
+  for _, context := range contexts {
+    t.Run(context.name, func(t *testing.T) {
+      type options struct {
+        Mode  string `json:"mode"`
+        Count int    `json:"count"`
+      }
+      for _, decode := range []func(interface{}) error{context.absent, context.decode(nil), context.decode(json.RawMessage{})} {
+        out := options{Mode: "default", Count: 7}
+        if err := decode(&out); err != nil || out != (options{Mode: "default", Count: 7}) {
+          t.Fatalf("absence changed defaults: out=%#v error=%v", out, err)
+        }
+        if err := decode(nil); err != nil {
+          t.Fatalf("absence decoded an invalid destination: %v", err)
+        }
+      }
+      decode := context.decode(json.RawMessage(`{"mode":"loud","unknown":true}`))
+      for _, count := range []int{7, 11} {
+        out := options{Mode: "default", Count: count}
+        if err := decode(&out); err != nil || out != (options{Mode: "loud", Count: count}) {
+          t.Fatalf("partial decode lost destination defaults: out=%#v error=%v", out, err)
+        }
+      }
+      out := options{Mode: "default", Count: 7}
+      var syntaxError *json.SyntaxError
+      if err := context.decode(json.RawMessage(`{"mode":`))(&out); !errors.As(err, &syntaxError) || out != (options{Mode: "default", Count: 7}) {
+        t.Fatalf("syntax error was swallowed or changed destination: out=%#v error=%v", out, err)
+      }
+      var typeError *json.UnmarshalTypeError
+      if err := context.decode(json.RawMessage(`{"count":"wrong"}`))(&out); !errors.As(err, &typeError) {
+        t.Fatalf("field type error was not returned: %v", err)
+      }
+      var destinationError *json.InvalidUnmarshalError
+      if err := decode(nil); !errors.As(err, &destinationError) {
+        t.Fatalf("present options accepted nil destination: %v", err)
+      }
+      scalar := 23
+      if err := context.decode(json.RawMessage(`null`))(&scalar); err != nil || scalar != 23 {
+        t.Fatalf("JSON null changed scalar default: value=%d error=%v", scalar, err)
+      }
+    })
+  }
+}

package/rule/graph.go

@@ -14,6 +14,15 @@ import "encoding/json"
 // author can cite actually has — a document and its sections, a data model and
 // its fields, an API operation — and any contributor that can materialize one
 // publishes it here.
+//
+// @evidence contracts/common.md#principled-implementation A named string discriminant expresses the finite artifact vocabulary that host consumers recognize.
+// @evidence contracts/common.md#clear-and-simple-design One shared kind type separates artifact classification from addresses and presentation.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Artifact kinds are supported protocol constants rather than contributor-specific dispatch patches.
+// @evidence contracts/common.md#meaningful-documentation Native prose explains vocabulary ownership and unknown-kind rejection; separated paragraphs and tags follow documentation guidance.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation GraphNodeKind is a declaration of data shape and performs no filesystem, path or process operation.
+// @evidenceExclude contracts/performance.md#efficient-algorithms GraphNodeKind is a declaration of data shape and chooses no algorithm or processing strategy.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work GraphNodeKind is a declaration of data shape and coordinates no computation that could be shared.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources GraphNodeKind is a declaration of data shape; the code that holds its values owns their lifetime.
 type GraphNodeKind string
 
 const (
@@ -40,6 +49,15 @@ const (
 // A consumer seeds its vocabulary from this rather than from a list of its own:
 // a kind added to the block above and not to a consumer's map is a node drawn
 // or ranked as something it is not.
+//
+// @evidence contracts/common.md#principled-implementation The returned literal slice enumerates the declared protocol kinds in their documented order.
+// @evidence contracts/common.md#clear-and-simple-design One function supplies the vocabulary so consumers need not maintain independent lists.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Enumeration contains protocol discriminants without consumer-specific branches or foreign mutation.
+// @evidence contracts/common.md#meaningful-documentation The native comment explains ordering and the consumer consistency reason; prose and tags are separated under documentation guidance.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation GraphNodeKinds performs no filesystem or process operation of its own.
+// @evidence contracts/performance.md#efficient-algorithms Constructing the fixed six-kind literal takes constant work and six returned slice slots; no input-dependent scan or artifact traversal occurs.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work Each call returns independently mutable slice slots containing the immutable protocol strings. Sharing a cached backing slice would let one caller corrupt another caller vocabulary; consumers own any reused lookup set derived from this fixed list.
+// @evidence contracts/performance.md#bound-retention-and-release-resources The caller owns one six-slot output allocation and its retention; protocol strings are static values. The function retains no historical outputs and acquires no native handle or task.
 func GraphNodeKinds() []GraphNodeKind {
   return []GraphNodeKind{
     GraphNodeMarkdownDocument,
@@ -54,14 +72,23 @@ func GraphNodeKinds() []GraphNodeKind {
 // GraphNode is one artifact a declaration's documentation can cite.
 //
 // It is a value, not a behavior, for the same reason Hint is: the host
-// serializes the set and hands it to a consumer that reads it long after the
-// lint process exited. What travels is what the consumer can answer from.
+// serializes the set and hands values to a consumer independently of whether
+// the sidecar exits or remains resident. The values contain no callable code.
 //
 // The node is an index entry, never content. A section carries its heading and
 // where it starts; the text under that heading is read from the file when
 // someone actually needs it, exactly as a function body is.
+//
+// @evidence contracts/common.md#principled-implementation Address, kind, containment and optional source position form a serializable artifact index while aliases refer to the same identity.
+// @evidence contracts/common.md#clear-and-simple-design The record exposes identity and navigation facts without mixing in diagnostic policy or document content.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Addresses are produced by the owning rule's grammar rather than fabricated by consumers or patched host internals.
+// @evidence contracts/common.md#meaningful-documentation Members explain parent handling, address ownership, aliases and 1-based positions; paragraphs, member gaps and tags follow documentation guidance.
+// @evidence contracts/portability.md#os-neutral-implementation File carries the producer-spelled native source path and Line its one-based position, while Address, Parent and Aliases belong to the producer's citation grammar. This record preserves those separate channels without deriving paths from addresses, folding filesystem case or manufacturing a source file for a fileless artifact.
+// @evidenceExclude contracts/performance.md#efficient-algorithms GraphNode is a declaration of data shape and chooses no algorithm or processing strategy.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work GraphNode is a declaration of data shape and coordinates no computation that could be shared.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources GraphNode is a declaration of data shape; the code that holds its values owns their lifetime.
 type GraphNode struct {
-  // Address is the identity a citation names, verbatim — `docs/sale.md#pricing`,
+  // Address is the identity a citation names, verbatim: `docs/sale.md#pricing`,
   // `prisma:Sale.price`, `POST:/orders/{orderId}`.
   //
   // The rule that produced it owns the grammar. A consumer keys on the string
@@ -75,7 +102,7 @@ type GraphNode struct {
   // dropped by the consumer.
   Kind GraphNodeKind `json:"kind"`
 
-  // Readable is the human-facing name — a heading's own text, a model's name.
+  // Readable is the human-facing name, such as heading text or a model name.
   // Empty when the artifact has none beyond its address.
   Readable string `json:"readable,omitempty"`
 
@@ -85,7 +112,7 @@ type GraphNode struct {
   Parent string `json:"parent,omitempty"`
 
   // File is where the artifact lives, as the rule spells it. Empty when the
-  // artifact has no file — an API operation is named by method and path, and
+  // artifact has no file. An API operation is named by method and path, and
   // which document declared it is not part of its identity.
   File string `json:"file,omitempty"`
 
@@ -98,11 +125,21 @@ type GraphNode struct {
   Aliases []string `json:"aliases,omitempty"`
 }
 
-// GraphContext is the read-only handle the host passes to GraphNodes.
+// GraphContext contains resolved inputs the host passes to GraphNodes.
+// Contributors treat them as read-only.
+//
+// State carries Check's published value for the current evaluation cycle,
+// allowing projection without storing Program data in the registered rule.
+// Registration accepts both value and pointer implementations, as with Hints.
 //
-// It mirrors HintContext exactly, and for the same reason: a rule value is
-// stateless, so without State here a projection could only ever return
-// constants.
+// @evidence contracts/common.md#principled-implementation Identity, exact published state and resolved settings bind graph projection to the Program Check evaluated.
+// @evidence contracts/common.md#clear-and-simple-design One projection context carries inputs without introducing a second mutable state owner.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The supported context transports state instead of reaching into foreign host internals.
+// @evidence contracts/common.md#meaningful-documentation Native member comments identify Program binding, state and settings; the tag block and member boundaries follow documentation guidance.
+// @evidence contracts/portability.md#os-neutral-implementation Identity preserves the host-resolved Program's separate logical/physical native paths, cwd and optional origins. ProjectIdentity and the host own resolution and spelling policy; this container neither infers filesystem case nor converts those channels to citation addresses or protocol URLs.
+// @evidenceExclude contracts/performance.md#efficient-algorithms GraphContext is a declaration of data shape and chooses no algorithm or processing strategy.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work GraphContext is a declaration of data shape and coordinates no computation that could be shared.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources GraphContext is a declaration of data shape; the code that holds its values owns their lifetime.
 type GraphContext struct {
   // Identity names the Program these nodes were built for, as during Check.
   Identity ProjectIdentity
@@ -117,6 +154,15 @@ type GraphContext struct {
 
 // DecodeOptions unmarshals the configured options into out. A missing options
 // tuple leaves out unchanged and returns nil.
+//
+// @evidence contracts/common.md#principled-implementation The nil-or-empty guard preserves caller defaults, while encoding/json handles present options and reports decoding errors.
+// @evidence contracts/common.md#clear-and-simple-design The context delegates JSON semantics to one standard decoder after its absence guard.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts No artifact-specific option bypass or foreign mutation is used.
+// @evidence contracts/common.md#meaningful-documentation The native method comment states empty-options behavior with a separated tag block under documentation guidance.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation GraphContext.DecodeOptions performs no filesystem or process operation of its own.
+// @evidence contracts/performance.md#efficient-algorithms The absence check is constant work; present options delegate validation and decoding to encoding/json, with work driven by JSON bytes and destination shape and storage allocated as required by decoded values. A destination custom unmarshaler can add its own work; absence of a wrapper loop does not make decoding fixed-cost.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work Decoding updates the supplied destination, preserves its omitted defaults and can invoke destination-defined unmarshaling effects. Equal JSON alone does not make different destinations or calls interchangeable; this helper owns no cross-request result cache.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Decoded values and their allocations belong to the caller-supplied destination; custom unmarshaler retention is owned by that implementation. This helper neither stores destination history nor acquires native handles or tasks, and its receiver owner controls the existing raw option bytes.
 func (c *GraphContext) DecodeOptions(out interface{}) error {
   if c == nil || len(c.Options) == 0 {
     return nil
@@ -127,10 +173,12 @@ func (c *GraphContext) DecodeOptions(out interface{}) error {
 // GraphRule is an optional marker a ProjectRule implements to publish the
 // artifacts a declaration's documentation can cite.
 //
-// The gate is HintRule's, for the same reasons: called at most once per Program,
-// always after Check, only when a consumer asks — never during `ttsc check` —
-// and never unless Check passed and published state. A rule configured off is
-// never asked, so `off` means no nodes with no code in the rule.
+// The gate is HintRule's: called after Check for a requested projection of one
+// project evaluation cycle, never during `ttsc check`, and never unless Check
+// passed and published state. Resident requests can start new cycles over a
+// reused loaded Program; graph output is not cached for that Program's entire
+// lifetime. A rule configured off is never asked, so `off` means no nodes with
+// no code in the rule.
 //
 // Pull, not push. A set of artifacts is a projection of FINISHED state; a rule
 // pushing nodes while building that state would publish the ones it had found
@@ -138,13 +186,31 @@ func (c *GraphContext) DecodeOptions(out interface{}) error {
 //
 // What crosses this boundary is what an artifact *is*, never what the rule
 // decided about it. No coverage, no cardinality, no policy, no diagnostic:
-// those are the linter's product and it already delivers them as compile
-// errors. A consumer that received them would hold a second, unmaintained
-// answer to a question the linter already answers.
+// those are the linter's product and it already delivers them as diagnostics.
+// A consumer that received them would hold a second, unmaintained answer to a
+// question the linter already answers.
+//
+// @evidence contracts/common.md#principled-implementation ProjectRule embedding permits a complete graph projection only from the checked Program state, keeping diagnostic results in their separate channel.
+// @evidence contracts/common.md#clear-and-simple-design One optional method extends project checking with artifact publication rather than duplicating coverage evaluation.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Graph publication is a supported marker interface with no host replacement or synthesized coverage result.
+// @evidence contracts/common.md#meaningful-documentation Native prose specifies publication gating and the artifact-versus-diagnostic boundary; paragraphs and tag spacing follow documentation guidance.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation GraphRule is a declaration of data shape and performs no filesystem, path or process operation.
+// @evidenceExclude contracts/performance.md#efficient-algorithms GraphRule is a declaration of data shape and chooses no algorithm or processing strategy.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work GraphRule is a declaration of data shape and coordinates no computation that could be shared.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources GraphRule is a declaration of data shape; the code that holds its values owns their lifetime.
 type GraphRule interface {
   ProjectRule
 
   // GraphNodes returns the artifacts this rule materialized, in any order.
   // Containment is expressed by Parent rather than by position.
+  //
+  // @evidence contracts/common.md#principled-implementation The returned artifacts carry explicit parent addresses, so containment does not depend on result ordering.
+  // @evidence contracts/common.md#clear-and-simple-design One complete slice represents the checked state projection without incremental publication callbacks.
+  // @evidence contracts/common.md#prohibited-implementation-shortcuts Artifacts use the supported projection method rather than fabricated diagnostic acknowledgments.
+  // @evidence contracts/common.md#meaningful-documentation The native comment states arbitrary order and explicit containment with a separated tag block under documentation guidance.
+  // @evidenceExclude contracts/portability.md#os-neutral-implementation GraphRule.GraphNodes is a method signature without a body; each implementation owns any filesystem or process behavior.
+  // @evidenceExclude contracts/performance.md#efficient-algorithms GraphRule.GraphNodes is a method signature without a body; each implementation chooses its own algorithm.
+  // @evidenceExclude contracts/performance.md#reuse-equivalent-work GraphRule.GraphNodes is a method signature without a body; each implementation decides what, if anything, to share.
+  // @evidenceExclude contracts/performance.md#bound-retention-and-release-resources GraphRule.GraphNodes is a method signature without a body; each implementation owns any retained state.
   GraphNodes(ctx *GraphContext) []GraphNode
 }