@ttsc/lint 0.30.3 → 0.31.0

package/linthost/format_indent_normalizes_same_line_decorated_member_test.go

@@ -0,0 +1,49 @@
+package linthost
+
+import (
+  "testing"
+
+  shimast "github.com/microsoft/typescript-go/shim/ast"
+)
+
+// TestFormatIndentNormalizesSameLineDecoratedMember verifies a member whose
+// decorator and declaration share one physical line is re-indented exactly
+// once, to member depth.
+//
+// For `@Column() name: string` the decorator's End() and the declaration
+// start resolve to the same physical line the decorator pass already
+// handles, so the second re-indent must be a no-op rather than a duplicate
+// or conflicting edit. This guards the same-line decorator boundary.
+//
+//  1. Parse a class with a single same-line decorated member at column 0.
+//  2. Apply the format/indent finding through the disk-backed fixer.
+//  3. Assert the one line lands at two spaces and is otherwise untouched.
+//  4. Require one finding with exactly one insertion before the decorator.
+//
+// @evidence contracts/testing.md#behavioral-verification format/indent must insert two spaces before the same-line decorator/member exactly once. The original full snapshot plus one finding with one exact zero-width insertion distinguishes redundant or conflicting duplicate edits that equal final bytes could hide.
+// @evidence contracts/testing.md#independent-expectations The supported class-member column independently requires only two leading spaces; decorator and declaration already share one physical line. Literal byte offsets identify its start, and all member content must remain unchanged.
+// @evidence contracts/testing.md#distinguishing-cases This positive puts both decorator and declaration on the same line at column zero. Direct exact edit-count/range/text assertions distinguish it from the separate-line host requiring two different indentation edits.
+// @evidence contracts/testing.md#execution-ownership TestFormatIndentNormalizesSameLineDecoratedMember owns its snapshot and direct parsed-source Engine assertions in the public Go unit population. The owning operation and edit harness execute in process without consumer installation, native artifact production or a real product host.
+func TestFormatIndentNormalizesSameLineDecoratedMember(t *testing.T) {
+  assertFixSnapshot(
+    t,
+    "format/indent",
+    "class User {\n@Column() name: string = \"\";\n}\n",
+    "class User {\n  @Column() name: string = \"\";\n}\n",
+  )
+  source := "class User {\n@Column() name: string = \"\";\n}\n"
+  file := parseTSFile(t, "/virtual/main.ts", source)
+  resolver := InlineRuleResolver{Rules: RuleConfig{"format/indent": SeverityError}}
+  findings := NewEngineWithResolver(resolver).Run([]*shimast.SourceFile{file}, nil)
+  if len(findings) != 1 {
+    t.Fatalf("expected one indentation finding, got %d: %v", len(findings), findings)
+  }
+  finding := findings[0]
+  if finding.Rule != "format/indent" || !finding.IsFormat || len(finding.Fix) != 1 {
+    t.Fatalf("same-line decorator must not create duplicate indentation edits: %+v", finding)
+  }
+  edit := finding.Fix[0]
+  if edit.Pos != len("class User {\n") || edit.End != edit.Pos || edit.Text != "  " {
+    t.Fatalf("expected one insertion before the decorator: %+v", edit)
+  }
+}

package/linthost/format_indent_normalizes_switch_case_body_depth_test.go

@@ -0,0 +1,29 @@
+package linthost
+
+import "testing"
+
+// TestFormatIndentNormalizesSwitchCaseBodyDepth verifies a switch case
+// body lands at depth 2 (four spaces) under the default tabWidth.
+//
+// The AST is SwitchStatement -> CaseBlock -> CaseClause -> statements.
+// CaseBlock is a descend-only +1 frame and the clause adds another +1, so
+// a top-level case-body statement sits at switchDepth+2. Without the
+// CaseBlock frame the body would land one indentation level short. This pins the
+// off-by-one fix.
+//
+//  1. Parse a top-level switch whose case body is flush left.
+//  2. Apply the rule's finding through the disk-backed fixer.
+//  3. Assert the body statement is re-indented to four spaces.
+//
+// @evidence contracts/testing.md#behavioral-verification format/indent must move the flush-left break inside a switch case to four spaces. Complete source detects failing to account for the switch case-body level and retains the case selector and break semantics.
+// @evidence contracts/testing.md#independent-expectations The supported switch layout places case labels at two spaces and their statements at four. The literal expected break column is independent of the implementation frame traversal.
+// @evidence contracts/testing.md#distinguishing-cases This positive has an unbraced case-body statement at column zero. CaseBlockBodyMatchesCaseDepth covers a same-line explicit block that must not add another level.
+// @evidence contracts/testing.md#execution-ownership TestFormatIndentNormalizesSwitchCaseBodyDepth owns its literal fixture in the public Go unit population. The owning syntax-only rule and edit application execute in process without installing a consumer, building native artifacts or starting a real product host.
+func TestFormatIndentNormalizesSwitchCaseBodyDepth(t *testing.T) {
+  assertFixSnapshot(
+    t,
+    "format/indent",
+    "switch (x) {\n  case 1:\nbreak;\n}\n",
+    "switch (x) {\n  case 1:\n    break;\n}\n",
+  )
+}

