@ttsc/lint 0.30.3 → 0.31.0

package/linthost/check_observations_retains_failed_program_and_raw_inputs_test.go

@@ -0,0 +1,266 @@
+package linthost
+
+import (
+  "bytes"
+  "crypto/sha256"
+  "encoding/hex"
+  "encoding/json"
+  "io/fs"
+  "os"
+  "path/filepath"
+  "reflect"
+  "testing"
+
+  publicrule "github.com/samchon/ttsc/packages/lint/rule"
+)
+
+// observedProjectInputRule exercises the optional actual reader contract in the
+// same Program cycle; it has no separate fixture/process or filesystem hook.
+type observedProjectInputRule struct{ location string }
+
+// Name supplies the independently authored registry identity used by the unit.
+func (r observedProjectInputRule) Name() string { return "test/observed-project-input" }
+
+// NeedsTypeChecker keeps this raw-reader contributor independent of checker use.
+func (r observedProjectInputRule) NeedsTypeChecker() bool { return false }
+
+// UsesProjectInputReader declares responsibility; the unit separately checks
+// actual returned bytes and authority, so this marker cannot prove consumption.
+func (r observedProjectInputRule) UsesProjectInputReader() bool { return true }
+
+// Check exposes the actual read bytes/error through supported cycle state,
+// letting the owning unit compare them with its separately authored BOM bytes.
+func (r observedProjectInputRule) Check(ctx *publicrule.ProjectContext) {
+  body, err := ctx.Inputs.ReadFile(r.location)
+  ctx.SetState(struct {
+    Body []byte
+    Err  error
+  }{body, err})
+}
+
+// TestCheckObservationsRetainsFailedProgramAndRawInputs exercises the actual
+// standalone check entry, same-Program publisher and generation reader. It
+// creates no installed consumer or native child. Typed configuration encoding
+// and missing/unsupported input authority remain independent of diagnostics.
+//
+// @evidence contracts/testing.md#behavioral-verification RunCheckWithIO selects the explicitly configured JSON through the authored lint plugin manifest and returns status2 and TS2322 while its private result retains the loaded source graph and actual JSON config fingerprint. Direct reader calls preserve BOM bytes, compiler decoding remains distinct, WalkDir sorts and skips, raw ReadDir membership is separately encoded from actual compiler AccessibleEntries and both survive the same-generation graph, failed listings withdraw authority, nil generations publish false, unsupported input contributors withdraw authority, and an updated Program cannot inherit the prior graph.
+// @evidence contracts/testing.md#independent-expectations The authored number/string assignment must report TS2322, the authored import must map index.ts to the actual dependency.ts source, raw BOM bytes and SHA256 are independently authored, nil authority must be false, and literal WalkDir visit names prescribe traversal. The independently encoded a/file and skip/directory records require the exact native directory digest; a raw query must not create an AccessibleEntries predicate, and a later real compiler query must retain its own lists. The JSON file fingerprint must retain version1, file kind, watch scope and stable identity.
+// @evidence contracts/testing.md#distinguishing-cases Failed check with valid Program differs from nil Program; supported actual-read contributor retains raw bytes/authority while topology-only unsupported contributor withdraws it; raw and decoded BOM hashes differ; relative native reads retain absolute wire coordinates; skipped children are absent; raw and compiler directory queries remain distinct, while a failed native listing remains incomplete; the file fingerprint retains its raw-byte encoding; update invalidates the old generation.
+// @evidence contracts/testing.md#execution-ownership This Go unit invokes the owning standalone host APIs in-process with temporary files, buffers and one loaded Program. It restores the prior contributor registration and closes the Program, with no CLI process, extra compiler generation for proof or E2E fixture loop.
+func TestCheckObservationsRetainsFailedProgramAndRawInputs(t *testing.T) {
+  root := t.TempDir()
+  write := func(name string, body []byte) {
+    t.Helper()
+    if err := os.WriteFile(filepath.Join(root, name), body, 0o644); err != nil {
+      t.Fatal(err)
+    }
+  }
+  source := []byte(`import { dependency } from "./dependency"; const value: number = "wrong"; export { value, dependency };`)
+  write("index.ts", source)
+  write("dependency.ts", []byte(`export const dependency = 1;`))
+  write("tsconfig.json", []byte(`{"compilerOptions":{"strict":true,"noEmit":true},"files":["index.ts"]}`))
+  config := append([]byte{0xef, 0xbb, 0xbf}, []byte(`{"rules":{}}`)...)
+  write("lint.config.json", config)
+  output := filepath.Join(root, "check.json")
+  var stdout, stderr bytes.Buffer
+  status := RunCheckWithIO([]string{"--cwd=" + root, "--tsconfig=tsconfig.json", "--plugins-json=" + lintManifestWithConfig(t, map[string]any{"configFile": "./lint.config.json"}), "--check-observations-json=" + output}, &stdout, &stderr)
+  if status != 2 || !bytes.Contains(stderr.Bytes(), []byte("TS2322")) {
+    t.Fatalf("failed standalone check: status=%d stderr=%s", status, &stderr)
+  }
+  var envelope struct {
+    Graph                *lintCheckGraph    `json:"graph"`
+    HostInputs           []string           `json:"hostInputs"`
+    HostInputHashes      map[string]*string `json:"hostInputHashes"`
+    ObservationsComplete *bool              `json:"observationsComplete"`
+  }
+  read := func(name string) {
+    t.Helper()
+    body, err := os.ReadFile(name)
+    if err != nil {
+      t.Fatal(err)
+    }
+    envelope.Graph = nil
+    envelope.ObservationsComplete = nil
+    envelope.HostInputs = nil
+    envelope.HostInputHashes = nil
+    if err := json.Unmarshal(body, &envelope); err != nil {
+      t.Fatal(err)
+    }
+  }
+  read(output)
+  if envelope.Graph == nil || envelope.ObservationsComplete != nil {
+    t.Fatalf("failed check lost its complete Program proof: %#v", envelope)
+  }
+  if _, ok := envelope.Graph.Edges["index.ts"]; !ok {
+    t.Fatal("the failed source is missing from its own graph")
+  }
+  if !reflect.DeepEqual(envelope.Graph.Edges["index.ts"], []string{"dependency.ts"}) {
+    t.Fatalf("same-Program realized reference edge: %v", envelope.Graph.Edges["index.ts"])
+  }
+  cfg := envelope.Graph.InputObservations["lint.config.json"].NativePredicates
+  sum := sha256.Sum256(config)
+  if len(cfg) != 1 || cfg[0].Kind != "file" || cfg[0].Version != 1 || cfg[0].Digest != hex.EncodeToString(sum[:]) || cfg[0].Scope != "watch" || !cfg[0].IdentityStable {
+    t.Fatalf("consumed JSON config proof: %#v", cfg)
+  }
+
+  var missing *program
+  nilOutput := filepath.Join(root, "nil.json")
+  if err := missing.writeCheckObservations(nilOutput); err != nil {
+    t.Fatal(err)
+  }
+  read(nilOutput)
+  if envelope.Graph != nil || envelope.ObservationsComplete == nil || *envelope.ObservationsComplete {
+    t.Fatal("nil Program gained observation authority")
+  }
+
+  prog, diags, err := loadProgram(root, "tsconfig.json", loadProgramOptions{observeInputs: true})
+  if err != nil || len(diags) != 0 || prog == nil {
+    t.Fatalf("load Program: %v %v", err, diags)
+  }
+  defer prog.close()
+  raw := append([]byte{0xef, 0xbb, 0xbf}, []byte("# Before\n")...)
+  write("document.md", raw)
+  document := filepath.Join(root, "document.md")
+  actual, err := prog.inputReader.ReadFile(document)
+  if err != nil || !bytes.Equal(actual, raw) {
+    t.Fatalf("raw reader changed bytes: %x %v", actual, err)
+  }
+  decoded, ok := prog.inputObserver.ReadFile(document)
+  if !ok || decoded != "# Before\n" {
+    t.Fatalf("compiler text changed its decoder contract: %q %v", decoded, ok)
+  }
+  t.Chdir(root)
+  relativeRaw, err := prog.inputReader.ReadFile("document.md")
+  if err != nil || !bytes.Equal(relativeRaw, raw) {
+    t.Fatalf("relative raw read: %x %v", relativeRaw, err)
+  }
+  if _, relative := prog.inputReader.inputs["document.md"]; relative {
+    t.Fatal("relative spelling escaped absolute wire coordinates")
+  }
+  rawSum := sha256.Sum256(raw)
+  if *prog.inputReader.inputs[document] != hex.EncodeToString(rawSum[:]) {
+    t.Fatal("raw host hash substituted decoded compiler text")
+  }
+  proof, failure := prog.inputObserver.predicateProof(document)
+  if failure != "" || proof.ReadFile == nil || proof.ReadFile.Hash == *prog.inputReader.inputs[document] {
+    t.Fatal("raw and decoded proofs collapsed")
+  }
+
+  tree := filepath.Join(root, "walk")
+  if err := os.MkdirAll(filepath.Join(tree, "skip"), 0o755); err != nil {
+    t.Fatal(err)
+  }
+  if err := os.WriteFile(filepath.Join(tree, "skip", "hidden"), nil, 0o644); err != nil {
+    t.Fatal(err)
+  }
+  if err := os.WriteFile(filepath.Join(tree, "a"), nil, 0o644); err != nil {
+    t.Fatal(err)
+  }
+  visited := []string{}
+  if err := prog.inputReader.WalkDir(tree, func(name string, entry fs.DirEntry, err error) error {
+    if err != nil {
+      return err
+    }
+    relative, err := filepath.Rel(tree, name)
+    if err != nil {
+      return err
+    }
+    visited = append(visited, relative)
+    if relative == "skip" {
+      return fs.SkipDir
+    }
+    return nil
+  }); err != nil {
+    t.Fatal(err)
+  }
+  if !reflect.DeepEqual(visited, []string{".", "a", "skip"}) {
+    t.Fatalf("WalkDir selection/ordering: %v", visited)
+  }
+
+  // The raw native listing must not manufacture a compiler accessible query.
+  rawListing, err := prog.inputReader.ReadDir(tree)
+  if err != nil || len(rawListing) != 2 {
+    t.Fatalf("native listing: %v %v", rawListing, err)
+  }
+  rawProof, rawFailure := prog.inputObserver.predicateProof(tree)
+  if rawFailure != "" || rawProof.AccessibleEntries != nil {
+    t.Fatalf("raw ReadDir borrowed compiler query authority: %#v %s", rawProof, rawFailure)
+  }
+  directory := prog.inputReader.directoryInputs[tree]
+  directorySum := sha256.Sum256([]byte("a\x00file\x00\x00skip\x00directory\x00"))
+  if directory.Kind != "directory" || directory.Version != 1 || directory.Digest != hex.EncodeToString(directorySum[:]) || !directory.IdentityStable {
+    t.Fatalf("native listing lost authored membership proof: %#v", directory)
+  }
+  compilerListing := prog.inputObserver.GetAccessibleEntries(tree)
+  if !reflect.DeepEqual(compilerListing.Files, []string{"a"}) || !reflect.DeepEqual(compilerListing.Directories, []string{"skip"}) {
+    t.Fatalf("compiler listing changed: %#v", compilerListing)
+  }
+  if _, err := prog.inputReader.ReadDir(tree); err != nil {
+    t.Fatal(err)
+  }
+  compilerProof, compilerFailure := prog.inputObserver.predicateProof(tree)
+  if compilerFailure != "" || compilerProof.AccessibleEntries == nil || prog.inputReader.incomplete {
+    t.Fatalf("raw/compiler queries conflicted: %#v %s", compilerProof, compilerFailure)
+  }
+  graphAfterListing := prog.checkGraph()
+  listingKey := lintInputKey(prog.cwd, tree)
+  if got := graphAfterListing.InputObservations[listingKey].NativePredicates; len(got) != 1 || got[0].Digest != directory.Digest {
+    t.Fatalf("same-generation publisher lost native listing: %#v", got)
+  }
+  failureReader := newProjectInputReader(prog.inputObserver)
+  if _, err := failureReader.ReadDir(filepath.Join(tree, "missing")); err == nil || !failureReader.incomplete || len(failureReader.directoryInputs) != 0 {
+    t.Fatal("failed native listing gained observation authority")
+  }
+
+  supportedAdapter, err := inspectProjectContributor(observedProjectInputRule{location: document})
+  if err != nil {
+    t.Fatal(err)
+  }
+  previousSupported, hadSupported := registeredProjectRules[supportedAdapter.name]
+  registeredProjectRules[supportedAdapter.name] = supportedAdapter
+  t.Cleanup(func() {
+    if hadSupported {
+      registeredProjectRules[supportedAdapter.name] = previousSupported
+    } else {
+      delete(registeredProjectRules, supportedAdapter.name)
+    }
+  })
+  supportedEngine := NewEngineWithResolver(InlineRuleResolver{Rules: RuleConfig{supportedAdapter.name: SeverityError}})
+  supportedCycle := supportedEngine.evaluateProject(prog.identity, prog.userSourceFiles(), prog.checker, prog.inputReader)
+  supportedCycle.finalize()
+  state, ok := supportedCycle.results.ProjectResult(supportedAdapter.name).State.(struct {
+    Body []byte
+    Err  error
+  })
+  if !ok || state.Err != nil || !bytes.Equal(state.Body, raw) || prog.inputReader.incomplete {
+    t.Fatalf("actual supported reader lost authority or consumed bytes: %#v", state)
+  }
+
+  // The existing topology-only contributor performs no observed reads.
+  adapter, err := inspectProjectContributor(commandProjectInputRule{})
+  if err != nil {
+    t.Fatal(err)
+  }
+  prior, existed := registeredProjectRules[adapter.name]
+  registeredProjectRules[adapter.name] = adapter
+  t.Cleanup(func() {
+    if existed {
+      registeredProjectRules[adapter.name] = prior
+    } else {
+      delete(registeredProjectRules, adapter.name)
+    }
+  })
+  engine := NewEngineWithResolver(InlineRuleResolver{Rules: RuleConfig{adapter.name: SeverityError}})
+  if err := engine.ConfigError(); err != nil {
+    t.Fatal(err)
+  }
+  engine.evaluateProject(prog.identity, prog.userSourceFiles(), prog.checker, prog.inputReader).finalize()
+  if !prog.inputReader.incomplete {
+    t.Fatal("topology-only contributor gained input proof")
+  }
+  write("index.ts", []byte("const value: number = 1; export { value };"))
+  prog.applyChange(filepath.Join(root, "index.ts"))
+  if prog.inputObserver != nil || prog.checkGraph() != nil {
+    t.Fatal("updated Program retained prior-generation observation authority")
+  }
+}

