@ttsc/lint 0.24.0 → 0.26.0

package/src/index.ts

@@ -8,9 +8,7 @@ import path from "node:path";
 import { pathToFileURL } from "node:url";
 
 import {
-  CONFIG_EVALUATOR_PROCESS_OPTIONS,
-  CONFIG_EVALUATOR_STATUS_FD,
-  configEvaluatorBoundaryEnvironment,
+  configEvaluatorFailureReason,
   configEvaluatorProcessFailure,
 } from "./internal/configEvaluatorFailure";
 import type { ITtscLintPlugin, ITtscLintPluginConfig } from "./structures";
@@ -630,33 +628,68 @@ const hooks = registerHooks({
   },
 });
 
-try {
-  const importedConfig = configLocation.toLowerCase().endsWith(".json")
-    ? JSON.parse(fs.readFileSync(configLocation, "utf8").replace(/^\uFEFF/, ""))
-    : await import(configUrl);
-  const current = await resolveConfig(importedConfig, true);
-  const pluginMaps = collectPluginObjects(current);
-  const entries: Array<{ namespace: string; source: string }> = [];
-  for (const map of pluginMaps) {
-    for (const [namespace, value] of Object.entries(map)) {
-      const source = extractPluginSource(value);
-      if (source === undefined || source.length === 0) {
-        throw new Error(
-          \`contributor \${JSON.stringify(namespace)} must resolve to an object with a non-empty "source" string\`,
-        );
+// Wrapped and settled explicitly rather than written as a top-level await.
+// The loader tsconfig's "module" now follows the config's own package, and
+// TS1378 rejects top-level await under a CommonJS module option however this
+// .mts file emits. The trailing catch is what a top-level await gave for
+// free: without it a throw from the finally would leave the promise
+// unsettled instead of failing the load.
+(async () => {
+  try {
+    const importedConfig = configLocation.toLowerCase().endsWith(".json")
+      ? JSON.parse(fs.readFileSync(configLocation, "utf8").replace(/^\uFEFF/, ""))
+      : await import(configUrl);
+    const current = await resolveConfig(importedConfig, true);
+    const pluginMaps = collectPluginObjects(current);
+    const entries: Array<{ namespace: string; source: string }> = [];
+    for (const map of pluginMaps) {
+      for (const [namespace, value] of Object.entries(map)) {
+        const source = extractPluginSource(value);
+        if (source === undefined || source.length === 0) {
+          throw new Error(
+            \`contributor \${JSON.stringify(namespace)} must resolve to an object with a non-empty "source" string\`,
+          );
+        }
+        entries.push({ namespace, source });
       }
-      entries.push({ namespace, source });
     }
+    fs.writeFileSync(outputPath, JSON.stringify({
+      dependencies: finalizeDependencies(),
+      entries,
+    }), "utf8");
+  } catch (error) {
+    reportLoaderFailure(error);
+  } finally {
+    hooks.deregister();
   }
-  fs.writeFileSync(outputPath, JSON.stringify({
-    dependencies: finalizeDependencies(),
-    entries,
-  }), "utf8");
-} catch (error) {
-  process.stderr.write(error instanceof Error && error.stack ? error.stack : String(error));
-  process.exit(1);
-} finally {
-  hooks.deregister();
+})().catch((error) => {
+  // Reached only when the finally above throws: the catch already ends the
+  // process, so this is the deregistration's own failure, not the config's.
+  reportLoaderFailure(error);
+});
+
+// reportLoaderFailure ends this loader on an error it can name, on both of the
+// channels the parent uses.
+//
+// The stack is for a reader and streams to stderr as it is written. The reason
+// is a fact about the user's config that a caller has to act on, so it travels
+// as data through the result file the parent already reads. Only a well-formed
+// envelope is honoured there, so a partially written or unrelated file leaves
+// the process status to speak for itself.
+function reportLoaderFailure(error: unknown): never {
+  // The trailing newline ends the stack as a line of its own. Without it the
+  // parent's own message, written to this same stream, starts mid-line.
+  process.stderr.write((error instanceof Error && error.stack ? error.stack : String(error)) + "\\n");
+  try {
+    fs.writeFileSync(
+      outputPath,
+      JSON.stringify({ __ttscLoaderError: error instanceof Error ? error.message : String(error) }),
+      "utf8",
+    );
+  } catch {
+    // A reason that cannot be written leaves the exit status as the report.
+  }
+  return process.exit(1);
 }
 
 function isObject(value: unknown): value is Record<string, unknown> {
@@ -1702,7 +1735,13 @@ function evaluateTtsxConfigPlugins(
             allowImportingTsExtensions: true,
             allowJs: true,
             checkJs: false,
-            module: "ESNext",
+            // The config is a Node module, so Node's rule decides its format:
+            // the nearest `package.json` `type` above it. Hardcoding one answer
+            // ran every ambiguous `.ts` config as ESM and broke `__dirname` in
+            // an ordinary CommonJS package (#1068). `moduleResolution` stays
+            // `bundler`, which tsgo accepts for both kinds, so extensionless
+            // relative imports keep resolving either way.
+            module: configModuleOption(configPath),
             moduleResolution: "bundler",
             noImplicitAny: false,
             outDir: path.join(tempDir, "out").replace(/\\/g, "/"),
@@ -1711,6 +1750,12 @@ function evaluateTtsxConfigPlugins(
             skipLibCheck: true,
             strict: false,
             target: "ES2022",
+            // TypeScript 7 includes no ambient type package unless `types` asks
+            // for it, and this Program extends nothing, so without the wildcard
+            // a config could not name a single Node global (#1068). The loader
+            // directory links the config's nearest `node_modules`, so the
+            // default `typeRoots` walk finds exactly what the project installed.
+            types: ["*"],
           },
           files: [
             loaderPath.replace(/\\/g, "/"),
@@ -1749,28 +1794,29 @@ function evaluateTtsxConfigPlugins(
     }
     const env = {
       ...nodeConfigLoaderEnv(configPath),
-      ...configEvaluatorBoundaryEnvironment(),
     };
     const command = ttsxThroughNodeIfNeeded(ttsxBinary);
     const result = spawnSync(command.binary, [...command.prefix, ...args], {
       cwd: tempDir,
       env,
-      encoding: "utf8",
-      ...CONFIG_EVALUATOR_PROCESS_OPTIONS,
-      stdio: [
-        "ignore",
-        "pipe",
-        "pipe",
-        ...Array.from(
-          { length: CONFIG_EVALUATOR_STATUS_FD - 2 },
-          () => "pipe" as const,
-        ),
-      ],
+      // Both child streams are human output, and they go straight to this
+      // process's stderr as they are written. Nothing is collected here: the
+      // parent's stdout is reserved for compiler JSON and LSP frames, and
+      // buffering the child only to replay it afterwards is what forced an
+      // invented output ceiling and made a long evaluation print nothing at all.
+      stdio: ["ignore", 2, 2],
       windowsHide: true,
     });
-    forwardConfigEvaluatorStreams(result.stdout, result.stderr);
     const processFailure = configEvaluatorProcessFailure(result, configPath);
-    if (processFailure) throw processFailure;
+    if (processFailure) {
+      // The evaluator's stack already reached the user's stderr as it ran. What
+      // it could not put there is a reason a caller can act on, so that arrives
+      // through the result file instead.
+      const reason = configEvaluatorFailureReason(outputPath);
+      throw reason === ""
+        ? processFailure
+        : new Error(`${processFailure.message}\n${reason}`);
+    }
     let payload: {
       dependencies?: ConfigDependencyFingerprint[];
       entries?: ConfigPluginEntry[];
@@ -1841,20 +1887,10 @@ function evaluateTtsxConfigPlugins(
     }
     return { dependencies, entries };
   } finally {
-    fs.rmSync(tempDir, { recursive: true, force: true });
+    removeEvaluationTempDir(tempDir);
   }
 }
 
-function forwardConfigEvaluatorStreams(
-  stdout: string | null | undefined,
-  stderr: string | null | undefined,
-): void {
-  // Both child streams are human output. Parent stdout is reserved for compiler
-  // JSON or LSP frames, so even a user console.log is redirected.
-  if (stdout) process.stderr.write(stdout);
-  if (stderr) process.stderr.write(stderr);
-}
-
 // ────────────────────────────────────────────────────────────────────────────
 // Config cache (shared with the Go sidecar — packages/lint/linthost/config.go)
 // ────────────────────────────────────────────────────────────────────────────
@@ -2268,6 +2304,64 @@ function findNearestNodeModules(start: string): string | undefined {
   }
 }
 
+/**
+ * The loader tsconfig's `module` for a given config file: the module kind Node
+ * would give the file itself.
+ *
+ * An explicit `.cts`/`.cjs` or `.mts`/`.mjs` extension already decides the emit
+ * format on its own, so those keep the ES-module setting and let the extension
+ * win — the same precedence tsgo applies. Everything ambiguous walks up for the
+ * nearest `package.json` `type`, exactly as Node does when it loads the file.
+ */
+function configModuleOption(configPath: string): string {
+  const extension = path.extname(configPath).toLowerCase();
+  if (extension !== ".ts" && extension !== ".tsx" && extension !== ".js") {
+    return "ESNext";
+  }
+  return nearestPackageType(configPath) === "commonjs" ? "CommonJS" : "ESNext";
+}
+
+/**
+ * Nearest `package.json` `"type"` at or above `configPath`, mirroring Node's
+ * package-scope lookup: the walk stops at the **first** manifest it finds, and
+ * a manifest that declares no `"type"` means CommonJS rather than a reason to
+ * keep climbing. Reaching the filesystem root without any manifest also means
+ * CommonJS.
+ */
+function nearestPackageType(configPath: string): "commonjs" | "module" {
+  let dir = path.dirname(path.resolve(configPath));
+  for (;;) {
+    // One read rather than a stat-then-read: an unreadable entry and a missing
+    // one are the same answer here — keep walking — and the Go loaders resolve
+    // it the same way, so the four implementations of this rule cannot drift.
+    let raw: string | undefined;
+    try {
+      raw = fs.readFileSync(path.join(dir, "package.json"), "utf8");
+    } catch {
+      raw = undefined;
+    }
+    if (raw !== undefined) {
+      try {
+        const manifest: unknown = JSON.parse(raw);
+        const type =
+          typeof manifest === "object" && manifest !== null
+            ? (manifest as { type?: unknown }).type
+            : undefined;
+        return type === "module" ? "module" : "commonjs";
+      } catch {
+        // A manifest that does not parse still bounds the package scope; Node
+        // refuses to look past it, and CommonJS is the format it defaults to.
+        return "commonjs";
+      }
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) {
+      return "commonjs";
+    }
+    dir = parent;
+  }
+}
+
 function linkNearestNodeModules(tempDir: string, sourceDir: string): void {
   const nodeModules = findNearestNodeModules(sourceDir);
   if (!nodeModules) return;
@@ -2400,3 +2494,19 @@ function ttsxThroughNodeIfNeeded(binary: string): {
   }
   return { binary, prefix: [] };
 }
+
+/**
+ * Remove an evaluation temp directory without letting cleanup replace a result.
+ *
+ * This runs from a `finally`, so a throw here would surface instead of the
+ * evaluation's own outcome — and on Windows a grandchild that inherited a
+ * handle, or a scanner holding the file, can make removal fail. Leaving bytes
+ * in the system temp directory is by far the lesser outcome.
+ */
+function removeEvaluationTempDir(directory: string): void {
+  try {
+    fs.rmSync(directory, { force: true, recursive: true });
+  } catch {
+    // Best effort.
+  }
+}

package/src/internal/configEvaluatorFailure.ts

@@ -1,51 +1,31 @@
-export const CONFIG_EVALUATOR_MAX_BUFFER = 16 * 1024 * 1024;
-export const CONFIG_EVALUATOR_TIMEOUT_MS = 60_000;
-export const CONFIG_EVALUATOR_TEARDOWN_GRACE_MS = 5_000;
-export const CONFIG_EVALUATOR_STATUS_FD = 3;
-export const CONFIG_EVALUATOR_PROCESS_OPTIONS = Object.freeze({
-  killSignal: "SIGKILL" as const,
-  maxBuffer: CONFIG_EVALUATOR_MAX_BUFFER,
-  timeout: CONFIG_EVALUATOR_TIMEOUT_MS + CONFIG_EVALUATOR_TEARDOWN_GRACE_MS,
-});
+import fs from "node:fs";
 
 interface ConfigEvaluatorProcessResult {
   error?: Error;
-  output?: readonly (string | null)[] | null;
   signal: NodeJS.Signals | null;
   status: number | null;
-  stderr: string | null | undefined;
 }
 
 /**
  * Classify the ways the isolated lint-config evaluator can stop.
  *
- * Node reports both timeout and max-buffer termination with the configured
- * signal, so the process error code must take precedence over the signal. The
- * evaluator uses `SIGKILL`: Node's synchronous process API otherwise keeps
- * waiting when a POSIX child handles the default `SIGTERM` without exiting. A
- * bare signal is an external termination and a non-zero status is an evaluator
- * failure whose stderr tail contains the useful user-config diagnostic.
+ * The evaluator writes the child's own output straight to this process's
+ * stderr, so a diagnostic has already reached the user by the time anything
+ * here runs. What is left to say is only how the process ended: it never
+ * launched, something outside killed it, or it exited non-zero after printing
+ * its own reason.
+ *
+ * Nothing is bounded here — not time, not output. Both were the compiler
+ * deciding, on numbers nobody chose for this machine, that a user's own config
+ * had run too long or said too much. A slow config is a slow build the user can
+ * watch and interrupt; a loud one is output they asked for. Neither is this
+ * process's memory to spend either, because the child's streams are no longer
+ * collected into it.
  */
 export function configEvaluatorProcessFailure(
   result: ConfigEvaluatorProcessResult,
   configPath: string,
 ): Error | undefined {
-  const code = (result.error as NodeJS.ErrnoException | undefined)?.code;
-  const nestedCode = result.output?.[CONFIG_EVALUATOR_STATUS_FD]?.trim() ?? "";
-  if (code === "ETIMEDOUT" || nestedCode === "ETIMEDOUT") {
-    return new Error(
-      `@ttsc/lint: ttsx evaluation of ${configPath} timed out after ` +
-        `${CONFIG_EVALUATOR_TIMEOUT_MS / 1_000} seconds. ` +
-        "Simplify the config or move heavy work out of top-level.",
-    );
-  }
-  if (code === "ENOBUFS" || nestedCode === "ENOBUFS") {
-    return new Error(
-      `@ttsc/lint: ttsx evaluation of ${configPath} exceeded the ` +
-        `${CONFIG_EVALUATOR_MAX_BUFFER / (1024 * 1024)} MiB output limit. ` +
-        "Reduce console output from the config and its dependencies.",
-    );
-  }
   if (result.error) {
     return new Error(
       `@ttsc/lint: failed to spawn ttsx for ${configPath}: ${result.error.message}`,
@@ -57,43 +37,34 @@ export function configEvaluatorProcessFailure(
     );
   }
   if (result.status !== 0) {
-    const reason = configEvaluatorFailureReason(result.stderr);
     return new Error(
-      `@ttsc/lint: lint config ${configPath} evaluation failed with exit code ${String(result.status)}` +
-        (reason === "" ? "" : "\n" + reason),
+      `@ttsc/lint: lint config ${configPath} evaluation failed with exit code ${String(result.status)}`,
     );
   }
   return undefined;
 }
 
 /**
- * Pass the semantic deadline and private status pipe through the `ttsx` wrapper
- * to the runtime child that actually executes the config.
- */
-export function configEvaluatorBoundaryEnvironment(
-  now: number = Date.now(),
-): NodeJS.ProcessEnv {
-  return {
-    TTSC_TTSX_EVALUATOR_DEADLINE_MS: String(now + CONFIG_EVALUATOR_TIMEOUT_MS),
-    TTSC_TTSX_EVALUATOR_MAX_BUFFER_BYTES: String(CONFIG_EVALUATOR_MAX_BUFFER),
-    TTSC_TTSX_EVALUATOR_STATUS_FD: String(CONFIG_EVALUATOR_STATUS_FD),
-  };
-}
-
-/**
- * Return the useful tail of evaluator stderr without turning an exception into
- * an unbounded duplicate of the already-forwarded child stream.
+ * Read the failure envelope the evaluator writes to its result file when it
+ * stops on an error it can name.
+ *
+ * This is the other half of classifying how the evaluation ended, which is why
+ * it lives beside {@link configEvaluatorProcessFailure} rather than at the call
+ * site: the status says that it failed, and this says why.
+ *
+ * Only a well-formed envelope is honoured. A real evaluation payload never
+ * carries this key, and every other shape — an absent file, a build that failed
+ * before the loader ran, a half-written result, a payload written before a
+ * later non-zero exit — leaves the process status to speak for itself.
  */
-function configEvaluatorFailureReason(
-  stderr: string | null | undefined,
-): string {
-  const bounded = (stderr ?? "").slice(-CONFIG_EVALUATOR_REASON_MAX_CHARS);
-  const lines = bounded
-    .split(/\r?\n/)
-    .map((line) => line.trimEnd())
-    .filter((line) => line.trim() !== "");
-  return lines.slice(-CONFIG_EVALUATOR_REASON_LINES).join("\n");
+export function configEvaluatorFailureReason(outputPath: string): string {
+  try {
+    const parsed: unknown = JSON.parse(fs.readFileSync(outputPath, "utf8"));
+    if (typeof parsed !== "object" || parsed === null) return "";
+    const message = (parsed as { __ttscLoaderError?: unknown })
+      .__ttscLoaderError;
+    return typeof message === "string" ? message.trim() : "";
+  } catch {
+    return "";
+  }
 }
-
-const CONFIG_EVALUATOR_REASON_LINES = 5;
-const CONFIG_EVALUATOR_REASON_MAX_CHARS = 8 * 1024;

package/src/structures/rules/ITtscLintFunctionalRuleOptions.ts

@@ -80,24 +80,45 @@ export interface ITtscLintFunctionalNoThrowStatementsRuleOptions {
 
 /** `functional/no-mixed-types` rule options. */
 export interface ITtscLintFunctionalNoMixedTypesRuleOptions {
-  /** Check interface member kinds. */
+  /**
+   * Check interface member kinds.
+   *
+   * @default true
+   */
   checkInterfaces?: boolean;
 
-  /** Check type-literal member kinds. */
+  /**
+   * Check type-literal member kinds.
+   *
+   * @default true
+   */
   checkTypeLiterals?: boolean;
 }
 
 /** `functional/no-return-void` rule options. */
 export interface ITtscLintFunctionalNoReturnVoidRuleOptions {
-  /** Permit a function that returns `null` to satisfy the rule. */
+  /**
+   * Permit a function whose declared return type is `null`. Set `false` to
+   * reject it the way a declared `void` is rejected.
+   *
+   * @default true
+   */
   allowNull?: boolean;
 
-  /** Permit a function that returns `undefined` to satisfy the rule. */
+  /**
+   * Permit a function whose declared return type is `undefined`. Set `false` to
+   * reject it the way a declared `void` is rejected.
+   *
+   * @default true
+   */
   allowUndefined?: boolean;
 
   /**
-   * Skip functions whose return type is inferred to be `void` rather than
-   * declared explicitly.
+   * Skip a bare `return;` inside a function that declares no return type. That
+   * statement is the one place the rule rejects a void-ness it inferred rather
+   * than read from an annotation.
+   *
+   * @default false
    */
   ignoreInferredTypes?: boolean;
 }
@@ -105,7 +126,8 @@ export interface ITtscLintFunctionalNoReturnVoidRuleOptions {
 /** `functional/prefer-immutable-types` rule options. */
 export interface ITtscLintFunctionalPreferImmutableTypesRuleOptions extends ITtscLintFunctionalPatternOptions {
   /**
-   * Minimum accepted immutability. The native subset treats any configured
+   * Minimum accepted immutability. Reserved for upstream-compatible configs;
+   * the native subset computes no immutability level and treats any configured
    * value as readonly-required.
    */
   enforcement?:
@@ -118,31 +140,62 @@ export interface ITtscLintFunctionalPreferImmutableTypesRuleOptions extends ITts
 
 /** `functional/prefer-readonly-type` rule options. */
 export interface ITtscLintFunctionalPreferReadonlyTypeRuleOptions extends ITtscLintFunctionalPatternOptions {
-  /** Permit mutation of locals while still policing exported types. */
+  /**
+   * Permit mutation of locals while still policing exported types. Reserved for
+   * upstream-compatible configs; the native subset reads type annotations and
+   * models no local-versus-exported distinction.
+   */
   allowLocalMutation?: boolean;
 
-  /** Permit a mutable return type even when parameters must be readonly. */
+  /**
+   * Permit a mutable return type even when parameters must be readonly. Covers
+   * every signature that can declare one, including call and construct
+   * signatures, constructor types, and a get accessor.
+   *
+   * @default false
+   */
   allowMutableReturnType?: boolean;
 
-  /** Also check property positions that have no explicit type annotation. */
+  /**
+   * Also check property positions that have no explicit type annotation.
+   * Reserved for upstream-compatible configs; judging an unannotated position
+   * needs the type checker, which this rule does not use.
+   */
   checkImplicit?: boolean;
 
-  /** Skip array / tuple / `Map` / `Set` types. */
+  /**
+   * Skip array / tuple / `Map` / `Set` types.
+   *
+   * @default false
+   */
   ignoreCollections?: boolean;
 
   /**
-   * Skip class fields. `"fieldsOnly"` keeps the rule active for non-field class
-   * members.
+   * Skip class members. `true` skips anything under a class, its heritage
+   * clause and type parameters included; `"fieldsOnly"` narrows that to field
+   * declarations and keeps methods, accessors, and constructor parameters
+   * checked.
+   *
+   * @default false
    */
   ignoreClass?: boolean | "fieldsOnly";
 
-  /** Skip interface members entirely. */
+  /**
+   * Skip interface members entirely.
+   *
+   * @default false
+   */
   ignoreInterface?: boolean;
 }
 
 /** `functional/prefer-tacit` rule options. */
 export interface ITtscLintFunctionalPreferTacitRuleOptions {
-  /** Check member expressions such as `x => service.map(x)`. */
+  /**
+   * Check member expressions such as `x => service.map(x)`. Set `false` to keep
+   * the rule on bare-identifier callees only.
+   *
+   * @default true
+   */
   checkMemberExpressions?: boolean;
 }
 
@@ -167,7 +220,11 @@ export interface ITtscLintFunctionalTypeDeclarationImmutabilityRule {
    */
   immutability?: "ReadonlyShallow" | "ReadonlyDeep" | "Immutable" | "Mutable";
 
-  /** Comparator applied to the immutability level above. */
+  /**
+   * Comparator applied to the immutability level above. Reserved for
+   * upstream-compatible configs alongside `immutability`: the native subset
+   * computes no immutability level, so there is nothing to compare.
+   */
   comparator?:
     | "Less"
     | "AtMost"