@ttsc/lint 0.18.4 → 0.19.1

package/linthost/string_length.go

@@ -0,0 +1,222 @@
+// Grapheme-cluster string length, mirroring typescript-eslint's
+// `getStringLength` utility. Directive descriptions are measured as Unicode
+// extended grapheme clusters, the same units exposed by `Intl.Segmenter` with
+// `granularity: "grapheme"`, rather than bytes, UTF-16 code units, or runes.
+//
+// The implementation follows the ordered extended-cluster rules in UAX #29.
+// Its generated property tables are pinned to Unicode 16.0.0, the Unicode
+// version used by the Node 24 runtime in this repository's CI. Regenerate the
+// tables and official conformance corpus together when that runtime advances.
+package linthost
+
+//go:generate go run ../tools/graphemegen -root ..
+
+// stringLength returns the number of Unicode extended grapheme clusters in s.
+func stringLength(s string) int {
+  return graphemeCount(s)
+}
+
+// graphemeCount applies UAX #29's ordered boundary rules in one pass. The
+// segmenter carries only the left contexts required by GB9c, GB11, and
+// GB12/GB13, keeping long combining and regional-indicator runs linear.
+func graphemeCount(s string) int {
+  count := 0
+  var segmenter graphemeSegmenter
+  for _, current := range s {
+    properties := graphemeProperties(current)
+    if segmenter.hasBoundaryBefore(properties) {
+      count++
+    }
+    segmenter.consume(properties)
+  }
+  return count
+}
+
+type graphemeRuneProperties struct {
+  breakClass           graphemeBreakClass
+  indicConjunctClass   indicConjunctBreakClass
+  extendedPictographic bool
+}
+
+type indicConjunctState uint8
+
+const (
+  indicConjunctStateNone indicConjunctState = iota
+  indicConjunctStateConsonant
+  indicConjunctStateLinked
+)
+
+type emojiSequenceState uint8
+
+const (
+  emojiSequenceStateNone emojiSequenceState = iota
+  emojiSequenceStatePictographic
+  emojiSequenceStateZWJ
+)
+
+type graphemeSegmenter struct {
+  hasPrevious        bool
+  previous           graphemeRuneProperties
+  regionalIndicators int
+  indicConjunct      indicConjunctState
+  emojiSequence      emojiSequenceState
+}
+
+// hasBoundaryBefore applies GB3 through GB999 in normative order. Start of
+// text is always a boundary (GB1); end of text needs no explicit handling when
+// only the number of clusters is required.
+func (s *graphemeSegmenter) hasBoundaryBefore(current graphemeRuneProperties) bool {
+  if !s.hasPrevious {
+    return true
+  }
+  previous := s.previous.breakClass
+  next := current.breakClass
+
+  // GB3: keep CRLF together.
+  if previous == graphemeBreakCR && next == graphemeBreakLF {
+    return false
+  }
+  // GB4/GB5: otherwise break before and after controls.
+  if isGraphemeControlClass(previous) || isGraphemeControlClass(next) {
+    return true
+  }
+  // GB6-GB8: keep Hangul and other data-defined conjoining sequences.
+  if isConjoiningGraphemeJoin(previous, next) {
+    return false
+  }
+  // GB9/GB9a: extending characters, ZWJ, and spacing marks continue the
+  // current cluster.
+  if next == graphemeBreakExtend || next == graphemeBreakZWJ || next == graphemeBreakSpacingMark {
+    return false
+  }
+  // GB9b: Prepend joins the following non-control character.
+  if previous == graphemeBreakPrepend {
+    return false
+  }
+  // GB9c: an Indic consonant-linker sequence joins its next consonant.
+  if current.indicConjunctClass == indicConjunctBreakConsonant && s.indicConjunct == indicConjunctStateLinked {
+    return false
+  }
+  // GB11: Extended_Pictographic Extend* ZWJ joins the next pictograph.
+  if current.extendedPictographic && s.emojiSequence == emojiSequenceStateZWJ {
+    return false
+  }
+  // GB12/GB13: regional indicators join in pairs. The state is the
+  // uninterrupted RI count immediately before this boundary.
+  if next == graphemeBreakRegionalIndicator && s.regionalIndicators%2 == 1 {
+    return false
+  }
+  // GB999: all remaining positions are boundaries.
+  return true
+}
+
+func (s *graphemeSegmenter) consume(current graphemeRuneProperties) {
+  if current.breakClass == graphemeBreakRegionalIndicator {
+    s.regionalIndicators++
+  } else {
+    s.regionalIndicators = 0
+  }
+
+  switch current.indicConjunctClass {
+  case indicConjunctBreakConsonant:
+    s.indicConjunct = indicConjunctStateConsonant
+  case indicConjunctBreakExtend:
+    // Extend preserves a preceding consonant/linker context.
+  case indicConjunctBreakLinker:
+    if s.indicConjunct != indicConjunctStateNone {
+      s.indicConjunct = indicConjunctStateLinked
+    }
+  default:
+    s.indicConjunct = indicConjunctStateNone
+  }
+
+  switch {
+  case current.extendedPictographic:
+    s.emojiSequence = emojiSequenceStatePictographic
+  case current.breakClass == graphemeBreakExtend && s.emojiSequence == emojiSequenceStatePictographic:
+    // Extend preserves the pictograph context immediately before a ZWJ.
+  case current.breakClass == graphemeBreakZWJ && s.emojiSequence == emojiSequenceStatePictographic:
+    s.emojiSequence = emojiSequenceStateZWJ
+  default:
+    s.emojiSequence = emojiSequenceStateNone
+  }
+
+  s.previous = current
+  s.hasPrevious = true
+}
+
+func graphemeProperties(r rune) graphemeRuneProperties {
+  return graphemeRuneProperties{
+    breakClass:           lookupGraphemeBreakClass(r),
+    indicConjunctClass:   lookupIndicConjunctBreakClass(r),
+    extendedPictographic: isExtendedPictographic(r),
+  }
+}
+
+func lookupGraphemeBreakClass(r rune) graphemeBreakClass {
+  lo, hi := 0, len(graphemeBreakRanges)
+  for lo < hi {
+    middle := int(uint(lo+hi) >> 1)
+    candidate := graphemeBreakRanges[middle]
+    switch {
+    case r < candidate.lo:
+      hi = middle
+    case r > candidate.hi:
+      lo = middle + 1
+    default:
+      return candidate.class
+    }
+  }
+  return graphemeBreakOther
+}
+
+func lookupIndicConjunctBreakClass(r rune) indicConjunctBreakClass {
+  lo, hi := 0, len(indicConjunctBreakRanges)
+  for lo < hi {
+    middle := int(uint(lo+hi) >> 1)
+    candidate := indicConjunctBreakRanges[middle]
+    switch {
+    case r < candidate.lo:
+      hi = middle
+    case r > candidate.hi:
+      lo = middle + 1
+    default:
+      return candidate.class
+    }
+  }
+  return indicConjunctBreakNone
+}
+
+func isExtendedPictographic(r rune) bool {
+  lo, hi := 0, len(extendedPictographicRanges)
+  for lo < hi {
+    middle := int(uint(lo+hi) >> 1)
+    candidate := extendedPictographicRanges[middle]
+    switch {
+    case r < candidate.lo:
+      hi = middle
+    case r > candidate.hi:
+      lo = middle + 1
+    default:
+      return true
+    }
+  }
+  return false
+}
+
+func isGraphemeControlClass(class graphemeBreakClass) bool {
+  return class == graphemeBreakControl || class == graphemeBreakCR || class == graphemeBreakLF
+}
+
+func isConjoiningGraphemeJoin(previous, next graphemeBreakClass) bool {
+  switch previous {
+  case graphemeBreakL:
+    return next == graphemeBreakL || next == graphemeBreakV || next == graphemeBreakLV || next == graphemeBreakLVT
+  case graphemeBreakLV, graphemeBreakV:
+    return next == graphemeBreakV || next == graphemeBreakT
+  case graphemeBreakLVT, graphemeBreakT:
+    return next == graphemeBreakT
+  default:
+    return false
+  }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ttsc/lint",
-  "version": "0.18.4",
-  "description": "Reference ttsc plugin: ESLint-style lint rules hosted in the same Program/Checker as the type-check pass.",
+  "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",
   "exports": {
@@ -26,6 +26,7 @@
   "files": [
     "README.md",
     "go.mod",
+    "internal",
     "lib",
     "linthost",
     "plugin",
@@ -36,7 +37,7 @@
     "@types/node": "^25.3.0",
     "rimraf": "^6.1.2",
     "typescript": "^7.0.2",
-    "ttsc": "0.18.4"
+    "ttsc": "0.19.1"
   },
   "repository": {
     "type": "git",

package/rule/project.go

@@ -0,0 +1,206 @@
+package rule
+
+import (
+  "encoding/json"
+
+  shimast "github.com/microsoft/typescript-go/shim/ast"
+  shimchecker "github.com/microsoft/typescript-go/shim/checker"
+)
+
+// ProjectIdentity names one loaded TypeScript Program without conflating the
+// caller's path spelling with the filesystem identity used by the compiler.
+// Empty explicit fields mean the caller did not provide that channel.
+type ProjectIdentity struct {
+  LifecycleID         string `json:"lifecycleId"`
+  InvocationCwd       string `json:"invocationCwd"`
+  LogicalConfigPath   string `json:"logicalConfigPath"`
+  LogicalProjectRoot  string `json:"logicalProjectRoot"`
+  PhysicalConfigPath  string `json:"physicalConfigPath"`
+  PhysicalProjectRoot string `json:"physicalProjectRoot"`
+  ExplicitProjectRoot string `json:"explicitProjectRoot,omitempty"`
+  PluginConfigOrigin  string `json:"pluginConfigOrigin,omitempty"`
+}
+
+// ProjectRuleStatus describes whether a named project rule exists, was
+// configured, and completed during the current Program cycle.
+type ProjectRuleStatus string
+
+const (
+  ProjectRuleAbsent       ProjectRuleStatus = "absent"
+  ProjectRuleOff          ProjectRuleStatus = "off"
+  ProjectRuleNotEvaluated ProjectRuleStatus = "not_evaluated"
+  ProjectRulePassed       ProjectRuleStatus = "passed"
+  ProjectRuleFailed       ProjectRuleStatus = "failed"
+)
+
+// ProjectFinding is a non-file finding retained in a project rule's cycle
+// result. Project findings never contain edits or source ranges.
+type ProjectFinding struct {
+  Message string
+}
+
+// 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
+}
+
+// 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
+}
+
+// ProjectRule is a contributor check that runs once for a loaded Program
+// before any node rule dispatch. It has no AST visit list or synthetic file.
+type ProjectRule interface {
+  Name() string
+  Check(ctx *ProjectContext)
+}
+
+// ProjectReporter is the cycle-scoped failure channel available to project
+// helpers. Report records a deterministic project finding and also marks the
+// current rule failed; Fail marks failure without adding a finding.
+type ProjectReporter interface {
+  Fail()
+  Report(message string)
+}
+
+// ProjectContext contains the immutable inputs for one project-rule check.
+// Sources is a defensive copy of the Program's tsconfig-selected user sources.
+type ProjectContext struct {
+  Identity ProjectIdentity
+  Sources  []*shimast.SourceFile
+  Checker  *shimchecker.Checker
+  Severity Severity
+  Options  json.RawMessage
+
+  reporter    ProjectReporter
+  stateSetter projectStateSetter
+}
+
+type projectStateSetter interface {
+  SetState(state any)
+}
+
+// NewProjectContext constructs the context a host passes to ProjectRule.Check.
+// Contributor code normally receives this value and does not construct it.
+func NewProjectContext(
+  identity ProjectIdentity,
+  sources []*shimast.SourceFile,
+  checker *shimchecker.Checker,
+  severity Severity,
+  options json.RawMessage,
+  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,
+    stateSetter: stateSetter,
+  }
+}
+
+// DecodeOptions unmarshals the configured project-rule options into out. A
+// missing options tuple leaves out unchanged and returns nil.
+func (c *ProjectContext) DecodeOptions(out interface{}) error {
+  if c == nil || len(c.Options) == 0 {
+    return nil
+  }
+  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 {
+    return
+  }
+  c.reporter.Fail()
+}
+
+// Report records one non-file project finding and marks the rule failed.
+func (c *ProjectContext) Report(message string) {
+  if c == nil || c.reporter == nil || c.Severity == SeverityOff {
+    return
+  }
+  c.reporter.Report(message)
+}
+
+var projectRegistry []ProjectRule
+
+// RegisterProject adds a contributor project rule to the global registry.
+// Hosts validate duplicate names after all contributor init functions finish.
+func RegisterProject(r ProjectRule) {
+  if r == nil {
+    panic("rule: RegisterProject called with nil rule")
+  }
+  projectRegistry = append(projectRegistry, r)
+}
+
+// RegisteredProjects returns a defensive copy of all registered project rules.
+func RegisteredProjects() []ProjectRule {
+  out := make([]ProjectRule, len(projectRegistry))
+  copy(out, projectRegistry)
+  return out
+}

