@ttsc/lint 0.10.2 → 0.11.0-dev.20260518

package/plugin/main.go

@@ -1,11 +1,15 @@
 // Command @ttsc/lint is the native backend for the `@ttsc/lint` plugin.
 //
-// The plugin host (ttsc / ttsx) spawns this binary with one of four
+// The plugin host (ttsc / ttsx) spawns this binary with one of five
 // subcommands:
 //
 //   - `version` / `-v` / `--version` — print the binary banner.
 //   - `check` — typecheck + lint without emit. Failure exit code if any
 //     error-severity diagnostic fires.
+//   - `fix` — apply lint-rule autofixes, then typecheck + lint without
+//     emit.
+//   - `format` — apply format-rule edits only. Write-only: no diagnostic
+//     output, no typecheck recheck.
 //   - `build` — typecheck + lint, then run the standard tsgo emit pipeline
 //     so JS files land on disk.
 //   - `transform --file=PATH` — single-file emit with the same lint pass.
@@ -13,36 +17,19 @@
 // Diagnostics share the renderer with tsgo's own output, so warnings come
 // out yellow, errors come out red, and the trailing `Found N errors`
 // summary is consistent with `tsc --noEmit`.
+//
+// Behavior lives in the sibling `linthost` library package. This binary is a
+// thin wrapper so out-of-process consumers (the native CLI here) and
+// in-process consumers (the ttsc.dev playground wasm) share the same
+// dispatch surface.
 package main
 
 import (
-  "fmt"
-  "os"
-)
+	"os"
 
-const version = "0.0.1"
+	"github.com/samchon/ttsc/packages/lint/linthost"
+)
 
 func main() {
-  os.Exit(run(os.Args[1:]))
-}
-
-func run(args []string) int {
-  if len(args) == 0 {
-    fmt.Fprintln(os.Stderr, "@ttsc/lint: command required (expected check|build|transform|version)")
-    return 2
-  }
-  switch args[0] {
-  case "-v", "--version", "version":
-    fmt.Fprintf(os.Stdout, "@ttsc/lint %s\n", version)
-    return 0
-  case "check":
-    return RunCheck(args[1:])
-  case "build":
-    return RunBuild(args[1:])
-  case "transform":
-    return RunTransform(args[1:])
-  default:
-    fmt.Fprintf(os.Stderr, "@ttsc/lint: unknown command %q\n", args[0])
-    return 2
-  }
+	os.Exit(linthost.Main(os.Args[1:]))
 }

package/rule/astutil/astutil.go

