fix: restore Reporter.withoutCache() — removing it was breaking

3.1.0 (e05416f) shipped Reporter.withoutCache() as the per-diagnostic
opt-out for findings whose correctness depends on inputs the cache
doesn't track. Dropping it in 47f5410 silently broke any rule that
relied on it — the call site would hit a TypeError at runtime, or
fail to type-check if written in TS.

Restore the API with semantics that match the original:

  - Diagnostic is still returned for the current run.
  - cache-flow filters it out before serialising the rule entry to
    disk, so the next warm hit on this file won't replay it (rule has
    to re-run to surface it again).

Marker is a Symbol.for('@tsslint/no-cache') stamped on the diagnostic
in core. Symbol-keyed → invisible to JSON.stringify and to
{...spread}, so it doesn't leak into the on-disk cache. Test 17
covers that explicitly.

README's "Caching" section is rewritten to describe the new two-layer
model and explain when withoutCache() still makes sense (external
inputs / fs-driven side reads); for cross-file types, the recommended
path is to read ctx.program once so layer 2 handles invalidation.

Tests:
  - cache-flow.test #15: marked diagnostic returned but not persisted
  - cache-flow.test #16: warm replay drops the marked one
  - cache-flow.test #17: marker doesn't leak through serialisation

Author: johnsoncodehk

README.md

@@ -163,11 +163,16 @@ defineConfig({
 
 ### Caching
 
-Diagnostics are cached on disk under `os.tmpdir()/tsslint-cache/`, keyed by file mtime. The cache is shared across rules and survives between editor sessions.
+Diagnostics are cached on disk under `os.tmpdir()/tsslint-cache/` in two layers, picked per rule:
 
-A diagnostic whose correctness depends on more than one file's mtime (e.g. anything that reads `ctx.program` for cross-file resolution and reports on the cached side) should opt out per-diagnostic via `.withoutCache()` on the reporter — the cached entry would otherwise go stale when an unrelated dependency file changes without invalidating its consumers' mtime.
+- **Layer 1** — invalidated by the linted file's mtime. Used for rules that don't read `ctx.program` (purely syntactic).
+- **Layer 2** — invalidated by TypeScript's `BuilderProgram` affected-file diff (transitive, includes ambient `.d.ts`). Used for rules that touch `ctx.program`. The first time a rule reads `ctx.program` it's classified type-aware and stays type-aware across sessions.
 
-Pass `--force` to the CLI to ignore the cache.
+A diagnostic whose correctness depends on inputs neither layer tracks — external resources, env vars, sibling files the rule reads directly via `fs` — should opt out per-diagnostic via `.withoutCache()` on the reporter. The diagnostic still surfaces on the current run; it just isn't written to disk, so the next warm hit on this file won't replay it (the rule has to re-run to surface it again).
+
+For diagnostics that depend on cross-file types, prefer reading `ctx.program` once instead — that re-classifies the rule type-aware and layer 2 handles invalidation properly.
+
+Pass `--force` to the CLI to ignore the cache. `--list-rules` prints each rule's classification (type-aware vs syntactic) after the run.
 
 ### Debugging
 

packages/cli/lib/cache-flow.ts

@@ -9,7 +9,7 @@
 // type-aware cleanup.
 
 import type * as ts from 'typescript';
-import type { Linter } from '@tsslint/core';
+import { NO_CACHE, type Linter } from '@tsslint/core';
 import type { FileCache, SerializedDiagnostic } from './cache.js';
 
 export function lintWithCache(
@@ -97,9 +97,16 @@ export function lintWithCache(
 				break;
 			}
 		}
+		// Drop diagnostics the rule marked via `Reporter.withoutCache()` —
+		// the rule is asserting they depend on inputs we don't track in
+		// the cache key, so a warm replay would be unsound. They're still
+		// included in the live `fresh` array returned from this function;
+		// they just don't survive to disk.
 		fileCache.rules[ruleId] = {
 			hasFix,
-			diagnostics: diags.map(serializeDiagnostic),
+			diagnostics: diags
+				.filter(d => !(d as any)[NO_CACHE])
+				.map(serializeDiagnostic),
 		};
 	}
 

packages/cli/test/cache-flow.test.ts

@@ -427,6 +427,98 @@ function emptyFileCache(mtime = 0): FileCache {
 	);
 }
 
