@ttsc/lint 0.30.3 → 0.31.0

package/linthost/behavioral_witness_audit_rejects_invalid_non_canonical_candidate_test.go

@@ -0,0 +1,49 @@
+package linthost
+
+import (
+  "strings"
+  "testing"
+)
+
+// TestBehavioralWitnessAuditRejectsInvalidNonCanonicalCandidate checks every
+// candidate, including one that would lose canonical lexical selection.
+//
+//  1. Accept the authored valid Alpha record alone.
+//  2. Add later records with wrong identity, empty route, unsupported kind or invalid source addresses and require rejection.
+//
+// @evidence contracts/testing.md#behavioral-verification A later candidate naming another rule is rejected even alongside a valid canonical Alpha record. Empty routes, unsupported kinds and invalid source-address shapes likewise fail; the valid canonical candidate alone is accepted.
+// @evidence contracts/testing.md#independent-expectations Each record must name its public rule, supply a route, use a supported prerequisite and identify exactly one test basename. These independent record constraints apply to all candidates, not just the lexical winner.
+// @evidence contracts/testing.md#distinguishing-cases The original noncanonical wrong-rule candidate remains; independent empty-route, invalid-kind, zero/two source, non-test source and non-basename source mutations isolate the remaining validation branches against a valid Alpha control.
+// @evidence contracts/testing.md#execution-ownership The auditor validates authored records directly in-process; filename strings exercise address grammar rather than repository existence or source-content comparisons. No production finding or native host is claimed by these synthetic decision inputs.
+func TestBehavioralWitnessAuditRejectsInvalidNonCanonicalCandidate(t *testing.T) {
+  public := map[string]struct{}{"fixture/rule": {}}
+  candidates := map[string][]behavioralWitness{
+    "fixture/rule": {
+      {Rule: "fixture/rule", Route: "TestAlpha", Kind: behavioralWitnessEngine, Sources: []string{"alpha_test.go"}},
+      {Rule: "fixture/other", Route: "TestZulu", Kind: behavioralWitnessEngine, Sources: []string{"zulu_test.go"}},
+    },
+  }
+  _, err := auditBehavioralWitnesses(public, candidates)
+  if err == nil || !strings.Contains(err.Error(), "fixture/other") {
+    t.Fatalf("invalid non-canonical candidate was not rejected: %v", err)
+  }
+  valid := candidates["fixture/rule"][0]
+  if _, err := auditBehavioralWitnesses(public, map[string][]behavioralWitness{"fixture/rule": {valid}}); err != nil {
+    t.Fatalf("valid canonical candidate rejected: %v", err)
+  }
+  for _, mutate := range []func(*behavioralWitness){
+    func(w *behavioralWitness) { w.Route = "" },
+    func(w *behavioralWitness) { w.Kind = "unsupported" },
+    func(w *behavioralWitness) { w.Sources = nil },
+    func(w *behavioralWitness) { w.Sources = []string{"alpha_test.go", "zulu_test.go"} },
+    func(w *behavioralWitness) { w.Sources = []string{"alpha.go"} },
+    func(w *behavioralWitness) { w.Sources = []string{"nested/alpha_test.go"} },
+  } {
+    invalid := valid
+    invalid.Route = "TestZulu"
+    mutate(&invalid)
+    if _, err := auditBehavioralWitnesses(public, map[string][]behavioralWitness{"fixture/rule": {valid, invalid}}); err == nil || !strings.Contains(err.Error(), "invalid witness records") {
+      t.Fatalf("invalid candidate accepted: %+v %v", invalid, err)
+    }
+  }
+}

package/linthost/behavioral_witness_coverage_test.go

