@ttsc/lint 0.5.0-dev.20260429

package/go-plugin/lint/engine.go

@@ -0,0 +1,259 @@
+// Package lint hosts the rule registry, the AST-walking engine, and the
+// orchestration glue that the `@ttsc/lint` native plugin uses to run rules
+// against a tsgo Program.
+//
+// Layering:
+//
+//   - `Rule` is the interface every rule implements. Rules are
+//     registered at package init time and never mutated.
+//   - `Engine` walks every user source file once, dispatching each visited
+//     node to the rules that opted in via `Visits()`.
+//   - `Context` is what a rule receives when it fires; it owns the
+//     report channel back to the engine.
+//
+// Rules are stateless across files: each invocation gets a fresh `Context`
+// and may not retain references to the previous file. This keeps the
+// engine concurrent-friendly even though the v0 implementation runs
+// serially.
+package lint
+
+import (
+	"sort"
+
+	shimast "github.com/microsoft/typescript-go/shim/ast"
+	shimchecker "github.com/microsoft/typescript-go/shim/checker"
+	shimscanner "github.com/microsoft/typescript-go/shim/scanner"
+)
+
+// Rule is the contract every lint rule satisfies.
+type Rule interface {
+	// Name is the identifier that users put in their `rules` map. Use
+	// the same names as `eslint` / `@typescript-eslint` where possible —
+	// this plugin is a host, not a renaming exercise.
+	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,
+	// which keeps the per-node hot path linear in active rules rather
+	// than total rules.
+	Visits() []shimast.Kind
+
+	// Check is invoked once per relevant node. Use `ctx.Report` to emit
+	// findings.
+	Check(ctx *Context, node *shimast.Node)
+}
+
+// Context is the per-(file, rule) handle the engine passes to `Check`.
+type Context struct {
+	File     *shimast.SourceFile
+	Checker  *shimchecker.Checker
+	Severity Severity
+
+	rule    Rule
+	collect func(*Finding)
+}
+
+// Finding is one rule-emitted diagnostic before it gets converted into a
+// driver Diagnostic.
+type Finding struct {
+	Rule     string
+	Severity Severity
+	File     *shimast.SourceFile
+	Pos      int
+	End      int
+	Message  string
+}
+
+// Report records a finding at the given node's source range. The pos is
+// trimmed past leading trivia (whitespace + comments) so the renderer's
+// `path:line:col` banner points at the offending token, not the start of
+// the surrounding indentation. A finding is silently dropped if the
+// configured severity is `off` (defensive — the engine already filters
+// by severity before calling Check, but a rule might lazy-evaluate in
+// the future).
+func (c *Context) Report(node *shimast.Node, message string) {
+	if c.Severity == SeverityOff || node == nil {
+		return
+	}
+	pos := node.Pos()
+	if c.File != nil {
+		pos = shimscanner.SkipTrivia(c.File.Text(), pos)
+	}
+	c.collect(&Finding{
+		Rule:     c.rule.Name(),
+		Severity: c.Severity,
+		File:     c.File,
+		Pos:      pos,
+		End:      node.End(),
+		Message:  message,
+	})
+}
+
+// ReportRange records a finding at an explicit byte range inside the
+// current file. Use this when the rule wants to highlight a sub-token of
+// a node (e.g. an operator inside a BinaryExpression).
+func (c *Context) ReportRange(pos, end int, message string) {
+	if c.Severity == SeverityOff || c.File == nil {
+		return
+	}
+	if end <= pos {
+		end = pos + 1
+	}
+	c.collect(&Finding{
+		Rule:     c.rule.Name(),
+		Severity: c.Severity,
+		File:     c.File,
+		Pos:      pos,
+		End:      end,
+		Message:  message,
+	})
+}
+
+// registry stores the package-global rule list keyed by name. Tests can
+// also reach into it via `LookupRule`.
+type registry struct {
+	rules map[string]Rule
+}
+
+var registered = &registry{rules: map[string]Rule{}}
+
+// Register adds a rule to the global registry. Called from each rule's
+// `init()`. Duplicate names are a programmer error and panic.
+func Register(rule Rule) {
+	if rule == nil {
+		panic("@ttsc/lint: Register called with nil rule")
+	}
+	if _, exists := registered.rules[rule.Name()]; exists {
+		panic("@ttsc/lint: rule " + rule.Name() + " registered twice")
+	}
+	registered.rules[rule.Name()] = rule
+}
+
+// LookupRule returns the registered rule by name, or nil if missing.
+func LookupRule(name string) Rule { return registered.rules[name] }
+
+// AllRuleNames returns the registry sorted alphabetically. Useful for
+// `--list-rules` style introspection and stable test snapshots.
+func AllRuleNames() []string {
+	names := make([]string, 0, len(registered.rules))
+	for n := range registered.rules {
+		names = append(names, n)
+	}
+	sort.Strings(names)
+	return names
+}
+
+// Engine binds a rule configuration to a Program and walks the AST once
+// per source file, dispatching each visited node to its interested rules.
+type Engine struct {
+	config   RuleConfig
+	rules    map[shimast.Kind][]Rule
+	enabled  map[string]Severity
+	unknown  []string
+}
+
+// NewEngine returns an engine configured for `config`. Rules whose
+// severity is `off` are skipped entirely. Configuration entries that name
+// an unknown rule are recorded so the caller can surface them as a
+// configuration warning rather than a silent typo.
+func NewEngine(config RuleConfig) *Engine {
+	eng := &Engine{
+		config:  config,
+		rules:   make(map[shimast.Kind][]Rule),
+		enabled: make(map[string]Severity),
+	}
+	for name, sev := range config {
+		rule, ok := registered.rules[name]
+		if !ok {
+			eng.unknown = append(eng.unknown, name)
+			continue
+		}
+		if sev == SeverityOff {
+			continue
+		}
+		eng.enabled[name] = sev
+		for _, kind := range rule.Visits() {
+			eng.rules[kind] = append(eng.rules[kind], rule)
+		}
+	}
+	sort.Strings(eng.unknown)
+	return eng
+}
+
+// UnknownRules returns the names of rules that appeared in the config but
+// have no registered implementation.
+func (e *Engine) UnknownRules() []string { return e.unknown }
+
+// EnabledRules returns the active rule set keyed by name. Mostly for
+// tests + introspection.
+func (e *Engine) EnabledRules() map[string]Severity { return e.enabled }
+
+// Run walks every non-declaration source file in the program and
+// returns the collected findings.
+func (e *Engine) Run(files []*shimast.SourceFile, checker *shimchecker.Checker) []*Finding {
+	var findings []*Finding
+	for _, file := range files {
+		if file == nil || file.IsDeclarationFile {
+			continue
+		}
+		findings = append(findings, e.runFile(file, checker)...)
+	}
+	return findings
+}
+
+// runFile is the per-file driver. The visitor is allocated once per file
+// to keep the per-node hot path branch-free; it visits children
+// post-order so parents see their already-checked subtrees.
+func (e *Engine) runFile(file *shimast.SourceFile, checker *shimchecker.Checker) []*Finding {
+	var collected []*Finding
+	collect := func(f *Finding) { collected = append(collected, f) }
+
+	var walk func(node *shimast.Node)
+	walk = func(node *shimast.Node) {
+		if node == nil {
+			return
+		}
+		if rules, ok := e.rules[node.Kind]; ok {
+			for _, rule := range rules {
+				ctx := &Context{
+					File:     file,
+					Checker:  checker,
+					Severity: e.enabled[rule.Name()],
+					rule:     rule,
+					collect:  collect,
+				}
+				rule.Check(ctx, node)
+			}
+		}
+		node.ForEachChild(func(child *shimast.Node) bool {
+			walk(child)
+			return false // visit every child
+		})
+	}
+
+	// SourceFile dispatches into its statement list directly; we walk
+	// statements explicitly so the file node itself can be inspected by
+	// rules (e.g., `ban-ts-comment` reads CommentDirectives off the
+	// SourceFile).
+	if rules, ok := e.rules[shimast.KindSourceFile]; ok {
+		for _, rule := range rules {
+			ctx := &Context{
+				File:     file,
+				Checker:  checker,
+				Severity: e.enabled[rule.Name()],
+				rule:     rule,
+				collect:  collect,
+			}
+			rule.Check(ctx, file.AsNode())
+		}
+	}
+
+	statements := file.Statements
+	if statements == nil {
+		return collected
+	}
+	for _, stmt := range statements.Nodes {
+		walk(stmt)
+	}
+	return collected
+}