@@ -0,0 +1,148 @@
+// Package astutil exposes the AST/text helpers `@ttsc/lint` built-in rules
+// already rely on, so third-party contributor rules can build autofixes
+// without re-implementing trivia, keyword location, or token-range math.
+//
+// These helpers are deliberately byte-oriented to match the
+// `rule.TextEdit` contract: positions returned from this package can be
+// fed directly into a `TextEdit{Pos, End, Text}` literal.
+//
+// All functions are pure (no shared state) and safe to call from any
+// goroutine — `*shimast.SourceFile` and `*shimast.Node` are read-only
+// from the rule's perspective.
+package astutil
+
+import (
+  "strings"
+
+  shimast "github.com/microsoft/typescript-go/shim/ast"
+  shimscanner "github.com/microsoft/typescript-go/shim/scanner"
+)
+
+// NodeText returns the source text under `node` with leading trivia
+// (whitespace + comments) stripped. Mirrors `nodeText` in the built-in
+// engine — useful for rules that compare textual identity (the
+// `no-self-assign` / `no-self-compare` shape) or that splice a sub-node's
+// text into a fix string.
+//
+// Returns "" when `file` or `node` is nil, or when the computed range
+// falls outside the file (defensive — shouldn't happen for engine-supplied
+// nodes).
+func NodeText(file *shimast.SourceFile, node *shimast.Node) string {
+  if file == nil || node == nil {
+    return ""
+  }
+  src := file.Text()
+  end := node.End()
+  pos := shimscanner.SkipTrivia(src, node.Pos())
+  if pos < 0 || end > len(src) || pos >= end {
+    return ""
+  }
+  return strings.TrimRight(src[pos:end], " \t\r\n")
+}
+
+// KeywordStart returns the source offset of a declaration keyword such as
+// `var`, `let`, `const`, `module`, `namespace`, or `function` that lives
+// at the start of `node` (after leading trivia). Returns -1 if not found.
+//
+// Use this to anchor TextEdits that swap a leading keyword:
+//
+//  start := astutil.KeywordStart(file, node, "let")
+//  if start >= 0 {
+//    ctx.ReportFix(node, "use const",
+//      rule.TextEdit{Pos: start, End: start + len("let"), Text: "const"})
+//  }
+func KeywordStart(file *shimast.SourceFile, node *shimast.Node, keyword string) int {
+  if file == nil || node == nil || keyword == "" {
+    return -1
+  }
+  src := file.Text()
+  pos := shimscanner.SkipTrivia(src, node.Pos())
+  end := pos + len(keyword)
+  if pos < 0 || end > len(src) {
+    return -1
+  }
+  if strings.HasPrefix(src[pos:], keyword) && (end == len(src) || !isIdentifierPart(src[end])) {
+    return pos
+  }
+  limit := node.End()
+  if limit > len(src) {
+    limit = len(src)
+  }
+  for i := pos; i+len(keyword) <= limit && i < pos+32; i++ {
+    end = i + len(keyword)
+    if strings.HasPrefix(src[i:], keyword) &&
+      (i == 0 || !isIdentifierPart(src[i-1])) &&
+      (end == len(src) || !isIdentifierPart(src[end])) {
+      return i
+    }
+  }
+  return -1
+}
+
+// FindKeyword scans `[pos, end)` for a keyword token whose lexeme is
+// `keyword` and returns its first-byte offset, or -1 if not found.
+// Differs from KeywordStart in that it works on an arbitrary byte range
+// instead of a node's leading-trivia-adjusted start — use this for fixes
+// that need to splice text after `import` or before `from`.
+//
+// The match is identifier-aware: a hit must be flanked by non-identifier
+// bytes (or file edges) so that searching for `import` does not match
+// the `import` prefix of `importMap`.
+func FindKeyword(file *shimast.SourceFile, pos, end int, keyword string) int {
+  if file == nil || keyword == "" {
+    return -1
+  }
+  src := file.Text()
+  if pos < 0 {
+    pos = 0
+  }
+  if end > len(src) {
+    end = len(src)
+  }
+  limit := end - len(keyword)
+  for i := pos; i <= limit; i++ {
+    if src[i] != keyword[0] {
+      continue
+    }
+    tail := i + len(keyword)
+    if src[i:tail] != keyword {
+      continue
+    }
+    if i > 0 && isIdentifierPart(src[i-1]) {
+      continue
+    }
+    if tail < len(src) && isIdentifierPart(src[tail]) {
+      continue
+    }
+    return i
+  }
+  return -1
+}
+
+// TokenRange returns the `[pos, end)` range of a node's primary token
+// with leading trivia stripped from the start. Useful for rules that
+// want their diagnostic and fix range aligned to the token rather than
+// the surrounding whitespace.
+//
+// Returns `(-1, -1)` when `file` or `node` is nil or when the computed
+// range is malformed.
+func TokenRange(file *shimast.SourceFile, node *shimast.Node) (int, int) {
+  if file == nil || node == nil {
+    return -1, -1
+  }
+  src := file.Text()
+  pos := shimscanner.SkipTrivia(src, node.Pos())
+  end := node.End()
+  if pos < 0 || pos > len(src) || end < pos || end > len(src) {
+    return -1, -1
+  }
+  return pos, end
+}
+
+func isIdentifierPart(ch byte) bool {
+  return (ch >= 'a' && ch <= 'z') ||
+    (ch >= 'A' && ch <= 'Z') ||
+    (ch >= '0' && ch <= '9') ||
+    ch == '_' ||
+    ch == '$'
+}

package/rule/rule.go

