@ttsc/lint 0.10.2 → 0.11.0-dev.20260518

package/linthost/config_format.go

@@ -0,0 +1,360 @@
+package linthost
+
+import (
+  "encoding/json"
+  "fmt"
+)
+
+// expandFormatBlock translates a Prettier-style `format` block into the
+// per-rule severity + options shape the existing rule parsers consume.
+// The result is a `map[string]any` that mirrors what a user would
+// have written under `rules` directly — entries like
+// `"format/semi": ["warning", {"prefer": "always"}]` — so the caller
+// can route it through either `ParseRulesWithOptions` (inline path) or
+// `parseExternalRuleMapInto` (flat-config path) without duplicating
+// option-decoding logic.
+//
+// The block's enablement matrix:
+//
+//   - `format/semi` — always on. `semi: false` flips to `prefer: "never"`.
+//   - `format/quotes` — always on. `singleQuote: true` flips to `prefer: "single"`.
+//   - `format/trailing-comma` — always on with the requested mode.
+//   - `format/print-width` — always on, driven by printWidth/tabWidth/useTabs/endOfLine.
+//   - `format/sort-imports` — opt-in by setting `importOrder`.
+//   - `format/jsdoc` — opt-in by setting `jsdoc` truthy.
+//
+// `severity` controls the per-finding severity for every emitted entry.
+// Default is "warning". Setting it to "off" returns an empty map so the
+// rest of the loader treats the block as if it were absent.
+//
+// The returned map is the raw form rules parsers expect. Callers MUST
+// merge any user-supplied `rules` map on top of this one (rules-wins
+// semantics) before invoking the existing parsers — `mergeRuleMaps`
+// below performs the merge with the right precedence.
+func expandFormatBlock(raw map[string]any) (map[string]any, error) {
+  if raw == nil {
+    return map[string]any{}, nil
+  }
+  if err := rejectUnknownFormatKeys(raw); err != nil {
+    return nil, err
+  }
+  severity := "warning"
+  if s, ok := raw["severity"]; ok && s != nil {
+    resolved, err := parseFormatSeverity(s)
+    if err != nil {
+      return nil, err
+    }
+    severity = resolved
+  }
+  if severityIsOff(severity) {
+    // `severity: "off"` collapses the whole block to a no-op so the
+    // engine never registers any of the format rules.
+    return map[string]any{}, nil
+  }
+
+  out := map[string]any{}
+
+  // format/semi
+  semiPrefer := "always"
+  if v, ok := raw["semi"]; ok {
+    b, err := asBool("format.semi", v)
+    if err != nil {
+      return nil, err
+    }
+    if !b {
+      semiPrefer = "never"
+    }
+  }
+  out["format/semi"] = []any{severity, map[string]any{"prefer": semiPrefer}}
+
+  // format/quotes
+  quotesPrefer := "double"
+  if v, ok := raw["singleQuote"]; ok {
+    b, err := asBool("format.singleQuote", v)
+    if err != nil {
+      return nil, err
+    }
+    if b {
+      quotesPrefer = "single"
+    }
+  }
+  out["format/quotes"] = []any{severity, map[string]any{"prefer": quotesPrefer}}
+
+  // format/trailing-comma
+  tcMode := "all"
+  if v, ok := raw["trailingComma"]; ok {
+    s, err := asString("format.trailingComma", v)
+    if err != nil {
+      return nil, err
+    }
+    switch s {
+    case "all", "es5", "none":
+      tcMode = s
+    default:
+      return nil, fmt.Errorf("@ttsc/lint: format.trailingComma must be \"all\", \"es5\", or \"none\"; got %q", s)
+    }
+  }
+  out["format/trailing-comma"] = []any{severity, map[string]any{"mode": tcMode}}
+
+  // format/print-width
+  pwOpts := map[string]any{}
+  if v, ok := raw["printWidth"]; ok {
+    n, err := asInt("format.printWidth", v)
+    if err != nil {
+      return nil, err
+    }
+    pwOpts["printWidth"] = n
+  }
+  if v, ok := raw["tabWidth"]; ok {
+    n, err := asInt("format.tabWidth", v)
+    if err != nil {
+      return nil, err
+    }
+    pwOpts["tabWidth"] = n
+  }
+  if v, ok := raw["useTabs"]; ok {
+    b, err := asBool("format.useTabs", v)
+    if err != nil {
+      return nil, err
+    }
+    pwOpts["useTabs"] = b
+  }
+  if v, ok := raw["endOfLine"]; ok {
+    s, err := asString("format.endOfLine", v)
+    if err != nil {
+      return nil, err
+    }
+    if s != "lf" && s != "crlf" {
+      return nil, fmt.Errorf("@ttsc/lint: format.endOfLine must be \"lf\" or \"crlf\"; got %q", s)
+    }
+    pwOpts["endOfLine"] = s
+  }
+  out["format/print-width"] = []any{severity, pwOpts}
+
+  // format/sort-imports — opt-in by `importOrder`.
+  if v, ok := raw["importOrder"]; ok {
+    siOpts := map[string]any{}
+    order, err := asStringSlice("format.importOrder", v)
+    if err != nil {
+      return nil, err
+    }
+    if len(order) == 0 {
+      return nil, fmt.Errorf("@ttsc/lint: format.importOrder must contain at least one entry; omit the field to keep format/sort-imports off")
+    }
+    siOpts["importOrder"] = order
+    if x, ok := raw["importOrderSeparation"]; ok {
+      b, err := asBool("format.importOrderSeparation", x)
+      if err != nil {
+        return nil, err
+      }
+      siOpts["importOrderSeparation"] = b
+    }
+    if x, ok := raw["importOrderSortSpecifiers"]; ok {
+      b, err := asBool("format.importOrderSortSpecifiers", x)
+      if err != nil {
+        return nil, err
+      }
+      siOpts["importOrderSortSpecifiers"] = b
+    }
+    if x, ok := raw["importOrderCaseInsensitive"]; ok {
+      b, err := asBool("format.importOrderCaseInsensitive", x)
+      if err != nil {
+        return nil, err
+      }
+      siOpts["importOrderCaseInsensitive"] = b
+    }
+    out["format/sort-imports"] = []any{severity, siOpts}
+  }
+
+  // format/jsdoc — opt-in by `jsdoc` truthy (boolean or object).
+  if v, ok := raw["jsdoc"]; ok && v != nil {
+    jdOpts := map[string]any{}
+    enabled := false
+    switch j := v.(type) {
+    case bool:
+      enabled = j
+    case map[string]any:
+      enabled = true
+      for key, val := range j {
+        switch key {
+        case "tagSynonyms":
+          ts, ok := val.(map[string]any)
+          if !ok {
+            return nil, fmt.Errorf("@ttsc/lint: format.jsdoc.tagSynonyms must be an object, got %T", val)
+          }
+          // Element values must be strings; surface
+          // typos early instead of after a downstream
+          // JSON-decode failure.
+          for k, v := range ts {
+            if _, ok := v.(string); !ok {
+              return nil, fmt.Errorf("@ttsc/lint: format.jsdoc.tagSynonyms[%q] must be a string, got %T", k, v)
+            }
+          }
+          jdOpts["tagSynonyms"] = ts
+        case "sortTags":
+          b, err := asBool("format.jsdoc.sortTags", val)
+          if err != nil {
+            return nil, err
+          }
+          jdOpts["sortTags"] = b
+        default:
+          return nil, fmt.Errorf("@ttsc/lint: format.jsdoc unknown key %q (allowed: tagSynonyms, sortTags)", key)
+        }
+      }
+    default:
+      return nil, fmt.Errorf("@ttsc/lint: format.jsdoc must be a boolean or object, got %T", v)
+    }
+    if enabled {
+      out["format/jsdoc"] = []any{severity, jdOpts}
+    }
+  }
+
+  return out, nil
+}
+
+// mergeRuleMaps overlays `overrides` on `base` and returns the merged
+// map. Identical keys in `overrides` replace the entire entry from
+// `base`; option objects are NOT deep-merged, which matches the
+// conflict-resolution policy spec: a `rules` entry that names a
+// `format/*` rule fully replaces the corresponding entry expanded
+// from the `format` block.
+func mergeRuleMaps(base, overrides map[string]any) map[string]any {
+  out := make(map[string]any, len(base)+len(overrides))
+  for k, v := range base {
+    out[k] = v
+  }
+  for k, v := range overrides {
+    out[k] = v
+  }
+  return out
+}
+
+func asBool(field string, v any) (bool, error) {
+  if b, ok := v.(bool); ok {
+    return b, nil
+  }
+  return false, fmt.Errorf("@ttsc/lint: %s must be a boolean, got %T", field, v)
+}
+
+func asString(field string, v any) (string, error) {
+  if s, ok := v.(string); ok {
+    return s, nil
+  }
+  return "", fmt.Errorf("@ttsc/lint: %s must be a string, got %T", field, v)
+}
+
+func asInt(field string, v any) (int, error) {
+  switch n := v.(type) {
+  case int:
+    return n, nil
+  case int32:
+    return int(n), nil
+  case int64:
+    return int(n), nil
+  case float64:
+    // JSON numbers decode as float64; coerce when integer-valued.
+    if float64(int(n)) == n {
+      return int(n), nil
+    }
+  case json.Number:
+    i, err := n.Int64()
+    if err == nil {
+      return int(i), nil
+    }
+  }
+  return 0, fmt.Errorf("@ttsc/lint: %s must be an integer, got %T", field, v)
+}
+
+func asStringSlice(field string, v any) ([]string, error) {
+  arr, ok := v.([]any)
+  if !ok {
+    return nil, fmt.Errorf("@ttsc/lint: %s must be an array of strings, got %T", field, v)
+  }
+  out := make([]string, 0, len(arr))
+  for i, item := range arr {
+    s, ok := item.(string)
+    if !ok {
+      return nil, fmt.Errorf("@ttsc/lint: %s[%d] must be a string, got %T", field, i, item)
+    }
+    out = append(out, s)
+  }
+  return out, nil
+}
+
+func severityIsOff(s string) bool {
+  switch s {
+  case "off":
+    return true
+  case "0":
+    return true
+  }
+  return false
+}
+
+// parseFormatSeverity validates a `format.severity` value (string or
+// numeric) against the documented allow-list and returns the
+// canonical string form. The strict allow-list catches typos
+// (`"warm"`, `"fatal"`) at the format block's boundary instead of
+// letting them leak through into per-rule entries where the eventual
+// error message blames the rule by name.
+func parseFormatSeverity(v any) (string, error) {
+  switch t := v.(type) {
+  case string:
+    switch t {
+    case "off", "warn", "warning", "error":
+      return t, nil
+    }
+    return "", fmt.Errorf("@ttsc/lint: format.severity must be one of \"off\", \"warn\", \"warning\", \"error\"; got %q", t)
+  case float64:
+    if t != float64(int(t)) {
+      return "", fmt.Errorf("@ttsc/lint: format.severity numeric form must be 0, 1, or 2; got %v", t)
+    }
+    switch int(t) {
+    case 0:
+      return "off", nil
+    case 1:
+      return "warn", nil
+    case 2:
+      return "error", nil
+    }
+    return "", fmt.Errorf("@ttsc/lint: format.severity numeric form must be 0, 1, or 2; got %d", int(t))
+  case int:
+    switch t {
+    case 0:
+      return "off", nil
+    case 1:
+      return "warn", nil
+    case 2:
+      return "error", nil
+    }
+    return "", fmt.Errorf("@ttsc/lint: format.severity numeric form must be 0, 1, or 2; got %d", t)
+  }
+  return "", fmt.Errorf("@ttsc/lint: format.severity must be a string or number, got %T", v)
+}
+
+// rejectUnknownFormatKeys surfaces typos in top-level format-block
+// keys at the boundary rather than silently ignoring them. The
+// allow-list mirrors `TtscLintFormatConfig` exactly.
+func rejectUnknownFormatKeys(raw map[string]any) error {
+  allowed := map[string]struct{}{
+    "severity":                   {},
+    "semi":                       {},
+    "singleQuote":                {},
+    "trailingComma":              {},
+    "printWidth":                 {},
+    "tabWidth":                   {},
+    "useTabs":                    {},
+    "endOfLine":                  {},
+    "importOrder":                {},
+    "importOrderSeparation":      {},
+    "importOrderSortSpecifiers":  {},
+    "importOrderCaseInsensitive": {},
+    "jsdoc":                      {},
+  }
+  for key := range raw {
+    if _, ok := allowed[key]; !ok {
+      return fmt.Errorf("@ttsc/lint: format unknown key %q; see TtscLintFormatConfig for the allowed surface", key)
+    }
+  }
+  return nil
+}