package/linthost/format_indent_still_fixes_single_line_head_arrow_body_test.go

@@ -0,0 +1,27 @@
+package linthost
+
+import "testing"
+
+// TestFormatIndentStillFixesSingleLineHeadArrowBody guards against the
+// multi-line-head cede over-reaching: an arrow whose head is on ONE line
+// (`const f = () => {`) opens its block at column 0, so depth*tabWidth is
+// correct and format/indent must still fix a mis-indented body. Pairs with
+// TestFormatIndentCedesBodyUnderMultilineArrowHead.
+//
+//  1. Parse a single-line-head arrow whose body statement has no indent.
+//  2. Apply format/indent.
+//  3. Assert the body is indented to one level.
+//
+// @evidence contracts/testing.md#behavioral-verification format/indent must indent the flush-left statement inside an ordinary one-head arrow by two spaces. Complete output distinguishes an overly broad continuation-body exclusion that cedes every arrow.
+// @evidence contracts/testing.md#independent-expectations The supported ordinary block indentation applies when the arrow header starts on its initializer line. Literal expected source retains the variable declaration without adding a semicolon, since this rule only owns indentation.
+// @evidence contracts/testing.md#distinguishing-cases This positive has a single-line arrow header at the top-level column. CedesBodyUnderMultilineArrowHead supplies the chained/wrapped negative and CedesCallbackArgumentBody supplies expression-owned callback layout.
+// @evidence contracts/testing.md#execution-ownership TestFormatIndentStillFixesSingleLineHeadArrowBody owns the literal source/options/output in the public Go unit population. The syntax-only owning rule and edit harness execute in process without a consumer install, native artifact build or product host.
+func TestFormatIndentStillFixesSingleLineHeadArrowBody(t *testing.T) {
+  assertFixSnapshotWithOptions(
+    t,
+    "format/indent",
+    "const f = () => {\nconst x = 1\n}\n",
+    `{"tabWidth":2}`,
+    "const f = () => {\n  const x = 1\n}\n",
+  )
+}

package/linthost/format_indent_strips_leading_indent_from_top_level_statement_test.go

@@ -0,0 +1,27 @@
+package linthost
+
+import "testing"
+
+// TestFormatIndentStripsLeadingIndentFromTopLevelStatement verifies
+// formatIndent removes the leading indentation of a top-level statement.
+//
+// Top-level statements live at depth 0, so the desired indent is the
+// empty string. A leading two-space run differs from "" and is replaced,
+// fixing the headline bug's stray leading indent.
+//
+//  1. Parse a file whose only statement is indented two spaces.
+//  2. Apply the rule's finding through the disk-backed fixer.
+//  3. Assert the statement now starts at column 0.
+//
+// @evidence contracts/testing.md#behavioral-verification format/indent must remove the two-space prefix from a top-level const statement. Complete source detects retaining stray leading indentation or altering the declaration while moving it.
+// @evidence contracts/testing.md#independent-expectations The supported top-level column is zero, so the literal expected source has no leading whitespace. The binding, initializer and terminator remain identical independently of the rule depth calculation.
+// @evidence contracts/testing.md#distinguishing-cases This singleton top-level positive repairs two spaces to the empty indentation run. Ordinary block and class-method positives cover nonzero destinations, while fixed-point hosts cover already-correct indentation.
+// @evidence contracts/testing.md#execution-ownership TestFormatIndentStripsLeadingIndentFromTopLevelStatement owns its literal source/output in the public Go unit population. The owning syntax-only rule and edit application run in process without consumer installation, native artifact production or a real product host.
+func TestFormatIndentStripsLeadingIndentFromTopLevelStatement(t *testing.T) {
+  assertFixSnapshot(
+    t,
+    "format/indent",
+    "  const a = 1;\n",
+    "const a = 1;\n",
+  )
+}

package/linthost/format_jsdoc_honors_custom_tag_synonyms_option_test.go

@@ -0,0 +1,26 @@
+package linthost
+
+import "testing"
+
+// TestFormatJSDocHonorsCustomTagSynonymsOption verifies the
+// `tagSynonyms` option layers on top of the built-in synonym table.
+//
+// User-supplied entries must augment the defaults, not replace them, so a
+// project can normalize a private convention (here `@property` → `@prop`)
+// without losing the standard `@return` → `@returns` rewrite. This pins
+// the merge semantics.
+//
+//  1. Configure a custom synonym not in the default table.
+//  2. Run the rule against a block exercising both the custom synonym and
+//     a default one.
+//  3. Assert both rewrites land.
+//
+// @evidence contracts/testing.md#behavioral-verification The owning JSDoc rule must rewrite property to prop and return to returns in one comment. Complete source detects replacing the built-in table with the custom table and preserves both tag descriptions and function code.
+// @evidence contracts/testing.md#independent-expectations The supported tagSynonyms option augments the built-in canonical aliases. Literal expected prop and returns spellings follow that option contract and JSDoc canonical return naming, independently of the implementation synonym map.
+// @evidence contracts/testing.md#distinguishing-cases The block contains both a valid custom alias and a built-in alias. RejectsMalformedTagSynonymValue covers invalid custom values, while SkipsCanonicalTags covers already canonical spellings.
+// @evidence contracts/testing.md#execution-ownership TestFormatJSDocHonorsCustomTagSynonymsOption owns its source, option and literal complete output in the public Go unit population. The syntax-only owning rule and edit harness run in process without installing a consumer, building native artifacts or starting a product host.
+func TestFormatJSDocHonorsCustomTagSynonymsOption(t *testing.T) {
+  source := "/**\n * @property name\n * @return greeting\n */\nexport function greet(): string { return \"hi\"; }\n"
+  want := "/**\n * @prop name\n * @returns greeting\n */\nexport function greet(): string { return \"hi\"; }\n"
+  assertFixSnapshotWithOptions(t, "format/jsdoc", source, `{"tagSynonyms":{"property":"prop"}}`, want)
+}