package/go-plugin/lint/host.go

@@ -0,0 +1,190 @@
+// Bootstrap glue for the @ttsc/lint native binary.
+//
+// We don't import `github.com/samchon/ttsc/packages/ttsc/driver` from a
+// source plugin because that would force every consumer of @ttsc/lint to
+// have the in-tree samchon/ttsc/packages/ttsc module on their go.work — a
+// dependency the public proxy cannot satisfy and that conflicts with
+// 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 lint
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"path/filepath"
+
+	shimast "github.com/microsoft/typescript-go/shim/ast"
+	"github.com/microsoft/typescript-go/shim/bundled"
+	shimchecker "github.com/microsoft/typescript-go/shim/checker"
+	shimcompiler "github.com/microsoft/typescript-go/shim/compiler"
+	shimcore "github.com/microsoft/typescript-go/shim/core"
+	"github.com/microsoft/typescript-go/shim/tsoptions"
+	"github.com/microsoft/typescript-go/shim/vfs/cachedvfs"
+	"github.com/microsoft/typescript-go/shim/vfs/osvfs"
+)
+
+// program bundles the tsgo Program with the parsed config and a checker
+// release callback so the orchestration code can clean up after itself.
+type program struct {
+	cwd            string
+	tsProgram      *shimcompiler.Program
+	parsed         *tsoptions.ParsedCommandLine
+	checker        *shimchecker.Checker
+	releaseChecker func()
+}
+
+type loadProgramOptions struct {
+	forceEmit   bool
+	forceNoEmit bool
+	outDir      string
+}
+
+// loadProgram parses the given tsconfig, builds a Program, and acquires a
+// type checker. Mirrors the canonical bootstrap pattern from
+// `03-tsgo.md` — the only ttsc-specific bit is that `forceEmit`/
+// `forceNoEmit`/`outDir` overrides are merged into the parsed config
+// before the program is created so `--noEmit` and friends behave like
+// they do in `ttsc check`.
+func loadProgram(cwd, tsconfigPath string, options loadProgramOptions) (*program, []*shimast.Diagnostic, error) {
+	if !filepath.IsAbs(cwd) {
+		abs, err := filepath.Abs(cwd)
+		if err != nil {
+			return nil, nil, fmt.Errorf("loadProgram: cwd: %w", err)
+		}
+		cwd = abs
+	}
+	resolved := tsconfigPath
+	if !filepath.IsAbs(resolved) {
+		resolved = filepath.Join(cwd, resolved)
+	}
+
+	fs := bundled.WrapFS(cachedvfs.From(osvfs.FS()))
+	host := shimcompiler.NewCompilerHost(cwd, fs, bundled.LibPath(), nil, nil)
+
+	parsed, parseDiags := tsoptions.GetParsedCommandLineOfConfigFile(
+		resolved,
+		&shimcore.CompilerOptions{},
+		nil,
+		host,
+		nil,
+	)
+	if parsed == nil {
+		return nil, nil, fmt.Errorf("tsoptions: parsed command line was nil for %s", resolved)
+	}
+	if len(parseDiags) > 0 {
+		return nil, parseDiags, nil
+	}
+	if len(parsed.Errors) > 0 {
+		return nil, parsed.Errors, nil
+	}
+	if options.forceNoEmit {
+		forceNoEmit(parsed)
+	}
+	if options.forceEmit {
+		forceEmit(parsed)
+	}
+	if options.outDir != "" {
+		overrideOutDir(cwd, parsed, options.outDir)
+	}
+
+	tsProgram := shimcompiler.NewProgram(shimcompiler.ProgramOptions{
+		Config:                      parsed,
+		SingleThreaded:              shimcore.TSTrue,
+		Host:                        host,
+		UseSourceOfProjectReference: true,
+	})
+	if tsProgram == nil {
+		return nil, nil, errors.New("compiler.NewProgram returned nil")
+	}
+	checker, release := tsProgram.GetTypeChecker(context.Background())
+	return &program{
+		cwd:            cwd,
+		tsProgram:      tsProgram,
+		parsed:         parsed,
+		checker:        checker,
+		releaseChecker: release,
+	}, nil, nil
+}
+
+func (p *program) close() {
+	if p == nil {
+		return
+	}
+	if p.releaseChecker != nil {
+		p.releaseChecker()
+		p.releaseChecker = nil
+	}
+}
+
+// userSourceFiles returns the program's user-authored source files
+// (declaration files filtered out — those belong to library typings).
+func (p *program) userSourceFiles() []*shimast.SourceFile {
+	out := make([]*shimast.SourceFile, 0)
+	for _, f := range p.tsProgram.SourceFiles() {
+		if f == nil || f.IsDeclarationFile {
+			continue
+		}
+		out = append(out, f)
+	}
+	return out
+}
+
+// programDiagnostics returns the bind + semantic diagnostics for the
+// loaded program. Same surface tsgo's CLI prints when you run a regular
+// `tsgo --noEmit`.
+func (p *program) programDiagnostics() []*shimast.Diagnostic {
+	if p == nil || p.tsProgram == nil {
+		return nil
+	}
+	ctx := context.Background()
+	raw := shimcompiler.GetDiagnosticsOfAnyProgram(
+		ctx,
+		p.tsProgram,
+		nil,
+		false,
+		p.tsProgram.GetBindDiagnostics,
+		p.tsProgram.GetSemanticDiagnostics,
+	)
+	return shimcompiler.SortAndDeduplicateDiagnostics(raw)
+}
+
+// findSourceFile locates a source file in the program by absolute path.
+// tsgo normalizes paths to forward slashes; we do the same on our side.
+func (p *program) findSourceFile(target string) *shimast.SourceFile {
+	want := filepath.ToSlash(target)
+	for _, file := range p.tsProgram.SourceFiles() {
+		if filepath.ToSlash(file.FileName()) == want {
+			return file
+		}
+	}
+	return nil
+}
+
+func forceEmit(parsed *tsoptions.ParsedCommandLine) {
+	if parsed == nil || parsed.ParsedConfig == nil || parsed.ParsedConfig.CompilerOptions == nil {
+		return
+	}
+	options := parsed.ParsedConfig.CompilerOptions
+	options.NoEmit = shimcore.TSFalse
+	options.EmitDeclarationOnly = shimcore.TSFalse
+}
+
+func forceNoEmit(parsed *tsoptions.ParsedCommandLine) {
+	if parsed == nil || parsed.ParsedConfig == nil || parsed.ParsedConfig.CompilerOptions == nil {
+		return
+	}
+	parsed.ParsedConfig.CompilerOptions.NoEmit = shimcore.TSTrue
+}
+
+func overrideOutDir(cwd string, parsed *tsoptions.ParsedCommandLine, outDir string) {
+	if parsed == nil || parsed.ParsedConfig == nil || parsed.ParsedConfig.CompilerOptions == nil {
+		return
+	}
+	if filepath.IsAbs(outDir) {
+		parsed.ParsedConfig.CompilerOptions.OutDir = filepath.ToSlash(outDir)
+		return
+	}
+	parsed.ParsedConfig.CompilerOptions.OutDir = filepath.ToSlash(filepath.Join(cwd, outDir))
+}

