@ttsc/lint 0.19.0 → 0.19.1

package/README.md

@@ -1182,6 +1182,36 @@ func init() { rule.RegisterProject(noCycles{}) }
 
 Each project rule runs once per loaded Program, before file rules. `ctx.Identity` includes the invocation cwd, logical and physical config paths and roots, an optional explicit project root, the plugin-config origin, and a lifecycle id. `Report` marks the rule failed and emits one project finding; `Fail` marks it failed without a finding. Later file rules can call `ctx.ProjectResult(name)` and distinguish `absent`, `off`, `not_evaluated`, `passed`, and `failed`.
 
+Use `ctx.SetState(value)` when a later file rule needs the exact project binding selected during that check. The host returns the same value without interpreting or serializing it:
+
+```go
+type projectBinding struct { /* contributor-owned fields */ }
+
+func (projectGuard) Check(ctx *rule.ProjectContext) {
+  ctx.SetState(loadProjectBinding(ctx.Identity))
+}
+
+func (guardedFileRule) Check(ctx *rule.Context, node *ast.Node) {
+  result := ctx.ProjectResult("demo/project-guard")
+  if result.Status != rule.ProjectRulePassed {
+    return
+  }
+  binding, ok := result.State.(*projectBinding)
+  if !ok {
+    return
+  }
+  if err := binding.Revalidate(); err != nil {
+    result.Report(err.Error())
+    return
+  }
+  useGuardedResource(binding, node)
+}
+```
+
+`ProjectResult` is a snapshot of the current status and findings, while its `Report` and `Fail` methods remain live until file dispatch finishes. Call `ctx.ProjectResult(name)` again to observe a failure reported by an earlier helper. Equal messages are deduplicated, distinct messages are sorted, and finalized project findings stay ahead of file findings. `absent`, `off`, and `not_evaluated` results expose no state and their mutation methods do nothing.
+
+State belongs to one loaded Program cycle. The host does not carry it into a watch or LSP rebuild: the new project check attaches that cycle's value and receives a new reporter. A reporter retained past file dispatch is inert. The host synchronizes status changes and finding deduplication across concurrent files. The contributor must create any required fresh state and synchronize mutable data inside its own value.
+
 Project rules use the normal `rules` map and `extends` order, but only global config entries may configure them. Any entry that contains `files`, including `files: []` or an `off` value, is rejected. Global `ignores` remain source-file filters rather than project-rule selectors. A later bare severity preserves the last explicit tuple options while replacing severity.
 
 CLI, API, watch, and LSP runs carry the same project identity into the native host. Structured API findings use `file: null`. LSP publishes project findings once at the logical config URI with a zero range and no document version; project findings never provide fixes or code actions.

package/linthost/engine.go

@@ -694,7 +694,7 @@ func (e *Engine) Run(files []*shimast.SourceFile, checker *shimchecker.Checker)
     currentDirectory, _ = os.Getwd()
   }
   fileFindings := e.runFiles(files, checker, cycle.results, currentDirectory)
-  return append(cycle.findings, fileFindings...)
+  return append(cycle.finalize(), fileFindings...)
 }
 
 func (e *Engine) runFiles(

package/linthost/host.go

@@ -263,11 +263,10 @@ func (p *program) runLintCycle(engine *Engine) []*Finding {
   }
   files := p.userSourceFiles()
   if p.projectCycle == nil {
-    cycle := engine.evaluateProject(p.identity, files, p.checker)
-    p.projectCycle = &cycle
+    p.projectCycle = engine.evaluateProject(p.identity, files, p.checker)
   }
-  projectFindings := append([]*Finding(nil), p.projectCycle.findings...)
-  return append(projectFindings, engine.runFiles(files, p.checker, p.projectCycle.results, p.cwd)...)
+  fileFindings := engine.runFiles(files, p.checker, p.projectCycle.results, p.cwd)
+  return append(p.projectCycle.finalize(), fileFindings...)
 }
 
 // close drops the standalone lint checker. Safe to call on a nil receiver and

package/linthost/project_engine.go

