@ttsc/lint 0.19.3 → 0.20.0

package/linthost/hints.go

@@ -0,0 +1,207 @@
+package linthost
+
+import (
+  "fmt"
+  "os"
+
+  publicrule "github.com/samchon/ttsc/packages/lint/rule"
+)
+
+// RunLSPHints prints the editor-completion corpus every project rule published
+// for this project, as JSON.
+//
+// Unlike the other LSP verbs this takes no `--uri`: a corpus describes the
+// Program, not a document. It loads a Program only when the resolved config
+// declares a rule that can publish one, because a corpus is a projection of what
+// a project rule's Check found — which is why the caller is expected to cache
+// the answer and ask again only when the Program's inputs changed, never per
+// editor request.
+//
+// An empty corpus is a successful answer. A project with no hint-publishing rule
+// is the common case, and a caller must be able to tell it apart from a failure;
+// a nonzero exit here would read as "the project is broken".
+func RunLSPHints(args []string) int {
+  opts, ok := parseLSPCommandOptions("lsp-hints", args)
+  if !ok {
+    return 2
+  }
+  hints, code := computeLSPHints(opts)
+  if code != 0 {
+    return code
+  }
+  return writeJSON(hints)
+}
+
+// computeLSPHints builds the corpus for one project. Split from RunLSPHints so
+// the resident lsp-serve loop reuses it over a warm Program, the same split
+// computeLSPDiagnostics and computeLSPCodeActions already take.
+func computeLSPHints(opts *lspCommandOptions) ([]publicrule.Hint, int) {
+  rules, err := loadRules(opts.pluginsJSON, opts.cwd, opts.tsconfig)
+  if err != nil {
+    fmt.Fprintln(os.Stderr, err)
+    return nil, 2
+  }
+  engine := NewEngineWithResolver(rules)
+  if err := engine.ConfigError(); err != nil {
+    fmt.Fprintln(os.Stderr, err)
+    return nil, 2
+  }
+  publishes, needsChecker := engine.hasHintPublisher()
+  if !publishes {
+    // Nothing the config declared can publish a corpus, so there is no
+    // projection to take and the Program is never built. A project with no
+    // hint-publishing rule is the common case, and it used to pay a full parse
+    // and bind — and a checker build, when any unrelated file rule was
+    // type-aware — to arrive at this same empty answer.
+    return []publicrule.Hint{}, 0
+  }
+  prog, parseDiags, closeProgram, err := acquireProgram(opts, needsChecker)
+  if closeProgram != nil {
+    defer closeProgram()
+  }
+  if err != nil {
+    fmt.Fprintf(os.Stderr, "@ttsc/lint: %v\n", err)
+    return nil, 2
+  }
+  if prog == nil || len(parseDiags) > 0 {
+    // The project does not parse right now. Rules never ran, so there is no
+    // corpus — but these are tsgo's diagnostics to own, and failing here would
+    // make an editor treat a syntax error mid-typing as a broken plugin. A nil
+    // Program without diagnostics reaches the same answer rather than a JSON
+    // null, which a caller decoding an array would read as a broken plugin too.
+    return []publicrule.Hint{}, 0
+  }
+  return collectProjectHints(prog.runProjectCycle(engine)), 0
+}
+
+// hasHintPublisher reports whether any declared project rule can publish a
+// corpus, and whether serving those rules needs a type checker.
+//
+// Both answers come from the registration table and the resolved config, so
+// they are available before a Program exists — which is the point. A rule that
+// the config never declared, or turned off, cannot contribute to the corpus,
+// and collectProjectHints would skip it after the Program was built anyway.
+//
+// The checker answer is deliberately narrower than Engine.NeedsTypeChecker.
+// That flag is engine-wide, so one type-aware *file* rule would make this verb
+// build a checker no corpus reads. Here a checker is requested only when a rule
+// that actually publishes hints declined to say it needs none — the same
+// conservative default projectRuleNeedsTypeChecker applies everywhere else.
+func (e *Engine) hasHintPublisher() (publishes bool, needsChecker bool) {
+  if e == nil {
+    return false, false
+  }
+  for _, name := range allProjectRuleNames() {
+    setting := e.projectSettings[name]
+    if !setting.Declared || setting.Severity == SeverityOff {
+      continue
+    }
+    adapter, registered := registeredProjectRules[name]
+    if !registered {
+      continue
+    }
+    if _, publisher := adapter.inner.(publicrule.HintRule); !publisher {
+      continue
+    }
+    publishes = true
+    if projectRuleNeedsTypeChecker(name) {
+      // Every publisher's need is folded in rather than returning early: one
+      // rule declining a checker does not spare a sibling that reads one.
+      needsChecker = true
+    }
+  }
+  return publishes, needsChecker
+}
+
+// collectProjectHints gathers the editor-completion corpus every declared
+// project rule published for this Program.
+//
+// It runs after evaluateProject rather than inside it, because a corpus is a
+// projection of finished state: asking mid-check would publish whatever the rule
+// had indexed so far. Nothing calls this during `ttsc check`, so a rule's Hints
+// is never invoked, and its corpus never allocated, unless an editor asks.
+//
+// A rule is asked only when it passed and published state — the same gate a file
+// rule writes by hand against ProjectRulePassed. A rule that failed produced a
+// corpus describing a Program it just rejected, and offering that would complete
+// against facts the rule itself disowns.
+func collectProjectHints(cycle *projectCycle) []publicrule.Hint {
+  if cycle == nil || cycle.results == nil {
+    return nil
+  }
+  hints := []publicrule.Hint{}
+  for _, name := range allProjectRuleNames() {
+    result, exists := cycle.results.byName[name]
+    if !exists || result.reporter == nil {
+      continue
+    }
+    adapter, registered := registeredProjectRules[name]
+    if !registered {
+      continue
+    }
+    provider, ok := adapter.inner.(publicrule.HintRule)
+    if !ok {
+      continue
+    }
+    snapshot := result.reporter.snapshot()
+    if snapshot.Status != publicrule.ProjectRulePassed || snapshot.State == nil {
+      continue
+    }
+    hints = append(hints, ruleHints(name, provider, result, snapshot)...)
+  }
+  return hints
+}
+
+// ruleHints calls one rule's Hints behind a recover barrier and drops the hints
+// a rule cannot have meant.
+//
+// The barrier matches the metadata-inspection contract: a contributor panicking
+// while describing itself loses its contribution rather than the process. This
+// path is worse than most to leave unguarded — it runs inside an editor session,
+// where a crash is not a failed build but a language server that stopped
+// answering.
+func ruleHints(
+  name string,
+  provider publicrule.HintRule,
+  result projectCycleResult,
+  snapshot publicrule.ProjectRuleResult,
+) (hints []publicrule.Hint) {
+  defer func() {
+    if recovered := recover(); recovered != nil {
+      fmt.Fprintf(
+        os.Stderr,
+        "@ttsc/lint: project rule %q panicked while publishing hints: %v; dropping its corpus\n",
+        name,
+        recovered,
+      )
+      hints = nil
+    }
+  }()
+  published := provider.Hints(&publicrule.HintContext{
+    Identity: result.identity,
+    State:    snapshot.State,
+    Severity: publicrule.Severity(result.severity),
+    Options:  result.options,
+  })
+  kept := make([]publicrule.Hint, 0, len(published))
+  for _, hint := range published {
+    if !usableHint(hint) {
+      continue
+    }
+    kept = append(kept, hint)
+  }
+  return kept
+}
+
+// usableHint reports whether a hint can be offered at all.
+//
+// A hint with no scope would apply anywhere on any line, which is never what a
+// rule meant — it would surface in every decorator and every string literal — so
+// it is dropped rather than honored. A hint with no After is the same mistake
+// spelled differently: it matches every line in scope, so the corpus fires on an
+// empty doc comment. An empty Insert completes to nothing.
+func usableHint(hint publicrule.Hint) bool {
+  return hint.Insert != "" &&
+    hint.Trigger.Scope != "" &&
+    hint.Trigger.After != ""
+}