@@ -0,0 +1,379 @@
+package linthost
+
+import (
+  "flag"
+  "fmt"
+  shimast "github.com/microsoft/typescript-go/shim/ast"
+  "path/filepath"
+  "runtime"
+  "sort"
+  "strings"
+  "sync"
+  "testing"
+)
+
+// behavioralWitnessKind describes the production prerequisite exercised by a
+// positive rule test. The kind is reporting metadata, not an exemption: every
+// witness still has to reach a real rule through Engine or the check command
+// and observe that rule's own diagnostic before it is recorded.
+type behavioralWitnessKind string
+
+const (
+  behavioralWitnessEngine   behavioralWitnessKind = "engine"
+  behavioralWitnessOptions  behavioralWitnessKind = "options"
+  behavioralWitnessFilename behavioralWitnessKind = "filename"
+  behavioralWitnessProject  behavioralWitnessKind = "project"
+  behavioralWitnessChecker  behavioralWitnessKind = "checker"
+  behavioralWitnessPlatform behavioralWitnessKind = "platform"
+)
+
+type behavioralWitness struct {
+  Rule    string
+  Route   string
+  Kind    behavioralWitnessKind
+  Sources []string
+}
+
+var behavioralWitnessRegistry = struct {
+  sync.Mutex
+  candidates map[string]map[string]behavioralWitness
+}{candidates: map[string]map[string]behavioralWitness{}}
+
+// recordBehavioralWitness is called only after a positive assertion has
+// verified a production finding. Multiple positive regression tests may exist
+// for one rule; the audit publishes their lexicographically first test name as
+// the single canonical coverage route so the contract remains deterministic.
+func recordBehavioralWitness(t *testing.T, ruleName string, kind behavioralWitnessKind) {
+  t.Helper()
+  recordBehavioralWitnessRoute(behavioralWitness{
+    Rule:    ruleName,
+    Route:   t.Name(),
+    Kind:    kind,
+    Sources: behavioralWitnessSourceFiles(),
+  })
+}
+
+func behavioralWitnessSourceFiles() []string {
+  callers := make([]uintptr, 32)
+  count := runtime.Callers(2, callers)
+  frames := runtime.CallersFrames(callers[:count])
+  source := ""
+  for {
+    frame, more := frames.Next()
+    if strings.HasSuffix(frame.File, "_test.go") {
+      // Keep the outermost test frame, not shared recorder/helper frames, so a
+      // witness names the test that owns the positive case.
+      source = filepath.Base(frame.File)
+    }
+    if !more {
+      break
+    }
+  }
+  if source == "" {
+    return nil
+  }
+  return []string{source}
+}
+
+func recordBehavioralWitnessRoute(candidate behavioralWitness) {
+  behavioralWitnessRegistry.Lock()
+  defer behavioralWitnessRegistry.Unlock()
+  routes := behavioralWitnessRegistry.candidates[candidate.Rule]
+  if routes == nil {
+    routes = map[string]behavioralWitness{}
+    behavioralWitnessRegistry.candidates[candidate.Rule] = routes
+  }
+  routes[candidate.Route] = candidate
+}
+
+func recordFindingBehavioralWitnesses(
+  t *testing.T,
+  findings []*Finding,
+  kind behavioralWitnessKind,
+) {
+  t.Helper()
+  recordFindingBehavioralWitnessesByRule(t, findings, func(string) behavioralWitnessKind {
+    return kind
+  })
+}
+
+func recordFindingBehavioralWitnessesByRule(
+  t *testing.T,
+  findings []*Finding,
+  kindForRule func(string) behavioralWitnessKind,
+) {
+  t.Helper()
+  recorded := map[string]struct{}{}
+  for _, finding := range findings {
+    if finding == nil || finding.Rule == "" {
+      continue
+    }
+    if _, ok := recorded[finding.Rule]; ok {
+      continue
+    }
+    recorded[finding.Rule] = struct{}{}
+    recordBehavioralWitness(t, finding.Rule, kindForRule(finding.Rule))
+  }
+}
+
+func recordedBehavioralWitnesses() map[string][]behavioralWitness {
+  behavioralWitnessRegistry.Lock()
+  defer behavioralWitnessRegistry.Unlock()
+  out := make(map[string][]behavioralWitness, len(behavioralWitnessRegistry.candidates))
+  for ruleName, routes := range behavioralWitnessRegistry.candidates {
+    for _, witness := range routes {
+      witness.Sources = append([]string(nil), witness.Sources...)
+      out[ruleName] = append(out[ruleName], witness)
+    }
+  }
+  return out
+}
+
+// registeredBuiltInNonFormatRuleSet returns the canonical built-in, non-format
+// rule set. Runtime contributors and test-only direct registrations have no
+// built-in TypeScript family property, while format rules are configured
+// through ITtscLintFormat instead of ITtscLintRules.
+func registeredBuiltInNonFormatRuleSet() map[string]struct{} {
+  out := make(map[string]struct{}, len(AllRuleNames()))
+  for _, name := range AllRuleNames() {
+    if !isRegisteredBuiltInNonFormatRule(name, LookupRule(name)) {
+      continue
+    }
+    out[name] = struct{}{}
+  }
+  return out
+}
+
+// isRegisteredBuiltInNonFormatRule classifies registry entries by runtime
+// provenance rather than namespace spelling. The append-only built-in rule-code
+// ledger excludes arbitrary direct registrations, and the structural adapter
+// check also excludes a contributor that reuses a retired ledger name.
+func isRegisteredBuiltInNonFormatRule(name string, candidate Rule) bool {
+  return isRegisteredBuiltInRule(name, candidate) && !isFormatRule(candidate)
+}
+
+// isRegisteredBuiltInFormatRule is the format-side twin used to compare the
+// live format-block expansion with every native formatter registration.
+func isRegisteredBuiltInFormatRule(name string, candidate Rule) bool {
+  return isRegisteredBuiltInRule(name, candidate) && isFormatRule(candidate)
+}
+
+func isRegisteredBuiltInRule(name string, candidate Rule) bool {
+  if candidate == nil {
+    return false
+  }
+  switch candidate.(type) {
+  case contributorAdapter, formatContributorAdapter:
+    return false
+  }
+  _, builtIn := builtInRuleCodes[name]
+  return builtIn
+}
+
+// behavioralWitnessPublicRuleSet is the rule set the witness audit requires a
+// positive production witness for: every user-facing registered rule. It is the
+// built-in non-format set (registeredBuiltInNonFormatRuleSet) plus the format/*
+// family. Format rules are user-facing but configured through the `format`
+// block rather than a typed `rules` key, so registeredBuiltInNonFormatRuleSet
+// excludes them. The witness audit asks a different question ("does every
+// user-facing rule fire in production?"), so it must not: the formatter family
+// is precisely the over-match-prone surface the witness doctrine exists to
+// guard. Format rules earn their witnesses through the dedicated
+// format tests in this package (the `format_*_test.go` files), the same route
+// other rules that cannot run the flat corpus already use.
+func behavioralWitnessPublicRuleSet() map[string]struct{} {
+  public := registeredBuiltInNonFormatRuleSet()
+  for _, name := range AllRuleNames() {
+    if strings.HasPrefix(name, "format/") {
+      public[name] = struct{}{}
+    }
+  }
+  return public
+}
+
+// verifyRecordedBehavioralWitnessCoverage runs after the package test suite.
+// A rule can enter the canonical map only after a positive assertion executed,
+// so registry parity can no longer be satisfied by an inert rule object.
+func verifyRecordedBehavioralWitnessCoverage() error {
+  candidates := recordedBehavioralWitnesses()
+  public := behavioralWitnessPublicRuleSet()
+  _, err := auditBehavioralWitnesses(public, candidates)
+  if err != nil {
+    return err
+  }
+  return verifyRequiredBehavioralWitnessKinds(public, candidates)
+}
+
+func verifyRequiredBehavioralWitnessKinds(
+  public map[string]struct{},
+  candidates map[string][]behavioralWitness,
+) error {
+  seen := map[behavioralWitnessKind]struct{}{}
+  for ruleName, routes := range candidates {
+    if _, ok := public[ruleName]; !ok {
+      continue
+    }
+    for _, candidate := range routes {
+      seen[candidate.Kind] = struct{}{}
+    }
+  }
+  required := []behavioralWitnessKind{
+    behavioralWitnessEngine,
+    behavioralWitnessOptions,
+    behavioralWitnessFilename,
+    behavioralWitnessProject,
+    behavioralWitnessChecker,
+    behavioralWitnessPlatform,
+  }
+  missing := make([]string, 0)
+  for _, kind := range required {
+    if _, ok := seen[kind]; !ok {
+      missing = append(missing, string(kind))
+    }
+  }
+  if len(missing) != 0 {
+    return fmt.Errorf("behavioral witness audit did not exercise prerequisite kinds: %v", missing)
+  }
+  return nil
+}
+
+// shouldVerifyRecordedBehavioralWitnessCoverage preserves focused test and
+// test-listing workflows. The aggregate contract is evaluated only when the
+// complete package suite ran; CI and `go test` use that path.
+func shouldVerifyRecordedBehavioralWitnessCoverage() bool {
+  for _, name := range []string{"test.run", "test.skip", "test.list", "test.fuzz"} {
+    value := flag.Lookup(name)
+    if value != nil && value.Value.String() != "" {
+      return false
+    }
+  }
+  short := flag.Lookup("test.short")
+  if short != nil && short.Value.String() == "true" {
+    return false
+  }
+  return true
+}
+
+// auditBehavioralWitnesses validates every candidate for the supplied public
+// set, then returns one lexically deterministic route per identity. The caller
+// owns public-set selection, including formatter rules. Unselected test/ and
+// demo/ witnesses are tolerated; other stale identities are rejected.
+func auditBehavioralWitnesses(
+  public map[string]struct{},
+  candidates map[string][]behavioralWitness,
+) (map[string]behavioralWitness, error) {
+  canonical := make(map[string]behavioralWitness, len(public))
+  missing := make([]string, 0)
+  stale := make([]string, 0)
+  invalid := make([]string, 0)
+
+  for ruleName := range public {
+    routes := append([]behavioralWitness(nil), candidates[ruleName]...)
+    if len(routes) == 0 {
+      missing = append(missing, ruleName)
+      continue
+    }
+    sort.Slice(routes, func(i, j int) bool {
+      if routes[i].Route != routes[j].Route {
+        return routes[i].Route < routes[j].Route
+      }
+      return routes[i].Kind < routes[j].Kind
+    })
+    valid := true
+    for _, candidate := range routes {
+      if candidate.Rule != ruleName || candidate.Route == "" ||
+        !validBehavioralWitnessKind(candidate.Kind) ||
+        !validBehavioralWitnessSources(candidate.Sources) {
+        invalid = append(invalid, fmt.Sprintf("%s=%+v", ruleName, candidate))
+        valid = false
+      }
+    }
+    if valid {
+      canonical[ruleName] = routes[0]
+    }
+  }
+  for ruleName := range candidates {
+    if _, ok := public[ruleName]; !ok && !isNonPublicRuleName(ruleName) {
+      stale = append(stale, ruleName)
+    }
+  }
+  sort.Strings(missing)
+  sort.Strings(stale)
+  sort.Strings(invalid)
+  if len(missing) != 0 || len(stale) != 0 || len(invalid) != 0 {
+    parts := make([]string, 0, 3)
+    if len(missing) != 0 {
+      parts = append(parts, fmt.Sprintf("public rules without a positive production witness: %v", missing))
+    }
+    if len(stale) != 0 {
+      parts = append(parts, fmt.Sprintf("witnesses for non-public rules: %v", stale))
+    }
+    if len(invalid) != 0 {
+      parts = append(parts, fmt.Sprintf("invalid witness records: %v", invalid))
+    }
+    return nil, fmt.Errorf("behavioral witness audit failed: %s", strings.Join(parts, "; "))
+  }
+  return canonical, nil
+}
+
+func validBehavioralWitnessKind(kind behavioralWitnessKind) bool {
+  switch kind {
+  case behavioralWitnessEngine,
+    behavioralWitnessOptions,
+    behavioralWitnessFilename,
+    behavioralWitnessProject,
+    behavioralWitnessChecker,
+    behavioralWitnessPlatform:
+    return true
+  default:
+    return false
+  }
+}
+
+func behavioralWitnessKindForRule(ruleName string) behavioralWitnessKind {
+  if rule := LookupRule(ruleName); ruleNeedsTypeChecker(rule) {
+    return behavioralWitnessChecker
+  }
+  return behavioralWitnessEngine
+}
+
+func behavioralWitnessKindForOptions(
+  ruleName string,
+  options RuleOptionsMap,
+) behavioralWitnessKind {
+  if _, ok := options[ruleName]; ok {
+    return behavioralWitnessOptions
+  }
+  return behavioralWitnessEngine
+}
+
+func validBehavioralWitnessSources(sources []string) bool {
+  if len(sources) != 1 {
+    return false
+  }
+  source := sources[0]
+  return source != "" && filepath.Base(source) == source &&
+    strings.HasSuffix(source, "_test.go")
+}
+
+// isNonPublicRuleName reports whether a recorded witness belongs to a rule that
+// is intentionally outside the public audit set. Only the test/ and demo/
+// families qualify: format/* rules ARE public (see behavioralWitnessPublicRuleSet),
+// so a stray format witness for an unregistered id is now correctly flagged
+// instead of silently tolerated.
+func isNonPublicRuleName(ruleName string) bool {
+  return strings.HasPrefix(ruleName, "test/") ||
+    strings.HasPrefix(ruleName, "demo/")
+}
+
+type inertBehavioralWitnessRule struct{}
+
+func (inertBehavioralWitnessRule) Name() string {
+  return "test/behavioral-witness-inert"
+}
+
+func (inertBehavioralWitnessRule) Visits() []shimast.Kind {
+  return []shimast.Kind{shimast.KindSourceFile}
+}
+
+func (inertBehavioralWitnessRule) Check(*Context, *shimast.Node) {}

