@ttsc/lint 0.30.4 → 0.31.0

package/linthost/format_sort_imports_preserves_comments_between_imports_test.go

@@ -0,0 +1,43 @@
+package linthost
+
+import (
+  "testing"
+
+  shimast "github.com/microsoft/typescript-go/shim/ast"
+)
+
+// TestFormatSortImportsPreservesCommentsBetweenImports verifies the rule
+// bails the block-level reorder when comments separate imports.
+//
+// User comments often anchor specific imports ("`// MUST be first`",
+// dependency-injection hints, etc.). Moving comments with the wrong
+// declaration is strictly worse than leaving the order alone. The rule's
+// `leadingTriviaIsAllWhitespace` guard is the load-bearing predicate;
+// this scenario pins it.
+//
+//  1. Parse a source file with a comment between two imports.
+//  2. Run the engine with formatSortImports enabled.
+//  3. Assert no block-level reorder finding fires (specifier-level findings
+//     may still fire for the same file, but the block reorder must not).
+//  4. Exercise the unsafe boundary and its adjacent positive.
+//
+// @evidence contracts/testing.md#behavioral-verification The original engine result must not contain a block-reorder finding; unsafe sorting must still preserve the intervening dependency-wiring comment without findings.
+// @evidence contracts/testing.md#independent-expectations The explicit comment is attached between zebra and alpha declarations. Literal comment-free output is alpha then zebra under the supported unsafe lexical-order policy.
+// @evidence contracts/testing.md#distinguishing-cases The original default runtime barrier remains covered. An unsafe negative isolates comment protection, and the same declarations without that comment supply its adjacent reorder positive.
+// @evidence contracts/testing.md#execution-ownership TestFormatSortImportsPreservesCommentsBetweenImports owns the original engine diagnostic check plus authored unsafe negative and comment-free full-output positive in the selected public Go unit population. Parsing, the owning rule and fixture edit observation execute in one Go process without native builds, consumer installation or product-host children.
+func TestFormatSortImportsPreservesCommentsBetweenImports(t *testing.T) {
+  source := "import zebra from \"zebra\";\n" +
+    "// pinned by dependency injection wiring\n" +
+    "import alpha from \"alpha\";\n" +
+    "JSON.stringify({ zebra, alpha });\n"
+  file := parseTS(t, source)
+  findings := NewEngine(RuleConfig{"format/sort-imports": SeverityError}).
+    Run([]*shimast.SourceFile{file}, nil)
+  for _, finding := range findings {
+    if finding.Message == "Imports must be sorted into canonical groups." {
+      t.Fatalf("block reorder fired despite intervening comment: %+v", finding)
+    }
+  }
+  assertRuleSkipsSourceWithOptions(t, "format/sort-imports", source, `{"unsafeSortRuntimeImports":true}`)
+  assertFixSnapshotWithOptions(t, "format/sort-imports", "import zebra from \"zebra\";\nimport alpha from \"alpha\";\nJSON.stringify({ zebra, alpha });\n", `{"unsafeSortRuntimeImports":true}`, "import alpha from \"alpha\";\nimport zebra from \"zebra\";\nJSON.stringify({ zebra, alpha });\n")
+}

package/linthost/format_sort_imports_preserves_comments_between_specifiers_test.go

@@ -0,0 +1,38 @@
+package linthost
+
+import (
+  "testing"
+
+  shimast "github.com/microsoft/typescript-go/shim/ast"
+)
+
+// TestFormatSortImportsPreservesCommentsBetweenSpecifiers verifies the
+// specifier-sort path declines to reorder a `{ b /*pin*/, a }` list.
+//
+// The rule rejoins sorted specifiers with `", "` — any `/* x */` or
+// `// x` between specifiers would be silently discarded. The
+// block-level sort already bails on comment trivia between
+// declarations (via `leadingTriviaIsAllWhitespace`); this scenario
+// pins the per-specifier analog so the cohort policy is consistent.
+//
+//  1. Parse an import whose named-specifier list carries an inline
+//     block comment between two specifiers.
+//  2. Run formatSortImports.
+//  3. Assert zero findings — the rule must NOT propose an edit that
+//     would silently drop the comment.
+//
+// @evidence contracts/testing.md#behavioral-verification A reversed b,a named list with an interior pin comment must emit zero findings, preserving its attachment and both uses.
+// @evidence contracts/testing.md#independent-expectations The literal user comment cannot disappear when specifier text is reconstructed. Zero findings independently enforces the supported comment-protection policy; the uncommented alphabetization host fixes the same ordering class.
+// @evidence contracts/testing.md#distinguishing-cases One declaration excludes runtime-block sorting as a confounder. The comment sits between two specifiers, unlike the final-specifier merge-protection and between-import comment hosts.
+// @evidence contracts/testing.md#execution-ownership TestFormatSortImportsPreservesCommentsBetweenSpecifiers owns its literal commented list and direct engine zero-finding assertion in the selected public Go unit population. Parsing, owning syntax rule and fixture observations execute in one Go process without native builds, consumer installation or real product-host children.
+func TestFormatSortImportsPreservesCommentsBetweenSpecifiers(t *testing.T) {
+  source := "import { b /* pin */, a } from \"./local\";\n" +
+    "console.log(a, b);\n"
+  file := parseTS(t, source)
+  findings := NewEngine(RuleConfig{"format/sort-imports": SeverityError}).
+    Run([]*shimast.SourceFile{file}, nil)
+  if len(findings) != 0 {
+    t.Fatalf("expected zero findings (specifier-sort must not drop inline comments), got %d:\n%v",
+      len(findings), findings)
+  }
+}