@@ -0,0 +1,291 @@
+// Package rule is the public API for `@ttsc/lint` rule contributors.
+//
+// Third-party lint rule packages ("contributors") import this package and
+// register their rules in an `init()`. At build time, ttsc copies a
+// contributor's Go source into a sub-package of the `@ttsc/lint` Go module
+// and synthesizes a blank-import in the host binary, which triggers the
+// contributor's `init()` and populates the registry below.
+//
+// The host (`@ttsc/lint`) walks this registry during engine bootstrap and
+// adapts each contributor rule onto the same dispatch table that drives
+// the built-in rules.
+//
+// Contributors operate on the same shim AST the host's first-party
+// plugins use (`github.com/microsoft/typescript-go/shim/ast` and friends)
+// — there is no facade layer in between. The shim packages are the
+// publicly maintained boundary ttsc already exposes; adding another
+// wrapper here would duplicate that maintenance burden without earning
+// any extra stability. Contributors get the full AST surface the host
+// has, so authoring a contributor rule and authoring a built-in rule are
+// the same exercise.
+//
+// Example contributor:
+//
+//  package myrules
+//
+//  import (
+//      shimast "github.com/microsoft/typescript-go/shim/ast"
+//      "github.com/samchon/ttsc/packages/lint/rule"
+//  )
+//
+//  func init() { rule.Register(noTodoComment{}) }
+//
+//  type noTodoComment struct{}
+//
+//  func (noTodoComment) Name() string             { return "demo/no-todo-comment" }
+//  func (noTodoComment) Visits() []shimast.Kind   { return []shimast.Kind{shimast.KindSourceFile} }
+//  func (noTodoComment) Check(ctx *rule.Context, node *shimast.Node) {
+//      // ctx.File, ctx.Checker, ctx.Severity available; ctx.Report(node, msg)
+//      // or ctx.ReportRange(pos, end, msg) push a finding through the engine.
+//  }
+package rule
+
+import (
+  "encoding/json"
+
+  shimast "github.com/microsoft/typescript-go/shim/ast"
+  shimchecker "github.com/microsoft/typescript-go/shim/checker"
+)
+
+// Severity mirrors the engine's three-level severity ladder. The
+// constants are kept value-compatible with the engine's internal
+// `Severity` type so the adapter layer can cast safely.
+type Severity int
+
+const (
+  // SeverityOff means the rule is disabled. Engine skips dispatch.
+  SeverityOff Severity = iota
+  // SeverityWarn produces a warning diagnostic (does not change exit
+  // code).
+  SeverityWarn
+  // SeverityError produces an error diagnostic and fails the command.
+  SeverityError
+)
+
+// Rule is the contract every contributor rule satisfies. Mirrors the
+// internal host interface so the host can dispatch via a thin adapter
+// without re-implementing the engine.
+type Rule interface {
+  // Name is the identifier users put in their `rules` map.
+  // Conventionally namespaced as "<plugin-namespace>/<rule-name>" to
+  // avoid colliding with built-in rule names.
+  Name() string
+
+  // Visits returns the AST kinds the rule cares about. The engine only
+  // dispatches to rules that registered for the visited node's kind.
+  Visits() []shimast.Kind
+
+  // Check is invoked once per relevant node. Use `ctx.Report` /
+  // `ctx.ReportRange` to emit findings.
+  Check(ctx *Context, node *shimast.Node)
+}
+
+// FormatRule is an optional marker contributors implement when a rule
+// belongs to the "format" category instead of the default "lint"
+// category. `ttsc fix` is the run-everything entry point and applies
+// edits from BOTH lint-class and format-class rules. `ttsc format` is
+// the format-only convenience: it filters to FormatRule findings so
+// lint-class rewrites are skipped. Lint rules (rules that do not
+// implement FormatRule) participate only in `ttsc fix` (and in
+// diagnostics during `ttsc check`).
+//
+// `IsFormat` exists as a structural marker, not a runtime toggle:
+// returning `false` is equivalent to not implementing the interface at
+// all, and the host treats either form the same way.
+type FormatRule interface {
+  Rule
+  IsFormat() bool
+}
+
+// Reporter is the engine-supplied callback that records a finding. The
+// host implements this and passes it to `NewContext` when invoking a
+// contributor rule.
+type Reporter interface {
+  // Report records a finding at the given node's source range.
+  Report(node *shimast.Node, message string)
+  // ReportRange records a finding at an explicit byte range inside the
+  // current file. Use this when the rule wants to highlight a
+  // sub-token.
+  ReportRange(pos, end int, message string)
+}
+
+// FixReporter is the optional extension a host implements to receive
+// autofix edits alongside a finding. The public `rule.Context` type-asserts
+// against this shape so any host whose reporter exposes both methods opts
+// into fix support without depending on a private interface name.
+//
+// Contributor rules do NOT implement this interface — it is the host-side
+// counterpart to `Context.ReportFix` / `Context.ReportRangeFix`. A
+// contributor authoring a fake reporter for unit tests can declare
+// `var _ rule.FixReporter = &myReporter{}` to compile-check that the fake
+// satisfies the fix surface. Go interface satisfaction is all-or-nothing:
+// a fake that wants the fix path must implement BOTH `ReportFix` and
+// `ReportRangeFix`.
+type FixReporter interface {
+  ReportFix(node *shimast.Node, message string, edits ...TextEdit)
+  ReportRangeFix(pos, end int, message string, edits ...TextEdit)
+}
+
+// TextEdit is one byte-range replacement offered by an autofixable finding.
+// Positions use the same byte offsets as shim AST nodes and must point inside
+// the current source file. An empty `Text` deletes the range; positions are
+// in lexer byte order, not visual order, so a UTF-8 multi-byte sequence must
+// be replaced as a whole.
+//
+// Application policy: a rule may emit several `TextEdit`s in one
+// `ReportFix` / `ReportRangeFix` call, in any order. The host treats the
+// per-pass edit set as a candidate list. Within a single fix pass, edits
+// must not overlap each other; when two edits cover overlapping ranges
+// (either from one rule emitting multiple edits in one call, or from two
+// different rules in the same pass), the host applies the earliest-starting
+// / shortest edit and silently drops the rest. There is no diagnostic for
+// dropped edits, and the host does not currently report when a comment
+// falls inside a deletion range. Design fixes so each finding emits one
+// contiguous TextEdit covering the entire replacement region.
+type TextEdit struct {
+  Pos  int
+  End  int
+  Text string
+}
+
+// Context is the per-(file, rule) handle the engine passes to `Check`.
+// The `Reporter` is supplied by the host when constructing the context;
+// contributors call `ctx.Report` / `ctx.ReportRange` directly through
+// this Context rather than touching the reporter.
+type Context struct {
+  // File is the source file currently being walked. Always non-nil
+  // when `Check` is invoked.
+  File *shimast.SourceFile
+
+  // Checker is the host's tsgo type checker. Available for type-aware
+  // rules; nil-safe enough that AST-only rules can ignore it.
+  Checker *shimchecker.Checker
+
+  // Severity is the rule's resolved severity for this file. Already
+  // filtered by the engine — rules do not need to check for
+  // SeverityOff.
+  Severity Severity
+
+  // Options is the raw JSON blob the user wrote in the second slot of
+  // their `[severity, options]` rule configuration tuple. Nil when the
+  // rule was configured with a bare severity literal. Contributors that
+  // accept options decode the blob into their own struct via
+  // `(*Context).DecodeOptions`.
+  Options json.RawMessage
+
+  reporter Reporter
+}
+
+// NewContext constructs a Context for the engine to pass into a
+// contributor rule's `Check`. Reserved for host code; contributors
+// should not need to call this.
+func NewContext(
+  file *shimast.SourceFile,
+  checker *shimchecker.Checker,
+  severity Severity,
+  options json.RawMessage,
+  reporter Reporter,
+) *Context {
+  return &Context{
+    File:     file,
+    Checker:  checker,
+    Severity: severity,
+    Options:  options,
+    reporter: reporter,
+  }
+}
+
+// DecodeOptions unmarshals the rule's options blob into `out`. Returns
+// nil with no side effect when the rule was configured with severity
+// alone, so contributors can write:
+//
+//  var opts myRuleOptions
+//  _ = ctx.DecodeOptions(&opts)
+//  // opts now holds either the user's settings or the zero value.
+func (c *Context) DecodeOptions(out interface{}) error {
+  if c == nil || len(c.Options) == 0 {
+    return nil
+  }
+  return json.Unmarshal(c.Options, out)
+}
+
+// Report records a finding at the given node's source range. Silently
+// ignored when severity is `off` (defensive — the engine already filters
+// by severity before invoking Check) or when no reporter is attached.
+func (c *Context) Report(node *shimast.Node, message string) {
+  if c == nil || c.reporter == nil || c.Severity == SeverityOff || node == nil {
+    return
+  }
+  c.reporter.Report(node, message)
+}
+
+// ReportFix records a finding at the given node's source range with optional
+// autofix edits. Older hosts that do not implement fix reporting receive the
+// diagnostic without edits.
+// Treat edits as best-effort: design the rule so the diagnostic alone is useful.
+func (c *Context) ReportFix(node *shimast.Node, message string, edits ...TextEdit) {
+  if c == nil || c.reporter == nil || c.Severity == SeverityOff || node == nil {
+    return
+  }
+  if len(edits) == 0 {
+    c.reporter.Report(node, message)
+    return
+  }
+  fixer, ok := c.reporter.(FixReporter)
+  if !ok {
+    c.reporter.Report(node, message)
+    return
+  }
+  fixer.ReportFix(node, message, edits...)
+}
+
+// ReportRange records a finding at an explicit byte range inside the
+// current file.
+func (c *Context) ReportRange(pos, end int, message string) {
+  if c == nil || c.reporter == nil || c.Severity == SeverityOff {
+    return
+  }
+  c.reporter.ReportRange(pos, end, message)
+}
+
+// ReportRangeFix records a finding at an explicit byte range with optional
+// autofix edits. Older hosts that do not implement fix reporting receive the
+// diagnostic without edits.
+// Treat edits as best-effort: design the rule so the diagnostic alone is useful.
+func (c *Context) ReportRangeFix(pos, end int, message string, edits ...TextEdit) {
+  if c == nil || c.reporter == nil || c.Severity == SeverityOff {
+    return
+  }
+  if len(edits) == 0 {
+    c.reporter.ReportRange(pos, end, message)
+    return
+  }
+  fixer, ok := c.reporter.(FixReporter)
+  if !ok {
+    c.reporter.ReportRange(pos, end, message)
+    return
+  }
+  fixer.ReportRangeFix(pos, end, message, edits...)
+}
+
+var registry []Rule
+
+// Register adds a contributor rule to the global registry. Called from a
+// contributor package's `init()`. Duplicate names are NOT checked here
+// — the host's adapter layer surfaces collisions with a clearer error
+// than a raw panic.
+func Register(r Rule) {
+  if r == nil {
+    panic("rule: Register called with nil rule")
+  }
+  registry = append(registry, r)
+}
+
+// Registered returns every contributor rule registered via `Register`.
+// Called once by the host during engine bootstrap. The returned slice is
+// a defensive copy so the host cannot mutate the registry.
+func Registered() []Rule {
+  out := make([]Rule, len(registry))
+  copy(out, registry)
+  return out
+}