package/linthost/behavioral_witness_kind_follows_rule_checker_requirement_test.go

@@ -0,0 +1,69 @@
+package linthost
+
+import (
+  "testing"
+
+  shimast "github.com/microsoft/typescript-go/shim/ast"
+)
+
+type witnessKindSentinelRule struct {
+  name string
+  // checker is nil for a rule that never declares the capability.
+  checker *bool
+}
+
+func (r witnessKindSentinelRule) Name() string                  { return r.name }
+func (r witnessKindSentinelRule) Visits() []shimast.Kind        { return nil }
+func (r witnessKindSentinelRule) Check(*Context, *shimast.Node) {}
+
+type witnessKindTypedSentinelRule struct {
+  witnessKindSentinelRule
+}
+
+func (r witnessKindTypedSentinelRule) NeedsTypeChecker() bool { return *r.checker }
+
+// TestBehavioralWitnessKindFollowsRuleCheckerRequirement verifies a rule's
+// witness prerequisite kind is the checker lane exactly when the registered rule
+// declares that it needs the type checker.
+//
+// Three sentinel rules cover the three shapes the classifier can meet: no
+// capability at all, a capability answering false, and a capability answering
+// true. Their expected kinds are fixed by that declaration, not by the
+// classifier's output.
+//
+//  1. Register an undeclared rule, a rule declaring NeedsTypeChecker false and a
+//     rule declaring it true.
+//  2. Classify each registered name.
+//  3. Require engine, engine and checker respectively.
+//
+// @evidence contracts/testing.md#behavioral-verification behavioralWitnessKindForRule is called on three registered sentinel names and returns the engine kind for a rule with no type-aware marker and for one whose marker answers false, and the checker kind for the one whose marker answers true.
+// @evidence contracts/testing.md#independent-expectations The expected kinds follow from what each sentinel declares (no marker, marker false, marker true) rather than from the classifier's own lookup, and no production rule name is asserted to be registered or to need a checker.
+// @evidence contracts/testing.md#distinguishing-cases The absent marker and the false marker are separate negatives next to the true marker, so a classifier that treats mere interface presence as checker demand, or that always answers one kind, fails one of the three rows.
+// @evidence contracts/testing.md#execution-ownership Unit entry TestBehavioralWitnessKindFollowsRuleCheckerRequirement registers private stubs through Register in the shared linthost test process and removes them on cleanup; it runs no rule, starts no checker and reads no repository file.
+func TestBehavioralWitnessKindFollowsRuleCheckerRequirement(t *testing.T) {
+  yes, no := true, false
+  rows := []struct {
+    rule Rule
+    want behavioralWitnessKind
+  }{
+    {witnessKindSentinelRule{name: "test/witness-kind-undeclared"}, behavioralWitnessEngine},
+    {witnessKindTypedSentinelRule{witnessKindSentinelRule{name: "test/witness-kind-declines", checker: &no}}, behavioralWitnessEngine},
+    {witnessKindTypedSentinelRule{witnessKindSentinelRule{name: "test/witness-kind-requires", checker: &yes}}, behavioralWitnessChecker},
+  }
+  for _, row := range rows {
+    name := row.rule.Name()
+    if LookupRule(name) != nil {
+      t.Fatalf("sentinel name %q is already registered", name)
+    }
+    Register(row.rule)
+    t.Cleanup(func() {
+      delete(registered.rules, name)
+      invalidateRuntimeRuleCodes()
+    })
+  }
+  for _, row := range rows {
+    if got := behavioralWitnessKindForRule(row.rule.Name()); got != row.want {
+      t.Fatalf("behavioral witness kind for %s = %s, want %s", row.rule.Name(), got, row.want)
+    }
+  }
+}