package/linthost/format_jsdoc_preserves_example_block_body_test.go

@@ -0,0 +1,63 @@
+package linthost
+
+import (
+  "strings"
+  "testing"
+
+  shimast "github.com/microsoft/typescript-go/shim/ast"
+)
+
+// TestFormatJSDocPreservesExampleBlockBody verifies the rule does not
+// rewrite tag synonyms inside an `@example` block.
+//
+// `@example` is JSDoc's sample-code tag. Its body is
+// free-form code that often quotes JSDoc itself, including the
+// synonyms (`@arg`, `@return`) the rule normally rewrites. A regression
+// that rewrote them inside the example would corrupt the documented
+// sample. The rule fast-forwards past the example body to the next
+// top-level `@` at line start.
+//
+//  1. Parse a JSDoc block containing one synonym outside `@example`
+//     (must be rewritten) and one synonym inside (must be preserved).
+//  2. Run formatJsdoc.
+//  3. Require the exact outer-tag edit and complete output preserving the sample.
+//  4. Add a synonym after the example and require normalization to resume.
+//
+// @evidence contracts/testing.md#behavioral-verification The owning JSDoc rule must rewrite only the outer return tag, preserve sample-code tag text, and resume normalization after the example. The original count assertion remains, strengthened by exact sole outer-tag edit and complete source oracles that expose wrong-position or skipped-recovery findings.
+// @evidence contracts/testing.md#independent-expectations The supported example-content policy leaves free-form sample bytes intact, while JSDoc recognizes return and arg as aliases of returns and param. Expected changes replace only explicitly named outer block-tag spellings; no expected edit is computed by the rule.
+// @evidence contracts/testing.md#distinguishing-cases The original example contains an outer return positive and an inner return negative, followed by a canonical description. An added variant puts arg after the example and requires its param rewrite, distinguishing resumption from skipping the rest of the block.
+// @evidence contracts/testing.md#execution-ownership TestFormatJSDocPreservesExampleBlockBody owns every literal/derived source variant, direct parsed-source Engine finding and full edit-output assertion in the public Go unit population. Only the owning rule and in-process edit harness run; there is no consumer install, native build or real product host.
+func TestFormatJSDocPreservesExampleBlockBody(t *testing.T) {
+  source := "/**\n" +
+    " * Outer description.\n" +
+    " * @return {number} the outer doc that gets rewritten\n" +
+    " * @example\n" +
+    " * function demo() {\n" +
+    " *   // @return inside example body — should NOT be rewritten\n" +
+    " * }\n" +
+    " * @description trailing canonical tag closes the example\n" +
+    " */\n" +
+    "export const value = 1;\n"
+  file := parseTS(t, source)
+  findings := NewEngine(RuleConfig{"format/jsdoc": SeverityError}).
+    Run([]*shimast.SourceFile{file}, nil)
+  if len(findings) != 1 {
+    t.Fatalf("expected 1 finding (only the outer @return → @returns), got %d:\n%v",
+      len(findings), findings)
+  }
+  finding := findings[0]
+  if finding.Rule != "format/jsdoc" || !finding.IsFormat || len(finding.Fix) != 1 {
+    t.Fatalf("expected only the outer tag-name edit: %+v", finding)
+  }
+  edit := finding.Fix[0]
+  start := strings.Index(source, "@return") + 1
+  if edit.Pos != start || edit.End != start+len("return") || edit.Text != "returns" {
+    t.Fatalf("tag edit must exclude example content: %+v", edit)
+  }
+  assertFixSnapshot(t, "format/jsdoc", source,
+    strings.Replace(source, "@return {number}", "@returns {number}", 1))
+  following := strings.Replace(source, "@description trailing canonical tag closes the example", "@arg trailing parameter", 1)
+  followingWant := strings.Replace(following, "@return {number}", "@returns {number}", 1)
+  followingWant = strings.Replace(followingWant, "@arg trailing parameter", "@param trailing parameter", 1)
+  assertFixSnapshot(t, "format/jsdoc", following, followingWant)
+}

package/linthost/format_jsdoc_rejects_malformed_tag_synonym_value_test.go