package/linthost/contrib_adapter.go

@@ -0,0 +1,134 @@
+// Adapter that bridges public `rule.Rule` contributors onto the engine's
+// internal `Rule` interface. Built-in rules live in `package main` and
+// dispatch directly through `Register`; contributors live in sibling
+// packages and call `rule.Register` from their `init()`. This file walks
+// the populated `rule.Registered()` slice and wraps each entry so the
+// engine sees the same surface for built-in and contributor rules.
+//
+// Init order: every contributor package's `init` runs before `package
+// main`'s init (Go spec). But the built-in rules also register from
+// `package main` init functions and the relative order across files in
+// the same package is alphabetical — so we cannot blindly run the
+// contributor wiring from a file-level `init()` and expect built-in
+// registration to have already completed. Instead, `registerContributors`
+// is invoked explicitly from `main.run` after all built-in `init` calls
+// have settled, which makes the collision check meaningful.
+package linthost
+
+import (
+  "fmt"
+  "os"
+  "sort"
+
+  shimast "github.com/microsoft/typescript-go/shim/ast"
+
+  "github.com/samchon/ttsc/packages/lint/rule"
+)
+
+// registerContributors wraps every contributor rule registered through
+// the public `rule` package into the engine's internal `Rule` interface
+// and pushes it onto the same dispatch table the built-in rules use.
+//
+// Collision policy: a contributor that shares a name with an existing
+// rule (built-in or another contributor whose init ran first) is dropped
+// with a stderr warning. The host prefers a deterministic, debuggable
+// outcome over panicking inside startup.
+func registerContributors() {
+  contributors := rule.Registered()
+  sort.SliceStable(contributors, func(i, j int) bool {
+    return contributors[i].Name() < contributors[j].Name()
+  })
+  for _, contributor := range contributors {
+    name := contributor.Name()
+    if name == "" {
+      fmt.Fprintln(os.Stderr, "@ttsc/lint: contributor rule with empty name ignored")
+      continue
+    }
+    if LookupRule(name) != nil {
+      fmt.Fprintf(os.Stderr,
+        "@ttsc/lint: contributor rule %q collides with an existing rule; dropping contributor entry\n",
+        name)
+      continue
+    }
+    if fr, ok := contributor.(rule.FormatRule); ok && fr.IsFormat() {
+      Register(formatContributorAdapter{contributorAdapter{inner: contributor}})
+      continue
+    }
+    Register(contributorAdapter{inner: contributor})
+  }
+}
+
+// contributorAdapter wraps a public `rule.Rule` so the engine's
+// `Register` accepts it. Forward `Name` and `Visits` directly; bridge
+// `Check` by constructing a `rule.Context` whose `Reporter` calls back
+// into the engine's existing `Context.Report` / `ReportRange`. The
+// public `rule.Context` and the engine's internal `Context` share the
+// same shim AST types, so no wrapping / unwrapping of nodes is needed.
+type contributorAdapter struct {
+  inner rule.Rule
+}
+
+// formatContributorAdapter is the FormatRule-tagged variant of
+// contributorAdapter. Wrapping the lint-only adapter (rather than
+// duplicating its method set) keeps the marker addition trivial and
+// guarantees the host's `isFormatRule` check fires through the standard
+// type assertion path.
+type formatContributorAdapter struct {
+  contributorAdapter
+}
+
+func (formatContributorAdapter) IsFormat() bool { return true }
+
+func (a contributorAdapter) Name() string           { return a.inner.Name() }
+func (a contributorAdapter) Visits() []shimast.Kind { return a.inner.Visits() }
+func (a contributorAdapter) Check(ctx *Context, node *shimast.Node) {
+  if ctx == nil {
+    return
+  }
+  pubCtx := rule.NewContext(
+    ctx.File,
+    ctx.Checker,
+    rule.Severity(ctx.Severity),
+    ctx.Options,
+    contextReporter{ctx: ctx},
+  )
+  a.inner.Check(pubCtx, node)
+}
+
+// contextReporter forwards `rule.Reporter` calls back to the host's
+// existing collect pipeline. Trivial because the public and internal
+// reporter signatures both speak `*shimast.Node`.
+type contextReporter struct {
+  ctx *Context
+}
+
+func (r contextReporter) Report(node *shimast.Node, message string) {
+  r.ctx.Report(node, message)
+}
+
+func (r contextReporter) ReportFix(node *shimast.Node, message string, edits ...rule.TextEdit) {
+  r.ctx.ReportFix(node, message, toInternalTextEdits(edits)...)
+}
+
+func (r contextReporter) ReportRange(pos, end int, message string) {
+  r.ctx.ReportRange(pos, end, message)
+}
+
+func (r contextReporter) ReportRangeFix(pos, end int, message string, edits ...rule.TextEdit) {
+  r.ctx.ReportRangeFix(pos, end, message, toInternalTextEdits(edits)...)
+}
+
+func toInternalTextEdits(edits []rule.TextEdit) []TextEdit {
+  if len(edits) == 0 {
+    return nil
+  }
+  out := make([]TextEdit, len(edits))
+  for i, edit := range edits {
+    out[i] = TextEdit{
+      Pos:  edit.Pos,
+      End:  edit.End,
+      Text: edit.Text,
+    }
+  }
+  return out
+}