package/rule/rule.go

@@ -112,6 +112,39 @@ type DeclarationFileRule interface {
   VisitsDeclarationFiles() bool
 }
 
+// TypeAwareRule is an optional marker contributors implement to declare
+// whether their rule reads `Context.Checker`. The host cannot infer a
+// third-party rule's shape, so a contributor that does not implement this
+// marker keeps the conservative default: it is treated as type-aware and
+// receives a live checker.
+//
+// Being treated as type-aware is not free. The host creates a standalone
+// checker spanning every source file, and the engine walks files serially so
+// that checker is never accessed concurrently. A purely syntactic rule that
+// never touches `Context.Checker` pays both costs for nothing.
+//
+// A contributor whose rule is AST-only can implement this with
+// `NeedsTypeChecker() bool { return false }` to opt out of the checker path,
+// preserving the engine's parallel file walk. Returning `true` is equivalent
+// to not implementing the interface at all. A rule that returns `false` must
+// not read `Context.Checker`: the host is free to leave it nil.
+type TypeAwareRule interface {
+  Rule
+  NeedsTypeChecker() bool
+}
+
+// OptionsRule is an optional marker contributors implement to declare whether
+// their rule accepts an options slot in its `[severity, options]` setting.
+// Contributor rules default to accepting options for backward compatibility
+// with the original public Context.Options contract. Return false for a
+// genuinely optionless rule so the host can reject accidental payloads before
+// linting. The domain-specific method name prevents an unrelated generic
+// AcceptsOptions method on an existing contributor from opting in by accident.
+// ProjectRule implementations may use the same marker.
+type OptionsRule interface {
+  AcceptsTtscLintOptions() 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.
@@ -191,6 +224,7 @@ type Context struct {
   Options json.RawMessage
 
   reporter Reporter
+  results  ProjectResultReader
 }
 
 // NewContext constructs a Context for the engine to pass into a
@@ -202,14 +236,37 @@ func NewContext(
   severity Severity,
   options json.RawMessage,
   reporter Reporter,
+) *Context {
+  return NewContextWithProjectResults(file, checker, severity, options, reporter, nil)
+}
+
+// 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,
+  severity Severity,
+  options json.RawMessage,
+  reporter Reporter,
+  results ProjectResultReader,
 ) *Context {
   return &Context{
     File:     file,
     Checker:  checker,
     Severity: severity,
-    Options:  options,
+    Options:  append(json.RawMessage(nil), options...),
     reporter: reporter,
+    results:  results,
+  }
+}
+
+// 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 {
+    return ProjectRuleResult{Status: ProjectRuleAbsent}
   }