package/src/defineConfig.ts

@@ -0,0 +1,69 @@
+import type { TtscLintConfig } from "./structures/TtscLintConfig";
+import type { TtscLintPlugins } from "./structures/TtscLintPlugins";
+
+/**
+ * Authoring helper that preserves the literal type of a lint config.
+ *
+ * ESLint's flat-config experience relies on `defineConfig` to capture the
+ * const-narrowed type of the configuration array, which is what makes plugin
+ * rule names autocomplete across entries. `@ttsc/lint` follows the same
+ * pattern: pass your config through this helper and the contributor plugin
+ * objects in `plugins` propagate their `rules` tuples into the rule-name
+ * union.
+ *
+ * ```ts
+ * import { defineConfig } from "@ttsc/lint";
+ * import importPlugin from "@ttsc/lint-plugin-import";
+ *
+ * export default defineConfig([
+ *   {
+ *     plugins: { import: importPlugin },
+ *     rules: {
+ *       "no-var": "error",
+ *       "import/no-cycle": ["error", { maxDepth: 1 }],
+ *     },
+ *   },
+ * ]);
+ * ```
+ *
+ * The function is a pure pass-through at runtime. The generic gymnastics below
+ * gather every `plugins` map across the array of config entries into one
+ * intersected `TtscLintPlugins` shape that gets threaded back into the
+ * `TtscLintConfig<P>` constraint. Without this, `TtscLintConfig`'s default `P =
+ * Record<string, never>` rules out every namespaced rule name and `{
+ * "import/no-cycle": "error" }` would be flagged as a typo.
+ */
+export function defineConfig<const T extends TtscLintConfig<GatherPlugins<T>>>(
+  config: T,
+): T {
+  return config;
+}
+
+/**
+ * Walks the input type to collect every plugin map declared across entries.
+ * Single entries yield the entry's `plugins`; arrays intersect every entry's
+ * `plugins` so each entry's rule-name union remains valid for the whole array.
+ * The intersection (vs. union) is load-bearing — TypeScript's `keyof (A | B)`
+ * collapses to `never`, which would reject every namespaced rule name.
+ *
+ * Plugins declared exclusively inside an `extends` chain are NOT collected:
+ * recursing into `T extends { extends?: infer E } ? GatherPlugins<E> : {}`
+ * blows TypeScript's instantiation budget (`extends` is itself a
+ * `TtscLintConfigEntry` tree). Authors should declare each plugin's `plugins`
+ * map on the outermost entry where its rules are configured. The runtime
+ * resolver still picks up plugins from `extends` entries; only the autocomplete
+ * domain is bounded.
+ */
+type GatherPlugins<T> = T extends { plugins?: infer P }
+  ? P extends TtscLintPlugins
+    ? P
+    : {}
+  : T extends readonly (infer Item)[]
+    ? UnionToIntersection<Item extends unknown ? GatherPlugins<Item> : never>
+    : {};
+
+type UnionToIntersection<U> = (
+  U extends unknown ? (x: U) => void : never
+) extends (x: infer I) => void
+  ? I
+  : never;