@ttsc/lint 0.10.2 → 0.11.0-dev.20260517

package/linthost/format.go

@@ -0,0 +1,107 @@
+package linthost
+
+import (
+  "fmt"
+  "os"
+)
+
+// maxFormatPasses bounds the format cascade for the same reason
+// `maxFixPasses` does in fix.go: a rule that re-reports its own edit
+// could otherwise loop forever. Format rules touch surface details
+// (quotes, semicolons, trailing commas, import order) so a real-world
+// cascade settles in a handful of passes; the cap is the safety net,
+// not the expected steady state.
+const maxFormatPasses = 10
+
+// RunFormat implements `@ttsc/lint format` — apply format-rule edits
+// only. Write-only by contract: no diagnostic output, no typecheck
+// recheck. Mirrors RunFix in flag handling so the host launcher can
+// forward the same option shape.
+func RunFormat(args []string) int {
+  opts, err := parseSubcommandFlags("format", args)
+  if err != nil {
+    fmt.Fprintln(os.Stderr, err)
+    return 2
+  }
+  if opts.emit {
+    fmt.Fprintln(os.Stderr, "@ttsc/lint format: --emit is not supported")
+    return 2
+  }
+  opts.noEmit = true
+  return runFormat(opts)
+}
+
+func runFormat(opts *subcommandOpts) int {
+  rules, err := loadRules(opts.pluginsJSON, opts.cwd, opts.tsconfig)
+  if err != nil {
+    fmt.Fprintln(os.Stderr, err)
+    return 2
+  }
+
+  prog, code := loadFixProgram(opts)
+  if code != 0 {
+    return code
+  }
+  defer func() {
+    if prog != nil {
+      prog.close()
+    }
+  }()
+
+  totalFixes := 0
+  cascadeConverged := false
+  for pass := 0; pass < maxFormatPasses; pass++ {
+    engine := NewEngineWithResolver(rules)
+    findings := engine.Run(prog.userSourceFiles(), prog.checker)
+    fixed, err := applyFindingFixes(opts.cwd, filterFormatFindings(findings))
+    if err != nil {
+      fmt.Fprintln(os.Stderr, err)
+      return 3
+    }
+    if fixed == 0 {
+      cascadeConverged = true
+      break
+    }
+    totalFixes += fixed
+    prog, code = reloadFixProgram(prog, opts)
+    if code != 0 {
+      return code
+    }
+  }
+  if !cascadeConverged {
+    // Format runs are write-only by contract, so a non-converged exit
+    // leaves the user's files in a partially-formatted state with no
+    // diagnostic surface to expose the cause. Emit an explicit signal
+    // and a non-zero exit code so a CI gate like
+    // `ttsc format && echo done` does not silently accept the
+    // non-idempotent state.
+    fmt.Fprintf(os.Stderr,
+      "@ttsc/lint: format cascade did not converge after %d passes; rerun or check for a non-idempotent format rule\n",
+      maxFormatPasses)
+    return 2
+  }
+
+  if opts.verbose && totalFixes > 0 {
+    fmt.Fprintf(os.Stdout, "@ttsc/lint: formatted=%d edits\n", totalFixes)
+  }
+  return 0
+}
+
+// filterFormatFindings keeps only findings produced by FormatRule
+// implementations that also carry at least one autofix edit.
+// `RunFormat` calls this so the format-only subcommand never applies
+// lint-class edits, and so a contributor format rule that reports a
+// fixable diagnostic via bare `ctx.Report` (no edits attached) does
+// not silently disappear — format mode is write-only, so a no-edit
+// finding has nothing to do here. `RunFix`, by contrast, applies
+// every finding regardless of category — fix is the run-everything
+// entry point.
+func filterFormatFindings(findings []*Finding) []*Finding {
+  out := make([]*Finding, 0, len(findings))
+  for _, finding := range findings {
+    if finding != nil && finding.IsFormat && len(finding.Fix) > 0 {
+      out = append(out, finding)
+    }
+  }
+  return out
+}

package/{plugin → linthost}/host.go