+  return c.results.ProjectResult(name)
 }
 
 // DecodeOptions unmarshals the rule's options blob into `out`. Returns

package/src/index.ts

@@ -22,6 +22,7 @@ type TtscPluginDescriptor = {
   capabilities?: {
     diagnosticsTiming?: boolean;
     lsp?: boolean;
+    projectContextArgs?: boolean;
     threadingArgs?: boolean;
   };
   contributors?: TtscPluginContributor[];
@@ -43,6 +44,12 @@ type TtscPluginFactoryContext<TConfig> = {
   /** This descriptor's own path — the ESM-safe replacement for `__filename`. */
   filename: string;
   plugin: TConfig;
+  /**
+   * Caller-declared anchor for plugin config-file discovery, present when the
+   * embedder compiles through a generated tsconfig outside the project (see
+   * `ITtscPluginFactoryContext.pluginConfigDir`).
+   */
+  pluginConfigDir?: string;
   projectRoot: string;
   tsconfig: string;
 };
@@ -104,7 +111,9 @@ const FRAMEWORK_KEYS = new Set<string>([
  * (`lint.config.{ts,cts,mts,js,cjs,mjs,json}` or `ttsc-lint.config.*`). The
  * tsconfig plugin entry carries no rule or plugin surface — it optionally names
  * the config file via `configFile`, otherwise the file is discovered by walking
- * upward from the tsconfig directory.
+ * upward from the tsconfig directory (or from the caller-declared
+ * `pluginConfigDir` when the resolved tsconfig is a generated wrapper in a temp
+ * directory).
  *
  * The factory locates the config file, evaluates it (via ttsx for TS / ESM
  * sources, `require` for CommonJS, `JSON.parse` for JSON), reads every
@@ -121,7 +130,12 @@ export default function createTtscPlugin(
   // declared, so consumers (and the existing key-shape regression
   // tests) see the same surface as before this feature shipped.
   const descriptor: TtscPluginDescriptor = {
-    capabilities: { diagnosticsTiming: true, lsp: true, threadingArgs: true },
+    capabilities: {
+      diagnosticsTiming: true,
+      lsp: true,
+      projectContextArgs: true,
+      threadingArgs: true,
+    },
     name: "@ttsc/lint",
     reportsTypeScriptDiagnostics: true,
     // `context.dirname` is this descriptor's own directory in every load mode —
@@ -187,9 +201,12 @@ type ConfigPluginEntry = { namespace: string; source: string };
  * Resolves the contributor lint plugins declared in the project's lint config
  * file.
  *
- * - When the tsconfig plugin entry sets `configFile`, that exact file is loaded.
+ * - When the tsconfig plugin entry sets `configFile`, that exact file is loaded
+ *   (relative paths resolve against the tsconfig directory, or against the
+ *   caller-declared `pluginConfigDir` when present).
  * - Otherwise a `lint.config.*` / `ttsc-lint.config.*` file is discovered by
- *   walking upward from the tsconfig directory.
+ *   walking upward from the tsconfig directory (or from `pluginConfigDir` when
+ *   present).
  *
  * Returns an empty array when no config file is set or discovered — the Go
  * sidecar surfaces the missing-config error; the factory only needs to forward
@@ -201,7 +218,7 @@ function resolveConfigFileContributors(
   const configFile = readConfigFileOption(context);
   const configPath =
     configFile !== undefined
-      ? path.resolve(tsconfigBaseDir(context), configFile)
+      ? path.resolve(pluginConfigBaseDir(context), configFile)
       : findLintConfigFile(context);
   if (!configPath || !fs.existsSync(configPath)) return [];
 
@@ -260,18 +277,15 @@ function readConfigFileOption(
 function findLintConfigFile(
   context: TtscPluginFactoryContext<ITtscLintPluginConfig>,
 ): string | undefined {
-  // Mirror the Go-side discovery origins: walk upward from the tsconfig
-  // directory first, then fall back to the working directory. The fallback
-  // covers callers that point at an out-of-tree tsconfig (e.g. a
-  // TtscCompiler invocation whose wrapper tsconfig lives in the system temp
-  // dir while cwd/projectRoot is the real project) — without it the walk
-  // dead-ends in the temp dir's ancestry and the project's config (and its
-  // contributor plugins) are silently missed.
-  const tsconfigDir = tsconfigBaseDir(context);
-  const cwd = path.resolve(context.cwd ?? context.projectRoot);
-  for (const origin of tsconfigDir === cwd
-    ? [tsconfigDir]
-    : [tsconfigDir, cwd]) {
+  // Mirror the Go side (driver.PluginConfigBaseDir): the caller-declared
+  // pluginConfigDir is the single walk origin when present — it names the
+  // real project when the resolved tsconfig is a generated wrapper in a temp
+  // dir (@ttsc/unplugin's alias overlay), and it keeps the wrapper's temp
+  // ancestry out of the walk so a stray config planted there is never
+  // honored. Otherwise walk upward from the tsconfig directory first, then
+  // fall back to the working directory: that covers callers that point at an
+  // out-of-tree tsconfig without declaring an anchor.
+  for (const origin of discoveryConfigBaseDirs(context)) {
     const discovered = findLintConfigFileFrom(origin);
     if (discovered !== undefined) {
       return discovered;
@@ -280,6 +294,17 @@ function findLintConfigFile(
   return undefined;
 }
 
+function discoveryConfigBaseDirs(
+  context: TtscPluginFactoryContext<ITtscLintPluginConfig>,
+): string[] {
+  if (context.pluginConfigDir) {
+    return [path.resolve(context.cwd ?? ".", context.pluginConfigDir)];
+  }
+  const tsconfigDir = tsconfigBaseDir(context);
+  const cwd = path.resolve(context.cwd ?? context.projectRoot);
+  return tsconfigDir === cwd ? [tsconfigDir] : [tsconfigDir, cwd];
+}
+
 function findLintConfigFileFrom(origin: string): string | undefined {
   // Mirror the Go-side discovery loop: walk from `origin` upward, returning
   // the first directory that has exactly one of the candidate filenames.
@@ -317,6 +342,22 @@ function findLintConfigFileFrom(origin: string): string | undefined {
   }
 }
 
+/**
+ * Base directory for resolving a relative `configFile` from the tsconfig plugin
+ * entry. Mirrors the Go side (driver.PluginConfigBaseDir): the caller-declared
+ * pluginConfigDir wins when present — the resolved tsconfig is then a generated
+ * wrapper in a temp directory that no longer identifies the project — otherwise
+ * the tsconfig directory, falling back to the working directory.
+ */
+function pluginConfigBaseDir(
+  context: TtscPluginFactoryContext<ITtscLintPluginConfig>,
+): string {
+  if (context.pluginConfigDir) {
+    return path.resolve(context.cwd ?? ".", context.pluginConfigDir);
+  }
+  return tsconfigBaseDir(context);
+}
+
 function tsconfigBaseDir(
   context: TtscPluginFactoryContext<ITtscLintPluginConfig>,
 ): string {

package/src/structures/ITtscLintConfig.ts

@@ -38,6 +38,9 @@ export interface ITtscLintConfig {
    * Built-in rules are concrete interface properties for autocomplete and typo
    * checking. Namespaced families and contributor rules use the familiar slash
    * form such as `react/jsx-key` or `demo/no-demo`.
+   *
+   * Project-scoped contributor rules use this same map, but their configuration
+   * must come from entries without a `files` selector.
    */
   rules?: ITtscLintRules;