@ttsc/lint 0.12.3 → 0.12.4

package/linthost/directives.go

@@ -1,3 +1,10 @@
+// Inline-disable directive parser and filter for the lint engine.
+//
+// Supports both `eslint-disable` and `lint-disable` comment families in
+// four forms: `disable`, `enable`, `disable-line`, and
+// `disable-next-line`. Rule lists are comma- or space-separated; an
+// empty list disables all rules. The `--` description separator (ESLint
+// convention) is also recognized and stripped before parsing rule names.
 package linthost
 
 import (
@@ -7,36 +14,61 @@ import (
   shimscanner "github.com/microsoft/typescript-go/shim/scanner"
 )
 
+// lintDirectiveKind classifies the four comment forms the parser recognizes.
 type lintDirectiveKind int
 
 const (
+  // lintDirectiveDisable activates suppression from the comment position until
+  // a matching `enable` is seen (or end of file).
   lintDirectiveDisable lintDirectiveKind = iota
+  // lintDirectiveEnable cancels a prior `disable` for the named rules (or all
+  // rules when no rule list is given).
   lintDirectiveEnable
+  // lintDirectiveDisableLine suppresses findings on the same source line as
+  // the directive comment.
   lintDirectiveDisableLine
+  // lintDirectiveDisableNextLine suppresses findings on the line immediately
+  // following the directive comment.
   lintDirectiveDisableNextLine
 )
 
+// lintDirective is the parsed representation of one directive comment.
 type lintDirective struct {
   kind  lintDirectiveKind
   rules lintDirectiveRules
 }
 
+// lintDirectiveRules holds the rule scope of a directive. When `all` is
+// true the directive applies to every rule; otherwise only the named rules
+// in `rules` are affected.
 type lintDirectiveRules struct {
   all   bool
   rules map[string]struct{}
 }
 
+// lintDirectiveEvent is one enable/disable transition recorded in source
+// order. `pos` is the byte offset of the comment. `on` is true for a
+// disable event and false for an enable event.
 type lintDirectiveEvent struct {
   pos   int
   rules lintDirectiveRules
   on    bool
 }
 
+// lintInlineDirectives accumulates the per-file directive information
+// extracted by parseLintInlineDirectives. `lines` maps a zero-based line
+// number to any disable-line / disable-next-line directives on that line.
+// `events` is the ordered list of range-style disable/enable transitions.
 type lintInlineDirectives struct {
   lines  map[int][]lintDirectiveRules
   events []lintDirectiveEvent
 }
 
+// lintDisableState tracks the cumulative suppress/allow state as
+// lintDirectiveEvents are replayed in order up to a finding's position.
+// `all` means every rule is suppressed. `rules` is the set of individually
+// suppressed rules. `enabledInAll` is the set of rules that were
+// re-enabled via `eslint-enable <rule>` while `all` was active.
 type lintDisableState struct {
   all          bool
   rules        map[string]struct{}
@@ -60,6 +92,9 @@ func filterInlineDisabledFindings(file *shimast.SourceFile, findings []*Finding)
   return filtered
 }
 
+// parseLintInlineDirectives scans all comment tokens in `file` for
+// recognized directive markers and returns a structured summary of the
+// per-line and range-style suppressions found.
 func parseLintInlineDirectives(file *shimast.SourceFile) *lintInlineDirectives {
   directives := &lintInlineDirectives{
     lines: make(map[int][]lintDirectiveRules),
@@ -111,10 +146,16 @@ scan:
   return directives
 }
 
+// empty reports whether no directives were found in the file, allowing the
+// caller to skip the filtering step entirely.
 func (d *lintInlineDirectives) empty() bool {
   return d == nil || (len(d.lines) == 0 && len(d.events) == 0)
 }
 
+// suppresses reports whether the directive set causes `finding` to be
+// suppressed. It checks the per-line map first (disable-line and
+// disable-next-line directives), then replays the ordered event list to
+// compute the range-style disable/enable state at the finding's position.
 func (d *lintInlineDirectives) suppresses(file *shimast.SourceFile, finding *Finding) bool {
   if d == nil || finding == nil || file == nil {
     return false
@@ -135,6 +176,10 @@ func (d *lintInlineDirectives) suppresses(file *shimast.SourceFile, finding *Fin
   return state.matches(finding.Rule)
 }
 
+// apply updates the disable state by folding in one directive event.
+// Disable events add rules; enable events remove them. When the event
+// targets all rules (`event.rules.all`), the entire state is replaced
+// rather than merged.
 func (s *lintDisableState) apply(event lintDirectiveEvent) {
   if event.on {
     if event.rules.all {
@@ -169,6 +214,9 @@ func (s *lintDisableState) apply(event lintDirectiveEvent) {
   }
 }
 
+// matches reports whether `rule` is currently suppressed given this state.
+// The name is normalized before lookup so that `@typescript-eslint/` prefixes
+// do not prevent a match.
 func (s lintDisableState) matches(rule string) bool {
   normalized := normalizeDirectiveRuleName(rule)
   if _, ok := s.rules[normalized]; ok {
@@ -181,6 +229,9 @@ func (s lintDisableState) matches(rule string) bool {
   return !enabled
 }
 
+// matches reports whether this rule-set covers `rule`. Returns true when the
+// directive targeted all rules or when `rule` (normalized) appears in the
+// named set.
 func (r lintDirectiveRules) matches(rule string) bool {
   if r.all {
     return true
@@ -189,6 +240,9 @@ func (r lintDirectiveRules) matches(rule string) bool {
   return ok
 }
 
+// parseLintDirectiveComment strips comment delimiters from `raw` and
+// delegates to parseLintDirectiveLine. Returns (zero, false) when the
+// comment does not contain a recognized directive marker.
 func parseLintDirectiveComment(raw string) (lintDirective, bool) {
   text := stripCommentDelimiters(raw)
   if directive, ok := parseLintDirectiveLine(text); ok {
@@ -197,6 +251,9 @@ func parseLintDirectiveComment(raw string) (lintDirective, bool) {
   return lintDirective{}, false
 }
 
+// stripCommentDelimiters removes `//` and `/* … */` syntax from `raw` and
+// returns the trimmed inner text. Handles JSDoc-style `* ` prefix on the
+// first content line.
 func stripCommentDelimiters(raw string) string {
   switch {
   case strings.HasPrefix(raw, "//"):
@@ -216,6 +273,9 @@ func stripCommentDelimiters(raw string) string {
   }
 }
 
+// parseLintDirectiveLine matches `text` against all recognized directive
+// markers in declaration order (longest suffix first to avoid prefix
+// ambiguity). Returns the first match found or (zero, false) if none match.
 func parseLintDirectiveLine(text string) (lintDirective, bool) {
   for _, prefix := range []string{"eslint", "lint"} {
     for _, form := range []struct {
@@ -241,6 +301,9 @@ func parseLintDirectiveLine(text string) (lintDirective, bool) {
   return lintDirective{}, false
 }
 
+// directivePayload returns the text after `marker` in `text` when `text`
+// starts with `marker` followed by whitespace or end of string. The
+// returned payload is trimmed of leading/trailing whitespace.
 func directivePayload(text, marker string) (string, bool) {
   if !strings.HasPrefix(text, marker) {
     return "", false
@@ -252,6 +315,9 @@ func directivePayload(text, marker string) (string, bool) {
   return strings.TrimSpace(rest), true
 }
 
+// parseDirectiveRules converts the payload (the text after the directive
+// marker) into a lintDirectiveRules value. The `--` separator strips an
+// optional human-readable description. An empty rule list means "all rules".
 func parseDirectiveRules(payload string) lintDirectiveRules {
   payload = stripDirectiveDescription(payload)
   payload = strings.ReplaceAll(payload, ",", " ")
@@ -272,6 +338,10 @@ func parseDirectiveRules(payload string) lintDirectiveRules {
   return lintDirectiveRules{rules: rules}
 }
 
+// stripDirectiveDescription returns the portion of `payload` before the
+// first ` -- ` token (ESLint's description separator). The separator must
+// be surrounded by whitespace or be at a string boundary to avoid
+// stripping `--` from rule names like `no--foo`.
 func stripDirectiveDescription(payload string) string {
   for i := 0; i < len(payload)-1; i++ {
     if payload[i] != '-' || payload[i+1] != '-' {
@@ -287,6 +357,8 @@ func stripDirectiveDescription(payload string) string {
   return payload
 }
 
+// normalizeDirectiveRuleName strips the common ESLint namespace prefixes so
+// both `@typescript-eslint/no-var` and `no-var` resolve to the same key.
 func normalizeDirectiveRuleName(name string) string {
   name = strings.TrimSpace(name)
   name = strings.TrimPrefix(name, "@typescript-eslint/")

package/linthost/dispatch.go

@@ -7,8 +7,8 @@
 package linthost
 
 import (
-	"fmt"
-	"os"
+  "fmt"
+  "os"
 )
 
 // Version is the build banner string the `version` subcommand prints.
@@ -25,41 +25,41 @@ var Version = "dev"
 // Recognized verbs: `version` / `-v` / `--version`, `check`, `fix`, `format`,
 // `build`, `transform`. Anything else is a usage error (exit code 2).
 func Main(args []string) int {
-	return run(args)
+  return run(args)
 }
 
 // run is the package-local dispatcher invoked by Main and by the in-tree
 // test/command corpus, which exercises end-to-end subcommand routing through
 // the same entry point the CLI uses.
 func run(args []string) int {
-	if len(args) == 0 {
-		fmt.Fprintln(os.Stderr, "@ttsc/lint: command required (expected check|fix|format|build|transform|version)")
-		return 2
-	}
-	switch args[0] {
-	case "-v", "--version", "version":
-		// Don't pay contributor-registration cost for the version banner.
-		fmt.Fprintf(os.Stdout, "@ttsc/lint %s\n", Version)
-		return 0
-	case "check", "fix", "format", "build", "transform":
-	default:
-		fmt.Fprintf(os.Stderr, "@ttsc/lint: unknown command %q\n", args[0])
-		return 2
-	}
-	// Wire contributor rules into the engine's dispatch table after every
-	// package init has settled. See contrib_adapter.go for the rationale.
-	registerContributors()
-	switch args[0] {
-	case "check":
-		return RunCheck(args[1:])
-	case "fix":
-		return RunFix(args[1:])
-	case "format":
-		return RunFormat(args[1:])
-	case "build":
-		return RunBuild(args[1:])
-	case "transform":
-		return RunTransform(args[1:])
-	}
-	return 2
+  if len(args) == 0 {
+    fmt.Fprintln(os.Stderr, "@ttsc/lint: command required (expected check|fix|format|build|transform|version)")
+    return 2
+  }
+  switch args[0] {
+  case "-v", "--version", "version":
+    // Don't pay contributor-registration cost for the version banner.
+    fmt.Fprintf(os.Stdout, "@ttsc/lint %s\n", Version)
+    return 0
+  case "check", "fix", "format", "build", "transform":
+  default:
+    fmt.Fprintf(os.Stderr, "@ttsc/lint: unknown command %q\n", args[0])
+    return 2
+  }
+  // Wire contributor rules into the engine's dispatch table after every
+  // package init has settled. See contrib_adapter.go for the rationale.
+  registerContributors()
+  switch args[0] {
+  case "check":
+    return RunCheck(args[1:])
+  case "fix":
+    return RunFix(args[1:])
+  case "format":
+    return RunFormat(args[1:])
+  case "build":
+    return RunBuild(args[1:])
+  case "transform":
+    return RunTransform(args[1:])
+  }
+  return 2
 }

package/linthost/engine.go

@@ -184,6 +184,10 @@ func (c *Context) ReportRangeFix(pos, end int, message string, edits ...TextEdit
   })
 }
 
+// cloneTextEdits returns a shallow copy of `edits` so that the caller's
+// variadic slice cannot be mutated through the stored Finding. Returns nil
+// when the input is empty, keeping the Finding.Fix field nil rather than
+// a zero-length slice.
 func cloneTextEdits(edits []TextEdit) []TextEdit {
   if len(edits) == 0 {
     return nil

package/linthost/eslint_runtime.go

@@ -13,23 +13,31 @@ import (
   shimdw "github.com/microsoft/typescript-go/shim/diagnosticwriter"
 )
 
+// eslintRuntimeProvider is the optional interface that a RuleResolver
+// implementation may satisfy to enable the external ESLint subprocess path.
+// ConfigStore implements all three methods; other resolvers that do not
+// implement this interface silently bypass the ESLint runtime.
 type eslintRuntimeProvider interface {
   ExternalConfigPath() string
   WantsESLintRuntime() bool
   RequiresESLintRuntime() bool
 }
 
+// eslintRuntimeOutput is the top-level JSON object written to stdout by
+// the embedded externalESLintRunnerScript.
 type eslintRuntimeOutput struct {
   Missing bool                `json:"missing"`
   Fixed   int                 `json:"fixed"`
   Results []eslintRuntimeFile `json:"results"`
 }
 
+// eslintRuntimeFile mirrors one entry from ESLint's LintResult array.
 type eslintRuntimeFile struct {
   FilePath string                 `json:"filePath"`
   Messages []eslintRuntimeMessage `json:"messages"`
 }
 
+// eslintRuntimeMessage mirrors one entry from ESLint's LintMessage array.
 type eslintRuntimeMessage struct {
   RuleID    string `json:"ruleId"`
   Severity  int    `json:"severity"`
@@ -40,6 +48,13 @@ type eslintRuntimeMessage struct {
   EndColumn int    `json:"endColumn"`
 }
 
+// runExternalESLintDiagnostics delegates to the project's installed ESLint
+// binary (via the embedded JS runner) and converts the JSON output into
+// LintDiagnostic values anchored to their source positions. Returns
+// (nil, false, nil) when the resolver does not want the ESLint runtime,
+// (nil, true, nil) when no source files qualify, and (diags, true, nil)
+// on success. The bool return is "ran ESLint" — callers use it to skip
+// native-rule diagnostics when ESLint was the sole configured source.
 func runExternalESLintDiagnostics(
   resolver RuleResolver,
   cwd string,
@@ -98,14 +113,17 @@ func runExternalESLintDiagnostics(
     }
     for _, msg := range result.Messages {
       if msg.Severity == 0 {
+        // ESLint severity 0 means "off" — skip silently.
         continue
       }
       ruleID := strings.TrimSpace(msg.RuleID)
       if ruleID == "" {
+        // ESLint can emit messages without a ruleId for parse errors.
         ruleID = "eslint"
       }
       category := shimdw.LintCategoryWarning
       if msg.Severity >= 2 {
+        // severity 2 = error; values above 2 are treated as error too.
         category = shimdw.LintCategoryError
       }
       pos := positionOfESLintLocation(file.Text(), msg.Line, msg.Column)
@@ -126,10 +144,14 @@ func runExternalESLintDiagnostics(
   return diagnostics, true, nil
 }
 
+// runExternalESLint invokes ESLint in check (read-only) mode.
 func runExternalESLint(cwd, configPath, fileListJSON string) (*eslintRuntimeOutput, error) {
   return runExternalESLintWithMode(cwd, configPath, fileListJSON, false)
 }
 
+// runExternalESLintFixes invokes ESLint in fix mode and returns the number of
+// files that were actually modified. The fix runner calls ESLint.outputFixes
+// inside the JS subprocess, which writes changes directly to disk.
 func runExternalESLintFixes(
   resolver RuleResolver,
   cwd string,
@@ -180,6 +202,10 @@ func runExternalESLintFixes(
   return output.Fixed, nil
 }
 
+// runExternalESLintWithMode spawns a Node.js subprocess that runs the embedded
+// externalESLintRunnerScript. When fix is true the runner calls
+// ESLint.outputFixes and returns the count of modified files; when false it
+// returns diagnostics only and leaves files untouched.
 func runExternalESLintWithMode(cwd, configPath, fileListJSON string, fix bool) (*eslintRuntimeOutput, error) {
   node := os.Getenv("TTSC_NODE_BINARY")
   if node == "" {
@@ -210,6 +236,11 @@ func runExternalESLintWithMode(cwd, configPath, fileListJSON string, fix bool) (
   return &output, nil
 }
 
+// positionOfESLintLocation converts a 1-based (line, column) position from
+// ESLint's output — where column is a UTF-16 code-unit offset — into a
+// zero-based byte offset into text. This matches how tsgo positions source
+// spans: lines are 1-based, columns are UTF-16 units (so a supplementary
+// codepoint counts as 2). Returns len(text) when the position is past EOF.
 func positionOfESLintLocation(text string, line, column int) int {
   if line <= 0 {
     line = 1

package/linthost/fix.go

@@ -1,3 +1,11 @@
+// Autofix orchestration for the `@ttsc/lint fix` subcommand.
+//
+// RunFix drives the fix cascade: it applies ESLint runtime fixes first
+// (one pass, external process), then repeatedly runs the native lint
+// engine and applies any emitted TextEdit suggestions until no more
+// fixable findings remain or maxFixPasses is reached. After the cascade
+// settles, it runs a final diagnostic pass so remaining issues are
+// surfaced in the normal error stream.
 package linthost
 
 import (
@@ -121,6 +129,8 @@ func runFix(opts *subcommandOpts) int {
   return 0
 }
 
+// loadFixProgram loads the TypeScript program for a fix/format pass with
+// NoEmit forced on. Returns (nil, 2) when loading or config parsing fails.
 func loadFixProgram(opts *subcommandOpts) (*program, int) {
   prog, parseDiags, err := loadProgram(opts.cwd, opts.tsconfig, loadProgramOptions{
     forceNoEmit: true,
@@ -137,6 +147,9 @@ func loadFixProgram(opts *subcommandOpts) (*program, int) {
   return prog, 0
 }
 
+// reloadFixProgram closes `current` and loads a fresh program from disk.
+// Used between cascade passes so the engine sees edits applied in the
+// previous pass rather than stale in-memory AST nodes.
 func reloadFixProgram(current *program, opts *subcommandOpts) (*program, int) {
   if current != nil {
     current.close()
@@ -144,12 +157,19 @@ func reloadFixProgram(current *program, opts *subcommandOpts) (*program, int) {
   return loadFixProgram(opts)
 }
 
+// fileFixes groups all pending TextEdit suggestions for a single file.
+// `text` is the source content at the time the findings were collected;
+// byte offsets in `edits` are relative to this snapshot.
 type fileFixes struct {
   path  string
   text  string
   edits []TextEdit
 }
 
+// applyFindingFixes groups all fixable findings by file, resolves each
+// file path to an absolute form, then applies the edit batches in
+// deterministic order (sorted by path). Returns the total number of edits
+// written to disk.
 func applyFindingFixes(cwd string, findings []*Finding) (int, error) {
   byFile := map[string]*fileFixes{}
   for _, finding := range findings {
@@ -191,6 +211,10 @@ func applyFindingFixes(cwd string, findings []*Finding) (int, error) {
   return total, nil
 }
 
+// applyTextEditsToFile selects the non-overlapping edits from `edits`, applies
+// them to `source` in reverse order (right-to-left) to preserve earlier
+// offsets, and writes the result to `path`. Returns the number of edits
+// applied, or 0 when no edits survive selection.
 func applyTextEditsToFile(path, source string, edits []TextEdit) (int, error) {
   selected := selectTextEdits(len(source), edits)
   if len(selected) == 0 {
@@ -210,6 +234,11 @@ func applyTextEditsToFile(path, source string, edits []TextEdit) (int, error) {
   return len(selected), nil
 }
 
+// selectTextEdits filters and sorts `edits` into a non-overlapping
+// application sequence. Out-of-bounds edits and exact duplicates are
+// removed first; the remainder is sorted by start position then end
+// position (left to right). A greedy scan then keeps the earliest-starting
+// edit and drops any that overlap with it, producing a disjoint set.
 func selectTextEdits(sourceLen int, edits []TextEdit) []TextEdit {
   if len(edits) == 0 {
     return nil

package/linthost/format.go

@@ -33,6 +33,8 @@ func RunFormat(args []string) int {
   return runFormat(opts)
 }
 
+// runFormat is the internal implementation of RunFormat. It drives the
+// cascade loop and applies format-rule edits until convergence.
 func runFormat(opts *subcommandOpts) int {
   rules, err := loadRules(opts.pluginsJSON, opts.cwd, opts.tsconfig)
   if err != nil {
@@ -89,10 +91,17 @@ func runFormat(opts *subcommandOpts) int {
   return 0
 }
 
+// formatCommandResolver wraps a RuleResolver and ensures every format-class
+// rule referenced in the loaded plugin options is activated at warn severity,
+// even if the user's config omitted it. This lets `ttsc format` format files
+// without requiring explicit rule declarations in the project config.
 type formatCommandResolver struct {
   inner RuleResolver
 }
 
+// ResolveRules implements RuleResolver. It delegates to the inner resolver
+// and then upgrades format-rule entries from off to warn so they are applied
+// even when the project config omits them.
 func (r formatCommandResolver) ResolveRules(fileName string) ResolvedRuleConfig {
   resolved := r.inner.ResolveRules(fileName)
   if resolved.Ignored {
@@ -109,6 +118,8 @@ func (r formatCommandResolver) ResolveRules(fileName string) ResolvedRuleConfig
   return resolved
 }
 
+// ActiveRuleNames implements RuleResolver. Returns the union of the inner
+// resolver's active rules and every format-option rule that is registered.
 func (r formatCommandResolver) ActiveRuleNames() []string {
   active := map[string]struct{}{}
   for _, name := range r.inner.ActiveRuleNames() {
@@ -120,6 +131,8 @@ func (r formatCommandResolver) ActiveRuleNames() []string {
   return sortedKeys(active)
 }
 
+// EnabledRuleConfig implements RuleResolver. Merges the inner config with
+// the format-option rules so callers see the full active set.
 func (r formatCommandResolver) EnabledRuleConfig() RuleConfig {
   enabled := r.inner.EnabledRuleConfig()
   if enabled == nil {
@@ -133,10 +146,14 @@ func (r formatCommandResolver) EnabledRuleConfig() RuleConfig {
   return enabled
 }
 
+// RuleOptions implements RuleResolver by delegating directly to the inner resolver.
 func (r formatCommandResolver) RuleOptions(name string) json.RawMessage {
   return r.inner.RuleOptions(name)
 }
 
+// formatOptionRuleNames returns the sorted list of rule names from the inner
+// resolver's options that are registered as format rules. These are the rules
+// that formatCommandResolver promotes from off to warn.
 func (r formatCommandResolver) formatOptionRuleNames() []string {
   options := resolverOptions(r.inner)
   if len(options) == 0 {
@@ -152,6 +169,9 @@ func (r formatCommandResolver) formatOptionRuleNames() []string {
   return names
 }
 
+// resolverOptions extracts the raw options map from a resolver whose concrete
+// type exposes one. Returns nil for resolver types that don't carry per-rule
+// options (e.g. bare RuleConfig).
 func resolverOptions(resolver RuleResolver) RuleOptionsMap {
   switch r := resolver.(type) {
   case InlineRuleResolver:
@@ -163,11 +183,14 @@ func resolverOptions(resolver RuleResolver) RuleOptionsMap {
   }
 }
 
+// isRegisteredFormatRule reports whether `name` is both registered in the
+// global rule registry and tagged as a format rule via the FormatRule marker.
 func isRegisteredFormatRule(name string) bool {
   rule, ok := registered.rules[name]
   return ok && isFormatRule(rule)
 }
 
+// sortedKeys returns the sorted slice of keys from a string-keyed set.
 func sortedKeys(input map[string]struct{}) []string {
   names := make([]string, 0, len(input))
   for name := range input {

package/linthost/host.go

@@ -108,6 +108,8 @@ func loadProgram(cwd, tsconfigPath string, options loadProgramOptions) (*program
   }, nil, nil
 }
 
+// close releases the type checker acquired by loadProgram. Safe to call on
+// a nil receiver and idempotent after the first call.
 func (p *program) close() {
   if p == nil {
     return
@@ -162,6 +164,8 @@ func (p *program) findSourceFile(target string) *shimast.SourceFile {
   return nil
 }
 
+// forceEmit clears the NoEmit and EmitDeclarationOnly flags so the
+// program emits JavaScript even when the tsconfig says otherwise.
 func forceEmit(parsed *tsoptions.ParsedCommandLine) {
   if parsed == nil || parsed.ParsedConfig == nil || parsed.ParsedConfig.CompilerOptions == nil {
     return
@@ -171,6 +175,9 @@ func forceEmit(parsed *tsoptions.ParsedCommandLine) {
   options.EmitDeclarationOnly = shimcore.TSFalse
 }
 
+// forceNoEmit sets the NoEmit flag regardless of what the tsconfig
+// specifies. Used by fix and check subcommands that must not write output
+// files as a side effect of type-checking.
 func forceNoEmit(parsed *tsoptions.ParsedCommandLine) {
   if parsed == nil || parsed.ParsedConfig == nil || parsed.ParsedConfig.CompilerOptions == nil {
     return
@@ -178,6 +185,10 @@ func forceNoEmit(parsed *tsoptions.ParsedCommandLine) {
   parsed.ParsedConfig.CompilerOptions.NoEmit = shimcore.TSTrue
 }
 
+// overrideOutDir replaces the parsed config's OutDir with `outDir`.
+// Relative outDir values are resolved against `cwd`; absolute paths are
+// used as-is. Paths are converted to forward slashes for tsgo
+// compatibility.
 func overrideOutDir(cwd string, parsed *tsoptions.ParsedCommandLine, outDir string) {
   if parsed == nil || parsed.ParsedConfig == nil || parsed.ParsedConfig.CompilerOptions == nil {
     return

package/linthost/print_dispatch.go

@@ -98,9 +98,10 @@ func verbatim(ctx *PrintContext, node *shimast.Node) 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).
+// verbatimRange returns a Text doc holding src[start:end] verbatim.
+// It is the position-only sibling of verbatim: use it when the sub-range
+// to copy does not correspond to a single AST node (e.g. `<T>` tokens
+// that surround a type-argument NodeList).
 func verbatimRange(src string, start, end int) Doc {
   if start < 0 || end < start || end > len(src) {
     return Doc{}
@@ -108,8 +109,9 @@ func verbatimRange(src string, start, end int) 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.
+// indentUnit returns the number of columns in one indentation step,
+// derived from PrintOptions.TabWidth. Falls back to 2 when TabWidth
+// is not set, matching the Prettier default.
 func (ctx *PrintContext) indentUnit() int {
   if ctx.Opts.TabWidth > 0 {
     return ctx.Opts.TabWidth

package/linthost/print_doc.go

@@ -56,6 +56,10 @@ package linthost
 // 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.
+
+// DocKind is the discriminant tag for a Doc node. Only the variant
+// fields relevant to that kind are populated; all others stay at their
+// zero value.
 type DocKind uint8
 
 const (

package/linthost/print_nodes_call.go

@@ -117,6 +117,9 @@ func printArgList(ctx *PrintContext, list *shimast.NodeList) Doc {
 // Type-argument byte-range helpers. The shim's NodeList.End() points
 // past the last argument; the surrounding `<` and `>` are not part of
 // the list's range, so we have to scan around it.
+
+// callTypeArgsStart returns the byte offset of the `<` that opens the
+// type-argument list of a CallExpression. Returns -1 when absent.
 func callTypeArgsStart(ctx *PrintContext, call *shimast.CallExpression) int {
   if call.TypeArguments == nil || len(call.TypeArguments.Nodes) == 0 {
     return -1
@@ -136,6 +139,8 @@ func callTypeArgsStart(ctx *PrintContext, call *shimast.CallExpression) int {
   return -1
 }
 
+// callTypeArgsEnd returns the byte offset one past the closing `>` of a
+// CallExpression's type-argument list. Returns -1 when absent.
 func callTypeArgsEnd(ctx *PrintContext, call *shimast.CallExpression) int {
   if call.TypeArguments == nil {
     return -1
@@ -149,6 +154,8 @@ func callTypeArgsEnd(ctx *PrintContext, call *shimast.CallExpression) int {
   return end
 }
 
+// newTypeArgsStart returns the byte offset of the `<` that opens the
+// type-argument list of a NewExpression. Returns -1 when absent.
 func newTypeArgsStart(ctx *PrintContext, ne *shimast.NewExpression) int {
   if ne.TypeArguments == nil || len(ne.TypeArguments.Nodes) == 0 {
     return -1
@@ -166,6 +173,8 @@ func newTypeArgsStart(ctx *PrintContext, ne *shimast.NewExpression) int {
   return -1
 }
 
+// newTypeArgsEnd returns the byte offset one past the closing `>` of a
+// NewExpression's type-argument list. Returns -1 when absent.
 func newTypeArgsEnd(ctx *PrintContext, ne *shimast.NewExpression) int {
   if ne.TypeArguments == nil {
     return -1