package/linthost/format_sort_imports_preserves_side_effect_imports_test.go

@@ -0,0 +1,55 @@
+package linthost
+
+import (
+  "testing"
+
+  shimast "github.com/microsoft/typescript-go/shim/ast"
+)
+
+// TestFormatSortImportsPreservesSideEffectImports verifies the rule
+// declines to sort a block that contains a side-effect-only import.
+//
+// `import "./polyfill"` runs the polyfill's top-level code for its
+// observable effect (e.g. installing globals). A later value import may
+// depend on that effect having already run, so sorting it lexically
+// next to other specifiers can silently change runtime behavior. The
+// rule's safety policy matches the comment-trivia bail: refuse to
+// reorder the block when correctness can't be locally proven.
+//
+//  1. Parse a source with mixed side-effect and value imports in an
+//     order the lexical sort would change.
+//  2. Run formatSortImports.
+//  3. Assert zero findings, preserving the block's source order.
+//
+// @evidence contracts/testing.md#behavioral-verification The original mixed polyfill/shim/value block must remain silent, and a reversed namespace dependency block must also emit no findings with safe defaults. The exact original default-plus-named b-before-namespace a module also remains edit-free; its existing runtime actor owns the independently authored b,a output.
+// @evidence contracts/testing.md#independent-expectations The public safe mode preserves runtime dependency order because module top-level effects can be observed. Zero findings independently forbids declaration edits rather than assuming a dependency is pure.
+// @evidence contracts/testing.md#distinguishing-cases The mixed block covers bare side-effect, named and default imports; a separate namespace pair covers that runtime syntax. The explicit unsafe bare-import unit supplies a permitted reorder positive. The binding-only case has no bare side-effect import and therefore distinguishes preserving effectful bindings from recognizing bare syntax alone.
+// @evidence contracts/testing.md#execution-ownership TestFormatSortImportsPreservesSideEffectImports owns its literal mixed-runtime input and direct engine zero-finding assertion plus the authored namespace and exact binding-only boundaries in the selected public Go unit population. The same binding-only main.mjs bytes execute through the existing test_e2e_runtime_batch actor rather than a new Node child. Parsing, owning syntax rule and fixture observations execute in one Go process without native builds, consumer installation or real product-host children.
+func TestFormatSortImportsPreservesSideEffectImports(t *testing.T) {
+  source := "import \"./polyfill\";\n" +
+    "import { reduce } from \"./local-a\";\n" +
+    "import \"./shim\";\n" +
+    "import alpha from \"alpha\";\n" +
+    "JSON.stringify({ reduce, alpha });\n"
+  file := parseTS(t, source)
+  findings := NewEngine(RuleConfig{"format/sort-imports": SeverityError}).
+    Run([]*shimast.SourceFile{file}, nil)
+  if len(findings) != 0 {
+    t.Fatalf("expected zero findings (side-effect imports inhibit sort), got %d:\n%v",
+      len(findings), findings)
+  }
+  assertRuleSkipsSource(t, "format/sort-imports", "import * as zebra from \"./z\";\nimport * as alpha from \"./a\";\nconsole.log(zebra, alpha);\n")
+  bindingSource := `import bDefault, { bNamed } from "./b.mjs";
+import * as aNamespace from "./a.mjs";
+console.log(globalThis.__sortImportsTrace.join(","));
+void bDefault;
+void bNamed;
+void aNamespace;
+`
+  bindingFile := parseTSFile(t, "/virtual/main.mjs", bindingSource)
+  bindingFindings := NewEngine(RuleConfig{"format/sort-imports": SeverityError}).
+    Run([]*shimast.SourceFile{bindingFile}, nil)
+  if len(bindingFindings) != 0 {
+    t.Fatalf("binding-only imports must preserve b-before-a order: findings=%+v", bindingFindings)
+  }
+}

package/linthost/format_sort_imports_recognizes_exact_builtin_specifiers_test.go