package/linthost/host.go

@@ -257,6 +257,23 @@ func resolveProjectPathAncestor(target string) (string, bool) {
   }
 }
 
+// runProjectCycle evaluates the project rules alone and returns the cycle,
+// without walking a single file.
+//
+// A consumer wanting only what project rules produced — a hint corpus, say —
+// should not pay for the file walk that produces findings it will throw away.
+// The cycle is memoized on the program exactly as runLintCycle memoizes it, so
+// asking for hints and then linting the same program evaluates each rule once.
+func (p *program) runProjectCycle(engine *Engine) *projectCycle {
+  if p == nil || engine == nil {
+    return nil
+  }
+  if p.projectCycle == nil {
+    p.projectCycle = engine.evaluateProject(p.identity, p.userSourceFiles(), p.checker)
+  }
+  return p.projectCycle
+}
+
 func (p *program) runLintCycle(engine *Engine) []*Finding {
   if p == nil || engine == nil {
     return nil
@@ -278,6 +295,57 @@ func (p *program) close() {
   p.checker = nil
 }
 
+// sourceFileByPath returns the resident Program's source file whose name matches
+// absPath (slash-normalized), or nil when the Program has no such file. Mirrors
+// how driver.Program.SourceFile resolves a path over SourceFiles().
+func (p *program) sourceFileByPath(absPath string) *shimast.SourceFile {
+  if p == nil || p.tsProgram == nil {
+    return nil
+  }
+  normalized := filepath.ToSlash(absPath)
+  for _, file := range p.tsProgram.SourceFiles() {
+    if file == nil {
+      continue
+    }
+    if filepath.ToSlash(file.FileName()) == normalized {
+      return file
+    }
+  }
+  return nil
+}
+
+// applyChange incrementally updates the resident Program for one changed file:
+// tsgo re-parses only that file and reuses every other file's AST, and the
+// standalone lint checker is rebuilt over the new Program. It mirrors
+// driver.Session.Apply, adapted to lint's standalone serial checker (lint cannot
+// borrow tsgo's pooled checker — see loadProgram). The caller has already
+// confirmed absPath is a known source file; a config edit or a new/removed file
+// is handled by a full reload upstream, not here. tsgo returns a rebuilt Program
+// when the edit reshaped the import graph, and that rebuilt Program is still
+// correct, so the reused flag is not consulted.
+func (p *program) applyChange(absPath string) {
+  if p == nil || p.tsProgram == nil {
+    return
+  }
+  name := absPath
+  if file := p.sourceFileByPath(absPath); file != nil {
+    name = file.FileName()
+  }
+  fs := bundled.WrapFS(cachedvfs.From(osvfs.FS()))
+  host := shimcompiler.NewCompilerHost(p.cwd, fs, bundled.LibPath(), nil, nil)
+  changed := shimtspath.ToPath(name, p.cwd, fs.UseCaseSensitiveFileNames())
+  newProg, _ := p.tsProgram.UpdateProgram(changed, host, nil)
+  if newProg != nil {
+    p.tsProgram = newProg
+    if p.checker != nil {
+      p.checker, _ = shimchecker.NewChecker(newProg, nil)
+    }
+  }
+  // The prior cycle described the pre-edit Program; drop it so the next verb
+  // re-evaluates its rules over the updated ASTs.
+  p.projectCycle = nil
+}
+
 // userSourceFiles returns the tsconfig-selected source files the lint engine
 // owns. The tsconfig file list is the boundary: imported libraries, generated
 // output, and JSON modules may still appear in Program.SourceFiles(), but lint

package/linthost/lsp.go

@@ -50,11 +50,39 @@ type lspRangeWire struct {
 }
 
 type lspDiagnostic struct {
-  Range    lspRange `json:"range"`
-  Severity int      `json:"severity,omitempty"`
-  Code     string   `json:"code,omitempty"`
-  Source   string   `json:"source,omitempty"`
-  Message  string   `json:"message"`
+  Range              lspRange                `json:"range"`
+  Severity           int                     `json:"severity,omitempty"`
+  Code               string                  `json:"code,omitempty"`
+  CodeDescription    *lspCodeDescription     `json:"codeDescription,omitempty"`
+  Source             string                  `json:"source,omitempty"`
+  Message            string                  `json:"message"`
+  Tags               []int                   `json:"tags,omitempty"`
+  RelatedInformation []lspRelatedInformation `json:"relatedInformation,omitempty"`
+}
+
+// lspLocation is the LSP Location: a URI plus a range inside it. The lint
+// sidecar only ever emits locations in the file being linted, so the URI is
+// always that file's, but the field is present because LSP requires it on every
+// related location.
+type lspLocation struct {
+  URI   string   `json:"uri"`
+  Range lspRange `json:"range"`
+}
+
+// lspRelatedInformation is one entry of a diagnostic's relatedInformation: a
+// secondary location the finding points at, with a message naming the link. The
+// editor renders each as a clickable line under the diagnostic.
+type lspRelatedInformation struct {
+  Location lspLocation `json:"location"`
+  Message  string      `json:"message"`
+}
+
+// lspCodeDescription mirrors the proxy's LSPCodeDescription: a docs URL for the
+// diagnostic's Code, which editors surface as the link on the rule id in the
+// Problems panel. ruleDocumentationURL derives the href per rule family (see
+// rule_docs.go); rules with no vetted page leave the whole field absent.
+type lspCodeDescription struct {
+  Href string `json:"href"`
 }
 
 type lspCommand struct {
@@ -123,18 +151,29 @@ type lspCommandOptions struct {
   projectIdentity publicrule.ProjectIdentity
 }
 
-// RunLSPCommandIDs prints the workspace/executeCommand ids owned by @ttsc/lint.
-func RunLSPCommandIDs([]string) int {
-  return writeJSON([]string{
+// lspCommandIDs is the workspace/executeCommand ids owned by @ttsc/lint, shared
+// by the one-shot verb and the resident lsp-serve loop.
+func lspCommandIDs() []string {
+  return []string{
     commandLintFixAll,
     commandLintApplySuggestion,
     commandFormatDocument,
-  })
+  }
+}
+
+// lspCodeActionKinds is the CodeActionKind values @ttsc/lint may return.
+func lspCodeActionKinds() []string {
+  return []string{"quickfix.ttsc", "source.fixAll.ttsc", "source.format"}
+}
+
+// RunLSPCommandIDs prints the workspace/executeCommand ids owned by @ttsc/lint.
+func RunLSPCommandIDs([]string) int {
+  return writeJSON(lspCommandIDs())
 }
 
 // RunLSPCodeActionKinds prints the CodeActionKind values @ttsc/lint may return.
 func RunLSPCodeActionKinds([]string) int {
-  return writeJSON([]string{"quickfix.ttsc", "source.fixAll.ttsc", "source.format"})
+  return writeJSON(lspCodeActionKinds())
 }
 
 // RunLSPDiagnostics prints lint diagnostics for one file URI as LSP JSON.
@@ -143,12 +182,23 @@ func RunLSPDiagnostics(args []string) int {
   if !ok {
     return 2
   }
+  result, code := computeLSPDiagnostics(opts)
+  if code != 0 {
+    return code
+  }
+  return writeJSON(result)
+}
+
+// computeLSPDiagnostics builds the diagnostics result for one file URI. Split
+// from RunLSPDiagnostics so the resident lsp-serve loop can produce the same
+// result against a warm Program without re-parsing per verb.
+func computeLSPDiagnostics(opts *lspCommandOptions) (lspDiagnosticsResult, int) {
   findings, prog, closeProgram, code := lspFindings(opts, false)
   if closeProgram != nil {
     defer closeProgram()
   }
   if code != 0 {
-    return code
+    return lspDiagnosticsResult{}, code
   }
   result := lspDiagnosticsResult{Document: []lspDiagnostic{}}
   for _, finding := range filterFindingsForPath(findings, mustFilePathFromURI(opts.uri)) {
@@ -164,7 +214,7 @@ func RunLSPDiagnostics(args []string) int {
     }
     result.Project = publication
   }
-  return writeJSON(result)
+  return result, 0
 }
 
 // RunLSPCodeActions prints code actions available for one file URI/range.
@@ -173,6 +223,17 @@ func RunLSPCodeActions(args []string) int {
   if !ok {
     return 2
   }
+  actions, code := computeLSPCodeActions(opts)
+  if code != 0 {
+    return code
+  }
+  return writeJSON(actions)
+}
+
+// computeLSPCodeActions builds the code actions for one file URI/range. Split
+// from RunLSPCodeActions so the resident lsp-serve loop reuses it over a warm
+// Program.
+func computeLSPCodeActions(opts *lspCommandOptions) ([]lspCodeAction, int) {
   acceptsLint := acceptsActionKind(opts.contextJSON, "source.fixAll.ttsc")
   acceptsQuickFix := acceptsActionKind(opts.contextJSON, "quickfix.ttsc")
   acceptsFormat := acceptsActionKind(opts.contextJSON, "source.format")
@@ -181,20 +242,20 @@ func RunLSPCodeActions(args []string) int {
     acceptsQuickFix = false
   }
   if !acceptsLint && !acceptsQuickFix && !acceptsFormat {
-    return writeJSON([]lspCodeAction{})
+    return []lspCodeAction{}, 0
   }
   if lspProjectTargetHasSegment(opts, "node_modules") {
-    return writeJSON([]lspCodeAction{})
+    return []lspCodeAction{}, 0
   }
   if lspProjectTargetOutsideCwd(opts) {
-    return writeJSON([]lspCodeAction{})
+    return []lspCodeAction{}, 0
   }
   findings, _, closeProgram, code := lspFindings(opts, acceptsFormat)
   if closeProgram != nil {
     defer closeProgram()
   }
   if code != 0 {
-    return code
+    return nil, code
   }
   findings = filterFindingsForPath(findings, mustFilePathFromURI(opts.uri))
   lintFindings := filterLintFindings(findings)
@@ -228,7 +289,7 @@ func RunLSPCodeActions(args []string) int {
       },
     })
   }
-  return writeJSON(actions)
+  return actions, 0
 }
 
 // RunLSPExecuteCommand returns a WorkspaceEdit for a lint-owned command.
@@ -347,21 +408,17 @@ func lspFindings(opts *lspCommandOptions, includeFormatDefaults bool) ([]*Findin
     fmt.Fprintln(os.Stderr, err)
     return nil, nil, nil, 2
   }
-  prog, parseDiags, err := loadProgram(opts.cwd, opts.tsconfig, loadProgramOptions{
-    forceNoEmit:      true,
-    needsRuleChecker: engine.NeedsTypeChecker(),
-    projectIdentity:  opts.projectIdentity,
-  })
+  prog, parseDiags, closeProgram, err := acquireProgram(opts, engine.NeedsTypeChecker())
   if err != nil {
     fmt.Fprintf(os.Stderr, "@ttsc/lint: %v\n", err)
     return nil, nil, nil, 2
   }
   if len(parseDiags) > 0 {
     // tsgo already owns parse diagnostics in the upstream LSP process.
-    return nil, prog, prog.close, 0
+    return nil, prog, closeProgram, 0
   }
   findings := prog.runLintCycle(engine)
-  return findings, prog, prog.close, 0
+  return findings, prog, closeProgram, 0
 }
 
 // loadLSPCommandRules constructs the resolver shared by every LSP command