package/linthost/binding_diagnostic_sites_helpers_test.go

@@ -0,0 +1,31 @@
+package linthost
+
+import (
+  "reflect"
+  "regexp"
+  "strconv"
+  "testing"
+)
+
+// assertBindingDiagnosticSites compares independently authored identifier
+// locations rather than accepting the same number of findings on wrong bindings.
+func assertBindingDiagnosticSites(t *testing.T, stderr string, expected [][2]int) {
+  t.Helper()
+  rendered := ansiControlSequencePattern.ReplaceAllString(stderr, "")
+  pattern := regexp.MustCompile(`(?m)main\.ts:(\d+):(\d+)\s+-\s+error\s+TS\d+:\s*\[prefer-const\]`)
+  actual := [][2]int{}
+  for _, match := range pattern.FindAllStringSubmatch(rendered, -1) {
+    line, err := strconv.Atoi(match[1])
+    if err != nil {
+      t.Fatal(err)
+    }
+    column, err := strconv.Atoi(match[2])
+    if err != nil {
+      t.Fatal(err)
+    }
+    actual = append(actual, [2]int{line, column})
+  }
+  if !reflect.DeepEqual(actual, expected) {
+    t.Fatalf("prefer-const binding sites: want=%v got=%v\nstderr=%s", expected, actual, stderr)
+  }
+}