@@ -0,0 +1,56 @@
+package linthost
+
+import (
+  "strconv"
+  "testing"
+)
+
+// TestFormatSortImportsRecognizesExactBuiltinSpecifiers verifies that Node's
+// built-in group recognizes actual module identifiers, including prefix-only
+// modules, while leaving unsupported subpaths and bare prefix-only names in
+// the third-party group. Every case reverses the independently expected order
+// so the real format engine must edit it without changing bindings or uses.
+//
+// @evidence contracts/testing.md#behavioral-verification The configured format/sort-imports engine applies a fix and compares the complete rewritten file for each actual built-in or adjacent third-party spelling. The group difference must reorder both import declarations while preserving their bindings and body.
+// @evidence contracts/testing.md#independent-expectations Literal classifications follow Node v24.18.0 module.isBuiltin and the documented mandatory node: prefix for sea, sqlite, test and test/reporters. Neither the production module map nor its string splitting generates the expected classifications.
+// @evidence contracts/testing.md#distinguishing-cases Bare and prefixed ordinary modules, every supported public subpath, internal modules, four prefix-only names and their bare twins, unknown subpaths, unknown prefixed names, case changes and relative lookalikes distinguish exact module membership from prefix or basename guesses.
+// @evidence contracts/testing.md#execution-ownership This Go unit owns each named literal specifier, classification and full-file oracle. assertFixSnapshotWithOptions executes the owning syntax engine and fix applier in-process with a fixture filesystem, without installing a consumer, building a native artifact or starting a product host.
+func TestFormatSortImportsRecognizesExactBuiltinSpecifiers(t *testing.T) {
+  cases := []struct {
+    specifier string
+    builtin   bool
+  }{
+    {"fs", true}, {"node:fs", true},
+    {"assert/strict", true}, {"dns/promises", true},
+    {"fs/promises", true}, {"inspector/promises", true},
+    {"path/posix", true}, {"path/win32", true},
+    {"readline/promises", true}, {"stream/consumers", true},
+    {"stream/promises", true}, {"stream/web", true},
+    {"timers/promises", true}, {"util/types", true},
+    {"node:fs/promises", true}, {"_http_agent", true},
+    {"node:_stream_duplex", true},
+    {"node:sea", true}, {"node:sqlite", true},
+    {"node:test", true}, {"node:test/reporters", true},
+    {"sea", false}, {"sqlite", false},
+    {"test", false}, {"test/reporters", false},
+    {"fs/not-a-real-builtin", false},
+    {"node:fs/not-a-real-builtin", false},
+    {"node:test/not-a-real-builtin", false},
+    {"node:not-a-real-builtin", false},
+    {"FS", false}, {"node:FS", false},
+    {"./fs", false}, {"../fs", false},
+  }
+  for _, test := range cases {
+    t.Run(test.specifier, func(t *testing.T) {
+      candidate := "import candidate from " + strconv.Quote(test.specifier) + ";\n"
+      thirdParty := "import external from \"@a/third-party\";\n"
+      body := "JSON.stringify({ candidate, external });\n"
+      source, expected := candidate+thirdParty+body, thirdParty+candidate+body
+      if test.builtin {
+        source, expected = thirdParty+candidate+body, candidate+thirdParty+body
+      }
+      assertFixSnapshotWithOptions(t, "format/sort-imports", source,
+        `{"unsafeSortRuntimeImports":true}`, expected)
+    })
+  }
+}

package/linthost/format_sort_imports_scopes_type_group_by_regex_test.go

@@ -0,0 +1,32 @@
+package linthost
+
+import "testing"
+
+// TestFormatSortImportsScopesTypeGroupByRegex verifies a <TYPES> group with a
+// trailing regex only claims type-only imports whose specifier matches.
+//
+// `<TYPES>^[.]` groups type-only relative imports; a type-only third-party
+// import falls through to a later group, exercising both the match and the
+// no-match arm of the type-group test.
+//
+//  1. Parse value + type-only imports across relative and third-party modules.
+//  2. Apply that order with unsafe runtime sorting enabled.
+//  3. Assert only the type-only relative import is hoisted.
+//
+// @evidence contracts/testing.md#behavioral-verification Only relative type T must enter the first TYPES regex group, followed by react value/type imports and local value, retaining v use.
+// @evidence contracts/testing.md#independent-expectations The supported TYPES regex requires both clause-level type-only status and matching relative module text. Literal output independently preserves phases and the configured group sequence.
+// @evidence contracts/testing.md#distinguishing-cases Relative type T matches, third-party type R does not, and relative value local does not. The unscoped TYPES host supplies its broader placeholder counterpart.
+// @evidence contracts/testing.md#execution-ownership TestFormatSortImportsScopesTypeGroupByRegex owns the authored matched/unmatched type and value fixture with custom order and unsafe option in the selected public Go unit population. Owning syntax rule and fixture edits execute in one Go process without native builds, consumer installation or real product-host children.
+func TestFormatSortImportsScopesTypeGroupByRegex(t *testing.T) {
+  source := "import { v } from \"react\";\n" +
+    "import type { R } from \"react\";\n" +
+    "import type { T } from \"./types\";\n" +
+    "import { local } from \"./local\";\n" +
+    "v;\n"
+  expected := "import type { T } from \"./types\";\n" +
+    "import { v } from \"react\";\n" +
+    "import type { R } from \"react\";\n" +
+    "import { local } from \"./local\";\n" +
+    "v;\n"
+  assertFixSnapshotWithOptions(t, "format/sort-imports", source, `{"order":["<TYPES>^[.]","<THIRD_PARTY_MODULES>","^[.]"],"unsafeSortRuntimeImports":true}`, expected)
+}

package/linthost/format_sort_imports_separator_spans_empty_group_test.go