package/go-plugin/lint/rules_arrays.go

@@ -0,0 +1,78 @@
+package lint
+
+import shimast "github.com/microsoft/typescript-go/shim/ast"
+
+// no-sparse-arrays: `[1, , 2]` — the implied undefined slot is almost
+// always a typo.
+// https://eslint.org/docs/latest/rules/no-sparse-arrays
+type noSparseArrays struct{}
+
+func (noSparseArrays) Name() string             { return "no-sparse-arrays" }
+func (noSparseArrays) Visits() []shimast.Kind   { return []shimast.Kind{shimast.KindArrayLiteralExpression} }
+func (noSparseArrays) Check(ctx *Context, node *shimast.Node) {
+	arr := node.AsArrayLiteralExpression()
+	if arr == nil || arr.Elements == nil {
+		return
+	}
+	for _, el := range arr.Elements.Nodes {
+		if el != nil && el.Kind == shimast.KindOmittedExpression {
+			ctx.Report(node, "Unexpected comma in middle of array.")
+			return
+		}
+	}
+}
+
+// no-array-constructor: forbid `new Array(0)` / `Array(1, 2, 3)` (use
+// array literals). The 1-arg numeric form is also banned because its
+// behavior depends on the runtime — see ESLint defaults.
+// https://eslint.org/docs/latest/rules/no-array-constructor
+type noArrayConstructor struct{}
+
+func (noArrayConstructor) Name() string { return "no-array-constructor" }
+func (noArrayConstructor) Visits() []shimast.Kind {
+	return []shimast.Kind{shimast.KindNewExpression, shimast.KindCallExpression}
+}
+func (noArrayConstructor) Check(ctx *Context, node *shimast.Node) {
+	var callee *shimast.Node
+	var argCount int
+	switch node.Kind {
+	case shimast.KindNewExpression:
+		ne := node.AsNewExpression()
+		if ne == nil {
+			return
+		}
+		if ne.TypeArguments != nil && len(ne.TypeArguments.Nodes) > 0 {
+			return // `new Array<string>()` is a typed empty array
+		}
+		callee = ne.Expression
+		if ne.Arguments != nil {
+			argCount = len(ne.Arguments.Nodes)
+		}
+	case shimast.KindCallExpression:
+		call := node.AsCallExpression()
+		if call == nil {
+			return
+		}
+		if call.TypeArguments != nil && len(call.TypeArguments.Nodes) > 0 {
+			return
+		}
+		callee = call.Expression
+		if call.Arguments != nil {
+			argCount = len(call.Arguments.Nodes)
+		}
+	}
+	if identifierText(callee) != "Array" {
+		return
+	}
+	// Single-arg numeric — ambiguous (length vs single element). Skip
+	// so existing patterns aren't flagged when the intent is preallocate.
+	if argCount == 1 {
+		return
+	}
+	ctx.Report(node, "The array literal notation [] is preferable.")
+}
+
+func init() {
+	Register(noSparseArrays{})
+	Register(noArrayConstructor{})
+}

