ttsc 0.30.4 → 0.31.0

package/internal/graph/doc_refs_are_the_use_the_checker_already_counts_test.go

@@ -2,6 +2,7 @@ package graph
 
 import (
   "path/filepath"
+  "reflect"
   "strings"
   "testing"
 
@@ -28,21 +29,24 @@ const unusedLocalsFixtureTSConfig = `{
 // rests on: the compiler resolves a documentation link and counts it as a use,
 // and recording the edge does not change what it reports.
 //
-// The whole argument for the edge is that it is a compiler fact rather than a
-// text match, and the compiler says so itself — an import supporting only a link
-// survives `noUnusedLocals` while the same import without one does not. That
-// asymmetry is the evidence the issue was opened on, and it lived only in its
-// prose. Pinning it here matters twice: it fails if a TypeScript upgrade ever
-// stops counting links as uses, which would make the edge a text match dressed
-// as a checker fact, and it fails if this pass ever changes what the compiler
-// reports, which it must never do.
+// Two local interfaces differ in whether the function's documentation links to
+// them. The native compiler must report the unlinked declaration unused and not
+// the linked one. Build must expose the matching spanned edge and preserve the
+// before/after rendered diagnostic list. This is the maintained compiler's
+// report for one fixture, not an independent full compiler-semantics oracle.
 //
-//  1. Build one file importing two types, using one only through a link and the
+//  1. Build one file declaring two types, using one only through a link and the
 //     other not at all.
-//  2. Assert the compiler reports the unlinked import unused and the linked one
+//  2. Assert the compiler reports the unlinked declaration unused and the linked one
 //     not.
 //  3. Assert the link produced its edge in the same build.
+//
+// @evidence contracts/testing.md#behavioral-verification Verifies the premise this edge rests on: the compiler resolves a documentation link and counts it as a use, and recording the edge does not change what it reports.
+// @evidence contracts/testing.md#independent-expectations Authored IUnlinked must match an unused-declaration report while ILinked must not, and the literal subject-to-ILinked suffix pair must have exactly one doc-ref with a positive span. The compiler supplies the report; ID grammar and full language correctness are not independently certified. The before/after rendered report equality checks Build transparency, not the correctness of unrelated diagnostics.
+// @evidence contracts/testing.md#distinguishing-cases Linked versus unlinked local interfaces contrast within one source. The positive unused control prevents an empty diagnostic set from satisfying the linked absence check; the spanned edge and unchanged rendered report are separately required after Build.
+// @evidence contracts/testing.md#execution-ownership This graph Go source-unit writes its native temporary project, constructs and closes a driver compiler Program in-process, queries Diagnostics, and calls Build. A restored empty linked-plugin manifest excludes ambient hooks; no installed consumer or native product command is used.
 func TestDocRefsAreTheUseTheCheckerAlreadyCounts(t *testing.T) {
+  t.Setenv(driver.LinkedPluginsEnv, "")
   root := t.TempDir()
   writeFile(t, filepath.Join(root, "tsconfig.json"), unusedLocalsFixtureTSConfig)
   writeFile(t, filepath.Join(root, "src", "main.ts"), `interface ILinked {
@@ -64,8 +68,10 @@ export function subject(): void {}
   defer func() { _ = prog.Close() }()
 
   linked, unlinked := false, false
+  before := []string{}
   for _, diagnostic := range prog.Diagnostics() {
     message := diagnostic.String()
+    before = append(before, message)
     if !strings.Contains(message, "never used") &&
       !strings.Contains(message, "declared but") {
       continue
@@ -87,7 +93,13 @@ export function subject(): void {}
       "match rather than a checker fact")
   }
 
-  // The same build produced the edge, so the fact the compiler counted and the
-  // fact the graph records are one fact.
-  assertDocRef(t, Build(prog), "#subject:function", "#ILinked:interface")
+  graph := Build(prog)
+  assertDocRef(t, graph, "#subject:function", "#ILinked:interface")
+  after := []string{}
+  for _, diagnostic := range prog.Diagnostics() {
+    after = append(after, diagnostic.String())
+  }
+  if !reflect.DeepEqual(after, before) {
+    t.Fatalf("Build changed the rendered diagnostic report: before %v, after %v", before, after)
+  }
 }

package/internal/graph/doc_refs_resolve_documentation_links_test.go

@@ -9,14 +9,10 @@ import (
 )
 
 // TestDocRefsResolveDocumentationLinks verifies that an inline link in a
-// declaration's documentation becomes a checker-resolved edge, and that the tag
-// it sits under changes nothing.
-//
-// The checker already resolves such a name and counts it as a use — the
-// companion negative case is a project where `noUnusedLocals` keeps an import
-// that only a link supports — so this was the one class of resolved reference
-// the graph held no edge for, and the citation-only `import type` a citation
-// convention recommends is exactly the form nothing else in the module records.
+// declaration's documentation becomes a checker-resolved edge across the
+// authored tag/prose forms. Its literal
+// suffix expectations distinguish the imported ISale from two resident rivals;
+// it does not independently certify the checker's full language semantics.
 //
 //  1. Build a fixture linking one type from a tag, one from ordinary prose, one
 //     through `{@linkcode}`, one qualified, and one that resolves to nothing.
@@ -28,14 +24,21 @@ import (
 //     import all three, and assert every link resolves to the one this module
 //     imports the name from — the claim the rest of the file now rests on,
 //     since three declarations of `ISale` exist here.
+//
+// @evidence contracts/testing.md#behavioral-verification Build records the asserted spanned doc-ref pairs for the authored tag, prose, linkcode/linkplain, qualified and supported host forms. Negative helper checks reject the specified unresolved, self, line-comment, unlinked and namespace/member-misattribution relations; the selected Promise endpoint must be external.
+// @evidence contracts/testing.md#independent-expectations The expectations are literal over a fixture in which three modules declare ISale: each resolvable link (from a tag, prose, linkcode, linkplain, see, qualified name, namespace member, closure, class, interface and class member) must produce exactly one doc-ref edge with a span to the declaration the importing module resolves; an unresolved link, a self link, a line-comment link, a namespace's own documentation and known param/returns tags must produce none; and the library type Promise must resolve to an external leaf. A text matcher that picked a rival ISale fails the ambiguousName checks.
+// @evidence contracts/testing.md#distinguishing-cases Resolvable links under a tag and in prose, in linkcode, qualified and member forms, and in a flanked three-way same-name case, contrast an unresolvable link, a self-link, a line-comment link, a namespace host with no node and an untagged declaration, each asserted by the doc-ref helpers over the one built graph.
+// @evidence contracts/testing.md#execution-ownership This graph Go source-unit writes its native project, constructs and closes a driver compiler Program in-process, and calls Build. A restored empty linked-plugin manifest excludes ambient hooks; no consumer installation or native product command runs. Literal ID suffixes distinguish the expected declaration rather than deriving that target from Build.
 func TestDocRefsResolveDocumentationLinks(t *testing.T) {
+  t.Setenv(driver.LinkedPluginsEnv, "")
   root := t.TempDir()
   writeFile(t, filepath.Join(root, "tsconfig.json"), fixtureTSConfig)
   // Two rivals, one sorting before `sale` and one after, each imported so the
   // program holds it. One rival is not enough: a text matcher has to break the
   // tie somehow, and whichever end it picks — lowest id, highest id, first or
-  // last in program order — a single rival leaves half of those choices landing
-  // on the right answer by luck. Flanking the real module closes every one.
+  // last in program order — a single rival leaves some ordering choices landing
+  // on the right answer by luck. The two authored rivals constrain those choices,
+  // not every possible text-matching algorithm.
   writeFile(t, filepath.Join(root, "src", "archive.ts"), `export interface ISale {
   archived: boolean;
 }
@@ -167,7 +170,8 @@ export namespace Documented2 {
   assertDocRef(t, g, "#fromCode:function", "sale.ts#ISale:interface")
   assertDocRef(t, g, "#fromPlain:function", "sale.ts#ISale:interface")
   // Distinct targets each get an edge; a target named twice collapses under the
-  // uniqueness rule every edge kind shares, keeping the first span.
+  // uniqueness expectation for this pair. The helper requires a positive span,
+  // not the exact first occurrence's offsets.
   assertDocRef(t, g, "#severalLinks:function", "sale.ts#ISale:interface")
   assertDocRef(t, g, "#severalLinks:function", "#Shopping.ICoupon:interface")
   assertDocRef(t, g, "#fromQualified:function", "#Shopping.ICoupon:interface")
@@ -176,8 +180,8 @@ export namespace Documented2 {
   // instead, so this case and the one below are one fix and one regression.
   assertDocRef(t, g, "#fromSee:function", "sale.ts#ISale:interface")
 
-  // A name the checker cannot resolve is not a relation, and must not
-  // fabricate a node to point at.
+  // A name the checker cannot resolve contributes no outgoing doc-ref here.
+  // This helper does not separately assert the absence of an unused ghost node.
   assertNoDocRef(t, g, "#fromUnresolved:function")
   // A declaration naming itself is not an edge, the same rule typeRefEdge keeps.
   assertNoDocRef(t, g, "#selfLinked:function")
@@ -209,12 +213,12 @@ export namespace Documented2 {
 
   // A member's link belongs to the member. The same walk hands a property's
   // subtree to its class as well, which is right for dependency edges and wrong
-  // here: the class's own documentation names nothing.
+  // here: the class's own documentation names ISale, not Shopping.ICoupon.
   assertDocRef(t, g, "#Documented.coupon:variable", "#Shopping.ICoupon:interface")
   assertNoDocRefTo(t, g, "#Documented:class", "#Shopping.ICoupon:interface")
   assertDocRef(t, g, "#Documented.run:method", "sale.ts#ISale:interface")
 
-  // Two modules declare `ISale`, and only the checker knows which one a link
+  // Three modules declare `ISale`, and checker resolution selects which one a link
   // means: it resolves the name through this module's imports. A text match on
   // the written token could not tell them apart, and would have to guess.
   assertNodeExists(t, g, "archive.ts#ISale:interface")

package/internal/graph/doc_tags.go

@@ -8,7 +8,7 @@ import (
 )
 
 // DocTag is one documentation tag TypeScript itself does not recognize, written
-// on a workspace declaration and captured verbatim.
+// on a workspace declaration, with comment text rendered into one line.
 //
 // A convention attaches a declaration to something outside the type system — a
 // specification section, an API operation, a reference document — and writes
@@ -21,28 +21,41 @@ import (
 // tags the parser had no meaning for, so it kept them as
 // KindJSDocUnknownTag. A known tag — `@param`, `@returns`, `@deprecated` — has
 // its own AST shape and its own meaning and is not this. Naming particular tags
-// here would make the compiler host know one convention, and would have left
-// out the 767 `@reference` tags this repository's own sources carry.
+// here would make the compiler host know one convention and leave out every
+// other convention's tags.
 //
 // Nothing is interpreted. Target is not split out of Text, because which part
 // of a tag's text names a thing is a convention's rule and this pass enforces
 // none; a consumer that ranks on a leading token does so in the layer that
 // declares its selection heuristic. This is the contract Decorator already
 // keeps for `@Controller`/`@Get`.
+//
+// @evidence contracts/common.md#principled-implementation Unknown-tag AST nodes preserve their written name and text while target identity associates the fact with its declaration.
+// @evidence contracts/common.md#clear-and-simple-design Source coordinates support collection deduplication without adding convention judgments to the record.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts The collector admits usable compiler-classified unknown tags without a handpicked convention allowlist; recognized tag kinds remain outside this population.
+// @evidence contracts/common.md#meaningful-documentation Native paragraphs explain unknown versus recognized tags, uninterpreted text and collection-only positions, using the documentation skill's separated members and tags.
+// @evidenceExclude contracts/performance.md#efficient-algorithms This record represents tag facts; traversal and deduplication belong to collection operations.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work The enclosing graph build owns shared AST reads.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The record does not own retention or native resources.
+// @evidence contracts/portability.md#os-neutral-implementation The path-bearing Target uses graph node-ID encoding and later shared dump projection; this record does not resolve native aliases or certify physical identity.
 type DocTag struct {
   // Target is the id of the graph node the tag was written on.
   Target string
+
   // Name is the tag name without its `@` (`evidence`, `evidenceExclude`,
   // `reference`).
   Name string
+
   // Text is everything after the tag name, with the comment's leading asterisks
   // and per-line indentation removed and its lines joined by single spaces.
   // Empty when the tag carries no text.
   Text string
+
   // Pos and End bound the written tag. They are not published — a tag rides its
   // target node, which carries the span a reader cites — and exist so one
   // declaration presented to the node pass twice contributes its tags once.
   Pos int
+
   End int
 }
 
@@ -105,7 +118,7 @@ func collectDocTags(g *Graph, targetID string, declaration *shimast.Node) {
 // the parser attached the documentation to are different. TypeScript attaches
 // one leading block to the variable *statement*, while the graph records a node
 // per binding, so asking the binding directly finds nothing and every citation
-// written on a `const` was lost. The statement is reached through its
+// written on a `const` would be lost. The statement is reached through its
 // declaration list, and both hops are checked rather than assumed.
 //
 // One statement can declare several bindings (`export const a = 1, b = 2`), and
@@ -248,8 +261,7 @@ func joinDocTagLines(text string) string {
 //
 // The checker resolves such a name and counts it as a use — a `noUnusedLocals`
 // project keeps an import that exists only to support a link — so this is a
-// compiler fact, not a text match, and it was the one class of resolved
-// reference the graph held no edge for. The link node carries an EntityName,
+// compiler fact, not a text match. The link node carries an EntityName,
 // which is the node class typeRefEdge already resolves, so the resolution and
 // the external-boundary and self-reference rules are the existing ones.
 //
@@ -270,15 +282,14 @@ func (g *Graph) collectDocRefs(checker *shimchecker.Checker, file *shimast.Sourc
 // attributed documentation to.
 //
 // The two passes cannot share a walk — one runs before the checker exists and
-// the other needs it — so they would otherwise share only a convention, and a
-// convention is what drifted. The container walk the edge pass would naturally
-// reuse never visits a class, an interface, or a namespace as a node of its
-// own: it descends straight into their members. So a link written on a class's
-// own documentation resolved to nothing while the tag beside it was indexed,
-// and the two halves a reader is meant to compose disagreed exactly where a
-// type is documented. Recording the host here means the edge pass covers every
-// declaration form the node pass records, including forms nobody has written
-// yet.
+// the other needs it — so they would otherwise share only a convention. The
+// container walk the edge pass would naturally reuse never visits a class, an
+// interface, or a namespace as a node of its own: it descends straight into
+// their members. A link written on a class's own documentation would then
+// resolve to nothing while the tag beside it was indexed, and the two halves a
+// reader is meant to compose would disagree exactly where a type is documented.
+// Recording the host here means the edge pass covers every declaration form the
+// node pass records.
 //
 // It also fixes the attribution: the container walk hands a property member's
 // subtree to the property *and* to its class, which is deliberate for the
@@ -327,13 +338,11 @@ type docHost struct {
 // tag a consumer invents, which is the rule this edge is defined by.
 //
 // The JSDoc node itself reports no children, so its prose comment is walked
-// explicitly beside the tags; that is the same reason the existing edge passes
-// never reached a link.
+// explicitly beside the tags.
 func (g *Graph) docRefsWithin(checker *shimchecker.Checker, from string, doc *shimast.Node) {
   // Guarded on the kind before the conversion, the way the tag walk is. A
   // documentation block is what this is handed and an AsJSDoc on anything else
-  // panics rather than returning nil — which is exactly how reading a tag's
-  // comment through its own struct crashed on the first `@param`.
+  // panics rather than returning nil.
   if doc == nil || doc.Kind != shimast.KindJSDoc {
     return
   }

package/internal/graph/doc_tags_are_claimed_before_they_are_read_test.go

@@ -11,15 +11,26 @@ import (
 )
 
 // TestDocTagsAreClaimedBeforeTheyAreRead verifies that the projection carries a
-// tag onto the wire and that a project with no tag is unchanged beside it.
+// tag onto the wire and that the selected node/edge projection matches the
+// otherwise identical untagged fixture after removing its tag facts.
 //
 // The capability the shipped commands declare is asserted where it is made, in
 // `cmd/ttscgraph`: a test that hands a capability list to the marshaller and
 // reads it back proves only that the slice was copied, and would leave the
 // production list free to lose the member with nothing failing. What this one
-// owns is the other half — that a tag reaches the document, and that a project
-// using no convention pays nothing for the feature.
+// owns is tag delivery and equality of its parsed probe fields. It measures no
+// runtime cost and does not compare source hashes or every wire field.
+//
+// 1. Load identical tagged and untagged declarations with the literal docs/a.md#x citation.
+// 2. Build and serialize both graphs with their declared doc-tag capability.
+// 3. Require one Cited doc tag, none on the untagged declaration, and equal parsed probe fields after removing doc tags.
+//
+// @evidence contracts/testing.md#behavioral-verification Build and MarshalDump deliver one literal doc tag for the tagged declaration and none for its untagged counterpart. After tag removal their parsed probe fields are equal; omitted wire fields and runtime costs are not compared. The docTags capability is supplied by the fixture and not independently asserted here; the command capability case owns that assertion.
+// @evidence contracts/testing.md#independent-expectations The authored annotation requires exactly docs/a.md#x Cited. The comparison retains only capabilities, the declared node ID/kind/name/signature/evidence fields, and edge endpoint/kind/evidence fields. Expected equality of those probe fields does not certify the full wire document or independently validate every graph fact.
+// @evidence contracts/testing.md#distinguishing-cases A tagged declaration and otherwise identical untagged declaration contrast one retained citation, no untagged citation and equality of the retained probe fields after omitting doc tags.
+// @evidence contracts/testing.md#execution-ownership This graph Go source-unit writes two native temporary projects, constructs and closes their driver compiler Programs in-process, and directly calls Build and MarshalDump. A restored empty linked-plugin manifest excludes ambient hooks; no consumer installation or product host command runs.
 func TestDocTagsAreClaimedBeforeTheyAreRead(t *testing.T) {
+  t.Setenv(driver.LinkedPluginsEnv, "")
   tagged := dumpDocTagFixture(t, `/** @evidence docs/a.md#x Cited. */
 export function subject(): void {}
 `)
@@ -34,9 +45,8 @@ export function subject(): void {}
     t.Fatalf("untagged dump carried %v", got)
   }
 
-  // The rest of the untagged document is what it was: the feature costs a
-  // project using no convention exactly nothing. Compared structurally rather
-  // than by count, because equal counts survive a changed id, name, or span.
+  // Compare the retained probe fields rather than counts. Fields omitted by
+  // dumpDocTagProbe, including source hashes, are outside this comparison.
   if !reflect.DeepEqual(strippedDocTags(tagged), untagged) {
     t.Fatalf("the two documents differ beyond the tag: tagged %+v, untagged %+v",
       strippedDocTags(tagged), untagged)

package/internal/graph/doc_tags_capture_every_unrecognized_tag_test.go

@@ -8,8 +8,9 @@ import (
 )
 
 // TestDocTagsCaptureEveryUnrecognizedTag verifies that the build pass records a
-// DocTag for each documentation tag TypeScript does not recognize, on every
-// declaration form, and records nothing for the tags it does.
+// ten authored unknown-tag/host pairs, including a bare tag and multiline text.
+// It rejects the fixture's param and returns tags and any tag on the untagged
+// function; it does not enumerate every parser-known tag or declaration form.
 //
 // The population boundary is the whole design: naming particular tags would make
 // the compiler host know one convention, so the pass collects exactly what the
@@ -24,7 +25,13 @@ import (
 //  2. Assert every unrecognized tag is recorded on its own declaration's node.
 //  3. Assert no known tag is recorded, and that an untagged declaration
 //     contributes nothing.
+//
+// @evidence contracts/testing.md#behavioral-verification Build returns exactly one matching fact for each of the ten authored tag/target pairs with its literal text, including multiline joining and the empty bare text. No param or returns fact is present, and the untagged function carries none.
+// @evidence contracts/testing.md#independent-expectations The expectations are literal: each unrecognized tag (evidence, evidenceExclude, reference, spec and a bare tag) must be recorded exactly once on its own declaration's node with its written text (a multi-line reason joined into one line, empty for the bare tag), param and returns must never be recorded, and the untagged declaration must carry none.
+// @evidence contracts/testing.md#distinguishing-cases Build a fixture whose declarations carry convention tags, known tags, a tag with no text, and a multi-line reason, across a function, a class, a class member, an interface member, a variable, a namespace member, and a closure; Assert every unrecognized tag is recorded on its own declaration's node; Assert no known tag is recorded, and that an untagged declaration contributes nothing.
+// @evidence contracts/testing.md#execution-ownership This graph Go source-unit writes its native temporary project, constructs and closes a driver compiler Program in-process, and calls Build directly. A restored empty linked-plugin manifest excludes ambient hooks; no installed consumer or native product command runs. Literal target-ID suffixes distinguish attribution without computing expectations from Build.
 func TestDocTagsCaptureEveryUnrecognizedTag(t *testing.T) {
+  t.Setenv(driver.LinkedPluginsEnv, "")
   root := t.TempDir()
   writeFile(t, filepath.Join(root, "tsconfig.json"), fixtureTSConfig)
   writeFile(t, filepath.Join(root, "src", "main.ts"), `/**

package/internal/graph/doc_tags_read_only_what_the_parser_attached_test.go

@@ -10,12 +10,10 @@ import (
 // TestDocTagsReadOnlyWhatTheParserAttached verifies the boundary cases that
 // decide whether a tag-shaped run of text is a fact about a declaration.
 //
-// Every case here is one a text scan would get wrong, and a wrong answer is
-// silent in both directions: a tag adopted from a line comment or from prose
-// attributes a citation to code that never made it, while a tag lost from a
-// merged declaration reports the declaration as citing nothing. The parser
-// already decides which block belongs to which declaration, so this pins that
-// the collection follows it rather than re-deciding.
+// The authored cases distinguish line-comment exclusion, a mid-sentence parsed
+// tag, overload-signature attachment and two reconstructed inline-link forms.
+// They do not enumerate every text-scanning algorithm, parser placement rule,
+// overload form or link spelling.
 //
 //  1. Build a fixture with a tag in a line comment, a tag written mid-sentence
 //     inside a documentation block, an overload run documented on its
@@ -24,7 +22,13 @@ import (
 //     the tag the parser says it is.
 //  3. Assert the overload keeps its signature's tag and the link keeps its
 //     braces.
+//
+// @evidence contracts/testing.md#behavioral-verification Verifies the boundary cases that decide whether a tag-shaped run of text is a fact about a declaration.
+// @evidence contracts/testing.md#independent-expectations The expectations are literal: a tag in a // comment must produce no tag, a tag written mid-sentence in a documentation block must be recorded with the text after the @evidence word (as TypeScript's parser opens it), an overload run's tag written on its first signature must be kept on the merged node, and a {@link ISale} or {@linkcode ISale} tag text must keep its braces and link keyword verbatim.
+// @evidence contracts/testing.md#distinguishing-cases Build a fixture with a tag in a line comment, a tag written mid-sentence inside a documentation block, an overload run documented on its signature, and a link tag whose braced form must survive verbatim; Assert the line comment contributes nothing and the mid-sentence one is the tag the parser says it is; Assert the overload keeps its signature's tag and the link keeps its braces.
+// @evidence contracts/testing.md#execution-ownership This graph Go source-unit writes its native temporary project, constructs and closes a driver compiler Program in-process, and calls Build. A restored empty linked-plugin manifest excludes ambient hooks; no installed consumer or native product command runs. Literal expected tag texts and target suffixes are authored independently of the collected facts.
 func TestDocTagsReadOnlyWhatTheParserAttached(t *testing.T) {
+  t.Setenv(driver.LinkedPluginsEnv, "")
   root := t.TempDir()
   writeFile(t, filepath.Join(root, "tsconfig.json"), fixtureTSConfig)
   writeFile(t, filepath.Join(root, "src", "main.ts"), `export interface ISale {
@@ -72,8 +76,8 @@ export function linkedCode(): void {}
     }
   }
 
-  // A tag written mid-sentence is still a tag, because TypeScript's own parser
-  // opens one at the `@` wherever it sits. This is deliberately not second-
+  // The authored mid-sentence @evidence is expected as a parser-attached tag.
+  // This fixture does not certify every @ placement. It is not second-
   // guessed: the population is "what the parser could not interpret", and a
   // graph that re-decided where a tag may begin would be reinterpreting the
   // compiler rather than reporting it. A convention that wants the stricter

package/internal/graph/doc_tags_stop_at_the_external_boundary_test.go

@@ -9,7 +9,8 @@ import (
 )
 
 // TestDocTagsStopAtTheExternalBoundary verifies that a documentation tag written
-// in a dependency contributes nothing.
+// in the explicitly loaded node_modules fixture contributes no collected tag,
+// while the workspace citation remains present.
 //
 // The graph's boundary is the workspace: a dependency's declaration enters only
 // as a named endpoint, never walked into. A tag read from one would put a
@@ -24,7 +25,13 @@ import (
 //     workspace source carries another.
 //  2. Assert the workspace tag is recorded.
 //  3. Assert no tag is recorded from the dependency, under any target.
+//
+// @evidence contracts/testing.md#behavioral-verification The explicitly loaded raw dependency source is resident, but Build returns the literal workspace citation and no collected tag whose target names node_modules or whose text names docs/vendor.md.
+// @evidence contracts/testing.md#independent-expectations The expectations are literal over a workspace source with one tag and a node_modules dependency with another: the workspace tag must be recorded on its declaration, and no recorded tag may have a target containing node_modules or text naming docs/vendor.md.
+// @evidence contracts/testing.md#distinguishing-cases Build a fixture whose `node_modules` dependency carries a tag and whose workspace source carries another; Assert the workspace tag is recorded; Assert no tag is recorded from the dependency, under any target.
+// @evidence contracts/testing.md#execution-ownership This graph Go source-unit writes its native workspace/dependency fixture, constructs and closes a driver compiler Program in-process, and calls Build. A restored empty linked-plugin manifest excludes ambient hooks; no installed consumer or native product command runs. The dependency is an explicit compiler input, not an installed package lookup.
 func TestDocTagsStopAtTheExternalBoundary(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", "globals.ts"), `/** @evidence docs/vendor.md#theirs Written by the dependency. */
@@ -43,6 +50,9 @@ export function ours(): void {}
   }
   defer func() { _ = prog.Close() }()
 
+  // Exclusion must not pass merely because the dependency was never loaded.
+  sourceFile(t, prog, "node_modules/dep/globals.ts")
+
   tags := docTagsByTargetSuffix(Build(prog))
 
   assertDocTag(t, tags, "#ours:function", "evidence", "docs/ours.md#mine Written here.")

package/internal/graph/doc_tags_survive_line_endings_and_repeated_blocks_test.go

@@ -11,11 +11,11 @@ import (
 // TestDocTagsSurviveLineEndingsAndRepeatedBlocks verifies the boundary cases
 // where one declaration's tags can be silently lost or doubled.
 //
-// Each is invisible when wrong. A CRLF checkout that joined a reason
+// A CRLF checkout that joined a reason
 // differently would make the same source produce different index entries on
 // Windows and POSIX, so a citation found on one machine would be missing on the
 // other. A merged identity declared twice keeps whichever declarations the walk
-// reached, and a `var` redeclaration is the one shape where the same identity
+// reached; the authored `var` redeclaration is one shape where the same identity
 // carries two documentation blocks that both have to survive. A link written
 // with trailing text inside its braces is reassembled from two fields, so the
 // text can be dropped without the target changing.
@@ -26,7 +26,13 @@ import (
 //  2. Assert the CRLF reason joins exactly as its LF twin does.
 //  3. Assert both blocks of the merged identity are kept, every binding of the
 //     statement carries its documentation, and the link keeps its text.
+//
+// @evidence contracts/testing.md#behavioral-verification Verifies the boundary cases where one declaration's tags can be silently lost or doubled.
+// @evidence contracts/testing.md#independent-expectations The expectations are literal and are asserted for the same source compiled with LF and with CRLF line terminators: a reason spread over two comment lines must be the single string docs/a.md#reason States the limit this section defines., a link tag keeps its trailing text, a var redeclared and documented twice keeps both tags, a multi-binding statement documents each binding, and a declaration with two documentation blocks keeps both tags.
+// @evidence contracts/testing.md#distinguishing-cases Build a fixture with CRLF sources, a redeclared `var` documented twice, a multi-binding statement, a declaration carrying two documentation blocks, and a link carrying trailing text; Assert the CRLF reason joins exactly as its LF twin does; Assert both blocks of the merged identity are kept, every binding of the statement carries its documentation, and the link keeps its text.
+// @evidence contracts/testing.md#execution-ownership This graph Go source-unit writes two separate native LF/CRLF projects, constructs and closes their driver compiler Programs in-process, and calls Build. A restored empty linked-plugin manifest excludes ambient hooks; no installed consumer or native product command runs. Each expected name/text/target-suffix pair must occur exactly once in each graph; full offset equivalence and other terminators are not certified.
 func TestDocTagsSurviveLineEndingsAndRepeatedBlocks(t *testing.T) {
+  t.Setenv(driver.LinkedPluginsEnv, "")
   root := t.TempDir()
   writeFile(t, filepath.Join(root, "tsconfig.json"), fixtureTSConfig)
 
@@ -119,22 +125,26 @@ export function twoBlocks(): void {}
   }
 }
 
-// assertDocTagIn fails unless a tag with this name and text sits on the node
+// assertDocTagIn fails unless exactly one tag with this name and text sits on the node
 // whose id ends with suffix, naming the source spelling in the failure.
 func assertDocTagIn(t *testing.T, tags map[string][]*DocTag, spelling, suffix, name, text string) {
   t.Helper()
+  found := 0
+  reported := []string{}
   for target, list := range tags {
     if !suffixMatch(target, suffix) {
       continue
     }
+    reported = append(reported, renderDocTags(list))
     for _, tag := range list {
       if tag.Name == name && tag.Text == text {
-        return
+        found++
       }
     }
-    t.Fatalf("%s %s carries %s, want @%s %q", spelling, suffix, renderDocTags(list), name, text)
   }
-  t.Fatalf("%s %s recorded no tags at all, want @%s %q", spelling, suffix, name, text)
+  if found != 1 {
+    t.Fatalf("%s %s recorded %d matching tags, want one @%s %q; tags: %s", spelling, suffix, found, name, text, strings.Join(reported, " | "))
+  }
 }
 
 func renderDocTags(list []*DocTag) string {