@@ -0,0 +1,31 @@
+package linthost
+
+import "testing"
+
+// TestFormatSortImportsSeparatorSpansEmptyGroup verifies a blank-line separator
+// still appears when the group it guards produced no imports.
+//
+// With order [third-party, "", @api, "", relative] and no `@api/*` import, the
+// transition from third-party straight to relative must still collapse to a
+// single blank line carried by the skipped middle group.
+//
+//  1. Parse a third-party and a relative import (no @api import).
+//  2. Apply that order with unsafe runtime sorting enabled.
+//  3. Assert one blank line separates the two populated groups.
+//
+// @evidence contracts/testing.md#behavioral-verification The alpha and local imports must receive exactly one blank line despite the empty api group, preserving both subsequent uses.
+// @evidence contracts/testing.md#independent-expectations The supported empty-string order entries contribute separators across skipped groups. The literal output independently specifies one blank line rather than accumulating two.
+// @evidence contracts/testing.md#distinguishing-cases The middle api group has no members. The custom-order host fills all groups and the CRLF twin checks the same empty-group boundary with another line ending.
+// @evidence contracts/testing.md#execution-ownership TestFormatSortImportsSeparatorSpansEmptyGroup owns the authored empty-middle-group whole-file LF snapshot and custom order in the selected public Go unit population. Owning syntax rule and fixture edits execute in one Go process without native builds, consumer installation or real product-host children.
+func TestFormatSortImportsSeparatorSpansEmptyGroup(t *testing.T) {
+  source := "import { a } from \"alpha\";\n" +
+    "import { b } from \"./local\";\n" +
+    "a;\n" +
+    "b;\n"
+  expected := "import { a } from \"alpha\";\n" +
+    "\n" +
+    "import { b } from \"./local\";\n" +
+    "a;\n" +
+    "b;\n"
+  assertFixSnapshotWithOptions(t, "format/sort-imports", source, `{"order":["<THIRD_PARTY_MODULES>","","@api/(.*)","","^[.]"],"unsafeSortRuntimeImports":true}`, expected)
+}

package/linthost/format_sort_imports_skips_already_sorted_files_test.go

@@ -0,0 +1,40 @@
+package linthost
+
+import (
+  "testing"
+
+  shimast "github.com/microsoft/typescript-go/shim/ast"
+)
+
+// TestFormatSortImportsSkipsAlreadySortedFiles verifies idempotence.
+//
+// Sort rules are particularly prone to oscillation: a buggy comparator that
+// is not stable can swap equal-key items every other pass and burn the
+// format loop's cap. The rule must produce zero findings on a file whose
+// imports and specifiers are already canonical.
+//
+//  1. Parse a source file with sorted third-party + relative groups laid out
+//     in the default order (no blank-line separator).
+//  2. Run the engine with formatSortImports enabled.
+//  3. Assert zero findings.
+//  4. Exercise the unsafe boundary and its adjacent positive.
+//
+// @evidence contracts/testing.md#behavioral-verification The canonical alpha/zebra then local-a/local-b declarations must emit no findings under both default and unsafe options; reverse bare-import order must change under unsafe options.
+// @evidence contracts/testing.md#independent-expectations The literal canonical source follows the supported default third-party-before-relative grouping and alphabetical order. The separate two-import output fixes the permitted lexical order without deriving it from the comparator.
+// @evidence contracts/testing.md#distinguishing-cases Default mode alone would hide sorting defects in this runtime block. Its unsafe fixed point isolates canonicality, while an unsafe reverse-order positive distinguishes a rule that never acts.
+// @evidence contracts/testing.md#execution-ownership TestFormatSortImportsSkipsAlreadySortedFiles owns its original engine zero-finding assertion plus unsafe canonical and reverse-order literal cases in the selected public Go unit population. Parsing, the owning rule and fixture edit observation execute in one Go process without native builds, consumer installation or product-host children.
+func TestFormatSortImportsSkipsAlreadySortedFiles(t *testing.T) {
+  source := "import alpha from \"alpha\";\n" +
+    "import zebra from \"zebra\";\n" +
+    "import { x } from \"./local-a\";\n" +
+    "import { reduce } from \"./local-b\";\n" +
+    "JSON.stringify({ alpha, zebra, x, reduce });\n"
+  file := parseTS(t, source)
+  findings := NewEngine(RuleConfig{"format/sort-imports": SeverityError}).
+    Run([]*shimast.SourceFile{file}, nil)
+  if len(findings) != 0 {
+    t.Fatalf("expected zero findings, got %d: %+v", len(findings), findings)
+  }
+  assertRuleSkipsSourceWithOptions(t, "format/sort-imports", source, `{"unsafeSortRuntimeImports":true}`)
+  assertFixSnapshotWithOptions(t, "format/sort-imports", "import \"./z\";\nimport \"./a\";\n", `{"unsafeSortRuntimeImports":true}`, "import \"./a\";\nimport \"./z\";\n")
+}

package/linthost/format_sort_imports_skips_invalid_regex_group_test.go

