@nifrajs/cli 3.3.0 → 4.0.0

package/src/check.ts

@@ -17,7 +17,8 @@
  */
 
 import { existsSync, readFileSync } from "node:fs"
-import { dirname, isAbsolute, join } from "node:path"
+import { dirname, isAbsolute, join, relative } from "node:path"
+import { BACKEND_APP_FILE } from "./app-files.ts"
 import {
   type CheckAssuranceContext,
   type CheckConfig,
@@ -26,11 +27,13 @@ import {
   collectCheckDiagnostics,
   type RuleOverride,
 } from "./check-diagnostics.ts"
+import { checkContractsLock, DEFAULT_CONTRACTS_LOCK } from "./contracts.ts"
+import { type Diagnostic, normalizeSeverity, toSarifLog } from "./diagnostics.ts"
 import { createSourceFacts } from "./internal/source-facts.ts"
-import { importProjectTypeScript, type TypeScriptApi } from "./internal/typescript-import.ts"
+import { loadProjectTypeScript, type TypeScriptApi } from "./internal/typescript-import.ts"
 // Type-only: `pipeline-report.ts` imports this module's source scanners, so a value import here would
 // close a cycle. Doctor is what actually runs the collector (see the `pipeline` rule below).
-import type { ProjectFactsSeed } from "./project-facts.ts"
+import type { ContractCheckFacts, ProjectFactsSeed } from "./project-facts.ts"
 import { RULE_CODES } from "./rules/codes.ts"
 import { sourceIndex } from "./rules/index.ts"
 
@@ -48,6 +51,7 @@ export type {
 
 import {
   createProjectSqlImports,
+  isBrowserSource,
   type ModuleReader,
   type ModuleResolver,
   resolveServerOnlyChains,
@@ -59,6 +63,7 @@ import {
   scanResponseRoutes,
   scanServerManifestDrift,
   scanStaticRouteText,
+  scanStreamText,
   scanUntypedClient,
   type TransitiveServerImportFinding,
   walkSource,
@@ -66,7 +71,6 @@ import {
 
 export * from "./check-scan.ts"
 
-const ROUTE_FILE = /(^|\/)routes\//
 interface TypecheckResult {
   readonly ran: boolean
   readonly ok: boolean
@@ -101,6 +105,9 @@ async function typecheck(cwd: string, signal?: AbortSignal): Promise<TypecheckRe
   const tsconfig = join(cwd, "tsconfig.json")
   if (!(await Bun.file(tsconfig).exists()))
     return { ran: false, ok: true, note: "no tsconfig.json" }
+  // Routes import their generated `./+types` modules; bring them up to date before tsc reads them.
+  const { refreshRouteTypes } = await import("./route-types.ts")
+  refreshRouteTypes(cwd, () => {})
   const tscBin = resolveTscBin(cwd)
   if (tscBin === undefined) {
     return {
@@ -111,7 +118,7 @@ async function typecheck(cwd: string, signal?: AbortSignal): Promise<TypecheckRe
     }
   }
   if (signal?.aborted) return { ran: true, ok: false, cancelled: true, output: "cancelled" }
-  const proc = Bun.spawn(["bun", tscBin, "--noEmit", "-p", tsconfig], {
+  const proc = Bun.spawn([process.execPath, tscBin, "--noEmit", "-p", tsconfig], {
     cwd,
     stdout: "pipe",
     stderr: "pipe",
@@ -230,10 +237,30 @@ interface CheckCollectionOptions {
 
 interface ProjectScan {
   readonly facts: ProjectFactsSeed
-  readonly typecheck: TypecheckResult
-  readonly sqlCompiler: TypeScriptApi | undefined
-  readonly checkConfigError?: string
-  readonly checkConfigWarnings: readonly string[]
+}
+
+async function collectContractFacts(cwd: string): Promise<ContractCheckFacts> {
+  const hasBackend = existsSync(join(cwd, BACKEND_APP_FILE))
+  const hasLock = existsSync(join(cwd, DEFAULT_CONTRACTS_LOCK))
+  if (!hasBackend && !hasLock) return { present: false, vacuous: false, diagnostics: [] }
+  try {
+    const result = await checkContractsLock(cwd)
+    return {
+      present: result.present,
+      vacuous: result.vacuous,
+      diagnostics: result.diagnostics,
+    }
+  } catch (error) {
+    if (error instanceof Error && error.message === "contract source not configured") {
+      return { present: false, vacuous: false, diagnostics: [] }
+    }
+    return {
+      present: hasLock,
+      vacuous: false,
+      diagnostics: [],
+      error: error instanceof Error ? error.message : String(error),
+    }
+  }
 }
 
 /** Build the rule input from one source walk and the other check-wide scans. */
@@ -242,79 +269,111 @@ async function buildProjectScan(
   opts: Pick<CheckCollectionOptions, "lintsOnly" | "signal" | "loadTypeScript">,
 ): Promise<ProjectScan> {
   const fetches: SourceFinding[] = []
+  const streams: SourceFinding[] = []
   const staticRoutes: StaticRouteFinding[] = []
   const untypedClients: SourceFinding[] = []
   const removedImports: SourceFinding[] = []
   const serverImports: TransitiveServerImportFinding[] = []
   const responseRoutes: SourceFinding[] = []
   const interpolatedSql: SourceFinding[] = []
-  const routeModules: Array<{ rel: string; content: string }> = []
+  const browserModules: Array<{ rel: string; content: string }> = []
   const sourceFiles: Array<{ file: string; content: string }> = []
   const {
     config: checkConfig,
     error: checkConfigError,
     warnings: checkConfigWarnings,
   } = await loadCheckConfig(cwd)
-  const sqlCompiler = await (opts.loadTypeScript ?? (() => importProjectTypeScript(cwd)))()
-  const sourceFacts = sqlCompiler === undefined ? undefined : createSourceFacts(sqlCompiler)
-  const sqlImports = sqlCompiler === undefined ? undefined : createProjectSqlImports(cwd)
-
-  const [typecheckResult, _, doctor, manifestDrift] = await Promise.all([
+  const [typecheckResult, _, doctor, manifestDrift, contracts] = await Promise.all([
     opts.lintsOnly
       ? Promise.resolve<TypecheckResult>({ ran: false, ok: true, note: "lints-only mode" })
       : typecheck(cwd, opts.signal),
     walkSource(cwd, (rel, content) => {
       sourceFiles.push({ file: rel, content })
       fetches.push(...scanFetchText(rel, content, checkConfig.externalMounts))
-      staticRoutes.push(...scanStaticRouteText(rel, content, sourceFacts))
+      streams.push(...scanStreamText(rel, content, checkConfig.externalMounts))
       untypedClients.push(...scanUntypedClient(rel, content))
       removedImports.push(...scanRemovedImports(rel, content))
-      if (ROUTE_FILE.test(rel)) routeModules.push({ rel, content })
-      responseRoutes.push(...scanResponseRoutes(rel, content, sourceFacts))
-      if (sqlCompiler !== undefined)
-        interpolatedSql.push(...scanInterpolatedSql(rel, content, sqlCompiler, sqlImports))
+      if (isBrowserSource(rel)) browserModules.push({ rel, content })
     }),
     import("./doctor.ts").then((m) => m.collectDoctorResult(cwd)),
     scanServerManifestDrift(cwd),
+    collectContractFacts(cwd),
   ])
 
-  const resolveModule: ModuleResolver = (fromFile, specifier) => {
-    try {
-      const fromAbs = isAbsolute(fromFile) ? fromFile : join(cwd, fromFile)
-      return Bun.resolveSync(specifier, dirname(fromAbs))
-    } catch {
-      return undefined
+  // TypeScript 7's unstable API materializes source files through one project session. Build the
+  // source index first so every syntax-backed scanner (including the independent rule registry)
+  // shares that session instead of spawning one compiler process per rule.
+  const source = sourceIndex(sourceFiles)
+  const loadedTypeScript = await loadProjectTypeScript(cwd, opts.loadTypeScript, source)
+  try {
+    const sqlCompiler = loadedTypeScript.compiler
+    const sourceFacts = sqlCompiler === undefined ? undefined : createSourceFacts(sqlCompiler)
+    const sqlImports = sqlCompiler === undefined ? undefined : createProjectSqlImports(cwd)
+    for (const { file, content } of sourceFiles) {
+      staticRoutes.push(...scanStaticRouteText(file, content, sourceFacts))
+      responseRoutes.push(...scanResponseRoutes(file, content, sourceFacts))
+      if (sqlCompiler !== undefined)
+        interpolatedSql.push(...scanInterpolatedSql(file, content, sqlCompiler, sqlImports))
     }
-  }
-  const readModule: ModuleReader = (absPath) => {
-    try {
-      return readFileSync(absPath, "utf8")
-    } catch {
-      return undefined
+
+    // Resolved modules stay project-relative, as the scanned files are: the zone of a path is read
+    // from its folders, and a checkout under a folder named `backend/` must not make it all backend.
+    const resolveModule: ModuleResolver = (fromFile, specifier) => {
+      try {
+        const fromAbs = isAbsolute(fromFile) ? fromFile : join(cwd, fromFile)
+        const resolved = Bun.resolveSync(specifier, dirname(fromAbs))
+        const rel = relative(cwd, resolved).replaceAll("\\", "/")
+        return rel.startsWith("../") || isAbsolute(rel) ? resolved : rel
+      } catch {
+        return undefined
+      }
+    }
+    const readModule: ModuleReader = (path) => {
+      try {
+        return readFileSync(isAbsolute(path) ? path : join(cwd, path), "utf8")
+      } catch {
+        return undefined
+      }
+    }
+    for (const { rel, content } of browserModules) {
+      serverImports.push(
+        ...resolveServerOnlyChains(rel, content, resolveModule, readModule, sourceFacts),
+      )
     }
-  }
-  for (const { rel, content } of routeModules) {
-    serverImports.push(
-      ...resolveServerOnlyChains(rel, content, resolveModule, readModule, sourceFacts),
-    )
-  }
 
-  const source = sourceIndex(sourceFiles)
-  const facts: ProjectFactsSeed = {
-    source,
-    routes: staticRoutes,
-    importGraph: serverImports,
-    packages: { doctor, manifestDrift },
-    ...(doctor.pipeline === undefined ? {} : { pipeline: doctor.pipeline }),
-    policies: { checkConfig, rulePacks: [] },
-    sourceFindings: { fetches, untypedClients, removedImports, responseRoutes, interpolatedSql },
-  }
-  return {
-    facts,
-    typecheck: typecheckResult,
-    sqlCompiler,
-    ...(checkConfigError === undefined ? {} : { checkConfigError }),
-    checkConfigWarnings,
+    const facts: ProjectFactsSeed = {
+      source,
+      routes: staticRoutes,
+      importGraph: serverImports,
+      packages: { doctor, manifestDrift },
+      ...(doctor.pipeline === undefined ? {} : { pipeline: doctor.pipeline }),
+      policies: { checkConfig, rulePacks: [] },
+      check: {
+        typecheck: typecheckResult,
+        sqlCompilerAvailable: sqlCompiler !== undefined,
+        ...(loadedTypeScript.unsupported === undefined
+          ? {}
+          : { unsupportedTypeScriptVersion: loadedTypeScript.unsupported.version }),
+        ...(loadedTypeScript.session === undefined
+          ? {}
+          : { typescriptSession: loadedTypeScript.session }),
+        ...(checkConfigError === undefined ? {} : { checkConfigError }),
+        checkConfigWarnings,
+        contracts,
+      },
+      sourceFindings: {
+        fetches,
+        streams,
+        untypedClients,
+        removedImports,
+        responseRoutes,
+        interpolatedSql,
+      },
+    }
+    return { facts }
+  } catch (error) {
+    await loadedTypeScript.session?.close()
+    throw error
   }
 }
 
@@ -326,7 +385,11 @@ export async function collectCheckResult(
   opts: CheckCollectionOptions = {},
 ): Promise<CheckResult> {
   const scan = await buildProjectScan(cwd, opts)
-  return collectCheckDiagnostics(cwd, scan, opts)
+  try {
+    return await collectCheckDiagnostics(cwd, scan, opts)
+  } finally {
+    await scan.facts.check.typescriptSession?.close()
+  }
 }
 
 /** The named rule sections of the human report, in print order. A rule absent from this list is NOT
@@ -334,9 +397,9 @@ export async function collectCheckResult(
  * its rule code, so a finding that can flip the exit code is never invisible in the default output. */
 const REPORT_SECTIONS = [
   ["typecheck", "typecheck"],
-  ["typed-client", "hand-rolled fetch() to your own API"],
+  ["typed-client", "hand-rolled fetch()/EventSource/WebSocket to your own API"],
   ["untyped-client", 'client("…") missing its <typeof app> type argument'],
-  ["server-only-import", "server-only import in a route module"],
+  ["server-only-import", "backend code in browser code"],
   ["interpolated-sql", "SQL built by interpolating a value into the statement"],
   ["response-route", "route returns a raw Response (typed client → data: never)"],
   ["undeclared-dependency", "undeclared dependency in package.json"],
@@ -380,6 +443,14 @@ export function renderCheckReport(result: CheckResult): string[] {
       `• intentional external mounts (not typed-client checked): ${result.externalMounts.join(", ")}`,
     )
   }
+  for (const gap of result.knownGaps ?? []) {
+    lines.push(`• known gap, not capability-analyzed: ${gap.path} - ${gap.reason}`)
+  }
+  const deduplicated = result.identityPreflight?.deduplicated ?? []
+  if (deduplicated.length > 0) {
+    const packages = deduplicated.map((finding) => finding.package).join(", ")
+    lines.push(`• identity-sensitive duplicate installs handled by singleCopy: ${packages}`)
+  }
   if (result.ruleOverrides !== undefined) {
     const active = Object.entries(result.ruleOverrides).map(([rule, override]) => {
       const parts: string[] = []
@@ -468,12 +539,29 @@ export async function runCheck(
     readonly json?: boolean
     readonly lintsOnly?: boolean
     readonly structured?: boolean
+    readonly sarif?: boolean
   } = {},
 ): Promise<boolean> {
   // The check view over the one project verification: the same collector `assure` and `levels` read.
   const { collectProjectVerification } = await import("./verification.ts")
   const verification = await collectProjectVerification(cwd, { lintsOnly: opts.lintsOnly ?? false })
   const result = await verification.check()
+  if (opts.sarif) {
+    const diagnostics: readonly Diagnostic[] =
+      result.structuredDiagnostics ??
+      result.diagnostics.map((value) => ({
+        code: value.code ?? value.rule,
+        severity: normalizeSeverity(value.severity),
+        message: value.message,
+        ...(value.file === undefined ? {} : { file: value.file }),
+        ...(value.line === undefined ? {} : { line: value.line }),
+        ...(value.evidence === undefined ? {} : { evidence: value.evidence }),
+        ...(value.fix === undefined ? {} : { fix: { recipe: value.fix } }),
+        ...(value.verify === undefined ? {} : { verify: value.verify }),
+      }))
+    console.log(JSON.stringify(toSarifLog(diagnostics), null, 2))
+    return result.ok
+  }
   if (opts.json) {
     console.log(
       JSON.stringify(
@@ -489,7 +577,7 @@ export async function runCheck(
 
   console.log(renderCheckReport(result).join("\n"))
   // Discoverability nudge: a project with no `.mcp.json` hasn't wired its nifra MCP for coding agents.
-  // `nifra init-agents` writes it (+ .cursor/mcp.json + a CLAUDE.md preamble), no-clobber. A non-fatal
+  // `nifra init-agents` writes it (+ .cursor/mcp.json + each agent's pointer to AGENTS.md), no-clobber. A non-fatal
   // one-line tip in the human report only (the `--json` path returns above, unaffected).
   if (!existsSync(join(cwd, ".mcp.json"))) {
     console.log(