package/linthost/blank_line_between_statements_returns_false_for_out_of_range_test.go

@@ -0,0 +1,51 @@
+package linthost
+
+import (
+  "testing"
+)
+
+// TestBlankLineBetweenStatementsReturnsFalseForOutOfRange verifies that
+// blankLineBetweenStatements returns false when positions produce an invalid
+// or inverted scan range.
+//
+// The guard `prevEnd < 0 || nextStart > len(src) || nextStart <= prevEnd`
+// prevents the newline-scan loop from running on invalid ranges. Two
+// triggerable cases: a negative prevEnd (which marks a position before the
+// start of the source) and a nextPos that resolves to a position at or before
+// prevEnd after trivia is skipped (an inverted range where the "next"
+// statement starts no later than the "previous" statement ended). Returning
+// false is the safe default: the block printer simply omits the extra
+// Literalline rather than reading garbage.
+//
+//  1. Call blankLineBetweenStatements with prevEnd=-1 (negative prevEnd).
+//  2. Call it with nextPos whose trivia-skipped result is before prevEnd.
+//  3. Assert both calls return false.
+//  4. Call it over a gap holding two line breaks and over a gap holding one,
+//     asserting true and false respectively, so the guard cannot be satisfied
+//     by an implementation that always returns false.
+//
+// @evidence contracts/testing.md#behavioral-verification blankLineBetweenStatements must reject negative/reversed ranges while distinguishing two actual breaks from one.
+// @evidence contracts/testing.md#independent-expectations Literal offsets two/four delimit the two LF bytes in a; followed by b;; the one-break source independently establishes the adjacent negative.
+// @evidence contracts/testing.md#distinguishing-cases Negative prevEnd, reversed range, valid two-break gap and valid one-break gap pin safety and the blank-line threshold.
+// @evidence contracts/testing.md#execution-ownership TestBlankLineBetweenStatementsReturnsFalseForOutOfRange is a plain top-level Go unit test, selectable with go test -run, that calls blankLineBetweenStatements directly on literal source strings and byte offsets, with no AST inside the test process; it installs no consumer, builds no native artifact and starts no product host.
+func TestBlankLineBetweenStatementsReturnsFalseForOutOfRange(t *testing.T) {
+  src := "a;\n\nb;\n"
+
+  // Case 1: negative prevEnd triggers the first guard condition.
+  if blankLineBetweenStatements(src, -1, 3) {
+    t.Fatalf("expected false for negative prevEnd")
+  }
+
+  // Case 2: nextStart (after SkipTrivia) lands before prevEnd: an inverted
+  // range. nextPos=1 → SkipTrivia returns 1 (no leading trivia at position 1),
+  // prevEnd=5 → nextStart(1) <= prevEnd(5) → guard fires.
+  if blankLineBetweenStatements(src, 5, 1) {
+    t.Fatalf("expected false for nextStart <= prevEnd")
+  }
+  if !blankLineBetweenStatements(src, 2, 4) {
+    t.Fatal("two valid line breaks must preserve a blank line")
+  }
+  if blankLineBetweenStatements("a;\nb;\n", 2, 3) {
+    t.Fatal("one line break is not a blank line")
+  }
+}