@@ -0,0 +1,30 @@
+package linthost
+
+import "testing"
+
+// TestFormatSortImportsSkipsInvalidRegexGroup verifies an uncompilable regex
+// entry in `order` is skipped rather than crashing the run.
+//
+// A bad pattern (`[`) is dropped; the remaining `^[.]` group still applies and
+// the third-party catch-all (injected at the front when omitted) takes the
+// unmatched specifier.
+//
+//  1. Parse a third-party and a relative import.
+//  2. Apply that order with unsafe runtime sorting (the first entry is invalid).
+//  3. Assert the run continues and groups by the surviving order.
+//
+// @evidence contracts/testing.md#behavioral-verification An invalid ordinary group pattern must not crash or block sorting; the output puts alpha before local and preserves both uses.
+// @evidence contracts/testing.md#independent-expectations The supported malformed-order policy skips invalid expressions and supplies a third-party fallback. The literal full output independently defines the surviving relative-group behavior.
+// @evidence contracts/testing.md#distinguishing-cases The first pattern is an unmatched opening bracket and the catch-all is omitted. The malformed TYPES-pattern peer covers another parser branch, while valid custom regexes have their own positive.
+// @evidence contracts/testing.md#execution-ownership TestFormatSortImportsSkipsInvalidRegexGroup owns the authored invalid-pattern option input and surviving-group complete-output oracle in the selected public Go unit population. Owning syntax rule and fixture edits execute in one Go process without native builds, consumer installation or real product-host children.
+func TestFormatSortImportsSkipsInvalidRegexGroup(t *testing.T) {
+  source := "import { b } from \"./local\";\n" +
+    "import { a } from \"alpha\";\n" +
+    "a;\n" +
+    "b;\n"
+  expected := "import { a } from \"alpha\";\n" +
+    "import { b } from \"./local\";\n" +
+    "a;\n" +
+    "b;\n"
+  assertFixSnapshotWithOptions(t, "format/sort-imports", source, `{"order":["[","^[.]"],"unsafeSortRuntimeImports":true}`, expected)
+}

package/linthost/format_sort_imports_skips_invalid_types_regex_group_test.go

@@ -0,0 +1,28 @@
+package linthost
+
+import "testing"
+
+// TestFormatSortImportsSkipsInvalidTypesRegexGroup verifies an uncompilable
+// regex attached to a <TYPES> entry is skipped rather than crashing the run.
+//
+// `<TYPES>[` carries a bad trailing pattern; the group is dropped and the run
+// proceeds with the remaining groups (here merging duplicate modules).
+//
+//  1. Parse two value imports of the same module.
+//  2. Apply that order with unsafe runtime sorting enabled.
+//  3. Assert the run merges the duplicates without crashing.
+//
+// @evidence contracts/testing.md#behavioral-verification An invalid TYPES regex must be ignored while duplicate m declarations merge into sorted a,b and both uses remain intact.
+// @evidence contracts/testing.md#independent-expectations The supported malformed-group policy skips bad expressions while retaining the declared third-party fallback. Literal complete output independently specifies legal same-module merging.
+// @evidence contracts/testing.md#distinguishing-cases The invalid pattern follows TYPES and an explicit fallback remains. The ordinary-invalid regex host differs in expression branch and implicit fallback ownership.
+// @evidence contracts/testing.md#execution-ownership TestFormatSortImportsSkipsInvalidTypesRegexGroup owns the authored invalid TYPES option input, explicit fallback and full merge oracle in the selected public Go unit population. Owning syntax rule and fixture edits execute in one Go process without native builds, consumer installation or real product-host children.
+func TestFormatSortImportsSkipsInvalidTypesRegexGroup(t *testing.T) {
+  source := "import { b } from \"m\";\n" +
+    "import { a } from \"m\";\n" +
+    "a;\n" +
+    "b;\n"
+  expected := "import { a, b } from \"m\";\n" +
+    "a;\n" +
+    "b;\n"
+  assertFixSnapshotWithOptions(t, "format/sort-imports", source, `{"order":["<TYPES>[","<THIRD_PARTY_MODULES>"],"unsafeSortRuntimeImports":true}`, expected)
+}

package/linthost/format_sort_imports_skips_single_import_files_test.go