@@ -0,0 +1,60 @@
+package linthost
+
+import (
+  "encoding/json"
+  "testing"
+
+  shimast "github.com/microsoft/typescript-go/shim/ast"
+)
+
+// TestFormatJSDocRejectsMalformedTagSynonymValue verifies the rule
+// silently drops user-supplied tagSynonyms entries whose canonical
+// value is empty or carries non-identifier bytes.
+//
+// A user passing `tagSynonyms: { "return": "" }` (or `"my tag"`,
+// `"returns!"`, etc.) would otherwise see the fixer emit a malformed
+// JSDoc tag like a bare `@`. The rule rejects those entries while
+// keeping the rest of the user's synonym table intact, so a single
+// typo doesn't poison every JSDoc block in the project.
+//
+//  1. Configure the rule with a malformed `tagSynonyms` value alongside
+//     a valid one.
+//  2. Run formatJsdoc on a source containing both candidate tags.
+//  3. Assert the built-in return alias and valid custom property alias
+//     both rewrite; malformed overrides must not replace the default.
+//
+// @evidence contracts/testing.md#behavioral-verification The owning JSDoc rule must reject malformed return overrides while retaining its built-in return-to-returns mapping and the valid property-to-prop entry. The original two-finding assertion remains and complete output prevents duplicated wrong-position findings from satisfying that count.
+// @evidence contracts/testing.md#independent-expectations The supported option policy accepts alphabetic canonical tag names and drops invalid overrides without deleting built-ins. Literal returns/prop output and unchanged descriptions independently establish successful recovery.
+// @evidence contracts/testing.md#distinguishing-cases The original empty return override stays. Empty, space-containing my tag and punctuation-containing returns! are each paired with a valid custom property alias; every variant requires both the default and valid custom rewrites.
+// @evidence contracts/testing.md#execution-ownership TestFormatJSDocRejectsMalformedTagSynonymValue owns the original direct Engine assertion and every malformed option/source/output variant in the public Go unit population. The owning rule and edit harness execute in process without consumer installation, native artifact production or a product host.
+func TestFormatJSDocRejectsMalformedTagSynonymValue(t *testing.T) {
+  source := "/** @return number\n * @property name */\nexport const value = 1;\n"
+  file := parseTS(t, source)
+  resolver := InlineRuleResolver{
+    Rules: RuleConfig{"format/jsdoc": SeverityError},
+    Options: RuleOptionsMap{
+      // `return` → "" is malformed (would emit bare `@`).
+      // `property` → "prop" is well-formed and should fire.
+      "format/jsdoc": json.RawMessage(`{"tagSynonyms":{"return":"","property":"prop"}}`),
+    },
+  }
+  findings := NewEngineWithResolver(resolver).Run([]*shimast.SourceFile{file}, nil)
+  // Built-in synonym table still has `@return` → `@returns`, so the
+  // malformed override gets dropped and the default value wins.
+  // Expect two findings: one for the built-in `return`→`returns`, one
+  // for the user `property`→`prop`.
+  if len(findings) != 2 {
+    t.Fatalf("expected 2 findings (return→returns built-in default + property→prop user override); got %d:\n%v",
+      len(findings), findings)
+  }
+  want := "/** @returns number\n * @prop name */\nexport const value = 1;\n"
+  for _, malformed := range []string{"", "my tag", "returns!"} {
+    options, err := json.Marshal(map[string]any{"tagSynonyms": map[string]string{
+      "return": malformed, "property": "prop",
+    }})
+    if err != nil {
+      t.Fatalf("Marshal options: %v", err)
+    }
+    assertFixSnapshotWithOptions(t, "format/jsdoc", source, string(options), want)
+  }
+}

package/linthost/format_jsdoc_rewrites_arg_synonyms_to_param_test.go

@@ -0,0 +1,25 @@
+package linthost
+
+import "testing"
+
+// TestFormatJSDocRewritesArgSynonymsToParam verifies both
+// `@arg` and `@argument` collapse onto `@param`.
+//
+// JSDoc documents `@arg` and `@argument` as aliases of `@param`. The
+// formatter chooses the canonical spelling while preserving parameter
+// names and their descriptions.
+// The rule normalizes both onto the canonical name in one rewrite each.
+//
+// 1. Parse a source file with one JSDoc block using `@arg` and `@argument`.
+// 2. Apply the rule's findings through the disk-backed fixer.
+// 3. Assert both synonyms become `@param`.
+//
+// @evidence contracts/testing.md#behavioral-verification The owning JSDoc rule must rewrite both arg and argument to param while preserving their parameter names, descriptions and function body. Complete source catches normalizing only one alias or altering unrelated content.
+// @evidence contracts/testing.md#independent-expectations Official JSDoc parameter documentation lists arg and argument as aliases of param. The formatter supported canonical spelling supplies the two literal replacements without consulting its synonym table.
+// @evidence contracts/testing.md#distinguishing-cases The same block contains both distinct parameter aliases as positives. SkipsCanonicalTags supplies the canonical param negative, and custom-option tests distinguish table extension and malformed overrides.
+// @evidence contracts/testing.md#execution-ownership TestFormatJSDocRewritesArgSynonymsToParam owns both tag inputs and the complete expected source in the public Go unit population. The syntax-only owning rule/edit application run in process without installing a consumer, building native artifacts or starting a product host.
+func TestFormatJSDocRewritesArgSynonymsToParam(t *testing.T) {
+  source := "/**\n * @arg name The recipient name.\n * @argument greeting The greeting prefix.\n */\nexport function greet(name: string, greeting: string): string {\n  return greeting + name;\n}\n"
+  expected := "/**\n * @param name The recipient name.\n * @param greeting The greeting prefix.\n */\nexport function greet(name: string, greeting: string): string {\n  return greeting + name;\n}\n"
+  assertFixSnapshot(t, "format/jsdoc", source, expected)
+}

