@ttsc/lint 0.12.3 → 0.13.0

package/src/index.ts

@@ -1,4 +1,5 @@
 import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
 import fs from "node:fs";
 import { createRequire } from "node:module";
 import os from "node:os";
@@ -9,18 +10,26 @@ import type { ITtscLintPlugin, ITtscLintPluginConfig } from "./structures";
 export * from "./defaultFormat";
 export * from "./structures/index";
 
+/** A resolved contributor: Go sub-package name + absolute source directory. */
 type TtscPluginContributor = {
   name: string;
   source: string;
 };
 
+/** Descriptor shape returned to ttsc's plugin builder by the factory. */
 type TtscPluginDescriptor = {
+  capabilities?: { threadingArgs?: boolean };
+  contributors?: TtscPluginContributor[];
   name: string;
+  reportsTypeScriptDiagnostics?: boolean;
   source: string;
   stage?: "check" | "transform";
-  contributors?: TtscPluginContributor[];
 };
 
+/**
+ * Context object injected by ttsc into every plugin factory call. The generic
+ * `TConfig` is the tsconfig plugin entry shape.
+ */
 type TtscPluginFactoryContext<TConfig> = {
   binary: string;
   cwd: string;
@@ -63,48 +72,50 @@ const LINT_CONFIG_FILENAMES = [
   "ttsc-lint.config.cjs",
   "ttsc-lint.config.js",
   "ttsc-lint.config.json",
-  "eslint.config.ts",
-  "eslint.config.mts",
-  "eslint.config.cts",
-  "eslint.config.mjs",
-  "eslint.config.cjs",
-  "eslint.config.js",
 ];
 
+/**
+ * Tsconfig plugin-entry keys owned by the ttsc host framework. They are
+ * accepted alongside the single lint-specific `configFile` key; every other key
+ * is rejected so a stale inline option (`rules`, `format`, `extends`, legacy
+ * `config`, `plugins`) surfaces as a clear migration error instead of being
+ * silently ignored. Mirrors `@ttsc/banner` and `@ttsc/strip`.
+ */
+const FRAMEWORK_KEYS = new Set<string>([
+  "enabled",
+  "name",
+  "stage",
+  "transform",
+]);
+
 /**
  * Plugin descriptor factory consumed by ttsc package discovery.
  *
- * Two discovery surfaces feed the descriptor's `contributors` field:
- *
- * 1. The tsconfig plugin entry's `plugins` map — namespace → npm specifier. Inline
- *    for projects that prefer to keep everything in `tsconfig.json`.
- * 2. The companion `lint.config.{ts,cts,mts,js,cjs,mjs,json}` (or
- *    `eslint.config.*`) file — an object with an in-memory `plugins: {
- *    ns: pluginObject }` map. The factory evaluates the config (via ttsx for TS
- *    / ESM sources, `require` for CommonJS, `JSON.parse` for JSON) and reads
- *    the `plugins` field.
+ * Contributor lint plugins come from one place: the project's lint config file
+ * (`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.
  *
- * Contributions from both sources are merged with the tsconfig entry winning on
- * namespace collisions, so a project can opt into a hand-curated subset of an
- * external `lint.config.ts` by overriding specific namespaces in
- * `tsconfig.json`.
+ * The factory locates the config file, evaluates it (via ttsx for TS / ESM
+ * sources, `require` for CommonJS, `JSON.parse` for JSON), reads its `plugins`
+ * map, and forwards each contributor's Go source directory to ttsc's plugin
+ * builder via the descriptor's `contributors` field.
  *
  * @internal
  */
 export default function createTtscPlugin(
   context: TtscPluginFactoryContext<ITtscLintPluginConfig>,
 ): TtscPluginDescriptor {
-  const inline = resolveInlineContributors(context);
-  const fromConfig = resolveConfigFileContributors(
-    context,
-    inline.map((c) => c.name),
-  );
-  const contributors = [...inline, ...fromConfig];
+  rejectUnsupportedEntryKeys(context.plugin);
+  const contributors = resolveConfigFileContributors(context);
   // Build the descriptor without a `contributors` key when none were
   // declared, so consumers (and the existing key-shape regression
   // tests) see the same surface as before this feature shipped.
   const descriptor: TtscPluginDescriptor = {
+    capabilities: { threadingArgs: true },
     name: "@ttsc/lint",
+    reportsTypeScriptDiagnostics: true,
     source: path.resolve(__dirname, "..", "plugin"),
     stage: "check",
   };
@@ -114,60 +125,6 @@ export default function createTtscPlugin(
   return descriptor;
 }
 
-// ────────────────────────────────────────────────────────────────────────────
-// tsconfig-inline `plugins` map (the original MVP path)
-// ────────────────────────────────────────────────────────────────────────────
-
-function resolveInlineContributors(
-  context: TtscPluginFactoryContext<ITtscLintPluginConfig>,
-): TtscPluginContributor[] {
-  const declared = (context.plugin as { plugins?: unknown }).plugins;
-  if (declared === undefined) return [];
-  if (
-    typeof declared !== "object" ||
-    declared === null ||
-    Array.isArray(declared)
-  ) {
-    throw new Error(
-      `@ttsc/lint: "plugins" in tsconfig plugin entry must be an object map of namespace → package specifier`,
-    );
-  }
-  const out: TtscPluginContributor[] = [];
-  // Track the post-`goSubpackageName` form so `a-b` and `a_b` are
-  // caught as colliding aliases before they reach the downstream
-  // contributor validator's opaque `duplicate name "a_b"` error.
-  // (`Object.entries` cannot itself surface duplicate string keys, so
-  // a verbatim-namespace guard is unreachable.)
-  const seenGoNames = new Map<string, string>();
-  for (const [namespace, specifier] of Object.entries(declared)) {
-    if (!NAMESPACE_PATTERN.test(namespace)) {
-      throw new Error(
-        `@ttsc/lint: contributor namespace ${JSON.stringify(namespace)} must match /^[a-z][a-z0-9_-]*$/`,
-      );
-    }
-    if (typeof specifier !== "string" || specifier.length === 0) {
-      throw new Error(
-        `@ttsc/lint: contributor ${JSON.stringify(namespace)} must point at a non-empty package specifier or path`,
-      );
-    }
-    const goName = goSubpackageName(namespace);
-    const earlier = seenGoNames.get(goName);
-    if (earlier !== undefined) {
-      throw new Error(
-        `@ttsc/lint: contributor namespaces ${JSON.stringify(earlier)} and ${JSON.stringify(namespace)} both map to Go sub-package ${JSON.stringify(goName)}; pick one form (hyphens collapse to underscores for the Go identifier)`,
-      );
-    }
-    seenGoNames.set(goName, namespace);
-    const plugin = loadContributorPluginViaRequire(
-      specifier,
-      context,
-      namespace,
-    );
-    out.push({ name: goName, source: plugin.source });
-  }
-  return out;
-}
-
 function loadContributorPluginViaRequire(
   specifier: string,
   context: TtscPluginFactoryContext<ITtscLintPluginConfig>,
@@ -212,42 +169,41 @@ function loadContributorPluginViaRequire(
 // lint.config.* discovery + evaluation
 // ────────────────────────────────────────────────────────────────────────────
 
-/** Plugin entries observed in the flat-config file, normalized per file. */
+/** Plugin entries observed in a lint config file, normalized per file. */
 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.
+ * - Otherwise a `lint.config.*` / `ttsc-lint.config.*` file is discovered by
+ *   walking upward from the tsconfig directory.
+ *
+ * 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
+ * contributors when a config file is present.
+ */
 function resolveConfigFileContributors(
   context: TtscPluginFactoryContext<ITtscLintPluginConfig>,
-  inlineNames: readonly string[],
 ): TtscPluginContributor[] {
-  // Read the new `rules` / `extends` fields with a one-time fallback to
-  // the legacy `config` field. The legacy fallback warns once per
-  // ttsc invocation so existing tsconfigs keep working through the
-  // deprecation window without crashing CI.
-  const { hasInlineRules, extendsPath } = readSeverityConfig(context);
-  if (hasInlineRules) {
-    // Inline rules → no lint.config.* file involved. Skip discovery so
-    // we don't pull in plugins from an unrelated file.
-    return [];
-  }
-
+  const configFile = readConfigFileOption(context);
   const configPath =
-    extendsPath !== undefined
-      ? path.resolve(tsconfigBaseDir(context), extendsPath)
+    configFile !== undefined
+      ? path.resolve(tsconfigBaseDir(context), configFile)
       : findLintConfigFile(context);
   if (!configPath || !fs.existsSync(configPath)) return [];
 
   const entries = readConfigPluginEntries(configPath, context);
-  // Dedup against the Go-subpackage form (post hyphen→underscore
-  // transform). The inline arm has already applied `goSubpackageName`
-  // when it produced `inlineNames`, so comparing on the original
-  // hyphenated namespace would always miss for hyphenated namespaces
-  // and emit a colliding contributor that `validatePluginContributors`
-  // later rejects as a duplicate name.
-  const occupied = new Set(inlineNames);
+  // Dedup on the Go-subpackage form (post hyphen→underscore transform)
+  // so two namespaces that collapse to the same Go identifier surface
+  // here instead of as the contributor validator's opaque
+  // `duplicate name "a_b"` error.
+  const occupied = new Set<string>();
   const out: TtscPluginContributor[] = [];
   for (const entry of entries) {
     const goName = goSubpackageName(entry.namespace);
-    if (occupied.has(goName)) continue; // tsconfig inline wins
+    if (occupied.has(goName)) continue;
     occupied.add(goName);
     out.push({ name: goName, source: entry.source });
   }
@@ -255,76 +211,39 @@ function resolveConfigFileContributors(
 }
 
 /**
- * Resolves the inline-rule vs file-path split between the new `rules` /
- * `extends` fields and the legacy `config` field.
- *
- * - `rules` (object) routes the discovery loop away from any `lint.config.*` file
- *   — the inline map is authoritative.
- * - `extends` (string) routes the file walk to a fixed path.
- * - `config` (legacy) silently maps onto the equivalent new field. The
- *   user-facing deprecation notice is emitted by the Go sidecar so that a
- *   single ttsc invocation prints exactly one warning regardless of how many
- *   entry points (JS factory, Go binary) parse the same key.
- * - Mixing legacy and new keys, or mixing `rules` with `extends`, is rejected
- *   outright so users don't end up with silent precedence surprises.
+ * Rejects any tsconfig plugin-entry key that is neither a host framework key
+ * nor the single lint-specific `configFile` key. Rule, format, and plugin
+ * settings live only in the lint config file, so a leftover inline key is
+ * surfaced as an explicit migration error rather than silently ignored.
  */
-function readSeverityConfig(
-  context: TtscPluginFactoryContext<ITtscLintPluginConfig>,
-): { hasInlineRules: boolean; extendsPath: string | undefined } {
-  const entry = context.plugin as Record<string, unknown>;
-  const rules = entry.rules;
-  const extendsRaw = entry.extends;
-  const legacy = entry.config;
-  const hasNewRules = rules !== undefined;
-  const hasExtends = extendsRaw !== undefined;
-  const hasLegacy = legacy !== undefined;
-
-  if (hasLegacy && (hasNewRules || hasExtends)) {
-    throw new Error(
-      `@ttsc/lint: tsconfig plugin entry mixes legacy "config" with the new "rules"/"extends" fields; remove "config" (deprecated)`,
-    );
-  }
-  if (hasNewRules && hasExtends) {
+function rejectUnsupportedEntryKeys(entry: ITtscLintPluginConfig): void {
+  for (const key of Object.keys(entry as Record<string, unknown>)) {
+    if (FRAMEWORK_KEYS.has(key) || key === "configFile") {
+      continue;
+    }
     throw new Error(
-      `@ttsc/lint: "rules" and "extends" cannot be combined on a single plugin entry; put base rules in the "extends" file and inline overrides in lint.config.ts itself`,
+      `@ttsc/lint: tsconfig plugin entry contains unsupported key ${JSON.stringify(key)}. ` +
+        `Rules, format, and plugin settings must live in a ` +
+        `lint.config.{ts,cts,mts,js,cjs,mjs,json} file. The only accepted key ` +
+        `in the tsconfig entry is "configFile" (optional path to the config file).`,
     );
   }
+}
 
-  if (hasNewRules) {
-    if (typeof rules !== "object" || rules === null || Array.isArray(rules)) {
-      const actual = Array.isArray(rules)
-        ? "array"
-        : rules === null
-          ? "null"
-          : typeof rules;
-      throw new Error(
-        `@ttsc/lint: "rules" must be a rule severity map, got ${actual}`,
-      );
-    }
-    return { hasInlineRules: true, extendsPath: undefined };
-  }
-  if (hasExtends) {
-    if (typeof extendsRaw !== "string" || extendsRaw.length === 0) {
-      throw new Error(`@ttsc/lint: "extends" must be a non-empty string path`);
-    }
-    return { hasInlineRules: false, extendsPath: extendsRaw };
-  }
-  if (hasLegacy) {
-    if (
-      typeof legacy === "object" &&
-      legacy !== null &&
-      !Array.isArray(legacy)
-    ) {
-      return { hasInlineRules: true, extendsPath: undefined };
-    }
-    if (typeof legacy === "string" && legacy.length > 0) {
-      return { hasInlineRules: false, extendsPath: legacy };
-    }
-    throw new Error(
-      `@ttsc/lint: legacy "config" must be a non-empty string path or a rule severity map, got ${typeof legacy}`,
-    );
+/**
+ * Reads the optional `configFile` key from the tsconfig plugin entry. It is the
+ * only lint-specific key the entry accepts; when present it overrides
+ * auto-discovery of the lint config file.
+ */
+function readConfigFileOption(
+  context: TtscPluginFactoryContext<ITtscLintPluginConfig>,
+): string | undefined {
+  const value = (context.plugin as { configFile?: unknown }).configFile;
+  if (value === undefined) return undefined;
+  if (typeof value !== "string" || value.length === 0) {
+    throw new Error(`@ttsc/lint: "configFile" must be a non-empty string path`);
   }
-  return { hasInlineRules: false, extendsPath: undefined };
+  return value;
 }
 
 function findLintConfigFile(
@@ -448,6 +367,12 @@ function readCjsConfigPlugins(configPath: string): ConfigPluginEntry[] {
     );
 }
 
+// TypeScript source written to a temp file and executed via ttsx. The
+// %CONFIG_IMPORT% placeholder is replaced with a JSON-quoted relative path
+// before the file hits disk. The script walks the exported config object,
+// collects every `plugins` map, and serialises each plugin's `source` field
+// as a JSON array for the parent process to parse — avoiding the need to
+// serialise arbitrary in-memory plugin objects across the process boundary.
 const TTSX_EXTRACTOR_SCRIPT = `import * as importedConfig from %CONFIG_IMPORT%;
 
 declare const process: {
@@ -530,7 +455,61 @@ function extractPluginSource(value: unknown): string | undefined {
 }
 `;
 
+/**
+ * Resolves the contributor plugin entries declared in a .ts/.mjs lint
+ * config, memoized through the shared on-disk config cache.
+ *
+ * Evaluating such a config spawns a full `ttsx` subprocess. A monorepo
+ * build runs one `ttsc` process per package, and each would otherwise
+ * re-spawn `ttsx` for the same shared config; the cache collapses that to
+ * a single evaluation. The cache is keyed by the config file's path and
+ * exact contents (see `configCacheKey`), so an edit re-evaluates cleanly.
+ */
 function readTtsxConfigPlugins(
+  configPath: string,
+  context: TtscPluginFactoryContext<ITtscLintPluginConfig>,
+): ConfigPluginEntry[] {
+  const cacheKey = configCacheKey("plugins", configPath);
+  if (cacheKey) {
+    const cached = readConfigPluginCache(cacheKey);
+    // Re-validate cached entries before trusting them: a contributor's
+    // resolved `source` directory may have moved since the entry was
+    // written. A stale entry falls through to a fresh evaluation rather
+    // than being forwarded to ttsc's plugin builder as a dead path.
+    if (cached && cached.every(isValidConfigPluginEntry)) return cached;
+  }
+  const entries = evaluateTtsxConfigPlugins(configPath, context);
+  if (cacheKey) writeConfigPluginCache(cacheKey, entries);
+  return entries;
+}
+
+/**
+ * Reports whether a cached plugin entry is still usable: a well-formed
+ * namespace and an absolute `source` that still points at a directory.
+ * Pure predicate — never throws — so a malformed cache entry simply
+ * triggers re-evaluation instead of aborting plugin discovery.
+ */
+function isValidConfigPluginEntry(entry: unknown): entry is ConfigPluginEntry {
+  if (
+    entry == null ||
+    typeof entry !== "object" ||
+    typeof (entry as ConfigPluginEntry).namespace !== "string" ||
+    typeof (entry as ConfigPluginEntry).source !== "string"
+  ) {
+    return false;
+  }
+  const { namespace, source } = entry as ConfigPluginEntry;
+  if (!NAMESPACE_PATTERN.test(namespace) || !path.isAbsolute(source)) {
+    return false;
+  }
+  try {
+    return fs.statSync(source).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+function evaluateTtsxConfigPlugins(
   configPath: string,
   _context: TtscPluginFactoryContext<ITtscLintPluginConfig>,
 ): ConfigPluginEntry[] {
@@ -580,7 +559,20 @@ function readTtsxConfigPlugins(
     );
 
     const ttsxBinary = process.env.TTSC_TTSX_BINARY ?? "ttsx";
-    const args = ["--project", tsconfigPath, "--cwd", tempDir, loaderPath];
+    // `--no-plugins` keeps this build hermetic: the loader only needs to
+    // type-check and run the user's lint config to extract its plugin
+    // entries. Loading the host project's transform/check plugins
+    // (`@nestia/core`, `typia`, …) would run their project checks
+    // against this deliberately lenient loader tsconfig and fail the
+    // build — e.g. `@nestia/core` rejects the loader's `strict: false`.
+    const args = [
+      "--project",
+      tsconfigPath,
+      "--cwd",
+      tempDir,
+      "--no-plugins",
+      loaderPath,
+    ];
     if (process.env.TTSC_TSGO_BINARY) {
       args.unshift("--binary", process.env.TTSC_TSGO_BINARY);
     }
@@ -658,6 +650,103 @@ function readTtsxConfigPlugins(
   }
 }
 
+// ────────────────────────────────────────────────────────────────────────────
+// Config cache (shared with the Go sidecar — packages/lint/linthost/config.go)
+// ────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Namespaces the on-disk config cache. Kept in lockstep with the Go
+ * sidecar's `configCacheVersion`; bump both when the cached shape changes.
+ */
+const CONFIG_CACHE_VERSION = "v1";
+
+/**
+ * Directory shared by this factory and the Go sidecar for cached lint
+ * configs. The two write different files (the `kind` segment of the cache
+ * key keeps their namespaces apart), so they coexist without collision.
+ */
+function configCacheDir(): string {
+  return path.join(os.tmpdir(), "ttsc-lint-config-cache");
+}
+
+/** Env opt-out, mirroring the Go sidecar's `TTSC_LINT_DISABLE_CONFIG_CACHE`. */
+function configCacheDisabled(): boolean {
+  return Boolean(process.env.TTSC_LINT_DISABLE_CONFIG_CACHE);
+}
+
+/**
+ * Content-addressed cache key for a lint config file. Mirrors the Go
+ * sidecar's `configCacheKey`: a version tag, a namespace `kind`, the
+ * config's absolute path, and its exact bytes. Returns "" — a "do not
+ * cache" signal — when the file cannot be read or the env opt-out is set.
+ */
+function configCacheKey(kind: string, configPath: string): string {
+  if (configCacheDisabled()) return "";
+  let content: Buffer;
+  try {
+    content = fs.readFileSync(configPath);
+  } catch {
+    return "";
+  }
+  return createHash("sha256")
+    .update(CONFIG_CACHE_VERSION)
+    .update("\0")
+    .update(kind)
+    .update("\0")
+    .update(path.resolve(configPath))
+    .update("\0")
+    .update(content)
+    .digest("hex");
+}
+
+/**
+ * Returns the cached plugin-entry list for `cacheKey`, or undefined on any
+ * miss — a missing file, an unreadable file, or content that is not a JSON
+ * array. Every failure is a soft miss: the caller re-evaluates.
+ */
+function readConfigPluginCache(
+  cacheKey: string,
+): ConfigPluginEntry[] | undefined {
+  let body: string;
+  try {
+    body = fs.readFileSync(
+      path.join(configCacheDir(), `${cacheKey}.json`),
+      "utf8",
+    );
+  } catch {
+    return undefined;
+  }
+  try {
+    const parsed: unknown = JSON.parse(body);
+    return Array.isArray(parsed)
+      ? (parsed as ConfigPluginEntry[])
+      : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Writes `entries` to the config cache under `cacheKey`. Best-effort: any
+ * failure leaves the cache cold rather than aborting plugin discovery. The
+ * temp-file + rename keeps a concurrent reader in a sibling `ttsc` process
+ * from observing a half-written file.
+ */
+function writeConfigPluginCache(
+  cacheKey: string,
+  entries: ConfigPluginEntry[],
+): void {
+  try {
+    const dir = configCacheDir();
+    fs.mkdirSync(dir, { recursive: true });
+    const tmp = path.join(dir, `${cacheKey}.${process.pid}.tmp`);
+    fs.writeFileSync(tmp, JSON.stringify(entries), "utf8");
+    fs.renameSync(tmp, path.join(dir, `${cacheKey}.json`));
+  } catch {
+    // Cold cache on failure — the next invocation re-evaluates.
+  }
+}
+
 // ────────────────────────────────────────────────────────────────────────────
 // Shared helpers
 // ────────────────────────────────────────────────────────────────────────────

package/src/structures/ITtscLintConfig.ts

@@ -5,8 +5,8 @@ import type { TtscLintRuleMap } from "./TtscLintRuleMap";
 /**
  * Top-level object accepted by `@ttsc/lint` config files.
  *
- * Keep the file shape plain: users export an object and use
- * `satisfies ITtscLintConfig` when they want type checking.
+ * Keep the file shape plain: users export an object and use `satisfies
+ * ITtscLintConfig` when they want type checking.
  */
 export interface ITtscLintConfig {
   /** Globs that select the files this entry applies to. */