+// ── Test 15: withoutCache() — diagnostic returned but not persisted ─────
+//
+// `Reporter.withoutCache()` is the rule's contract: "this finding's
+// correctness depends on inputs neither layer tracks; please don't
+// replay it from the cache." The current run still surfaces the
+// diagnostic; it just isn't written to disk, so the next warm hit on
+// the same file won't see it.
+{
+	const ctx = makeContext({ '/a.ts': 'const x = 1;' });
+	const config: Config = {
+		rules: {
+			env_dependent: ((rctx: RuleContext) => {
+				rctx.report('depends on env', 0, 1).withoutCache();
+				rctx.report('plain', 0, 1);
+			}),
+		},
+	};
+	const linter = core.createLinter(ctx, '/', config, () => []);
+	const cache = emptyFileCache(1);
+	const diags = cacheFlow.lintWithCache(
+		linter,
+		'/a.ts',
+		cache,
+		1,
+		ctx.languageService.getProgram()!,
+	);
+	check('current run returns both diagnostics', diags.length === 2);
+	check(
+		'cache entry exists for the rule',
+		!!cache.rules['env_dependent'],
+	);
+	check(
+		'only the non-marked diagnostic is persisted',
+		cache.rules['env_dependent']?.diagnostics.length === 1,
+		`expected 1 cached diagnostic, got ${cache.rules['env_dependent']?.diagnostics.length}`,
+	);
+	check(
+		'persisted diagnostic is the plain one',
+		cache.rules['env_dependent']?.diagnostics[0]?.messageText === 'plain',
+	);
+}
+
+// ── Test 16: withoutCache() — second run cache-hits with the survivor ───
+{
+	const ctx = makeContext({ '/a.ts': 'const x = 1;' });
+	const config: Config = {
+		rules: {
+			env_dependent: ((rctx: RuleContext) => {
+				rctx.report('depends on env', 0, 1).withoutCache();
+				rctx.report('plain', 0, 1);
+			}),
+		},
+	};
+	const linter = core.createLinter(ctx, '/', config, () => []);
+	const cache = emptyFileCache(1);
+	cacheFlow.lintWithCache(linter, '/a.ts', cache, 1, ctx.languageService.getProgram()!);
+
+	// Second run with the same mtime — rule cache-hits, only the
+	// persisted diagnostic comes back.
+	const linter2 = core.createLinter(ctx, '/', config, () => []);
+	const diags = cacheFlow.lintWithCache(
+		linter2,
+		'/a.ts',
+		cache,
+		1,
+		ctx.languageService.getProgram()!,
+	);
+	check('warm cache hit returns 1 diagnostic', diags.length === 1);
+	check('warm replay drops the marked one', diags[0]?.messageText === 'plain');
+}
+
+// ── Test 17: NO_CACHE marker doesn't leak through serialisation ─────────
+//
+// Symbol-keyed property must stay invisible to JSON.stringify and to
+// `{...spread}` so the on-disk cache stays clean.
+{
+	const ctx = makeContext({ '/a.ts': 'const x = 1;' });
+	const config: Config = {
+		rules: {
+			r: ((rctx: RuleContext) => {
+				rctx.report('marked', 0, 1).withoutCache();
+			}),
+		},
+	};
+	const linter = core.createLinter(ctx, '/', config, () => []);
+	const cache = emptyFileCache(1);
+	cacheFlow.lintWithCache(linter, '/a.ts', cache, 1, ctx.languageService.getProgram()!);
+	// rule entry exists but with 0 diagnostics — no smuggled keys.
+	const json = JSON.stringify(cache);
+	check('NO_CACHE marker not visible in serialised cache', !json.includes('no-cache'));
+}
+
 // ── Done ────────────────────────────────────────────────────────────────
 process.stdout.write('\n');
 if (failures.length) {

packages/core/index.ts

@@ -6,6 +6,13 @@ import minimatch = require('minimatch');
 
 export type Linter = ReturnType<typeof createLinter>;
 
+// Marker stamped onto diagnostics by `Reporter.withoutCache()`. The CLI
+// cache-flow filters these out before serialising to disk so they're
+// never replayed from a warm cache hit. Symbol-keyed (via Symbol.for so
+// it's stable across module instances) — invisible to JSON.stringify and
+// to `{...spread}` so it doesn't leak into the serialised cache.
+export const NO_CACHE = Symbol.for('@tsslint/no-cache');
+
 export function createLinter(
 	ctx: LinterContext,
 	rootDir: string,
@@ -199,6 +206,10 @@ export function createLinter(
 						});
 						return this;
 					},
+					withoutCache() {
+						(error as any)[NO_CACHE] = true;
+						return this;
+					},
 				};
 			}
 		},

packages/types/index.ts

@@ -56,4 +56,14 @@ export interface Reporter {
 	withUnnecessary(): Reporter;
 	withFix(title: string, getChanges: () => FileTextChanges[]): Reporter;
 	withRefactor(title: string, getChanges: () => FileTextChanges[]): Reporter;
+	// Mark this diagnostic as ineligible for the CLI's per-file cache.
+	// The diagnostic is still returned for the current run, but won't be
+	// written to disk — so the next warm run (cache hit on this file)
+	// won't replay it, and the rule must re-run to surface it again.
+	// Use when a diagnostic's correctness depends on inputs the layer-1
+	// mtime check doesn't track (external resources, env, sibling files
+	// the rule reads directly via fs). For type-checker-derived findings
+	// just read `ctx.program` once — that re-classifies the rule
+	// type-aware, and layer 2 handles cross-file invalidation properly.
+	withoutCache(): Reporter;
 }