package/linthost/format_jsdoc_rewrites_return_to_returns_test.go

@@ -0,0 +1,24 @@
+package linthost
+
+import "testing"
+
+// TestFormatJSDocRewritesReturnToReturns verifies the canonical
+// rewrite for the most common tag synonym.
+//
+// `@return` and `@returns` are interchangeable per JSDoc grammar but the
+// canonical name is `@returns`. The formatter uses that spelling while
+// retaining the documented return description and the program bytes.
+//
+// 1. Parse a source file with one JSDoc comment containing `@return`.
+// 2. Apply the rule's finding through the disk-backed fixer.
+// 3. Assert the rewritten file uses `@returns`.
+//
+// @evidence contracts/testing.md#behavioral-verification The owning JSDoc rule must change return to returns and retain its description and function bytes. The complete output distinguishes missing normalization or editing tag content beyond its name.
+// @evidence contracts/testing.md#independent-expectations Official JSDoc return documentation names returns as the canonical tag with return as its alias. That supported spelling independently determines the literal output.
+// @evidence contracts/testing.md#distinguishing-cases This singleton return alias is a positive. SkipsCanonicalTags supplies the already-returns negative and PreservesExampleBlockBody distinguishes the same alias inside sample content.
+// @evidence contracts/testing.md#execution-ownership TestFormatJSDocRewritesReturnToReturns owns its literal source/output in the public Go unit population. The syntax-only owning operation and edit harness execute in process without consumer installation, native artifact production or a real product host.
+func TestFormatJSDocRewritesReturnToReturns(t *testing.T) {
+  source := "/**\n * @return The user-facing message.\n */\nexport function greet(): string { return \"hi\"; }\n"
+  expected := "/**\n * @returns The user-facing message.\n */\nexport function greet(): string { return \"hi\"; }\n"
+  assertFixSnapshot(t, "format/jsdoc", source, expected)
+}

package/linthost/format_jsdoc_skips_canonical_tags_test.go

@@ -0,0 +1,32 @@
+package linthost
+
+import (
+  "testing"
+
+  shimast "github.com/microsoft/typescript-go/shim/ast"
+)
+
+// TestFormatJSDocSkipsCanonicalTags verifies the rule is idempotent.
+//
+// A JSDoc block that already uses `@returns`, `@param`, `@description`, etc.
+// must not produce any finding. Otherwise the formatter would burn passes
+// re-reporting itself. The rule must abstain on canonical names rather
+// than returning unnecessary spelling edits.
+//
+// 1. Parse a source file with only canonical JSDoc tags.
+// 2. Run the engine with formatJsdoc enabled.
+// 3. Assert zero findings.
+//
+// @evidence contracts/testing.md#behavioral-verification The owning JSDoc rule must emit no findings for canonical param, returns and description tags. The absence oracle detects unnecessary self-rewrites that could waste cascade passes.
+// @evidence contracts/testing.md#independent-expectations The supported canonical tag spellings are already present in the authored block. Keeping them and their descriptions unchanged is determined independently of the implementation alias lookup.
+// @evidence contracts/testing.md#distinguishing-cases The negative combines three canonical names. Return and argument synonym hosts supply the positive transformations, so this fixed-point case does not stand in for normalization correctness.
+// @evidence contracts/testing.md#execution-ownership TestFormatJSDocSkipsCanonicalTags owns its parsed source and direct Engine no-finding assertion in the public Go unit population. The rule executes in process without installing a consumer, building native artifacts or starting a product host.
+func TestFormatJSDocSkipsCanonicalTags(t *testing.T) {
+  source := "/**\n * @param name The name.\n * @returns The greeting.\n * @description Builds a greeting.\n */\nexport function greet(name: string): string { return name; }\n"
+  file := parseTS(t, source)
+  findings := NewEngine(RuleConfig{"format/jsdoc": SeverityError}).
+    Run([]*shimast.SourceFile{file}, nil)
+  if len(findings) != 0 {
+    t.Fatalf("expected zero findings, got %d: %+v", len(findings), findings)
+  }
+}

package/linthost/format_jsdoc_skips_inline_at_text_test.go

