@nifrajs/cli 3.5.0 → 4.0.2

package/src/rules/secrets.ts

@@ -0,0 +1,174 @@
+/**
+ * NF-C032: what looks like a credential in browser code or in `public/`, checked from source with the
+ * scanner every client build runs (`@nifrajs/web/zones`). The build also matches the values of the
+ * build environment's private variables in its output; that needs the build's environment, so it
+ * stays the build's.
+ */
+import { existsSync, readFileSync } from "node:fs"
+import { join } from "node:path"
+import {
+  publicScanFiles,
+  type SecretExemption,
+  type SecretScanFile,
+  scanForSecrets,
+} from "@nifrajs/web/zones"
+import { CONFIG_FILE } from "../app-files.ts"
+import { stripComments } from "../check-scan.ts"
+import { type Diagnostic, diagnostic } from "../diagnostics.ts"
+import { codeUnitOrder } from "../internal/code-unit-order.ts"
+import type { CheckRule } from "./index.ts"
+import { zonedFiles } from "./zones.ts"
+
+const BROWSER_CODE = new Set(["route-frontend", "frontend", "shared"])
+
+const EXEMPTIONS_START = /\bexport\s+const\s+secretExemptions\b[^=]*=\s*\[/
+
+type Token = { readonly kind: "string" | "word" | "punct"; readonly value: string }
+
+/**
+ * The tokens of an array literal, from just after its `[` to the `]` that closes it. A string is one
+ * token, so a bracket or a colon inside one (`"routes/[lang]/index.tsx"`) is text, never syntax.
+ */
+function arrayTokens(src: string, from: number): Token[] {
+  const tokens: Token[] = []
+  let depth = 0
+  let i = from
+  while (i < src.length) {
+    const c = src[i] as string
+    if (c === '"' || c === "'" || c === "`") {
+      let value = ""
+      let j = i + 1
+      while (j < src.length && src[j] !== c) {
+        if (src[j] === "\\") {
+          value += src[j + 1] ?? ""
+          j += 2
+        } else value += src[j++]
+      }
+      tokens.push({ kind: "string", value })
+      i = j + 1
+    } else if (/[\w$]/.test(c)) {
+      let j = i
+      while (j < src.length && /[\w$]/.test(src[j] as string)) j++
+      tokens.push({ kind: "word", value: src.slice(i, j) })
+      i = j
+    } else {
+      if (c === "]" || c === "}" || c === ")") {
+        if (depth === 0) break
+        depth--
+      } else if (c === "[" || c === "{" || c === "(") depth++
+      if (!/\s/.test(c)) tokens.push({ kind: "punct", value: c })
+      i++
+    }
+  }
+  return tokens
+}
+
+const isPunct = (token: Token | undefined, value: string): boolean =>
+  token?.kind === "punct" && token.value === value
+
+/**
+ * The app's `secretExemptions`, read statically from `nifra.config.ts` (check never imports app code):
+ * an array literal of object literals with string fields, the form the build error suggests.
+ */
+export function readSecretExemptions(appRoot: string): SecretExemption[] {
+  const path = join(appRoot, CONFIG_FILE)
+  if (!existsSync(path)) return []
+  const text = stripComments(readFileSync(path, "utf8"))
+  const opened = EXEMPTIONS_START.exec(text)
+  if (opened === null) return []
+  const tokens = arrayTokens(text, opened.index + opened[0].length)
+  const exemptions: SecretExemption[] = []
+  let depth = 0
+  let fields: Record<string, string> | undefined
+  for (let i = 0; i < tokens.length; i++) {
+    const token = tokens[i] as Token
+    if (token.kind === "punct" && "[{(".includes(token.value)) {
+      depth++
+      if (depth === 1 && token.value === "{") fields = {}
+    } else if (token.kind === "punct" && "]})".includes(token.value)) {
+      if (depth === 1 && fields !== undefined) {
+        const { rule, reason, file, env } = fields
+        if (rule !== undefined && reason !== undefined) {
+          exemptions.push({
+            rule: rule as SecretExemption["rule"],
+            reason,
+            ...(file === undefined ? {} : { file }),
+            ...(env === undefined ? {} : { env }),
+          })
+        }
+        fields = undefined
+      }
+      depth--
+    } else if (
+      depth === 1 &&
+      fields !== undefined &&
+      token.kind !== "punct" &&
+      isPunct(tokens[i + 1], ":") &&
+      tokens[i + 2]?.kind === "string" &&
+      (isPunct(tokens[i + 3], ",") || isPunct(tokens[i + 3], "}"))
+    ) {
+      fields[token.value] ??= (tokens[i + 2] as Token).value
+      i += 2
+    }
+  }
+  return exemptions
+}
+
+export const secretSourceRule: CheckRule = {
+  code: "NF-C032",
+  title: "Credential in browser code",
+  async scan(ctx) {
+    const { files } = zonedFiles(ctx)
+    const apps = new Map<string, SecretScanFile[]>()
+    for (const { file, app, classification } of files) {
+      if (!apps.has(app)) apps.set(app, [])
+      if (!BROWSER_CODE.has(classification.zone)) continue
+      const text = ctx.sources.read(file)
+      if (text === undefined) continue
+      const name = app === "" ? file : file.slice(app.length + 1)
+      apps.get(app)?.push({ name, text, firstParty: true })
+    }
+    const findings: Diagnostic[] = []
+    for (const [app, sources] of apps) {
+      const appRoot = join(ctx.root, app)
+      const publicDir = join(appRoot, "public")
+      try {
+        const found = scanForSecrets({
+          sources,
+          artifacts: existsSync(publicDir) ? publicScanFiles(publicDir, "public") : [],
+          exemptions: readSecretExemptions(appRoot),
+        })
+        for (const finding of found) {
+          const file = app === "" ? finding.file : `${app}/${finding.file}`
+          findings.push(
+            diagnostic({
+              code: "NF-C032",
+              severity: "error",
+              file,
+              line: finding.line,
+              message: `${file} carries what looks like a credential (${finding.what}), and it reaches the browser. Read it from the environment in a route's backend half or under backend/, and rotate it if it was ever committed`,
+              evidence: [`rule: ${finding.rule}`, `match: ${finding.preview}`],
+              verify: "nifra check",
+            }),
+          )
+        }
+      } catch (error) {
+        // A malformed exemption: the build refuses it with the same message.
+        findings.push(
+          diagnostic({
+            code: "NF-C032",
+            severity: "error",
+            file: join(app, CONFIG_FILE),
+            message: error instanceof Error ? error.message : String(error),
+            verify: "nifra check",
+          }),
+        )
+      }
+    }
+    return findings.sort(
+      (a, b) => codeUnitOrder(a.file ?? "", b.file ?? "") || (a.line ?? 0) - (b.line ?? 0),
+    )
+  },
+}
+
+export const secretRules = Object.freeze([secretSourceRule])

package/src/rules/security.ts

@@ -1,8 +1,10 @@
 import type * as TSApi from "typescript"
+import { isBrowserSource } from "../check-scan.ts"
 import { type Diagnostic, diagnostic } from "../diagnostics.ts"
-import { importProjectTypeScript } from "../internal/typescript-import.ts"
+import { scriptKindOf } from "../internal/script-kind.ts"
 import { commentBlockHasMarker } from "./comment-markers.ts"
 import type { CheckRule, SourceIndex } from "./index.ts"
+import { loadRuleTypeScript } from "./typescript.ts"
 
 /**
  * A security rule that cannot run says so as an advisory finding instead of silently returning no
@@ -42,17 +44,33 @@ function reviewedEvidence(lines: readonly string[], line: number): readonly stri
 
 /**
  * NF-S002 severity by file role. Server-side code compares real secret material - a timing oracle
- * there is exploitable, so it fails the gate. Client-bundled code (route modules, .tsx/.jsx)
+ * there is exploitable, so it fails the gate. Browser code (a route's frontend half, `frontend/`)
  * compares values the client already holds, so the same shape is advisory rather than a gate
- * failure. A server marker beats a client marker (`routes/x.server.ts` is server), and a plain .ts
- * that cannot be classified is treated as server - fail closed.
+ * failure. `shared/` also runs on the server, and a file that cannot be classified is treated as
+ * server - fail closed.
  */
 function secretComparisonSeverity(file: string): "error" | "warn" {
   const path = file.replaceAll("\\", "/")
-  if (/\.server\.[cm]?[tj]sx?$/.test(path)) return "error"
-  if (/(?:^|\/)server\//.test(path) || /(?:^|\/)backend\.[cm]?[tj]s$/.test(path)) return "error"
-  if (/\.[tj]sx$/.test(path) || /(?:^|\/)routes\//.test(path)) return "warn"
-  return "error"
+  if (!isBrowserSource(path) || /\.server\.[cm]?[tj]sx?$/.test(path)) return "error"
+  if (/\.shared\.[^/]+$/.test(path) || /(?:^|\/)shared\//.test(path)) return "error"
+  return "warn"
+}
+
+const CONFIRMATION_NAME =
+  /^(?:confirm|confirmation|confirmPassword|passwordConfirmation|passwordConfirm|passwordRepeat|repeatPassword)$/i
+
+/** Client form confirmation compares two values already held by the browser, not secret material. */
+function isClientConfirmationPair(
+  file: string,
+  left: string | undefined,
+  right: string | undefined,
+): boolean {
+  if (secretComparisonSeverity(file) !== "warn") return false
+  const names = [left, right]
+  return (
+    names.some((name) => name?.toLowerCase() === "password") &&
+    names.some((name) => name !== undefined && CONFIRMATION_NAME.test(name))
+  )
 }
 
 function nameOf(ts: typeof TSApi, node: TSApi.Node): string | undefined {
@@ -63,18 +81,20 @@ function nameOf(ts: typeof TSApi, node: TSApi.Node): string | undefined {
 
 /**
  * The operand name to match secret-like patterns against for NF-S002, or undefined when the operand
- * cannot hold runtime secret material. A property access to an uppercase-initial member
+ * cannot hold runtime secret material. A property access to a PascalCase member
  * (`ts.SyntaxKind.PlusToken`, `MediaKind.Audio`) reads an enum/type-constant discriminant, never a
  * secret string or byte buffer, so comparing against it is a kind check a timing oracle does not
- * apply to. Runtime secret fields follow the camelCase convention (`apiToken`, `signature`), so an
- * uppercase-initial member is a safe exclusion. Identifiers stay matched in every case, so an
- * `UPPER_SNAKE` secret constant still surfaces.
+ * apply to. An `UPPER_SNAKE` member is the configuration spelling (`process.env.API_TOKEN`,
+ * `env.WEBHOOK_SECRET`) and stays matched, as does a string-literal element access
+ * (`process.env["API_KEY"]`).
  */
 function secretName(ts: typeof TSApi, node: TSApi.Node): string | undefined {
   if (ts.isPropertyAccessExpression(node)) {
     const member = node.name.text
-    return /^[A-Z]/.test(member) ? undefined : member
+    return /^[A-Z]/.test(member) && !/^[A-Z][A-Z0-9_]*$/.test(member) ? undefined : member
   }
+  if (ts.isElementAccessExpression(node) && ts.isStringLiteralLike(node.argumentExpression))
+    return node.argumentExpression.text
   return nameOf(ts, node)
 }
 
@@ -99,8 +119,7 @@ function isPresenceComparison(ts: typeof TSApi, node: TSApi.BinaryExpression): b
 }
 
 function parse(ts: typeof TSApi, file: string, source: string): TSApi.SourceFile {
-  const kind = /\.tsx?$/.test(file) ? ts.ScriptKind.TSX : ts.ScriptKind.JS
-  return ts.createSourceFile(file, source, ts.ScriptTarget.Latest, true, kind)
+  return ts.createSourceFile(file, source, ts.ScriptTarget.Latest, true, scriptKindOf(ts, file))
 }
 
 function parsedFile(
@@ -123,62 +142,138 @@ function parsedFile(
   return parsed
 }
 
+interface SecretComparison {
+  readonly node: TSApi.BinaryExpression
+  readonly left: string | undefined
+  readonly right: string | undefined
+  readonly line: number
+}
+
+function secretComparisons(
+  ts: typeof TSApi,
+  file: string,
+  tree: TSApi.SourceFile,
+): readonly SecretComparison[] {
+  const operators = [
+    ts.SyntaxKind.EqualsEqualsEqualsToken,
+    ts.SyntaxKind.ExclamationEqualsEqualsToken,
+    ts.SyntaxKind.EqualsEqualsToken,
+    ts.SyntaxKind.ExclamationEqualsToken,
+  ]
+  const found: SecretComparison[] = []
+  const visit = (node: TSApi.Node): void => {
+    if (
+      ts.isBinaryExpression(node) &&
+      operators.includes(node.operatorToken.kind) &&
+      !isPresenceComparison(ts, node)
+    ) {
+      const left = secretName(ts, node.left)
+      const right = secretName(ts, node.right)
+      if (
+        ((left !== undefined && SECRET.test(left)) ||
+          (right !== undefined && SECRET.test(right))) &&
+        !isClientConfirmationPair(file, left, right)
+      ) {
+        const line = tree.getLineAndCharacterOfPosition(node.getStart(tree)).line + 1
+        found.push({ node, left, right, line })
+      }
+    }
+    ts.forEachChild(node, visit)
+  }
+  visit(tree)
+  return found
+}
+
+function timingSafeHelper(file: string): string {
+  const typed = /\.[cm]?tsx?$/.test(file)
+  return [
+    'import { timingSafeEqual as nifraTimingSafeEqualBytes } from "node:crypto"',
+    "",
+    typed
+      ? "function nifraTimingSafeEqual(left: string, right: string): boolean {"
+      : "function nifraTimingSafeEqual(left, right) {",
+    "  const leftBytes = Buffer.from(left)",
+    "  const rightBytes = Buffer.from(right)",
+    "  return leftBytes.length === rightBytes.length && nifraTimingSafeEqualBytes(leftBytes, rightBytes)",
+    "}",
+  ].join("\n")
+}
+
+/**
+ * Rewrite every unreviewed NF-S002 comparison in one file to `nifraTimingSafeEqual(left, right)` and
+ * add the helper once. Sites come from the syntax tree, not a reported line: the helper lands above
+ * them, so a line number a check run reported no longer names the same statement after the first fix.
+ */
+export function rewriteSecretComparisons(ts: typeof TSApi, file: string, source: string): string {
+  const tree = parse(ts, file, source)
+  const lines = tree.text.split("\n")
+  const sites = secretComparisons(ts, file, tree).filter((site) => !hasReview(lines, site.line))
+  // A comparison nested inside another (`(token === a) === flag`) is left for the next run, so every
+  // edit below covers a disjoint range and applying them from the end keeps earlier offsets valid.
+  const outer = sites.filter(
+    ({ node }) =>
+      !sites.some(
+        (other) => other.node !== node && other.node.pos >= node.pos && other.node.end <= node.end,
+      ),
+  )
+  if (outer.length === 0) return source
+  let text = source
+  for (const { node } of outer.toSorted((a, b) => b.node.end - a.node.end)) {
+    const call = `nifraTimingSafeEqual(${node.left.getText(tree)}, ${node.right.getText(tree)})`
+    const negated =
+      node.operatorToken.kind === ts.SyntaxKind.ExclamationEqualsEqualsToken ||
+      node.operatorToken.kind === ts.SyntaxKind.ExclamationEqualsToken
+    text = `${text.slice(0, node.getStart(tree))}${negated ? `!${call}` : call}${text.slice(node.end)}`
+  }
+  if (source.includes("function nifraTimingSafeEqual")) return text
+  // After a shebang and the directive prologue: an import above `"use client"` turns it into a no-op.
+  let at = 0
+  for (const statement of tree.statements) {
+    if (!ts.isExpressionStatement(statement) || !ts.isStringLiteral(statement.expression)) break
+    at = statement.end
+  }
+  if (at === 0 && text.startsWith("#!")) at = text.includes("\n") ? text.indexOf("\n") : text.length
+  const helper = timingSafeHelper(file)
+  return at === 0 ? `${helper}\n\n${text}` : `${text.slice(0, at)}\n\n${helper}\n${text.slice(at)}`
+}
+
 export const secretComparisonRule: CheckRule = {
   code: "NF-S002",
   title: "Non-constant-time secret comparison",
   async scan(ctx) {
-    const ts = await importProjectTypeScript(ctx.root)
+    const loaded = await loadRuleTypeScript(ctx)
+    if (loaded.diagnostics !== undefined) return loaded.diagnostics
+    const ts = loaded.compiler
     if (ts === undefined) return didNotRun("NF-S002", "Non-constant-time secret comparison scan")
     const findings: Diagnostic[] = []
     for (const file of ctx.project.source.files) {
       const parsed = parsedFile(ts, ctx.project.source, file)
       if (parsed === undefined) continue
       const { tree, lines } = parsed
-      const visit = (node: TSApi.Node): void => {
-        if (
-          ts.isBinaryExpression(node) &&
-          [
-            ts.SyntaxKind.EqualsEqualsEqualsToken,
-            ts.SyntaxKind.ExclamationEqualsEqualsToken,
-            ts.SyntaxKind.EqualsEqualsToken,
-            ts.SyntaxKind.ExclamationEqualsToken,
-          ].includes(node.operatorToken.kind) &&
-          !isPresenceComparison(ts, node)
-        ) {
-          const left = secretName(ts, node.left)
-          const right = secretName(ts, node.right)
-          if (
-            (left !== undefined && SECRET.test(left)) ||
-            (right !== undefined && SECRET.test(right))
-          ) {
-            const line = tree.getLineAndCharacterOfPosition(node.getStart(tree)).line + 1
-            const reviewed = hasReview(lines, line)
-            findings.push(
-              diagnostic({
-                code: "NF-S002",
-                severity: reviewed ? "info" : secretComparisonSeverity(file),
-                file,
-                line,
-                message: reviewed
-                  ? "secret comparison is explicitly marked as reviewed"
-                  : "secret-like values must use a length check and timing-safe comparison",
-                evidence: [left ?? right ?? "secret comparison", ...reviewedEvidence(lines, line)],
-                ...(reviewed
-                  ? {}
-                  : {
-                      fix: {
-                        recipe: "security.timing-safe-equal",
-                        command: "nifra fix --code NF-S002",
-                      },
-                    }),
-                verify: "nifra check --lints-only",
-              }),
-            )
-          }
-        }
-        ts.forEachChild(node, visit)
+      for (const { left, right, line } of secretComparisons(ts, file, tree)) {
+        const reviewed = hasReview(lines, line)
+        findings.push(
+          diagnostic({
+            code: "NF-S002",
+            severity: reviewed ? "info" : secretComparisonSeverity(file),
+            file,
+            line,
+            message: reviewed
+              ? "secret comparison is explicitly marked as reviewed"
+              : "secret-like values must use a length check and timing-safe comparison",
+            evidence: [left ?? right ?? "secret comparison", ...reviewedEvidence(lines, line)],
+            ...(reviewed
+              ? {}
+              : {
+                  fix: {
+                    recipe: "security.timing-safe-equal",
+                    command: "nifra fix --code NF-S002",
+                  },
+                }),
+            verify: "nifra check --lints-only",
+          }),
+        )
       }
-      visit(tree)
     }
     return findings
   },
@@ -188,7 +283,9 @@ export const piiLogRule: CheckRule = {
   code: "NF-S003",
   title: "Sensitive value in log call",
   async scan(ctx) {
-    const ts = await importProjectTypeScript(ctx.root)
+    const loaded = await loadRuleTypeScript(ctx)
+    if (loaded.diagnostics !== undefined) return loaded.diagnostics
+    const ts = loaded.compiler
     if (ts === undefined) return didNotRun("NF-S003", "Sensitive-value-in-log scan")
     const findings: Diagnostic[] = []
     for (const file of ctx.project.source.files) {
@@ -232,11 +329,37 @@ export const piiLogRule: CheckRule = {
   },
 }
 
+/**
+ * A function's own name, or for an anonymous arrow/function expression the name it is bound to
+ * (`const requireAuth = async () => …`, `{ canEdit: () => … }`), which is how a gate is usually written.
+ */
+function functionName(ts: typeof TSApi, fn: TSApi.Node): string | undefined {
+  if (ts.isFunctionLike(fn) && fn.name !== undefined)
+    return ts.isIdentifier(fn.name) ? fn.name.text : undefined
+  let binding = fn.parent
+  while (
+    binding !== undefined &&
+    (ts.isParenthesizedExpression(binding) ||
+      ts.isAsExpression(binding) ||
+      ts.isSatisfiesExpression(binding))
+  )
+    binding = binding.parent
+  if (
+    binding !== undefined &&
+    (ts.isVariableDeclaration(binding) || ts.isPropertyAssignment(binding)) &&
+    ts.isIdentifier(binding.name)
+  )
+    return binding.name.text
+  return undefined
+}
+
 export const failOpenGateRule: CheckRule = {
   code: "NF-S001",
   title: "Fail-open gate",
   async scan(ctx) {
-    const ts = await importProjectTypeScript(ctx.root)
+    const loaded = await loadRuleTypeScript(ctx)
+    if (loaded.diagnostics !== undefined) return loaded.diagnostics
+    const ts = loaded.compiler
     if (ts === undefined) return didNotRun("NF-S001", "Fail-open gate scan")
     const findings: Diagnostic[] = []
     for (const file of ctx.project.source.files) {
@@ -247,10 +370,7 @@ export const failOpenGateRule: CheckRule = {
         if (ts.isCatchClause(node)) {
           let parent: TSApi.Node | undefined = node.parent
           while (parent !== undefined && !ts.isFunctionLike(parent)) parent = parent.parent
-          const name =
-            ts.isFunctionLike(parent) && parent.name && ts.isIdentifier(parent.name)
-              ? parent.name.text
-              : undefined
+          const name = parent === undefined ? undefined : functionName(ts, parent)
           // `can` only names a gate in camelCase (`canEdit`, `canAccess`) - matching it
           // case-insensitively swept in `canonicalize…`, `cancel…`, `candidate…`, none of them
           // authorization decisions. The other roots stay case-insensitive.
@@ -317,7 +437,9 @@ export const corsOriginPredicateRule: CheckRule = {
   code: "NF-S004",
   title: "CORS origin predicate ignores the origin",
   async scan(ctx) {
-    const ts = await importProjectTypeScript(ctx.root)
+    const loaded = await loadRuleTypeScript(ctx)
+    if (loaded.diagnostics !== undefined) return loaded.diagnostics
+    const ts = loaded.compiler
     if (ts === undefined) return didNotRun("NF-S004", "CORS origin predicate scan")
     const findings: Diagnostic[] = []
     for (const file of ctx.project.source.files) {
@@ -378,7 +500,9 @@ export const externalRedirectRule: CheckRule = {
   code: "NF-S005",
   title: "External redirect opt-out",
   async scan(ctx) {
-    const ts = await importProjectTypeScript(ctx.root)
+    const loaded = await loadRuleTypeScript(ctx)
+    if (loaded.diagnostics !== undefined) return loaded.diagnostics
+    const ts = loaded.compiler
     if (ts === undefined) return didNotRun("NF-S005", "External redirect opt-out scan")
     const findings: Diagnostic[] = []
     for (const file of ctx.project.source.files) {
@@ -435,7 +559,9 @@ export const assuranceEscapeHatchRule: CheckRule = {
   code: "NF-S006",
   title: "Security escape hatch enabled",
   async scan(ctx) {
-    const ts = await importProjectTypeScript(ctx.root)
+    const loaded = await loadRuleTypeScript(ctx)
+    if (loaded.diagnostics !== undefined) return loaded.diagnostics
+    const ts = loaded.compiler
     if (ts === undefined) return didNotRun("NF-S006", "Security escape hatch scan")
     const findings: Diagnostic[] = []
     for (const file of ctx.project.source.files) {
@@ -478,7 +604,9 @@ export const unprefixedSecureCookieRule: CheckRule = {
   code: "NF-S007",
   title: "Secure cookie without a __Host-/__Secure- prefix",
   async scan(ctx) {
-    const ts = await importProjectTypeScript(ctx.root)
+    const loaded = await loadRuleTypeScript(ctx)
+    if (loaded.diagnostics !== undefined) return loaded.diagnostics
+    const ts = loaded.compiler
     if (ts === undefined) return didNotRun("NF-S007", "Secure cookie prefix scan")
     const findings: Diagnostic[] = []
     for (const file of ctx.project.source.files) {

package/src/rules/typescript.ts

@@ -0,0 +1,77 @@
+import type { Diagnostic } from "../diagnostics.ts"
+import {
+  loadProjectTypeScript,
+  type TypeScriptApi,
+  type TypeScriptSession,
+  unsupportedTypeScriptDiagnostic,
+} from "../internal/typescript-import.ts"
+import type { RuleContext } from "./index.ts"
+
+interface RuleTypeScriptLoad {
+  readonly compiler: TypeScriptApi | undefined
+  readonly session: TypeScriptSession | undefined
+  readonly diagnostics: readonly Diagnostic[] | undefined
+}
+
+interface SessionCacheEntry {
+  readonly pending: ReturnType<typeof loadProjectTypeScript>
+  leases: number
+}
+
+const sessionCache = new WeakMap<RuleContext["sources"], SessionCacheEntry>()
+
+function cachedLoad(ctx: RuleContext): SessionCacheEntry {
+  const cached = sessionCache.get(ctx.sources)
+  if (cached !== undefined) return cached
+  const entry: SessionCacheEntry = {
+    pending: loadProjectTypeScript(ctx.root, undefined, ctx.sources),
+    leases: 0,
+  }
+  sessionCache.set(ctx.sources, entry)
+  return entry
+}
+
+/** Retain a direct rule-registry session until the whole registry run has completed. */
+export function retainRuleTypeScript(ctx: RuleContext): void {
+  const entry = cachedLoad(ctx)
+  entry.leases += 1
+}
+
+/** Release a direct rule-registry session and terminate its TypeScript 7 worker when unused. */
+export async function releaseRuleTypeScript(ctx: RuleContext): Promise<void> {
+  const entry = sessionCache.get(ctx.sources)
+  if (entry === undefined) return
+  entry.leases = Math.max(0, entry.leases - 1)
+  if (entry.leases !== 0) return
+  sessionCache.delete(ctx.sources)
+  try {
+    const loaded = await entry.pending
+    await loaded.session?.close()
+  } catch {
+    // The scanner that consumed the same pending load owns the diagnostic for load failures.
+  }
+}
+
+/** Keep every AST-backed rule on the same project compiler session. */
+export async function loadRuleTypeScript(ctx: RuleContext): Promise<RuleTypeScriptLoad> {
+  if (ctx.project.check.unsupportedTypeScriptVersion !== undefined) {
+    // The check-wide loader already supplied the single structured failure diagnostic.
+    return { compiler: undefined, session: undefined, diagnostics: [] }
+  }
+  if (ctx.typescriptSession !== undefined) {
+    return {
+      compiler: ctx.typescriptSession.compiler,
+      session: ctx.typescriptSession,
+      diagnostics: undefined,
+    }
+  }
+  const loaded = await cachedLoad(ctx).pending
+  if (loaded.unsupported !== undefined) {
+    return {
+      compiler: undefined,
+      session: undefined,
+      diagnostics: [unsupportedTypeScriptDiagnostic(loaded.unsupported.version)],
+    }
+  }
+  return { compiler: loaded.compiler, session: loaded.session, diagnostics: undefined }
+}