package/linthost/block_has_non_statement_comment_returns_false_for_out_of_range_test.go

@@ -0,0 +1,56 @@
+package linthost
+
+import (
+  "testing"
+
+  shimast "github.com/microsoft/typescript-go/shim/ast"
+)
+
+// TestBlockHasNonStatementCommentReturnsFalseForOutOfRange verifies that
+// blockHasNonStatementComment returns false when the node's End() position
+// exceeds the length of the context's Source string.
+//
+// The shared nodeHasNonItemComment helper rejects a node range that exceeds
+// the supplied source before scanning for delimiters. This case deliberately
+// pairs one parsed block with a shorter context; it is an authored invalid
+// range input, not evidence that production partial reparses construct it.
+// The same block with its full source must report the comment, distinguishing
+// the range guard from an implementation that always returns false.
+//
+//  1. Parse a block `{ /* c */ }` that starts at position 0 in the source.
+//  2. Construct a PrintContext whose Source is the 9-byte prefix
+//     "{ /* c */" (shorter than the block End(), yet containing a comment opener).
+//  3. Call blockHasNonStatementComment with the mismatched context.
+//  4. Assert the function returns false, then assert it returns true when the
+//     context carries the full source (control).
+//
+// @evidence contracts/testing.md#behavioral-verification blockHasNonStatementComment must return false when the parsed block range extends beyond the supplied source.
+// @evidence contracts/testing.md#independent-expectations The literal 9-byte context source "{ /* c */" cannot contain the complete 11-byte parsed block, yet it holds a comment opener, so a scan beyond the range guard would answer true; the range-safety contract prohibits inspecting a node beyond its supplied source bounds.
+// @evidence contracts/testing.md#distinguishing-cases The truncated context (false) is contrasted with the full-source control on the same block (true, comment reported); inter-statement comments in covered blocks are owned by the uncovered-block dispatch cases.
+// @evidence contracts/testing.md#execution-ownership TestBlockHasNonStatementCommentReturnsFalseForOutOfRange is a plain top-level Go unit test, selectable with go test -run, that calls blockHasNonStatementComment directly on a parsed block paired with a truncated PrintContext source inside the test process; it installs no consumer, builds no native artifact and starts no product host.
+func TestBlockHasNonStatementCommentReturnsFalseForOutOfRange(t *testing.T) {
+  // Top-level `{ /* c */ }` is a block statement starting at position 0 and
+  // ending at 11. The truncated context source "{ /* c */" is 9 bytes long:
+  // it still contains a complete comment opener, so an implementation without
+  // the range guard would scan it and report true. SkipTrivia(src, 0) = 0, so
+  // the guard fires on end(11) > len(src)(9).
+  file := parseTS(t, "{ /* c */ }\n")
+  block := firstNodeOfKind(t, file, shimast.KindBlock)
+
+  shortCtx := &PrintContext{
+    Source: "{ /* c */",
+    Opts:   DefaultPrintOptions(),
+  }
+
+  got := blockHasNonStatementComment(shortCtx, block, nil)
+  if got {
+    t.Fatalf("blockHasNonStatementComment should return false for out-of-range node, got true")
+  }
+
+  // Control: with the full source the same block does report its comment, so
+  // the false above comes from the range guard, not from a comment-free block.
+  fullCtx := NewPrintContext(file, DefaultPrintOptions())
+  if !blockHasNonStatementComment(fullCtx, block, nil) {
+    t.Fatalf("blockHasNonStatementComment should report the comment when the source covers the block")
+  }
+}