@@ -0,0 +1,34 @@
+package linthost
+
+import (
+  "testing"
+
+  shimast "github.com/microsoft/typescript-go/shim/ast"
+)
+
+// TestFormatJSDocSkipsInlineAtText verifies the rule does not
+// rewrite `@`-prefixed words that are part of prose.
+//
+// In `user@return-handler@example.com`, each at sign follows letters
+// rather than a tag-opening boundary. Preserving these bytes while a real
+// neighboring return tag changes distinguishes prose from a block tag.
+//
+// 1. Parse email-like prose alone and beside a real return-tag block.
+// 2. Run the engine with formatJsdoc enabled.
+// 3. Assert no findings for prose alone and only the real tag changes.
+//
+// @evidence contracts/testing.md#behavioral-verification The owning JSDoc rule must preserve both at-sign sequences inside the email-like prose while normalizing an adjacent real return tag. The original no-finding assertion remains, and full paired output distinguishes excluding prose from skipping every comment.
+// @evidence contracts/testing.md#independent-expectations The literal user@return-handler@example.com is authored description text, so its bytes must remain intact. The supported canonical return spelling independently determines the sole adjacent returns change.
+// @evidence contracts/testing.md#distinguishing-cases The original email-only negative has at signs preceded by letters. Adding a separate real return-tag block supplies a neighboring positive; this host does not claim every whitespace-preceded at sign inside prose is recognized correctly.
+// @evidence contracts/testing.md#execution-ownership TestFormatJSDocSkipsInlineAtText owns the original direct Engine no-finding assertion and paired source/output in the public Go unit population. The owning rule and edit harness run in process without consumer installation, native artifact building or a real product host.
+func TestFormatJSDocSkipsInlineAtText(t *testing.T) {
+  source := "/**\n * Mailto: user@return-handler@example.com\n */\nexport const x = 1;\n"
+  file := parseTS(t, source)
+  findings := NewEngine(RuleConfig{"format/jsdoc": SeverityError}).
+    Run([]*shimast.SourceFile{file}, nil)
+  if len(findings) != 0 {
+    t.Fatalf("expected zero findings, got %d: %+v", len(findings), findings)
+  }
+  assertFixSnapshot(t, "format/jsdoc", "/** @return number */\n"+source,
+    "/** @returns number */\n"+source)
+}

package/linthost/format_jsdoc_skips_jsdoc_like_strings_in_source_test.go

@@ -0,0 +1,41 @@
+package linthost
+
+import (
+  "testing"
+
+  shimast "github.com/microsoft/typescript-go/shim/ast"
+)
+
+// TestFormatJSDocSkipsJSDocLikeStringsInSource verifies the rule does
+// not rewrite tag synonyms inside string literals that happen to contain
+// a JSDoc-shaped substring.
+//
+// A naive byte-scan for `/**` would treat `const s = "/** @return */"`
+// as a JSDoc block and rewrite the embedded `@return`, corrupting the
+// user's runtime string data. The rule now drives off the tsgo
+// scanner's `MultiLineCommentTrivia` ranges so only real comments are
+// processed.
+//
+//  1. Parse ordinary string and template payloads with JSDoc-like text.
+//  2. Run formatJsdoc.
+//  3. Assert zero findings, then add a real comment and require only its
+//     tag spelling to change while both runtime payloads stay intact.
+//
+// @evidence contracts/testing.md#behavioral-verification The owning JSDoc rule must leave JSDoc-shaped substrings inside both an ordinary string and a template untouched while changing a neighboring real comment. The original no-finding assertion remains, and paired full output catches both corrupting runtime payload and skipping real comments.
+// @evidence contracts/testing.md#independent-expectations String and template contents are runtime data rather than comment tokens. The literal source suffix is retained byte for byte, while the supported return-to-returns alias independently supplies the real-comment replacement.
+// @evidence contracts/testing.md#distinguishing-cases The original two lexical payload negatives remain and the same source with a real return block adds an adjacent positive. PreservesExampleBlockBody covers tag-looking content inside a real documentation comment.
+// @evidence contracts/testing.md#execution-ownership TestFormatJSDocSkipsJSDocLikeStringsInSource owns the parsed lexical fixtures, direct Engine assertion and complete paired output in the public Go unit population. The owning rule and in-process edit harness use no consumer install, native build or real product host.
+func TestFormatJSDocSkipsJSDocLikeStringsInSource(t *testing.T) {
+  source := "export const s = \"/** @return number */\";\n" +
+    "export const t = `/** @arg x */`;\n" +
+    "console.log(s, t);\n"
+  file := parseTS(t, source)
+  findings := NewEngine(RuleConfig{"format/jsdoc": SeverityError}).
+    Run([]*shimast.SourceFile{file}, nil)
+  if len(findings) != 0 {
+    t.Fatalf("expected zero findings (no real JSDoc in source), got %d:\n%v",
+      len(findings), findings)
+  }
+  assertFixSnapshot(t, "format/jsdoc", "/** @return number */\n"+source,
+    "/** @returns number */\n"+source)
+}

package/linthost/format_orphan_semi_inert_under_semi_true_test.go