package/go-plugin/lint/rules_console.go

@@ -0,0 +1,37 @@
+package lint
+
+import shimast "github.com/microsoft/typescript-go/shim/ast"
+
+// no-console: forbid `console.*` calls. Default mode flags every method;
+// users who want to allow specific methods can configure ESLint-style
+// allowlists in a future iteration.
+// https://eslint.org/docs/latest/rules/no-console
+type noConsole struct{}
+
+func (noConsole) Name() string             { return "no-console" }
+func (noConsole) Visits() []shimast.Kind   { return []shimast.Kind{shimast.KindCallExpression} }
+func (noConsole) Check(ctx *Context, node *shimast.Node) {
+	call := node.AsCallExpression()
+	if call == nil || call.Expression == nil {
+		return
+	}
+	if call.Expression.Kind != shimast.KindPropertyAccessExpression {
+		return
+	}
+	access := call.Expression.AsPropertyAccessExpression()
+	if access == nil {
+		return
+	}
+	if identifierText(access.Expression) != "console" {
+		return
+	}
+	method := identifierText(access.Name())
+	if method == "" {
+		return
+	}
+	ctx.Report(node, "Unexpected console statement.")
+}
+
+func init() {
+	Register(noConsole{})
+}

package/go-plugin/lint/rules_debugger.go

@@ -0,0 +1,29 @@
+package lint
+
+import shimast "github.com/microsoft/typescript-go/shim/ast"
+
+// no-debugger: forbid `debugger` statements.
+// https://eslint.org/docs/latest/rules/no-debugger
+type noDebugger struct{}
+
+func (noDebugger) Name() string             { return "no-debugger" }
+func (noDebugger) Visits() []shimast.Kind   { return []shimast.Kind{shimast.KindDebuggerStatement} }
+func (noDebugger) Check(ctx *Context, node *shimast.Node) {
+	ctx.Report(node, "Unexpected `debugger` statement.")
+}
+
+// no-with: forbid `with` statements (already disallowed in strict mode,
+// but lint catches it before the parse error).
+// https://eslint.org/docs/latest/rules/no-with
+type noWith struct{}
+
+func (noWith) Name() string             { return "no-with" }
+func (noWith) Visits() []shimast.Kind   { return []shimast.Kind{shimast.KindWithStatement} }
+func (noWith) Check(ctx *Context, node *shimast.Node) {
+	ctx.Report(node, "Unexpected `with` statement.")
+}
+
+func init() {
+	Register(noDebugger{})
+	Register(noWith{})
+}