@@ -3,6 +3,7 @@ package linthost
 import (
   "fmt"
   "sort"
+  "sync"
 
   shimast "github.com/microsoft/typescript-go/shim/ast"
   shimchecker "github.com/microsoft/typescript-go/shim/checker"
@@ -10,7 +11,13 @@ import (
 )
 
 type projectCycleResults struct {
-  byName map[string]publicrule.ProjectRuleResult
+  byName map[string]projectCycleResult
+}
+
+type projectCycleResult struct {
+  status   publicrule.ProjectRuleStatus
+  severity Severity
+  reporter *projectReporter
 }
 
 func (r *projectCycleResults) ProjectResult(name string) publicrule.ProjectRuleResult {
@@ -21,22 +28,33 @@ func (r *projectCycleResults) ProjectResult(name string) publicrule.ProjectRuleR
   if !ok {
     return publicrule.ProjectRuleResult{Status: publicrule.ProjectRuleAbsent}
   }
-  result.Findings = append([]publicrule.ProjectFinding(nil), result.Findings...)
-  return result
+  if result.reporter == nil {
+    return publicrule.ProjectRuleResult{Status: result.status}
+  }
+  return result.reporter.snapshot()
 }
 
 type projectCycle struct {
-  findings []*Finding
-  results  *projectCycleResults
+  finalizeOnce sync.Once
+  findings     []*Finding
+  results      *projectCycleResults
 }
 
 type projectReporter struct {
+  mu       sync.Mutex
+  active   bool
   failed   bool
   messages map[string]struct{}
+  state    any
 }
 
 func (r *projectReporter) Fail() {
-  if r != nil {
+  if r == nil {
+    return
+  }
+  r.mu.Lock()
+  defer r.mu.Unlock()
+  if r.active {
     r.failed = true
   }
 }
@@ -45,6 +63,11 @@ func (r *projectReporter) Report(message string) {
   if r == nil {
     return
   }
+  r.mu.Lock()
+  defer r.mu.Unlock()
+  if !r.active {
+    return
+  }
   r.failed = true
   if r.messages == nil {
     r.messages = map[string]struct{}{}
@@ -52,13 +75,85 @@ func (r *projectReporter) Report(message string) {
   r.messages[message] = struct{}{}
 }
 
+func (r *projectReporter) SetState(state any) {
+  if r == nil {
+    return
+  }
+  r.mu.Lock()
+  defer r.mu.Unlock()
+  if r.active {
+    r.state = state
+  }
+}
+
+func (r *projectReporter) snapshot() publicrule.ProjectRuleResult {
+  return r.snapshotLocked(false)
+}
+
+func (r *projectReporter) snapshotAndClose() publicrule.ProjectRuleResult {
+  return r.snapshotLocked(true)
+}
+
+func (r *projectReporter) snapshotLocked(close bool) publicrule.ProjectRuleResult {
+  if r == nil {
+    return publicrule.ProjectRuleResult{Status: publicrule.ProjectRuleAbsent}
+  }
+  r.mu.Lock()
+  defer r.mu.Unlock()
+  if close {
+    r.active = false
+  }
+  messages := make([]string, 0, len(r.messages))
+  for message := range r.messages {
+    messages = append(messages, message)
+  }
+  sort.Strings(messages)
+  status := publicrule.ProjectRulePassed
+  if r.failed {
+    status = publicrule.ProjectRuleFailed
+  }
+  findings := make([]publicrule.ProjectFinding, 0, len(messages))
+  for _, message := range messages {
+    findings = append(findings, publicrule.ProjectFinding{Message: message})
+  }
+  return publicrule.NewProjectRuleResult(status, r.state, findings, r)
+}
+
+func (c *projectCycle) finalize() []*Finding {
+  if c == nil || c.results == nil {
+    return nil
+  }
+  c.finalizeOnce.Do(func() {
+    names := make([]string, 0, len(c.results.byName))
+    for name := range c.results.byName {
+      names = append(names, name)
+    }
+    sort.Strings(names)
+    for _, name := range names {
+      entry := c.results.byName[name]
+      if entry.reporter == nil {
+        continue
+      }
+      result := entry.reporter.snapshotAndClose()
+      for _, finding := range result.Findings {
+        c.findings = append(c.findings, &Finding{
+          Rule:     name,
+          Severity: entry.severity,
+          Message:  finding.Message,
+        })
+      }
+    }
+  })
+  return append([]*Finding(nil), c.findings...)
+}
+
 func (e *Engine) evaluateProject(
   identity publicrule.ProjectIdentity,
   files []*shimast.SourceFile,
   checker *shimchecker.Checker,
-) projectCycle {
-  results := &projectCycleResults{byName: map[string]publicrule.ProjectRuleResult{}}
-  cycle := projectCycle{results: results}
+) *projectCycle {
+  results := &projectCycleResults{byName: map[string]projectCycleResult{}}
+  cycle := &projectCycle{results: results}
   names := allProjectRuleNames()
   if len(names) == 0 {
     return cycle
@@ -68,11 +163,11 @@ func (e *Engine) evaluateProject(
   for _, name := range names {
     setting := e.projectSettings[name]
     if !setting.Declared {
-      results.byName[name] = publicrule.ProjectRuleResult{Status: publicrule.ProjectRuleNotEvaluated}
+      results.byName[name] = projectCycleResult{status: publicrule.ProjectRuleNotEvaluated}
       continue
     }
     if setting.Severity == SeverityOff {
-      results.byName[name] = publicrule.ProjectRuleResult{Status: publicrule.ProjectRuleOff}
+      results.byName[name] = projectCycleResult{status: publicrule.ProjectRuleOff}
       continue
     }
     adapter, exists := registeredProjectRules[name]
@@ -83,7 +178,7 @@ func (e *Engine) evaluateProject(
       sources = e.projectSources(files)
       sourcesResolved = true
     }
-    reporter := &projectReporter{}
+    reporter := &projectReporter{active: true}
     context := publicrule.NewProjectContext(
       identity,
       sources,
@@ -93,25 +188,10 @@ func (e *Engine) evaluateProject(
       reporter,
     )
     runProjectRuleCheck(adapter, context, reporter)
-    messages := make([]string, 0, len(reporter.messages))
-    for message := range reporter.messages {
-      messages = append(messages, message)
-    }
-    sort.Strings(messages)
-    status := publicrule.ProjectRulePassed
-    if reporter.failed {
-      status = publicrule.ProjectRuleFailed
-    }
-    result := publicrule.ProjectRuleResult{Status: status}
-    for _, message := range messages {
-      result.Findings = append(result.Findings, publicrule.ProjectFinding{Message: message})
-      cycle.findings = append(cycle.findings, &Finding{
-        Rule:     name,
-        Severity: setting.Severity,
-        Message:  message,
-      })
+    results.byName[name] = projectCycleResult{
+      severity: setting.Severity,
+      reporter: reporter,
     }
-    results.byName[name] = result
   }
   return cycle
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ttsc/lint",
-  "version": "0.19.0",
+  "version": "0.19.1",
   "description": "Reference ttsc plugin: ESLint-style lint rules over the TypeScript-Go Program used by the type-check pass.",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -37,7 +37,7 @@
     "@types/node": "^25.3.0",
     "rimraf": "^6.1.2",
     "typescript": "^7.0.2",
-    "ttsc": "0.19.0"
+    "ttsc": "0.19.1"
   },
   "repository": {
     "type": "git",

package/rule/project.go

@@ -39,16 +39,59 @@ type ProjectFinding struct {
   Message string
 }
 
-// ProjectRuleResult is the finalized, read-only view of one named project
-// rule. Findings is returned as a defensive copy by host result readers.
+// ProjectRuleResult is one snapshot of a named project rule in the current
+// Program cycle. State is the contributor-owned value attached during the
+// project check; the host neither interprets nor synchronizes its contents.
+// Findings is returned as a defensive copy by host result readers.
+//
+// Evaluated results retain a cycle-scoped failure channel through file-rule
+// dispatch. Call Report or Fail immediately before a guarded operation, then
+// call Context.ProjectResult again when the updated status is needed. Absent,
+// off, and not-evaluated results have no state or live failure channel.
 type ProjectRuleResult struct {
   Status   ProjectRuleStatus
+  State    any
   Findings []ProjectFinding
+
+  reporter ProjectReporter
 }
 
-// ProjectResultReader supplies finalized project state to later file-rule
-// contexts. Hosts return ProjectRuleAbsent for names with no registered
-// project rule.
+// NewProjectRuleResult constructs one host-owned project-result snapshot.
+// Contributor code normally receives this value from Context.ProjectResult
+// and does not construct it.
+func NewProjectRuleResult(
+  status ProjectRuleStatus,
+  state any,
+  findings []ProjectFinding,
+  reporter ProjectReporter,
+) ProjectRuleResult {
+  return ProjectRuleResult{
+    Status:   status,
+    State:    state,
+    Findings: append([]ProjectFinding(nil), findings...),
+    reporter: reporter,
+  }
+}
+
+// Fail marks this evaluated project result failed without adding a finding.
+// It is a no-op after file dispatch or for a result that was not evaluated.
+func (r ProjectRuleResult) Fail() {
+  if r.reporter != nil {
+    r.reporter.Fail()
+  }
+}
+
+// Report records one project finding and marks this evaluated result failed.
+// Equal messages are deduplicated by the host. It is a no-op after file
+// dispatch or for a result that was not evaluated.
+func (r ProjectRuleResult) Report(message string) {
+  if r.reporter != nil {
+    r.reporter.Report(message)
+  }
+}
+
+// ProjectResultReader supplies live project state to later file-rule contexts.
+// Hosts return ProjectRuleAbsent for names with no registered project rule.
 type ProjectResultReader interface {
   ProjectResult(name string) ProjectRuleResult
 }
@@ -77,7 +120,12 @@ type ProjectContext struct {
   Severity Severity
   Options  json.RawMessage
 
-  reporter ProjectReporter
+  reporter    ProjectReporter
+  stateSetter projectStateSetter
+}
+
+type projectStateSetter interface {
+  SetState(state any)
 }
 
 // NewProjectContext constructs the context a host passes to ProjectRule.Check.
@@ -91,13 +139,15 @@ func NewProjectContext(
   reporter ProjectReporter,
 ) *ProjectContext {
   copiedSources := append([]*shimast.SourceFile(nil), sources...)
+  stateSetter, _ := reporter.(projectStateSetter)
   return &ProjectContext{
-    Identity: identity,
-    Sources:  copiedSources,
-    Checker:  checker,
-    Severity: severity,
-    Options:  append(json.RawMessage(nil), options...),
-    reporter: reporter,
+    Identity:    identity,
+    Sources:     copiedSources,
+    Checker:     checker,
+    Severity:    severity,
+    Options:     append(json.RawMessage(nil), options...),
+    reporter:    reporter,
+    stateSetter: stateSetter,
   }
 }
 
@@ -110,6 +160,17 @@ func (c *ProjectContext) DecodeOptions(out interface{}) error {
   return json.Unmarshal(c.Options, out)
 }
 
+// SetState attaches one contributor-owned value to this rule's evaluated
+// result. The exact value is returned to file rules in the same Program cycle;
+// contributors own any synchronization needed inside it. The host does not
+// serialize the value or retain it for a later watch or LSP rebuild.
+func (c *ProjectContext) SetState(state any) {
+  if c == nil || c.stateSetter == nil || c.Severity == SeverityOff {
+    return
+  }
+  c.stateSetter.SetState(state)
+}
+
 // Fail marks the current project rule failed without adding a diagnostic.
 func (c *ProjectContext) Fail() {
   if c == nil || c.reporter == nil || c.Severity == SeverityOff {

package/rule/rule.go

@@ -240,8 +240,8 @@ func NewContext(
   return NewContextWithProjectResults(file, checker, severity, options, reporter, nil)
 }
 
-// NewContextWithProjectResults constructs a file-rule Context with the
-// finalized project state for the same loaded Program cycle.
+// NewContextWithProjectResults constructs a file-rule Context with the live
+// project results for the same loaded Program cycle.
 func NewContextWithProjectResults(
   file *shimast.SourceFile,
   checker *shimchecker.Checker,
@@ -260,7 +260,7 @@ func NewContextWithProjectResults(
   }
 }
 
-// ProjectResult returns the finalized state for a named project rule in this
+// ProjectResult returns a current snapshot for a named project rule in this
 // file's Program cycle. Missing registrations return ProjectRuleAbsent.
 func (c *Context) ProjectResult(name string) ProjectRuleResult {
   if c == nil || c.results == nil {