package/linthost/check_serve.go

@@ -120,6 +120,20 @@ func residentCheckPath(location string) (string, bool) {
 // RunCheckServe runs the check-stage watch daemon. It accepts the same base
 // arguments as `check`, reads one JSON request per line, and emits one response
 // per request until stdin closes.
+//
+// One invocation owns one warm Program and drops its reference on exit or incompatible
+// changes. Requests are served serially; callers supply nonnil streams. Exit
+// status 2 reports startup, input or response-write failure, while request
+// failures appear in each response.
+//
+// @evidence contracts/common.md#principled-implementation The line protocol separates fixed compiler options from filesystem transitions, resets rule state per cycle and rebuilds when an unknown non-external path changes program topology.
+// @evidence contracts/common.md#clear-and-simple-design The loop owns protocol lifetime and one state object owns the warm Program. Each processed request creates fresh engines and output buffers; the Program can retain its latest project-cycle memo until update, the next diagnostic run or close.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Supported incremental compiler updates implement compatible edits and a real program reload handles topology changes instead of layered retries over stale source.
+// @evidence contracts/common.md#meaningful-documentation Native prose states serial stream ownership, Program release and exit-versus-response failures; tags are separated.
+// @evidence contracts/portability.md#os-neutral-implementation Filesystem inputs use native filepath and shared file-URI conversion, with physical canonical identities for external dependencies; no shell command or guessed platform separator implements watch transitions.
+// @evidence contracts/performance.md#efficient-algorithms Each request parses its line bytes and normalizes declared external/changed paths. Source membership scans n Program files for each of c changed paths and again during applyChange, with path comparison/physical-identity work; supported compiler updates and dependency-validated config loads add their own input-dependent work. Diagnostics still traverse selected sources/rules and format/encode findings. Temporary request/response space grows with path lists, line bytes and diagnostic bytes; no globally linear transition or unmeasured speedup is claimed.
+// @evidence contracts/performance.md#reuse-equivalent-work One warm Program serves the fixed-option session when the caller reports compatible transitions. Explicit invalidation and unknown non-external paths drop it; known paths use the supported UpdateProgram result and checker refresh, and a newly required missing checker forces reload. Config loading revalidates recorded executable dependencies under its cache premises. New engines and cleared project-cycle memos avoid replaying prior request results; omitted changes or incorrectly declared external paths are not independently discovered by this protocol.
+// @evidence contracts/performance.md#bound-retention-and-release-resources The state holds at most one current Program reference, not a bound on source/checker bytes. Invalidation, incompatible transition, recovered request panic and loop exit close its standalone checker and drop that reference; compiler-owned backing becomes reclaimable when otherwise unreferenced. The current Program can keep the latest project-cycle memo until an update, successful diagnostic setup or close. Request buffers and encoded responses are temporary, while delegated config caches retain their own process/disk history without eviction here. There is no input-line/response byte cap or caller cancellation deadline; blocked streams or user evaluators can keep the synchronous session alive.
 func RunCheckServe(in io.Reader, out io.Writer, args []string) int {
   var startup bytes.Buffer
   base, err := parseSubcommandFlagsWithIO(
@@ -141,7 +155,10 @@ func RunCheckServe(in io.Reader, out io.Writer, args []string) int {
   for {
     raw, readErr := reader.ReadString('\n')
     if line := strings.TrimSpace(raw); line != "" {
-      handleServeCheckLine(line, base, state, encoder)
+      if err := handleServeCheckLine(line, base, state, encoder); err != nil {
+        fmt.Fprintf(os.Stderr, "@ttsc/lint check-serve: write error: %v\n", err)
+        return 2
+      }
     }
     if readErr != nil {
       if readErr != io.EOF {
@@ -158,7 +175,7 @@ func handleServeCheckLine(
   base *subcommandOpts,
   state *residentCheckState,
   encoder *json.Encoder,
-) {
+) (writeErr error) {
   response := serveCheckResponse{Status: 2}
   defer func() {
     if recovered := recover(); recovered != nil {
@@ -174,7 +191,7 @@ func handleServeCheckLine(
       ProgramUpdates: state.programUpdates,
       Reused:         response.Telemetry.Reused,
     }
-    _ = encoder.Encode(response)
+    writeErr = encoder.Encode(response)
   }()
 
   var req serveCheckRequest
@@ -186,6 +203,7 @@ func handleServeCheckLine(
     return
   }
   response = state.run(base, state.apply(req))
+  return
 }
 
 func (s *residentCheckState) run(
@@ -210,6 +228,7 @@ func (s *residentCheckState) run(
     return s.response(2, stdout, stderr, false)
   }
   engine.SetSerial(opts.singleThreaded)
+  engine.SetCurrentDirectory(opts.cwd)
 
   if s.program == nil || (engine.NeedsTypeChecker() && s.program.checker == nil) {
     if s.program != nil {
@@ -226,6 +245,7 @@ func (s *residentCheckState) run(
         singleThreaded:     opts.singleThreaded,
         checkers:           opts.checkers,
         tsgoArgs:           opts.tsgoArgs,
+        tsgoArgsCwd:        opts.tsgoArgsCwd,
         projectIdentity:    opts.projectIdentity,
       },
     )

package/linthost/check_serve_reuses_program_and_matches_cold_cycles_test.go

@@ -0,0 +1,168 @@
+package linthost
+
+import (
+  "bytes"
+  "path/filepath"
+  "strings"
+  "testing"
+)
+
+// TestCheckServeReusesProgramAndMatchesColdCycles verifies check-serve keeps one
+// Program only across changes that preserve compiler topology.
+//
+// Residency is sound only if an incremental answer equals the established
+// one-shot command, request-owned rule/reporting state is rebuilt, external
+// data does not evict the Program, and a new TypeScript root does. The load and
+// update counters are product telemetry, not a test-only hook.
+//
+//  1. Run an initial failing no-var cycle and observe one Program load.
+//  2. Edit the known source, apply it incrementally, and compare the clean
+//     resident result byte-for-byte with a cold check of the same filesystem.
+//  3. Reintroduce the finding and compare the failing incremental and cold
+//     diagnostics byte-for-byte.
+//  4. Apply a declared external JSON change and assert the Program stays warm.
+//  5. Change the import graph and require honest full-rebuild telemetry.
+//  6. Add an unknown TypeScript root and assert the next cycle fully reloads.
+//
+// @evidence contracts/testing.md#behavioral-verification check-serve cycles distinguish no-var diagnostics, zero-error edits, reintroduced errors, external JSON changes, topology edits and added roots while checking Program load/update telemetry.
+// @evidence contracts/testing.md#independent-expectations The authored failing no-var source independently requires literal status 2 and a no-var stderr line on the first cycle, and the Program load/update counts are literal. Later clean and failing cycles are compared only against a cold RunCheckWithIO of the same files, so literal status zero is never asserted. Cold output is a differential oracle for diagnostics, not an independent proof of all rule semantics.
+// @evidence contracts/testing.md#distinguishing-cases One failing no-var project is driven through five edit kinds that must each change the Program telemetry differently: a same-topology source edit (reused, one update), a reintroduced violation (reused, two updates), a declared external JSON change (reused), an import added to an existing file (a second load, not reused) and a newly added root file (a third load, not reused). Cases without a resident daemon boundary, such as removals or config changes, are not covered here.
+// @evidence contracts/testing.md#execution-ownership Drives residentCheckState (run and apply) and RunCheckWithIO in the shared Go test process against one temporary project that the test rewrites on disk between cycles; no daemon process, stdin framing or built binary is started.
+func TestCheckServeReusesProgramAndMatchesColdCycles(t *testing.T) {
+  root := seedLintProject(t, "var legacy = 1;\nJSON.stringify(legacy);\n")
+  dependency := filepath.Join(root, "src", "dependency.ts")
+  writeFile(t, dependency, "export const dependency = true;\n")
+  seedLintRules(t, root, map[string]string{"no-var": "error"})
+  base, err := parseSubcommandFlagsWithIO(
+    "check-serve",
+    []string{
+      "--cwd", root,
+      "--plugins-json", lintManifest(t),
+    },
+    nil,
+    nil,
+  )
+  if err != nil {
+    t.Fatal(err)
+  }
+  base.noEmit = true
+  state := &residentCheckState{}
+  defer state.close()
+
+  first := state.run(base, false)
+  if first.Status != 2 ||
+    first.Telemetry.ProgramLoads != 1 ||
+    first.Telemetry.Reused ||
+    !strings.Contains(first.Stderr, "[no-var]") {
+    t.Fatalf("initial resident cycle = %#v", first)
+  }
+
+  source := filepath.Join(root, "src", "main.ts")
+  writeFile(t, source, "const modern = 1;\nJSON.stringify(modern);\n")
+  incremental := state.run(
+    base,
+    state.apply(serveCheckRequest{Changed: []string{source}}),
+  )
+  var coldOut bytes.Buffer
+  var coldErr bytes.Buffer
+  coldCode := RunCheckWithIO(
+    []string{
+      "--cwd", root,
+      "--plugins-json", lintManifest(t),
+    },
+    &coldOut,
+    &coldErr,
+  )
+  if incremental.Status != coldCode ||
+    incremental.Stdout != coldOut.String() ||
+    incremental.Stderr != coldErr.String() {
+    t.Fatalf(
+      "incremental/cold mismatch\nresident=%#v\ncold=(%d,%q,%q)",
+      incremental,
+      coldCode,
+      coldOut.String(),
+      coldErr.String(),
+    )
+  }
+  if incremental.Telemetry.ProgramLoads != 1 ||
+    incremental.Telemetry.ProgramUpdates != 1 ||
+    !incremental.Telemetry.Reused {
+    t.Fatalf("incremental telemetry = %#v", incremental.Telemetry)
+  }
+
+  writeFile(t, source, "var legacy = 1;\nJSON.stringify(legacy);\n")
+  failing := state.run(
+    base,
+    state.apply(serveCheckRequest{Changed: []string{source}}),
+  )
+  coldOut.Reset()
+  coldErr.Reset()
+  coldCode = RunCheckWithIO(
+    []string{
+      "--cwd", root,
+      "--plugins-json", lintManifest(t),
+    },
+    &coldOut,
+    &coldErr,
+  )
+  if failing.Status != coldCode ||
+    failing.Stdout != coldOut.String() ||
+    failing.Stderr != coldErr.String() {
+    t.Fatalf(
+      "failing incremental/cold mismatch\nresident=%#v\ncold=(%d,%q,%q)",
+      failing,
+      coldCode,
+      coldOut.String(),
+      coldErr.String(),
+    )
+  }
+  if failing.Telemetry.ProgramLoads != 1 ||
+    failing.Telemetry.ProgramUpdates != 2 ||
+    !failing.Telemetry.Reused {
+    t.Fatalf("failing incremental telemetry = %#v", failing.Telemetry)
+  }
+
+  external := filepath.Join(root, "openapi.json")
+  writeFile(t, external, `{"openapi":"3.1.0"}`)
+  externalCycle := state.run(
+    base,
+    state.apply(serveCheckRequest{
+      Changed:  []string{external},
+      External: []string{external},
+    }),
+  )
+  if externalCycle.Telemetry.ProgramLoads != 1 ||
+    !externalCycle.Telemetry.Reused {
+    t.Fatalf("external cycle telemetry = %#v", externalCycle.Telemetry)
+  }
+
+  writeFile(
+    t,
+    source,
+    "import { dependency } from \"./dependency\";\n"+
+      "var legacy = dependency;\nJSON.stringify(legacy);\n",
+  )
+  importGraphCycle := state.run(
+    base,
+    state.apply(serveCheckRequest{Changed: []string{source}}),
+  )
+  if importGraphCycle.Telemetry.ProgramLoads != 2 ||
+    importGraphCycle.Telemetry.ProgramUpdates != 2 ||
+    importGraphCycle.Telemetry.Reused {
+    t.Fatalf(
+      "import-graph rebuild telemetry = %#v",
+      importGraphCycle.Telemetry,
+    )
+  }
+
+  added := filepath.Join(root, "src", "added.ts")
+  writeFile(t, added, "export const added = true;\n")
+  reloaded := state.run(
+    base,
+    state.apply(serveCheckRequest{Changed: []string{added}}),
+  )
+  if reloaded.Telemetry.ProgramLoads != 3 ||
+    reloaded.Telemetry.Reused {
+    t.Fatalf("topology reload telemetry = %#v", reloaded.Telemetry)
+  }
+}

package/linthost/check_tag_names_publishes_canonical_hints_test.go

@@ -0,0 +1,62 @@
+package linthost
+
+import (
+  "sort"
+  "testing"
+
+  publicrule "github.com/samchon/ttsc/packages/lint/rule"
+)
+
+// TestJSDocCheckTagNamesPublishesCanonicalHints verifies the built-in
+// validator also supplies the exact tag vocabulary it accepts to editors.
+//
+// Complete table-to-output equality checks the adapter's ordering and metadata
+// correspondence, not the vocabulary's independent correctness. Literal detail
+// expectations cover four classifications, and real validation accepts @param
+// while rejecting its adjacent @parm spelling.
+//
+//  1. Evaluate the globally enabled rule through its project companion.
+//  2. Collect the finished hint corpus through the host gate.
+//  3. Compare every sorted item with the validator's canonical tag tables.
+//
+// @evidence contracts/testing.md#behavioral-verification evaluateProject and collectProjectHints verify the active validator publishes sorted JSDoc hints, @ triggers, classifications and its complete table-to-hint correspondence; real validation also accepts param and rejects parm.
+// @evidence contracts/testing.md#independent-expectations Literal expectedDetails independently pins alpha as an ordinary tag, inheritDoc as empty, method as a function alias and param as typed. The complete table/detail equality is only an adapter consistency check and cannot independently detect an incorrect canonical vocabulary or every incorrect classification; the accepted/rejected tag source adds an independent parameter spelling oracle.
+// @evidence contracts/testing.md#distinguishing-cases Four distinct detail meanings and complete ordered emission are checked; @param is the accepted spelling and @parm its rejected adjacent typo. Other documentation-tag rules own content requirements.
+// @evidence contracts/testing.md#execution-ownership TestJSDocCheckTagNamesPublishesCanonicalHints is a named Go unit exercising actual project hint collection and source validation in one shared test process; its table consistency check concerns produced editor output, not committed source arrangement.
+func TestJSDocCheckTagNamesPublishesCanonicalHints(t *testing.T) {
+  const name = "jsdoc/check-tag-names"
+  engine := NewEngine(RuleConfig{name: SeverityWarn})
+  cycle := engine.evaluateProject(publicrule.ProjectIdentity{}, nil, nil)
+  hints := collectProjectHints(cycle)
+
+  tags := make([]string, 0, len(knownJSDocTags))
+  for tag := range knownJSDocTags {
+    tags = append(tags, tag)
+  }
+  sort.Strings(tags)
+  if len(hints) != len(tags) {
+    t.Fatalf("want %d known-tag hints, got %d: %#v", len(tags), len(hints), hints)
+  }
+  details := make(map[string]string, len(hints))
+  for index, tag := range tags {
+    hint := hints[index]
+    if hint.Insert != tag || hint.Label != "" || hint.Detail != jsdocTagHintDetail(tag) ||
+      hint.Trigger.Scope != publicrule.HintScopeJSDoc || hint.Trigger.After != "@" {
+      t.Fatalf("hint %d for %q does not match the rule corpus: %#v", index, tag, hint)
+    }
+    details[tag] = hint.Detail
+  }
+  expectedDetails := map[string]string{
+    "alpha":      "JSDoc tag",
+    "inheritDoc": "no content",
+    "method":     "alias for @function",
+    "param":      "accepts a type",
+  }
+  for tag, expected := range expectedDetails {
+    if detail := details[tag]; detail != expected {
+      t.Fatalf("%q detail: want %q, got %q", tag, expected, detail)
+    }
+  }
+  assertJSDocRuleLines(t, name, "/**\n * Handles the input.\n * @param value Input value.\n */\nexport function handle(value: unknown): unknown { return value; }\n")
+  assertJSDocRuleLines(t, name, "/**\n * Handles the input.\n * @parm value Input value.\n */\nexport function handle(value: unknown): unknown { return value; }\n", 3)
+}

package/linthost/check_tag_names_test.go

@@ -0,0 +1,30 @@
+package linthost
+
+import "testing"
+
+// TestRuleJSDocCheckTagNames verifies jsdoc/check-tag-names reports an unknown
+// tag spelling and accepts the known spelling.
+//
+// The rule scans the JSDoc comment text directly, so the unknown tag is reported
+// on its own comment line without depending on which declaration the comment
+// attaches to.
+//
+//  1. Run the rule over a block whose third line is `@parm name description`
+//     and expect one finding on line 3.
+//  2. Run the rule over a block with `@param name description` and expect none.
+//
+// @evidence contracts/testing.md#behavioral-verification assertJSDocRuleLines runs the registered jsdoc/check-tag-names rule through NewEngine.Run over a parsed virtual TypeScript file. The misspelled @parm yields exactly one finding, with that rule at error severity, on line 3; the separately authored block with @param yields none.
+// @evidence contracts/testing.md#independent-expectations The supported parameter tag is @param, so @parm is unknown. The literal comment text and the expected line 3 are authored from that policy, not taken from the rule output. The Test does not assert the message text.
+// @evidence contracts/testing.md#distinguishing-cases The authored @parm block reports and the separately authored @param block stays clean; their descriptions, function names and types also differ, so this is not a spelling-only mutation.
+// @evidence contracts/testing.md#execution-ownership The Test is a single Go unit with two direct helper calls; assertJSDocRuleLines parses the source with parseTSFile and runs the rule engine in the test process, with no installed consumer, native build or host.
+func TestRuleJSDocCheckTagNames(t *testing.T) {
+  assertJSDocRuleLines(t, "jsdoc/check-tag-names", `/**
+ * Handles a name.
+ * @parm name description
+ */
+export function handle(name: string): string {
+  return name;
+}
+`, 3)
+  assertJSDocRuleLines(t, "jsdoc/check-tag-names", "/**\n * Explains the declaration.\n * @param name description\n */\nexport function value(name: unknown): unknown { return name; }\n")
+}

package/linthost/check_values_test.go

@@ -0,0 +1,31 @@
+package linthost
+
+import "testing"
+
+// TestRuleJSDocCheckValues verifies jsdoc/check-values reports an @access value
+// outside the visibility vocabulary and accepts `public`.
+//
+// The rule validates only @access, whose valid values are a closed set, so no
+// TypeScript checker is needed.
+//
+//  1. Run the rule over a block whose third line is `@access friend` and
+//     expect one finding on line 3.
+//  2. Run the rule over a block with `@access public` and expect none.
+//  3. Repeat for `protected`, `private` and `package` and expect none.
+//
+// @evidence contracts/testing.md#behavioral-verification assertJSDocRuleLines runs the registered jsdoc/check-values rule through NewEngine.Run over a parsed virtual TypeScript file. `@access friend` yields exactly one finding, with that rule at error severity, on line 3; `@access public`, `protected`, `private` and `package` each yield none.
+// @evidence contracts/testing.md#independent-expectations The JSDoc @access vocabulary is public, protected, private and package, so `friend` is invalid and `public` is valid. The literal sources and the expected line 3 follow from that vocabulary; the message text is not asserted.
+// @evidence contracts/testing.md#distinguishing-cases The authored friend block is rejected; four separately authored function blocks accept public/protected/private/package. The positive and clean blocks also differ in description and declaration shape.
+// @evidence contracts/testing.md#execution-ownership The Test is a single Go unit invoking the helper for one rejected value and all four accepted values; assertJSDocRuleLines parses the source with parseTSFile and runs the rule engine in the test process, with no installed consumer, native build or host.
+func TestRuleJSDocCheckValues(t *testing.T) {
+  assertJSDocRuleLines(t, "jsdoc/check-values", `/**
+ * Creates a value.
+ * @access friend
+ */
+export const value = 1;
+`, 3)
+  assertJSDocRuleLines(t, "jsdoc/check-values", "/**\n * Explains the declaration.\n * @access public\n */\nexport function value(name: unknown): unknown { return name; }\n")
+  for _, access := range []string{"protected", "private", "package"} {
+    assertJSDocRuleLines(t, "jsdoc/check-values", "/**\n * Explains the declaration.\n * @access "+access+"\n */\nexport function value(name: unknown): unknown { return name; }\n")
+  }
+}