package/linthost/block_has_non_statement_comment_skips_nil_stmts_test.go

@@ -0,0 +1,42 @@
+package linthost
+
+import (
+  "testing"
+
+  shimast "github.com/microsoft/typescript-go/shim/ast"
+)
+
+// TestBlockHasNonStatementCommentSkipsNilStmts verifies that
+// blockHasNonStatementComment skips nil entries in the stmts slice when
+// building the statement-range exclusion list.
+//
+// blockHasNonStatementComment delegates to nodeHasNonItemComment, whose item
+// loop skips nil pointers before reading their byte ranges. This test supplies
+// the nil placeholder directly; it does not establish that parser recovery
+// emits such a list. The comment-free source independently requires false,
+// and a missing nil guard would dereference the placeholder during range
+// collection rather than reach that result.
+//
+//  1. Parse a block from a real source so the node has valid byte positions.
+//  2. Call blockHasNonStatementComment with a stmts slice containing one nil
+//     element (bypassing the real block.Statements.Nodes list directly).
+//  3. Assert the function returns false without panicking (the block holds no
+//     comment, so even with the nil stmt skipped the result is false).
+//
+// @evidence contracts/testing.md#behavioral-verification blockHasNonStatementComment must safely skip nil entries and report no comment in the comment-free block.
+// @evidence contracts/testing.md#independent-expectations The literal block { a(); } contains no comment delimiter, so a nil item cannot create one.
+// @evidence contracts/testing.md#distinguishing-cases The supplied singleton nil statement exercises item filtering; comment-only and inter-statement-comment dispatch cases own the opposite coverage outcome.
+// @evidence contracts/testing.md#execution-ownership TestBlockHasNonStatementCommentSkipsNilStmts is a plain top-level Go unit test, selectable with go test -run, that calls blockHasNonStatementComment directly on a parsed comment-free block and a hand-built statement slice holding nil inside the test process; it installs no consumer, builds no native artifact and starts no product host.
+func TestBlockHasNonStatementCommentSkipsNilStmts(t *testing.T) {
+  // Parse a block with no comments so the expected result is false.
+  file := parseTS(t, "{ a(); }\n")
+  block := firstNodeOfKind(t, file, shimast.KindBlock)
+  ctx := NewPrintContext(file, DefaultPrintOptions())
+
+  // Pass a stmts list with a nil entry; the nil must be skipped, not dereferenced.
+  stmtsWithNil := []*shimast.Node{nil}
+  got := blockHasNonStatementComment(ctx, block, stmtsWithNil)
+  if got {
+    t.Fatalf("blockHasNonStatementComment should return false for comment-free block, got true")
+  }
+}