package/{plugin → linthost}/directives.go

@@ -1,4 +1,4 @@
-package main
+package linthost
 
 import (
   "strings"

package/linthost/dispatch.go

@@ -0,0 +1,65 @@
+// Library entry for the @ttsc/lint native engine.
+//
+// The native `@ttsc/lint` CLI lives at `packages/lint/plugin` and is a thin
+// wrapper that calls `linthost.Main(os.Args[1:])`. Other consumers (e.g. the
+// ttsc.dev playground wasm) link `linthost` directly and dispatch through the
+// same entrypoint so the subcommand surface stays in one place.
+package linthost
+
+import (
+	"fmt"
+	"os"
+)
+
+// Version is the build banner string the `version` subcommand prints.
+// Overridden at link time via
+// `-ldflags "-X github.com/samchon/ttsc/packages/lint/linthost.Version=..."`.
+// Defaults to `"dev"` so local Go builds and `go test` runs print a
+// distinguishable value without depending on the release pipeline.
+var Version = "dev"
+
+// Main dispatches the lint plugin subcommands. `args` is the argv tail after
+// the binary name (i.e. `os.Args[1:]`). The return value is the exit code the
+// caller should propagate to the OS (`os.Exit`) or the host (`Plugin.Run`).
+//
+// 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)
+}
+
+// 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
+}