@@ -0,0 +1,24 @@
+package linthost
+
+import "testing"
+
+// TestFormatOrphanSemiInertUnderSemiTrue verifies the rule does not act
+// under semi:true, where the leading-semicolon guard idiom does not
+// apply and dropping a redundant `;` depends on the semicolon policy.
+//
+//  1. Parse the same guard shape with semi:true.
+//  2. Run format/orphan-semi.
+//  3. Assert the rule reports nothing.
+//
+// @evidence contracts/testing.md#behavioral-verification The owning orphan-semi rule must report nothing for a separated parenthesis guard under semi:true. The absence assertion prevents applying a no-semicolon idiom when semicolon policy excludes this rule.
+// @evidence contracts/testing.md#independent-expectations The supported rule scope is explicitly semi:false; under true it leaves the source untouched. This local no-finding contract is independent of the implementation option decoder and does not claim a complete formatter preserves redundant semicolons.
+// @evidence contracts/testing.md#distinguishing-cases The separated parenthesis guard is a negative solely because semi is true. MergesGuardUnderNoSemi supplies the parenthesis, bracket and template positives with semi:false.
+// @evidence contracts/testing.md#execution-ownership TestFormatOrphanSemiInertUnderSemiTrue owns its literal source/options and no-finding assertion in the public Go unit population. The syntax-only owning rule executes in process without consumer installation, native artifact production or a product host.
+func TestFormatOrphanSemiInertUnderSemiTrue(t *testing.T) {
+  assertRuleSkipsSourceWithOptions(
+    t,
+    "format/orphan-semi",
+    "foo();\n;\n(bar as Baz).qux();\n",
+    `{"semi":true}`,
+  )
+}

package/linthost/format_orphan_semi_merges_guard_under_no_semi_test.go

@@ -0,0 +1,35 @@
+package linthost
+
+import "testing"
+
+// TestFormatOrphanSemiMergesGuardUnderNoSemi verifies that under
+// semi:false a lone leading-semicolon ASI guard is pulled onto the
+// statement it protects.
+//
+// Prettier writes `;(expr)` rather than a standalone `;` line before a
+// `(`-leading statement. The rule deletes only the whitespace gap, so
+// the guard keeps its indent and the statement follows on the same line.
+//
+//  1. Parse separated guards before parenthesis, bracket and backtick forms.
+//  2. Apply format/orphan-semi with semi:false.
+//  3. Assert each guard merges without changing its statement.
+//  4. Require no finding when the parenthesis guard is already adjacent.
+//
+// @evidence contracts/testing.md#behavioral-verification The owning orphan-semi rule must delete the whitespace between an orphan guard and its parenthesis-, bracket- or template-leading statement, retaining the guard and every statement token. Full literal outputs catch deleting the semicolon or missing a hazard kind.
+// @evidence contracts/testing.md#independent-expectations The supported no-semicolon guard layout keeps the leading semicolon attached to the statement it protects, matching Prettier. Literal expected outputs remove only the gap and retain call, array or template content.
+// @evidence contracts/testing.md#distinguishing-cases The original parenthesis positive stays, with bracket and backtick positives added. An already adjacent parenthesis guard is a no-finding negative; sibling tests cover semi:true, comments, non-hazard successors and EOF.
+// @evidence contracts/testing.md#execution-ownership TestFormatOrphanSemiMergesGuardUnderNoSemi owns all three hazard snapshots and the canonical no-finding fixture in the public Go unit population. The syntax-only owning operation and edit application run in process without installing a consumer, building native artifacts or starting a product host.
+func TestFormatOrphanSemiMergesGuardUnderNoSemi(t *testing.T) {
+  assertFixSnapshotWithOptions(
+    t,
+    "format/orphan-semi",
+    "// guard\n;\n(bar as Baz).qux()\n",
+    `{"semi":false}`,
+    "// guard\n;(bar as Baz).qux()\n",
+  )
+  assertFixSnapshotWithOptions(t, "format/orphan-semi", ";\n[1, 2].forEach(visit)\n",
+    `{"semi":false}`, ";[1, 2].forEach(visit)\n")
+  assertFixSnapshotWithOptions(t, "format/orphan-semi", ";\n`value`\n",
+    `{"semi":false}`, ";`value`\n")
+  assertRuleSkipsSourceWithOptions(t, "format/orphan-semi", ";(bar as Baz).qux()\n", `{"semi":false}`)
+}

package/linthost/format_orphan_semi_skips_comment_between_guard_and_statement_test.go

@@ -0,0 +1,28 @@
+package linthost
+
+import "testing"
+
+// TestFormatOrphanSemiSkipsCommentBetweenGuardAndStatement verifies the
+// rule abstains when a comment sits between the leading-semicolon guard and
+// the statement it would protect. Removing that intervening span would
+// discard comment trivia, so the rule leaves the gap alone.
+//
+//  1. Parse a semicolon guard separated by a block or line comment
+//     from a parenthesis-leading statement.
+//  2. Run format/orphan-semi under semi:false.
+//  3. Assert the rule reports nothing.
+//
+// @evidence contracts/testing.md#behavioral-verification The owning orphan-semi rule must report nothing when a block or line comment separates the guard and parenthesis-leading statement. The absence assertions prevent deleting or relocating comment trivia.
+// @evidence contracts/testing.md#independent-expectations The supported safe merge only removes a whitespace gap; comment content is excluded and must remain in place. The no-finding oracle follows that ownership contract independently of the gap scanner.
+// @evidence contracts/testing.md#distinguishing-cases The original block-comment negative remains and a line-comment negative is added. MergesGuardUnderNoSemi provides the adjacent whitespace-only positive with the same hazard direction.
+// @evidence contracts/testing.md#execution-ownership TestFormatOrphanSemiSkipsCommentBetweenGuardAndStatement owns both literal comment fixtures in the public Go unit population. The owning syntax-only rule runs in process without consumer installation, native artifact building or an actual product host.
+func TestFormatOrphanSemiSkipsCommentBetweenGuardAndStatement(t *testing.T) {
+  assertRuleSkipsSourceWithOptions(
+    t,
+    "format/orphan-semi",
+    ";\n/* c */\n(bar as Baz).qux();\n",
+    `{"semi":false}`,
+  )
+  assertRuleSkipsSourceWithOptions(t, "format/orphan-semi",
+    ";\n// c\n(bar as Baz).qux();\n", `{"semi":false}`)
+}