@@ -7,7 +7,7 @@
 // ttsc's runtime-generated go.work overlay. Instead, this file inlines a
 // minimal Program/Checker bootstrap (the same pattern documented in
 // 03-tsgo.md and used by every other source-plugin reference fixture).
-package main
+package linthost
 
 import (
   "context"

package/linthost/print_dispatch.go

@@ -0,0 +1,118 @@
+package linthost
+
+import (
+  shimast "github.com/microsoft/typescript-go/shim/ast"
+  shimscanner "github.com/microsoft/typescript-go/shim/scanner"
+)
+
+// AST → Doc dispatcher.
+//
+// The dispatcher is the bridge between the TypeScript-Go AST and the
+// printer engine. It walks one node at a time and emits a Doc tree
+// shaped to that node's grammar. Coverage is intentionally partial in
+// v1; the verbatim fallback below guarantees that an un-handled node
+// kind contributes its original source bytes verbatim, so the printer
+// can be wired up to a rule without breaking files that happen to use
+// shapes the per-node printers don't yet understand.
+//
+// The price of verbatim fallback is that reflow stops at the boundary
+// of an un-handled node. A long line buried inside an expression the
+// dispatcher doesn't recognize stays long. That trade-off is preferable
+// to corrupting unfamiliar shapes — extension over time turns each
+// verbatim hop into a real reflow.
+
+// PrintContext bundles the per-file inputs every per-node printer
+// needs. The dispatcher constructs one per top-level reflow and threads
+// it into every recursive call.
+type PrintContext struct {
+  File   *shimast.SourceFile
+  Source string
+  Opts   PrintOptions
+}
+
+// NewPrintContext returns a context wired to `file` and `opts`. The
+// helper exists so call sites do not have to remember to read
+// `file.Text()` and Opts defaults at every level.
+func NewPrintContext(file *shimast.SourceFile, opts PrintOptions) *PrintContext {
+  if opts.PrintWidth == 0 {
+    opts = DefaultPrintOptions()
+  }
+  return &PrintContext{File: file, Source: file.Text(), Opts: opts}
+}
+
+// PrintNode is the dispatcher entry. It picks a per-node printer based
+// on `node.Kind` and falls back to the verbatim source slice when no
+// printer is registered. Returns the printed Doc and a boolean
+// indicating whether the dispatch actually reformatted the node. The
+// boolean is currently only used by the format/print-width rule, which
+// skips edit emission when every printable child fell back to
+// verbatim (no behavior change, no diagnostic).
+func PrintNode(ctx *PrintContext, node *shimast.Node) (Doc, bool) {
+  if node == nil {
+    return Doc{}, false
+  }
+  if doc, reformatted, ok := dispatchNode(ctx, node); ok {
+    return doc, reformatted
+  }
+  return verbatim(ctx, node), false
+}
+
+// dispatchNode is the per-kind switch. Each branch returns
+// (doc, reformatted, true) when it produces a structured Doc, or
+// (zero, false, false) to let the caller fall back to verbatim. The
+// reformatted flag is true when the per-node printer asserts the
+// result may differ from the original bytes.
+func dispatchNode(ctx *PrintContext, node *shimast.Node) (Doc, bool, bool) {
+  switch node.Kind {
+  case shimast.KindObjectLiteralExpression:
+    return printObjectLiteral(ctx, node), true, true
+  case shimast.KindArrayLiteralExpression:
+    return printArrayLiteral(ctx, node), true, true
+  case shimast.KindCallExpression:
+    return printCallExpression(ctx, node), true, true
+  case shimast.KindNewExpression:
+    return printNewExpression(ctx, node), true, true
+  case shimast.KindNamedImports:
+    return printNamedImports(ctx, node), true, true
+  case shimast.KindNamedExports:
+    return printNamedExports(ctx, node), true, true
+  case shimast.KindImportDeclaration:
+    return printImportDeclaration(ctx, node), true, true
+  }
+  return Doc{}, false, false
+}
+
+// verbatim returns the original source bytes for `node`, leading trivia
+// trimmed. Use this whenever a printer cannot fully cover a node — the
+// surrounding doc tree still flows, but the verbatim slice carries
+// whatever the user wrote, including comments and embedded line breaks.
+func verbatim(ctx *PrintContext, node *shimast.Node) Doc {
+  if node == nil {
+    return Doc{}
+  }
+  start := shimscanner.SkipTrivia(ctx.Source, node.Pos())
+  end := node.End()
+  if start < 0 || end < start || end > len(ctx.Source) {
+    return Doc{}
+  }
+  return Text(ctx.Source[start:end])
+}
+
+// verbatimRange is the position-only sibling of verbatim — useful when
+// the printer needs to copy a sub-range that does not correspond to a
+// single AST node (e.g. tokens between two siblings).
+func verbatimRange(src string, start, end int) Doc {
+  if start < 0 || end < start || end > len(src) {
+    return Doc{}
+  }
+  return Text(src[start:end])
+}
+
+// indentUnit returns one indentation step's worth of columns. Each
+// per-node printer uses this for its own list nesting.
+func (ctx *PrintContext) indentUnit() int {
+  if ctx.Opts.TabWidth > 0 {
+    return ctx.Opts.TabWidth
+  }
+  return 2
+}

package/linthost/print_doc.go

@@ -0,0 +1,168 @@
+package linthost
+
+// Pretty-printer doc IR.
+//
+// This file defines the abstract layout language consumed by the printer
+// engine in print_engine.go. The design is a Go port of the Wadler /
+// Lindig algebra of pretty-printers that Prettier and dprint implement:
+// a node-level printer translates an AST node into a tree of Doc
+// values, and the engine lays the tree out under a width budget,
+// breaking groups whose flat form would overflow.
+//
+// Doc is intentionally a sum type encoded as a tagged struct rather than
+// an interface. The hot path of the engine is a tight loop over a slice
+// of (indent, mode, doc) frames; an interface dispatch per node would
+// dominate the cost. The tag is a small enum (DocKind) and each field is
+// only read by the case that owns it.
+//
+// Layout contract:
+//
+//   - DocText is verbatim output. The printer never reflows or wraps it.
+//     The caller is responsible for keeping its width meaningful — a
+//     text fragment longer than printWidth still flows verbatim, but it
+//     will force surrounding groups to break.
+//   - DocLine renders as either a single space or a newline + indent,
+//     depending on the surrounding group's chosen mode. Use this for
+//     soft separators (e.g. between call arguments).
+//   - DocSoftline is the empty-or-newline variant: flat mode emits
+//     nothing, break mode emits a newline + indent.
+//   - DocHardline always emits a newline and propagates "break" upward to
+//     every enclosing group. Use it for declarations that must stand on
+//     their own line regardless of width.
+//   - DocLiteralline is a hardline that does NOT emit indentation after
+//     the newline. Used for template-literal interior lines where the
+//     original spacing must be preserved.
+//   - DocGroup is the fit-or-break primitive: the engine measures the
+//     group's flat width; if it fits in the remaining column budget the
+//     group renders flat (Lines collapse to spaces, Softlines to
+//     nothing), otherwise it breaks (Lines and Softlines emit
+//     newline+indent).
+//   - DocIndent adds N columns of indentation to every newline emitted
+//     by its child doc. Nesting composes: an Indent inside another
+//     Indent adds the two amounts.
+//   - DocAlign is like Indent but the increment is the current output
+//     column rather than a fixed offset. Used to align continuation
+//     lines under an opening token (e.g. inside a call expression's
+//     arguments).
+//   - DocIfBreak renders one doc when the surrounding group breaks and
+//     another when it stays flat. The canonical use is a trailing comma
+//     that should appear only in multi-line lists.
+//   - DocConcat is a sequence of child docs. The printer flattens nested
+//     concats inline.
+//   - DocLineSuffix queues output until the next hardline/softline that
+//     actually breaks; used for trailing line comments that must stick
+//     to their source line.
+//
+// The doc tree is built by helper constructors (Text, Line, Group, …)
+// below. Constructors take their children as variadic or slice
+// arguments so call sites read like a layout DSL.
+type DocKind uint8
+
+const (
+  docNil DocKind = iota
+  docText
+  docLine
+  docSoftline
+  docHardline
+  docLiteralline
+  docGroup
+  docIndent
+  docAlign
+  docIfBreak
+  docConcat
+  docLineSuffix
+)
+
+// Doc is one node in the layout tree. Only the fields relevant to the
+// kind are populated; the rest stay at their zero value.
+//
+// Doc is a value type. Helper constructors return a fresh Doc, so the
+// caller never needs to copy. The engine reads Doc trees but never
+// mutates them, so concurrent prints over a shared tree are safe.
+//
+// The `Width` field carries the column increment for `docIndent`
+// nodes. It is named `Width` rather than `Indent` to avoid a
+// collision with the `Indent()` constructor, which would otherwise
+// shadow the field name at every constructor body.
+type Doc struct {
+  Kind     DocKind
+  Text     string
+  Children []Doc
+  Width    int
+  // IfBreak pairs: BreakChild stored in Children[0], FlatChild in Children[1].
+}
+
+// Text constructs a verbatim text doc.
+func Text(s string) Doc { return Doc{Kind: docText, Text: s} }
+
+// Line is the soft separator: space when flat, newline+indent when broken.
+func Line() Doc { return Doc{Kind: docLine} }
+
+// Softline is the empty-or-newline separator.
+func Softline() Doc { return Doc{Kind: docSoftline} }
+
+// Hardline forces a newline and propagates break upward.
+func Hardline() Doc { return Doc{Kind: docHardline} }
+
+// Literalline is a hardline that emits the newline without applying
+// indentation. The next characters appear in column 0 of the new line.
+func Literalline() Doc { return Doc{Kind: docLiteralline} }
+
+// Group wraps a child doc in a fit-or-break decision. Variadic args are
+// concatenated.
+func Group(parts ...Doc) Doc { return Doc{Kind: docGroup, Children: parts} }
+
+// Indent adds `width` columns of indentation to every newline emitted by
+// the child doc. Nesting composes.
+func Indent(width int, parts ...Doc) Doc {
+  return Doc{Kind: docIndent, Width: width, Children: parts}
+}
+
+// Align makes every newline emitted by the child doc align to the
+// current output column rather than to a fixed indent.
+func Align(parts ...Doc) Doc { return Doc{Kind: docAlign, Children: parts} }
+
+// IfBreak emits `whenBroken` when the surrounding group breaks and
+// `whenFlat` when it stays flat. The two arguments are stored as
+// Children[0] and Children[1] respectively.
+func IfBreak(whenBroken, whenFlat Doc) Doc {
+  return Doc{Kind: docIfBreak, Children: []Doc{whenBroken, whenFlat}}
+}
+
+// Concat sequences child docs. Empty Concat is the layout no-op.
+func Concat(parts ...Doc) Doc {
+  if len(parts) == 1 {
+    return parts[0]
+  }
+  return Doc{Kind: docConcat, Children: parts}
+}
+
+// LineSuffix queues output until the next line break. Used for trailing
+// line comments that must appear after the current source line ends.
+func LineSuffix(parts ...Doc) Doc {
+  return Doc{Kind: docLineSuffix, Children: parts}
+}
+
+// Join interleaves `sep` between the entries of `parts` and returns the
+// flattened concat. Empty input returns a no-op doc. Single-entry input
+// returns the entry verbatim.
+func Join(sep Doc, parts []Doc) Doc {
+  switch len(parts) {
+  case 0:
+    return Doc{Kind: docNil}
+  case 1:
+    return parts[0]
+  }
+  out := make([]Doc, 0, len(parts)*2-1)
+  for i, p := range parts {
+    if i > 0 {
+      out = append(out, sep)
+    }
+    out = append(out, p)
+  }
+  return Concat(out...)
+}
+
+// IsNil reports whether the doc is the zero-value no-op. Helpful when a
+// helper returns "nothing to print" — the engine ignores nil docs.
+func (d Doc) IsNil() bool { return d.Kind == docNil }