@@ -0,0 +1,38 @@
+package linthost
+
+import (
+  "testing"
+
+  shimast "github.com/microsoft/typescript-go/shim/ast"
+)
+
+// TestFormatSortImportsSkipsSingleImportFiles verifies the rule skips the
+// block-level pass on empty and single-import files.
+//
+// Block-level sorting needs at least two items to make any rearrangement
+// meaningful; firing on a single-import file would be pointless churn. The
+// `len(imports) >= 2` guard exists for that reason.
+//
+// 1. Parse a source file with exactly one import declaration.
+// 2. Run the engine with formatSortImports enabled.
+// 3. Assert no block-level reorder finding fires.
+//  4. Exercise the unsafe boundary and its adjacent positive.
+//
+// @evidence contracts/testing.md#behavioral-verification The original single-import engine result must have no block-reorder finding. Empty and singleton sources stay silent under unsafe options, while two reverse imports reorder.
+// @evidence contracts/testing.md#independent-expectations Zero or one declaration has no block permutation. A literal two-declaration expected source independently defines the alphabetical unsafe order.
+// @evidence contracts/testing.md#distinguishing-cases Empty, singleton and two-item boundaries distinguish insufficient block size from a permanently disabled runtime sorter. The separate named-specifier host retains single-import local sorting.
+// @evidence contracts/testing.md#execution-ownership TestFormatSortImportsSkipsSingleImportFiles owns its original singleton diagnostic check and the authored unsafe empty/singleton negatives plus two-item full-output positive in the selected public Go unit population. Parsing, the owning rule and fixture edit observation execute in one Go process without native builds, consumer installation or product-host children.
+func TestFormatSortImportsSkipsSingleImportFiles(t *testing.T) {
+  source := "import zebra from \"zebra\";\nzebra;\n"
+  file := parseTS(t, source)
+  findings := NewEngine(RuleConfig{"format/sort-imports": SeverityError}).
+    Run([]*shimast.SourceFile{file}, nil)
+  for _, finding := range findings {
+    if finding.Message == "Imports must be sorted into canonical groups." {
+      t.Fatalf("block reorder fired on single-import file: %+v", finding)
+    }
+  }
+  assertRuleSkipsSourceWithOptions(t, "format/sort-imports", source, `{"unsafeSortRuntimeImports":true}`)
+  assertRuleSkipsSourceWithOptions(t, "format/sort-imports", "", `{"unsafeSortRuntimeImports":true}`)
+  assertFixSnapshotWithOptions(t, "format/sort-imports", "import \"./z\";\nimport \"./a\";\n", `{"unsafeSortRuntimeImports":true}`, "import \"./a\";\nimport \"./z\";\n")
+}

package/linthost/format_sort_imports_sorts_erased_type_only_block_test.go

@@ -0,0 +1,26 @@
+package linthost
+
+import "testing"
+
+// TestFormatSortImportsSortsErasedTypeOnlyBlock verifies the safe default still
+// orders declarations when every import is erased before runtime evaluation.
+//
+// Blocking every declaration-level operation would protect runtime semantics
+// but discard safe formatter value. An all-`import type` block has no module
+// evaluation order to preserve, so it remains eligible for grouping and sort.
+//
+//  1. Parse two type-only imports in reverse lexical order.
+//  2. Apply format/sort-imports without unsafe options.
+//  3. Assert the erased declarations sort alphabetically.
+//
+// @evidence contracts/testing.md#behavioral-verification Safe default sorting must place erased Alpha before Zebra while preserving both clause-level type-only bindings.
+// @evidence contracts/testing.md#independent-expectations The official TypeScript module contract erases import type declarations, so they add no runtime dependency ordering. The literal output independently fixes alphabetical order and preserves type-only form.
+// @evidence contracts/testing.md#distinguishing-cases All declarations are erased and unsafe permission is absent. Runtime and inline-type blocks stay protected in separate hosts, and same-module type-only merging supplies another safe positive.
+// @evidence contracts/testing.md#execution-ownership TestFormatSortImportsSortsErasedTypeOnlyBlock owns its literal erased-type source and complete default-options sorted output in the selected public Go unit population. Parsing, owning syntax rule and fixture observations execute in one Go process without native builds, consumer installation or real product-host children.
+func TestFormatSortImportsSortsErasedTypeOnlyBlock(t *testing.T) {
+  source := "import type { Zebra } from \"zebra\";\n" +
+    "import type { Alpha } from \"alpha\";\n"
+  expected := "import type { Alpha } from \"alpha\";\n" +
+    "import type { Zebra } from \"zebra\";\n"
+  assertFixSnapshot(t, "format/sort-imports", source, expected)
+}

package/linthost/format_sort_imports_sorts_named_specifiers_without_reordering_runtime_imports_test.go

@@ -0,0 +1,28 @@
+package linthost
+
+import "testing"
+
+// TestFormatSortImportsSortsNamedSpecifiersWithoutReorderingRuntimeImports
+// verifies safe local formatting remains active inside a protected value block.
+//
+// The runtime guard applies only to declaration-level reconstruction. Named
+// specifier order has no effect on dependency evaluation, so the rule should
+// still fix `{ zebra, alpha }` without moving its declaration across a sibling.
+//
+//  1. Parse reverse-lexical runtime declarations and one unsorted named list.
+//  2. Apply format/sort-imports with safe defaults.
+//  3. Assert only the named list changes and declaration order remains intact.
+//
+// @evidence contracts/testing.md#behavioral-verification Safe defaults must change the first list to alpha,zebra while keeping b before a as dependency declaration order and retaining the complete console use.
+// @evidence contracts/testing.md#independent-expectations The public safe contract permits local named-specifier sorting without runtime declaration movement. Literal whole-file output independently distinguishes these two orderings and retains binding meaning.
+// @evidence contracts/testing.md#distinguishing-cases A runtime block is reverse lexical by module and its first named list is reverse lexical by binding. The output changes only the safe list, contrasting unsafe whole-block reordering and comment protection.
+// @evidence contracts/testing.md#execution-ownership TestFormatSortImportsSortsNamedSpecifiersWithoutReorderingRuntimeImports owns its literal mixed-runtime source and complete local-list-only expected edit in the selected public Go unit population. Parsing, owning syntax rule and fixture observations execute in one Go process without native builds, consumer installation or real product-host children.
+func TestFormatSortImportsSortsNamedSpecifiersWithoutReorderingRuntimeImports(t *testing.T) {
+  source := "import { zebra, alpha } from \"./b\";\n" +
+    "import value from \"./a\";\n" +
+    "console.log(alpha, zebra, value);\n"
+  expected := "import { alpha, zebra } from \"./b\";\n" +
+    "import value from \"./a\";\n" +
+    "console.log(alpha, zebra, value);\n"
+  assertFixSnapshot(t, "format/sort-imports", source, expected)
+}