package/linthost/format_orphan_semi_skips_non_hazard_successor_test.go

@@ -0,0 +1,29 @@
+package linthost
+
+import "testing"
+
+// TestFormatOrphanSemiSkipsNonHazardSuccessor verifies format/orphan-semi
+// leaves a standalone `;` alone when the next statement does not open with
+// an ASI-hazard token. The rule only glues a leading-semicolon guard onto
+// the statement it protects (one starting with `(`, `[`, or a backtick);
+// a `const` after the `;` is no guard, so merging would be wrong.
+//
+//  1. Parse a standalone semicolon followed by const or by EOF, with
+//     and without a final newline.
+//  2. Run format/orphan-semi under semi:false.
+//  3. Assert the rule reports nothing.
+//
+// @evidence contracts/testing.md#behavioral-verification The owning orphan-semi rule must report nothing for a const successor or an orphan semicolon at EOF. These assertions prevent merging unrelated statements or reporting an edit without any statement to protect.
+// @evidence contracts/testing.md#independent-expectations The supported guard merge requires a following parenthesis, bracket or backtick hazard. A const declaration and EOF have none, so unchanged source is required independently of the implementation byte switch.
+// @evidence contracts/testing.md#distinguishing-cases The original const-successor negative stays. Semicolon-plus-newline EOF and bare-semicolon EOF exercise both empty-successor boundaries; the merge host supplies all three actual hazard positives.
+// @evidence contracts/testing.md#execution-ownership TestFormatOrphanSemiSkipsNonHazardSuccessor owns the non-hazard and two EOF fixtures in the public Go unit population. The syntax-only owning rule executes in process without consumer installation, native artifact production or starting a product host.
+func TestFormatOrphanSemiSkipsNonHazardSuccessor(t *testing.T) {
+  assertRuleSkipsSourceWithOptions(
+    t,
+    "format/orphan-semi",
+    ";\nconst a = 1;\n",
+    `{"semi":false}`,
+  )
+  assertRuleSkipsSourceWithOptions(t, "format/orphan-semi", ";\n", `{"semi":false}`)
+  assertRuleSkipsSourceWithOptions(t, "format/orphan-semi", ";", `{"semi":false}`)
+}

package/linthost/format_parameter_properties_breaks_multi_param_constructor_test.go

@@ -0,0 +1,30 @@
+package linthost
+
+import "testing"
+
+// TestFormatParameterPropertiesBreaksMultiParamConstructor verifies a
+// constructor with two-plus parameters and at least one parameter
+// property is broken one-parameter-per-line even when the flat form fits.
+//
+// Prettier 3 force-breaks such a constructor regardless of width. The
+// rule rewrites only the `(...)` region and emits no trailing comma; the
+// trailing comma is added by format/trailing-comma once the list is
+// multi-line, so this fixture asserts only the line breaks and indent.
+//
+//  1. Parse a class with a two-parameter-property constructor.
+//  2. Apply format/parameter-properties (tabWidth 2).
+//  3. Assert each parameter lands on its own indented line.
+//
+// @evidence contracts/testing.md#behavioral-verification The owning parameter-properties rule must break the two parameter properties onto separate four-space lines while preserving constructor and class tokens. Complete output catches missing force-break or damaging modifier/type spelling.
+// @evidence contracts/testing.md#independent-expectations The supported parameter-property policy, matching Prettier constructor layout, force-breaks a multi-parameter list. This dedicated rule emits no final trailing comma because the sibling comma rule owns it; literal output reflects that scope.
+// @evidence contracts/testing.md#distinguishing-cases This positive has two explicit parameter properties under tabWidth two. The singleton, plain-parameter and decorated-plain hosts provide negatives, and CRLF and override hosts cover other decisions.
+// @evidence contracts/testing.md#execution-ownership TestFormatParameterPropertiesBreaksMultiParamConstructor owns its literal source/options/output in the public Go unit population. The syntax-only owning rule and edit application run in process without installing a consumer, building native artifacts or starting a product host.
+func TestFormatParameterPropertiesBreaksMultiParamConstructor(t *testing.T) {
+  assertFixSnapshotWithOptions(
+    t,
+    "format/parameter-properties",
+    "class A {\n  constructor(private x: Foo, public y: Bar) {}\n}\n",
+    `{"tabWidth":2}`,
+    "class A {\n  constructor(\n    private x: Foo,\n    public y: Bar\n  ) {}\n}\n",
+  )
+}