ttsc 0.30.3 → 0.31.0

package/internal/graph/artifacts.go

@@ -20,6 +20,15 @@ import (
 // Nothing here is a judgement. The rule that materialized these decides what is
 // covered, what is a legitimate exclusion, and what is missing, and it delivers
 // those as compile errors. The graph reports; the linter judges.
+//
+// @evidence contracts/common.md#principled-implementation Opaque canonical addresses and aliases represent plugin-published noncompiler facts without pretending they follow declaration identity syntax.
+// @evidence contracts/common.md#clear-and-simple-design The JSON record defines the separate producer boundary while keeping coverage judgments in the publishing linter.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Published kind discriminants are the wire vocabulary, not special cases for particular documents or expected evidence answers.
+// @evidence contracts/common.md#meaningful-documentation Native paragraphs distinguish artifact facts, JSON ownership and linter judgments; prose and tags follow the documentation skill.
+// @evidence contracts/portability.md#os-neutral-implementation File carries a producer-supplied native location for later path mapping, while Address and Aliases remain opaque protocol identities on every OS.
+// @evidenceExclude contracts/performance.md#efficient-algorithms This wire record selects no algorithm.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work Snapshot owners decide whether published records remain reusable.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The record owns no independent process, cache or acquisition lifecycle.
 type Artifact struct {
   Address  string   `json:"address"`
   Kind     string   `json:"kind"`
@@ -52,6 +61,15 @@ var artifactNodeKinds = map[string]NodeKind{
 // id built from the `path#name:kind` grammar, and a tour seed. A document
 // section is neither the shape of a declaration nor an answer to "what is this
 // project and how does it run".
+//
+// @evidence contracts/common.md#principled-implementation Membership in the published artifact-kind mapping distinguishes opaque document addresses from compiler declaration IDs.
+// @evidence contracts/common.md#clear-and-simple-design One vocabulary table supplies both artifact ingestion and downstream boundary checks.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The closed producer vocabulary excludes unknown kinds rather than fabricating declarations from address spelling.
+// @evidence contracts/common.md#meaningful-documentation Native prose explains why artifacts cannot use declaration identity or tour seeding, with documentation-skill tag spacing.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation This pure kind predicate does not access paths, files or processes.
+// @evidence contracts/performance.md#efficient-algorithms The scan is bounded by the fixed published kind vocabulary and needs no allocation.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work The predicate coordinates no request or retained computation.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources No resource or state is acquired.
 func IsArtifactKind(kind NodeKind) bool {
   for _, mapped := range artifactNodeKinds {
     if mapped == kind {
@@ -61,13 +79,25 @@ func IsArtifactKind(kind NodeKind) bool {
   return false
 }
 
-// LoadArtifacts reads the artifact set a plugin published, or nil when no path
-// was given.
+// LoadArtifacts reads a supplied artifact publication, or nil for an omitted or
+// whitespace-only path and for os.IsNotExist acquisition failures.
 //
 // A missing file is not an error: the caller names a path a plugin may or may
 // not have produced, and a project that publishes nothing is the common case. A
 // file that exists and does not parse is an error, because that is a producer
 // the caller was told to expect.
+// Native reading is not an atomic snapshot or producer authentication. Decoding
+// checks JSON/field types; accepted artifact kinds and addresses are separate
+// ApplyArtifacts admission decisions.
+//
+// @evidence contracts/common.md#principled-implementation A nonblank path is read verbatim and decoded; omitted/blank paths and os.IsNotExist mean no publication, while other acquisition and JSON decode errors propagate without certifying producer origin or artifact admission.
+// @evidence contracts/common.md#clear-and-simple-design Native acquisition delegates decoding to ParseArtifacts so callers needing byte identity can use the same parser.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Only the supported absent-publication case is optional; decoding failures are not hidden to satisfy an expected empty graph.
+// @evidence contracts/common.md#meaningful-documentation Native paragraphs distinguish omitted path, missing file and malformed publication, following the documentation skill.
+// @evidence contracts/portability.md#os-neutral-implementation os.ReadFile and os.IsNotExist preserve native path and failure semantics without shell interpolation or OS-specific separators.
+// @evidence contracts/performance.md#efficient-algorithms Path whitespace inspection precedes native whole-file acquisition and JSON decoding; work includes path bytes, native open/read effects, payload scanning and record/string/slice allocation rather than a single syscall or schema-bounded payload.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work This independent acquisition does not own snapshot identity or repeated-consumer reuse; callers that hash bytes use ParseArtifacts directly.
+// @evidence contracts/performance.md#bound-retention-and-release-resources Native ReadFile defers descriptor close under its own error semantics. File bytes and decoded records coexist without a payload cap; the bytes are temporary and returned records belong to the caller, with no retained watcher or cache.
 func LoadArtifacts(path string) ([]Artifact, error) {
   if strings.TrimSpace(path) == "" {
     return nil, nil
@@ -88,6 +118,18 @@ func LoadArtifacts(path string) ([]Artifact, error) {
 // parses. Reading the file twice — once to state what it holds and once to
 // decode it — lets an overwrite land between the two, leaving a session whose
 // recorded identity describes a set it is not holding.
+// The caller must keep these bytes stable while parsing and separately bind any
+// hash to the same captured input. Standard JSON decoding accepts null and
+// unknown fields and does not validate artifact kinds, address identity or origin.
+//
+// @evidence contracts/common.md#principled-implementation encoding/json decodes the supplied stable bytes; binding a captured hash to those same bytes and admitting artifact identity remain with the caller, not this parser.
+// @evidence contracts/common.md#clear-and-simple-design A byte-only parser isolates protocol decoding from native acquisition.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Decode errors propagate without accepting fixture-specific malformed records or reparsing changed disk bytes.
+// @evidence contracts/common.md#meaningful-documentation Native prose explains the same-byte identity requirement and why parsing is separate, with documentation-skill tag spacing.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation Parsing a JSON byte slice owns no native filesystem or process boundary.
+// @evidence contracts/performance.md#efficient-algorithms Decode work and allocated record space scale linearly with the JSON payload.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work Reuse of parsed publication is the caller's snapshot decision, not this one-shot parser's responsibility.
+// @evidence contracts/performance.md#bound-retention-and-release-resources Decoded strings, records and alias slices scale with supplied bytes without a parser-level payload cap; returned data belongs to the caller and this helper retains no independent buffer cache or native handle.
 func ParseArtifacts(data []byte) ([]Artifact, error) {
   var artifacts []Artifact
   if err := json.Unmarshal(data, &artifacts); err != nil {
@@ -109,12 +151,25 @@ func ParseArtifacts(data []byte) ([]Artifact, error) {
 //
 // An address that collides with an existing node loses: a checker-resolved
 // declaration is a fact of this Program, and a published artifact is not.
+// Equal published addresses retain caller order; the first accepted record
+// wins. Aliases cannot replace canonical nodes, and parents resolve only among
+// accepted artifacts, excluding self-parent links. This is not schema or cycle
+// validation of the supplied publication.
+//
+// @evidence contracts/common.md#principled-implementation Only accepted canonical records publish aliases and parent facts; compiler identities and canonical addresses win collisions before documentation references resolve.
+// @evidence contracts/common.md#clear-and-simple-design Ordered acceptance, alias registration, containment and citation projection keep each identity decision in a separate pass over the accepted publication.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Unknown producer kinds and colliding records are rejected consistently instead of compensating through aliases or mutating compiler declarations.
+// @evidence contracts/common.md#meaningful-documentation Native paragraphs state opaque IDs, collision precedence, containment ownership and edge deduplication, separated under the documentation skill.
+// @evidence contracts/portability.md#os-neutral-implementation Addresses remain opaque; supplied File strings pass unchanged to the dump's native path boundary without this function certifying their physical identity.
+// @evidence contracts/performance.md#efficient-algorithms Stable sorting includes address-text comparisons and record swaps; subsequent scans include all aliases, existing edges and tags, with string hashing/comparison and leading-token scans. Population-only constant-time lookup or O(A log A) does not describe the full byte and stable-swap costs.
+// @evidence contracts/performance.md#reuse-equivalent-work A shared canonical/alias map resolves every citation consistently and an edge-key set reuses existing relationship identity instead of appending equivalent edges.
+// @evidence contracts/performance.md#bound-retention-and-release-resources Sorting, acceptance and lookup scratch scale with the supplied population and have no size cap; accepted artifact strings, nodes and new relationships remain in the caller-owned graph generation until the caller releases it and other aliases.
 func ApplyArtifacts(g *Graph, artifacts []Artifact) {
   if g == nil || len(artifacts) == 0 {
     return
   }
-  // Sorted so the emitted node and edge order is a function of the addresses
-  // rather than of the order a plugin happened to walk its documents.
+  // Sort distinct addresses while retaining input order for duplicate addresses,
+  // whose first accepted record supplies the node and publication metadata.
   sorted := make([]Artifact, len(artifacts))
   copy(sorted, artifacts)
   sort.SliceStable(sorted, func(i, j int) bool { return sorted[i].Address < sorted[j].Address })
@@ -122,6 +177,7 @@ func ApplyArtifacts(g *Graph, artifacts []Artifact) {
   // Every address an artifact answers to, including its aliases, so a citation
   // written against either spelling resolves to the one node.
   byAddress := map[string]string{}
+  accepted := make([]Artifact, 0, len(sorted))
   for _, artifact := range sorted {
     kind, known := artifactNodeKinds[artifact.Kind]
     if !known || artifact.Address == "" {
@@ -142,22 +198,23 @@ func ApplyArtifacts(g *Graph, artifacts []Artifact) {
     }
     g.Nodes[artifact.Address] = node
     byAddress[artifact.Address] = artifact.Address
+    accepted = append(accepted, artifact)
   }
 
   // Aliases are registered after every address, and only where nothing claims
   // the spelling. An alias is an additional name for one artifact, never a
-  // rename of another: registering it in the same pass let one artifact's alias
+  // rename of another: registering it in the same pass would let one artifact's alias
   // overwrite an earlier artifact's own address, and a citation of that address
-  // then resolved to the wrong node — a confident wrong answer, which is worse
-  // than the token it replaced.
-  for _, artifact := range sorted {
-    if _, published := g.Nodes[artifact.Address]; !published {
-      continue
-    }
+  // would then resolve to the wrong node — a confident wrong answer, which is
+  // worse than the token it replaced.
+  for _, artifact := range accepted {
     for _, alias := range artifact.Aliases {
       if alias == "" || alias == artifact.Address {
         continue
       }
+      if _, claimed := g.Nodes[alias]; claimed {
+        continue
+      }
       if _, claimed := byAddress[alias]; claimed {
         continue
       }
@@ -171,7 +228,7 @@ func ApplyArtifacts(g *Graph, artifacts []Artifact) {
   // naming nothing published is cleared: the child is still a real artifact and
   // sits at the top of its chain, and fabricating the parent is what must not
   // happen.
-  for _, artifact := range sorted {
+  for _, artifact := range accepted {
     node, exists := g.Nodes[artifact.Address]
     if !exists || artifact.Parent == "" {
       continue

package/internal/graph/artifacts_index_what_a_plugin_published_test.go

@@ -8,13 +8,10 @@ import (
 )
 
 // TestArtifactsIndexWhatAPluginPublished verifies that a published artifact
-// becomes a node a citation resolves to, and that nothing else does.
-//
-// The reverse question already worked without this: a lookup on an address
-// answered with the declarations citing it, keyed on the token. What it could
-// not answer is what the address names — the heading's own text, what sits under
-// it — and that is what a node adds. The edge is the same `doc-ref` a resolved
-// `{@link}` already produced; the difference is that it now has an other end.
+// becomes a node a citation resolves to. Four accepted authored records add
+// nodes, while the unknown kind, unpublished cited address and unpublished
+// parent do not. It exercises the native graph builder and direct publication;
+// no plugin publisher or consumer query runs.
 //
 // Every negative here is a way the index could lie. A fabricated node for an
 // address nobody published would answer a question with an invention; a parent
@@ -25,8 +22,14 @@ import (
 //  2. Apply a published set covering three of them, one by an alias, one under
 //     a parent, plus an unpublishable entry.
 //  3. Assert the nodes, their containment, and the resolved edges — and that the
-//     uncited address, the unknown kind, and the dangling parent produced none.
+//     unpublished cited address, unknown kind, and dangling parent produced none.
+//
+// @evidence contracts/testing.md#behavioral-verification Direct ApplyArtifacts adds the four accepted literal addresses and resolves authored citations to canonical artifact nodes; the unknown kind and unpublished cited or parent addresses add no nodes.
+// @evidence contracts/testing.md#independent-expectations The expectations are literal over a fixture citing four addresses: applying five published records must add exactly four nodes (the unknown kind adds none), no node for the unpublished cited address or the unpublished parent prisma:Sale, the Pricing section must carry the readable text Pricing, line 7 and parent docs/sale.md, a parent naming no published node must be cleared, doc-ref edges must land on the pricing section (twice: its address and its alias) and the prisma column, and the shadowing alias must claim nothing.
+// @evidence contracts/testing.md#distinguishing-cases The fixture contrasts canonical and alias citations, a published and missing parent, an unknown kind and accepted kinds, an unpublished cited address, and an alias that attempts to shadow an existing canonical address.
+// @evidence contracts/testing.md#execution-ownership This graph Go source-unit writes its temporary project, constructs and closes a driver compiler Program in-process, then calls Build and ApplyArtifacts directly. A restored empty linked-plugin manifest excludes ambient hooks. It installs no consumer and builds or starts no native product command.
 func TestArtifactsIndexWhatAPluginPublished(t *testing.T) {
+  t.Setenv(driver.LinkedPluginsEnv, "")
   root := t.TempDir()
   writeFile(t, filepath.Join(root, "tsconfig.json"), `{
   "compilerOptions": { "target": "ES2022", "module": "commonjs", "strict": true },
@@ -97,6 +100,14 @@ export function unpublished(): void {}
   if got := len(g.Nodes) - before; got != 4 {
     t.Fatalf("added %d nodes, want 4; an unknown kind must contribute none", got)
   }
+  for _, address := range []string{"docs/sale.md", "docs/sale.md#pricing", "prisma:Sale.price", "docs/sale.md#shadow"} {
+    if g.Nodes[address] == nil {
+      t.Fatalf("accepted artifact %q has no node", address)
+    }
+  }
+  if _, fabricated := g.Nodes["docs/sale.md#unknown"]; fabricated {
+    t.Fatal("an unknown artifact kind became a node")
+  }
   if _, fabricated := g.Nodes["docs/sale.md#nobody-published-this"]; fabricated {
     t.Fatal("an address nobody published became a node; the tag text carries it and the linter judges it")
   }

package/internal/graph/artifacts_survive_a_partial_rebuild_test.go

@@ -8,22 +8,21 @@ import (
 )
 
 // TestArtifactsSurviveAPartialRebuild verifies that a citation of an artifact is
-// still a relation after the incremental path rebuilds the file that wrote it.
-//
-// A partial build re-resolves the outgoing facts of the files it selected, and a
-// citation is one of them. The full snapshot applied the published artifacts and
-// the incremental one did not, so editing a declaration that cites a document
-// section rebuilt it with that edge missing — the client's graph silently lost a
-// relation it had a moment earlier, and only a full reload brought it back.
-//
-// The nodes are re-added rather than assumed present because a partial starts
-// with only its selected files' nodes. They are the same nodes under the same
-// ids, which is why the store can replace like with like.
+// still a relation after a selected-file BuildFiles call followed by explicit
+// ApplyArtifacts. Both builds use the same unchanged compiler Program; this
+// tests the publication steps directly, not an edit, shard coordinator, or
+// client/store replacement.
 //
 //  1. Build the complete graph with artifacts applied, and confirm the edge.
-//  2. Rebuild only the citing file, as the shard path does.
+//  2. Rebuild only the selected citing file using the same unchanged Program.
 //  3. Assert the edge is there again, and that the artifact came with it.
+//
+// @evidence contracts/testing.md#behavioral-verification Full Build and selected-file BuildFiles, each followed by ApplyArtifacts, expose a doc-ref to the literal artifact address; the partial result contains that artifact node.
+// @evidence contracts/testing.md#independent-expectations The expectation is the same literal fixture built two ways: the doc-ref edge to docs/sale.md#pricing must exist after the complete build with artifacts applied, and again after BuildFiles over only the citing file followed by ApplyArtifacts, and the partial graph must hold the artifact node. The complete build is the baseline, so only the selected file path is taken from the code under test.
+// @evidence contracts/testing.md#distinguishing-cases Full versus selected-file construction contrasts while the authored Program and artifact remain unchanged. The literal edge is required in both, and node membership is separately required in the partial result; no source mutation or coordinator publication is exercised.
+// @evidence contracts/testing.md#execution-ownership This graph Go source-unit writes its temporary project, constructs and closes a driver compiler Program in-process, and directly calls Build, BuildFiles and ApplyArtifacts. A restored empty linked-plugin manifest excludes ambient hooks. It installs no consumer and builds or starts no native product command.
 func TestArtifactsSurviveAPartialRebuild(t *testing.T) {
+  t.Setenv(driver.LinkedPluginsEnv, "")
   root := t.TempDir()
   writeFile(t, filepath.Join(root, "tsconfig.json"), `{
   "compilerOptions": { "target": "ES2022", "module": "commonjs", "strict": true },

package/internal/graph/assigned_implementations_of_declaration_file_symbols_leave_no_edge_source_test.go

@@ -24,18 +24,10 @@ const ambientGlobalFixtureTSConfig = `{
 `
 
 // TestAssignedImplementationsOfDeclarationFileSymbolsLeaveNoEdgeSource verifies
-// that assigning a function to a symbol declared in a declaration file records
-// no edge leaving the external boundary leaf that symbol enters the graph as.
-//
-// An external leaf has no outgoing side: the graph never walks a dependency's
-// internals, and no shard may hold an edge whose source is one — an external
-// node is owned by the non-source external shard, which is forbidden to own
-// edges. Attributing the assigned body to it therefore did not merely misplace
-// facts (with evidence offsets from the implementation read against the
-// declaration file); it produced a snapshot `ttscgraph serve` could not
-// assemble, so every request against such a project failed. The calls the body
-// makes are not lost by refusing it: the module that runs the assignment owns
-// them.
+// that the graph's modeled external nodes own no outgoing edges after an arrow
+// is assigned to an ambient declaration-file symbol. The main module must still
+// own the authored call to helper. This does not require an external node for
+// the assignment target or execute shard assembly, a server, or client queries.
 //
 //  1. Compile a fixture whose `src/globals.d.ts` declares `var patched` in a
 //     global augmentation and whose `src/main.ts` assigns an arrow function to
@@ -43,7 +35,13 @@ const ambientGlobalFixtureTSConfig = `{
 //  2. Build the graph.
 //  3. Assert no edge leaves an external node, and that `main.ts`'s module node
 //     still owns the value-call edge to `helper`.
+//
+// @evidence contracts/testing.md#behavioral-verification After the authored ambient-symbol assignment, no edge whose source resolves to a modeled external node is present, and the main module has the literal helper value-call relation.
+// @evidence contracts/testing.md#independent-expectations The expectations follow from the ownership rule stated in the test and are checked over a literal fixture: no edge in the built graph may have an external node as its source, and the main.ts module node (moduleID of its path) must own a value-call edge to the helper node (nodeID of its path). The ids are built by the package's own id functions, so a change to id grammar would not be caught here.
+// @evidence contracts/testing.md#distinguishing-cases Compile a fixture whose `src/globals.d.ts` declares `var patched` in a global augmentation and whose `src/main.ts` assigns an arrow function to it that calls a local `helper`; Build the graph; Assert no edge leaves an external node, and that `main.ts`'s module node still owns the value-call edge to `helper`.
+// @evidence contracts/testing.md#execution-ownership This graph Go source-unit writes its native temporary project and constructs and closes a driver compiler Program in-process before Build. A restored empty linked-plugin manifest excludes ambient hooks. It installs no consumer and builds or starts no native product command.
 func TestAssignedImplementationsOfDeclarationFileSymbolsLeaveNoEdgeSource(t *testing.T) {
+  t.Setenv(driver.LinkedPluginsEnv, "")
   root := t.TempDir()
   writeFile(t, filepath.Join(root, "tsconfig.json"), ambientGlobalFixtureTSConfig)
   writeFile(t, filepath.Join(root, "src", "globals.d.ts"), `declare global {

package/internal/graph/assigned_implementations_of_node_modules_symbols_leave_no_edge_source_test.go

@@ -28,7 +28,7 @@ const nodeModulesGlobalFixtureTSConfig = `{
 //
 // `IsWorkspaceSourceFile` refuses a file for two disjoint reasons, and only one
 // of them is being a declaration file. A dependency that ships raw TypeScript
-// is not a declaration file and still owns no facts in this graph, so an
+// is not a declaration file and still owns no outgoing source facts, so an
 // assignment to something it declares must be refused by the same rule. Without
 // this case the fix is pinned on one branch of the classifier and a change to
 // the other would pass.
@@ -39,7 +39,13 @@ const nodeModulesGlobalFixtureTSConfig = `{
 //  2. Build the graph.
 //  3. Assert no edge leaves an external node, and that `main.ts`'s module node
 //     still owns the value-call edge to `helper`.
+//
+// @evidence contracts/testing.md#behavioral-verification driver.LoadProgram loads a project whose files list names node_modules/dep/globals.ts, a raw .ts declaring `var patched` in a global augmentation, and src/main.ts, which assigns an arrow function to patched that calls a local helper; Build then yields no edge whose source node is External and an EdgeValueCall edge from main.ts's module node to the helper node. Re-attributing the assigned body to the external symbol would add an edge from an external node and fail the first loop, and losing the call altogether would fail the final edge assertion.
+// @evidence contracts/testing.md#independent-expectations The expected ownership comes from the boundary stated by IsWorkspaceSourceFile and assignedFunctionTarget (an external node owns no outgoing edge, so the running module owns the assigned body's calls) applied to the literal fixture sources. The module and helper ids are built with the package's own moduleID and nodeID, so a change to the id grammar would not be caught by this test.
+// @evidence contracts/testing.md#distinguishing-cases The declaring file is a non-declaration .ts under node_modules, so only the path-segment branch of IsWorkspaceSourceFile refuses it; the declaration-file branch is covered by the sibling declaration-file test. The test pairs the absent external-source edge with the present module-owned edge so a graph with no edges at all cannot pass. It has one fixture and no case where the assignment target is a workspace symbol.
+// @evidence contracts/testing.md#execution-ownership This graph Go source-unit writes its fixture under t.TempDir, constructs and closes a driver compiler Program in-process, and calls Build. A restored empty linked-plugin manifest excludes ambient hooks; it installs no consumer and builds or starts no native product command.
 func TestAssignedImplementationsOfNodeModulesSymbolsLeaveNoEdgeSource(t *testing.T) {
+  t.Setenv(driver.LinkedPluginsEnv, "")
   root := t.TempDir()
   writeFile(t, filepath.Join(root, "tsconfig.json"), nodeModulesGlobalFixtureTSConfig)
   writeFile(t, filepath.Join(root, "node_modules", "dep", "package.json"), `{