package/linthost/format_sort_imports_treats_inline_type_bindings_as_runtime_import_test.go

@@ -0,0 +1,24 @@
+package linthost
+
+import "testing"
+
+// TestFormatSortImportsTreatsInlineTypeBindingsAsRuntimeImport verifies only a
+// clause-level `import type` declaration enters the erased-block safe path.
+//
+// `import { type T }` still uses a runtime import declaration and can become an
+// evaluating `import {}` under verbatim module syntax. Classifying it from the
+// specifier modifier would therefore weaken the evaluation-order guard.
+//
+//  1. Parse an inline-type binding before a lexically earlier type-only import.
+//  2. Apply format/sort-imports with safe defaults.
+//  3. Assert the mixed runtime/type block remains unchanged.
+//
+// @evidence contracts/testing.md#behavioral-verification The inline-type Zebra declaration must remain before clause-level type Alpha with zero findings under safe defaults.
+// @evidence contracts/testing.md#independent-expectations The supported runtime guard distinguishes clause-level import type from a normal import containing inline type bindings. The literal source must be preserved because verbatim module syntax can retain an evaluating empty import.
+// @evidence contracts/testing.md#distinguishing-cases Every binding appears type-related but only Alpha is clause-level erased. The all-clause-type sorting positive distinguishes actual declaration phase from specifier spelling.
+// @evidence contracts/testing.md#execution-ownership TestFormatSortImportsTreatsInlineTypeBindingsAsRuntimeImport owns its literal inline-type/clause-type input and default-options zero-finding assertion in the selected public Go unit population. Parsing, owning syntax rule and fixture observations execute in one Go process without native builds, consumer installation or real product-host children.
+func TestFormatSortImportsTreatsInlineTypeBindingsAsRuntimeImport(t *testing.T) {
+  source := "import { type Zebra } from \"./zebra\";\n" +
+    "import type { Alpha } from \"./alpha\";\n"
+  assertRuleSkipsSource(t, "format/sort-imports", source)
+}

package/linthost/format_sort_imports_unsafe_option_reorders_runtime_imports_test.go

@@ -0,0 +1,34 @@
+package linthost
+
+import "testing"
+
+// TestFormatSortImportsUnsafeOptionReordersRuntimeImports verifies the explicit
+// unsafe option restores declaration-level sorting for runtime dependencies.
+//
+// The option is deliberately named for its semantic cost. This positive twin
+// proves it controls the runtime guard rather than becoming a documented flag
+// that the implementation silently ignores.
+//
+//  1. Parse two bare runtime imports in reverse lexical order.
+//  2. Enable unsafeSortRuntimeImports.
+//  3. Assert the declarations reorder alphabetically.
+//  4. Assert the same reversed source produces no findings without unsafe permission.
+//
+// @evidence contracts/testing.md#behavioral-verification Explicit unsafe permission must reorder bare a before z; the identical reversed input must emit no findings with safe defaults.
+// @evidence contracts/testing.md#independent-expectations The public unsafe option permits alphabetical runtime dependency sorting, while safe mode retains authored evaluation order. Independently authored literal output and zero-finding input fix both sides of that permission contract.
+// @evidence contracts/testing.md#distinguishing-cases The exact same two bare dependencies distinguish absent versus explicit runtime permission. Type-only default sorting and local named-list sorting exercise separate safe operations.
+// @evidence contracts/testing.md#execution-ownership TestFormatSortImportsUnsafeOptionReordersRuntimeImports owns its literal bare-import source and complete unsafe-mode reorder output plus its identical-input safe-mode negative in the selected public Go unit population. Parsing, owning syntax rule and fixture observations execute in one Go process without native builds, consumer installation or real product-host children.
+func TestFormatSortImportsUnsafeOptionReordersRuntimeImports(t *testing.T) {
+  source := "import \"./z\";\n" +
+    "import \"./a\";\n"
+  expected := "import \"./a\";\n" +
+    "import \"./z\";\n"
+  assertFixSnapshotWithOptions(
+    t,
+    "format/sort-imports",
+    source,
+    `{"unsafeSortRuntimeImports":true}`,
+    expected,
+  )
+  assertRuleSkipsSource(t, "format/sort-imports", source)
+}

package/linthost/format_statement_split_abstains_on_empty_statements_test.go