@@ -415,14 +472,65 @@ func filterFindingsForPath(findings []*Finding, target string) []*Finding {
 
 func findingToLSPDiagnostic(finding *Finding) lspDiagnostic {
   return lspDiagnostic{
-    Range:    lspRangeForFinding(finding),
-    Severity: lspSeverity(finding.Severity),
-    Code:     finding.Rule,
-    Source:   "@ttsc/lint",
-    Message:  finding.Message,
+    Range:              lspRangeForFinding(finding),
+    Severity:           lspSeverity(finding.Severity),
+    Code:               finding.Rule,
+    CodeDescription:    lspCodeDescriptionForRule(finding.Rule),
+    Source:             "@ttsc/lint",
+    Message:            finding.Message,
+    Tags:               lspDiagnosticTags(finding.Tags),
+    RelatedInformation: lspRelatedInformationForFinding(finding),
   }
 }
 
+// lspRelatedInformationForFinding renders the finding's related locations. Each
+// location lives in the finding's own file, so it resolves the byte ranges
+// against that file's text and stamps the file's URI onto every entry. Returns
+// nil for a finding with no related locations, keeping the omitempty field
+// absent rather than an empty array.
+func lspRelatedInformationForFinding(finding *Finding) []lspRelatedInformation {
+  if finding == nil || len(finding.RelatedInformation) == 0 || finding.File == nil {
+    return nil
+  }
+  text := finding.File.Text()
+  uri := fileURL(finding.File.FileName())
+  out := make([]lspRelatedInformation, 0, len(finding.RelatedInformation))
+  for _, item := range finding.RelatedInformation {
+    out = append(out, lspRelatedInformation{
+      Location: lspLocation{
+        URI: uri,
+        Range: lspRange{
+          Start: byteOffsetToLSPPosition(text, item.Pos),
+          End:   byteOffsetToLSPPosition(text, item.End),
+        },
+      },
+      Message: item.Message,
+    })
+  }
+  return out
+}
+
+// lspDiagnosticTags converts the rule-supplied tags to their integer wire
+// values, dropping any the wire does not define so a future rule.DiagnosticTag
+// value cannot ship an integer no editor understands. Returns nil for an empty
+// set, keeping the omitempty field absent rather than an empty array.
+func lspDiagnosticTags(tags []publicrule.DiagnosticTag) []int {
+  if len(tags) == 0 {
+    return nil
+  }
+  out := make([]int, 0, len(tags))
+  for _, tag := range tags {
+    switch tag {
+    case publicrule.DiagnosticTagUnnecessary, publicrule.DiagnosticTagDeprecated:
+      out = append(out, int(tag))
+    }
+  }
+  if len(out) == 0 {
+    return nil
+  }
+  return out
+}
+
 func lspRangeForFinding(finding *Finding) lspRange {
   text := ""
   if finding != nil && finding.File != nil {
@@ -1297,6 +1405,17 @@ func filePathFromURI(raw string) (string, error) {
   return abs, nil
 }
 
+// byteOffsetToLSPPosition converts a byte offset in the linted file into the LSP
+// Position the editor is given for it: a 0-based line and a column counted in
+// UTF-16 code units.
+//
+// UTF-16 is both the LSP default and the encoding the sidecar protocol fixes:
+// the host settles the session's PositionEncodingKind negotiation on UTF-16 so a
+// sidecar always emits UTF-16 columns and always receives them, which is why no
+// request or response on this wire carries an encoding field. The compiler's own
+// ranges for a line and the ranges emitted here therefore agree. See the LSP
+// sidecar verb section of
+// website/src/content/docs/development/concepts/protocol.mdx.
 func byteOffsetToLSPPosition(text string, offset int) lspPosition {
   if offset < 0 {
     offset = 0

package/linthost/print_dispatch.go

@@ -121,6 +121,30 @@ func dispatchNode(ctx *PrintContext, node *shimast.Node) (Doc, bool, bool) {
   case shimast.KindConditionalExpression:
     doc, covered := printConditionalExpression(ctx, node)
     return doc, covered, true
+  case shimast.KindPropertyAssignment,
+    shimast.KindMethodDeclaration,
+    shimast.KindGetAccessor,
+    shimast.KindSetAccessor:
+    doc, covered := printObjectMember(ctx, node)
+    return doc, covered, true
+  case shimast.KindForStatement,
+    shimast.KindForOfStatement,
+    shimast.KindForInStatement,
+    shimast.KindWhileStatement,
+    shimast.KindIfStatement,
+    shimast.KindTryStatement,
+    shimast.KindSwitchStatement:
+    doc, covered := printControlFlowStatement(ctx, node)
+    return doc, covered, true
+  case shimast.KindCaseBlock:
+    doc, covered := printSwitchCaseBlock(ctx, node)
+    return doc, covered, true
+  case shimast.KindVariableStatement:
+    doc, covered := printVariableStatement(ctx, node)
+    return doc, covered, true
+  case shimast.KindThrowStatement:
+    doc, covered := printThrowStatement(ctx, node)
+    return doc, covered, true
   }
   return Doc{}, false, false
 }