@@ -0,0 +1,26 @@
+package linthost
+
+import "testing"
+
+// TestFormatStatementSplitAbstainsOnEmptyStatements verifies the rule
+// ignores `;;` empty statements instead of spreading them across lines.
+//
+// Empty statements carry no content; splitting each onto its own line
+// only multiplies blank-ish noise. The rule abstains on
+// KindEmptyStatement, so a run of `;;;` stays put. This pins that guard.
+//
+//  1. Parse a line holding a statement followed by extra `;;`.
+//  2. Run the rule.
+//  3. Assert it emits no finding for the empty statements.
+//
+// @evidence contracts/testing.md#behavioral-verification format/statement-split must decline to split trailing empty statements after const a rather than multiplying content-free lines.
+// @evidence contracts/testing.md#independent-expectations The literal extra semicolons are empty statements with no payload; preserving them without a split follows the rule contract independently of the AST visitor.
+// @evidence contracts/testing.md#distinguishing-cases The adjacent empty-statement negative complements real two/three-statement splitting positives. This case asserts zero findings, not a source-read comparison.
+// @evidence contracts/testing.md#execution-ownership TestFormatStatementSplitAbstainsOnEmptyStatements is selected by the lint semantic-unit Evidence claim as a public Go unit. The owning formatter rule runs through the shared syntax-only rule harness on temporary fixture source; this entry owns its assertions and any named subtests without consumer installation, native product build or host process.
+func TestFormatStatementSplitAbstainsOnEmptyStatements(t *testing.T) {
+  assertRuleSkipsSource(
+    t,
+    "format/statement-split",
+    "const a = 1;;;\n",
+  )
+}

package/linthost/format_statement_split_abstains_when_block_comment_in_gap_test.go

@@ -0,0 +1,28 @@
+package linthost
+
+import "testing"
+
+// TestFormatStatementSplitAbstainsWhenBlockCommentInGap verifies the rule
+// abstains when a block comment sits in the inter-statement gap.
+//
+// The rule scans the full gap from the previous statement's end, not
+// just the immediate whitespace run before the second declaration. The
+// comment is outside that replacement span, so replacing only immediate
+// whitespace would not itself delete its bytes; the guard instead declines
+// to split this comment-bearing boundary at all.
+
+//  1. Parse two statements on one line with a block comment between them.
+//  2. Run the rule.
+//  3. Assert it emits no finding.
+//
+// @evidence contracts/testing.md#behavioral-verification format/statement-split must offer no edit for two same-line statements separated by a block comment, leaving this comment-bearing boundary unsplit.
+// @evidence contracts/testing.md#independent-expectations The literal c comment lies between two complete declarations; preserving its bytes is independent of the whitespace insertion algorithm.
+// @evidence contracts/testing.md#distinguishing-cases This full-gap comment negative complements comment-free same-line splitting and separately indented block statements; it observes no finding for this one source.
+// @evidence contracts/testing.md#execution-ownership TestFormatStatementSplitAbstainsWhenBlockCommentInGap is selected by the lint semantic-unit Evidence claim as a public Go unit. The owning formatter rule runs through the shared syntax-only rule harness on temporary fixture source; this entry owns its assertions and any named subtests without consumer installation, native product build or host process.
+func TestFormatStatementSplitAbstainsWhenBlockCommentInGap(t *testing.T) {
+  assertRuleSkipsSource(
+    t,
+    "format/statement-split",
+    "const a = 1; /*c*/ const b = 2;\n",
+  )
+}

package/linthost/format_statement_split_breaks_statements_sharing_a_line_test.go

@@ -0,0 +1,28 @@
+package linthost
+
+import "testing"
+
+// TestFormatStatementSplitBreaksStatementsSharingALine verifies
+// formatStatementSplit puts two top-level statements that share one
+// physical line onto their own lines.
+//
+// This is the headline behavior: Prettier never leaves
+// `const a = 1; let b = 2;` on one line. The rule inserts EOL + the
+// depth-0 indent ("" at top level) before the second statement.
+//
+//  1. Parse a file with two statements on a single line.
+//  2. Apply the rule's finding through the disk-backed fixer.
+//  3. Assert each statement now starts its own line.
+//
+// @evidence contracts/testing.md#behavioral-verification format/statement-split must move the second same-line declaration onto a new top-level line while retaining a=1, b=2 and their declaration kinds.
+// @evidence contracts/testing.md#independent-expectations The independent complete source literal specifies one statement per LF line; the const and let payloads are unchanged by the expected whitespace edit.
+// @evidence contracts/testing.md#distinguishing-cases This two-statement changed positive complements the already-one-per-line negative and gap-comment guard; the three-statement case owns multiple simultaneous splits.
+// @evidence contracts/testing.md#execution-ownership TestFormatStatementSplitBreaksStatementsSharingALine is a public Go unit selected by the lint semantic-unit Evidence claim. Its shared syntax-only harness invokes the owning formatter on temporary fixture source and applies its reported edits for exact output assertions in the same process, without a consumer install, native product build or host execution.
+func TestFormatStatementSplitBreaksStatementsSharingALine(t *testing.T) {
+  assertFixSnapshot(
+    t,
+    "format/statement-split",
+    "const a = 1; let b = 2;\n",
+    "const a = 1;\nlet b = 2;\n",
+  )
+}