@nifrajs/cli 3.1.0 → 3.2.0

package/src/openapi-tool.ts

@@ -1,6 +1,7 @@
 import { basename } from "node:path"
 import { toOpenAPI } from "@nifrajs/schema/openapi"
 import type { LoadedApp } from "./load.ts"
+import { type InferredOpenAPIResponses, inferOpenAPIResponses } from "./openapi-types.ts"
 
 export type OpenApiFormat = "json" | "yaml"
 
@@ -52,10 +53,19 @@ function toYaml(value: unknown, depth = 0): string {
  * the trimmed document still references those names, and recomputing the exact reachable subset isn't
  * worth the risk of emitting a `$ref` with no target.
  */
-export function renderOpenApi(app: LoadedApp, format: OpenApiFormat, pathPrefix?: string): string {
+function renderOpenApiWithResponses(
+  app: LoadedApp,
+  format: OpenApiFormat,
+  pathPrefix: string | undefined,
+  inferredResponses: InferredOpenAPIResponses | undefined,
+): string {
   const title = `${basename(app.cwd)} API`
   const input = hasRoutesMethod(app.backend) ? app.backend : {}
-  const generated = toOpenAPI(input, { title, version: "1.0.0" })
+  const generated = toOpenAPI(input, {
+    title,
+    version: "1.0.0",
+    ...(inferredResponses === undefined ? {} : { inferredResponses }),
+  })
   // Narrow to operations under the prefix, rebuilding the doc (its `paths` is readonly). `components`
   // stays - see the doc comment for why the schema set isn't recomputed.
   const document =
@@ -69,3 +79,23 @@ export function renderOpenApi(app: LoadedApp, format: OpenApiFormat, pathPrefix?
       : generated
   return format === "yaml" ? toYaml(document) : JSON.stringify(document, null, 2)
 }
+
+/** Render the current runtime route table without loading the TypeScript compiler. */
+export function renderOpenApi(app: LoadedApp, format: OpenApiFormat, pathPrefix?: string): string {
+  return renderOpenApiWithResponses(app, format, pathPrefix, undefined)
+}
+
+/**
+ * Render OpenAPI with optional build-time response-type inference. The TypeScript compiler is loaded
+ * only in this explicit CLI path; the server and schema runtime packages remain compiler-free.
+ */
+export async function renderOpenApiWithTypes(
+  app: LoadedApp,
+  format: OpenApiFormat,
+  pathPrefix?: string,
+): Promise<string> {
+  const inferred = await inferOpenAPIResponses(app.cwd)
+  for (const warning of inferred.warnings)
+    console.warn(`[nifra] OpenAPI type inference: ${warning}`)
+  return renderOpenApiWithResponses(app, format, pathPrefix, inferred.responses)
+}

package/src/openapi-types.ts

@@ -0,0 +1,261 @@
+/**
+ * Build-time response-type reflection for OpenAPI.
+ *
+ * This module is CLI-only. It loads the project's TypeScript compiler on demand, inspects the
+ * exported `backend` type, and returns inert JSON Schema metadata. It never imports or executes the
+ * generated schema at request time, and unsupported/opaque types are omitted rather than guessed.
+ */
+
+import { existsSync } from "node:fs"
+import { mkdtemp, rm, writeFile } from "node:fs/promises"
+import { tmpdir } from "node:os"
+import { dirname, join, resolve } from "node:path"
+import type { JsonSchema } from "@nifrajs/core/reflection"
+import type * as TSApi from "typescript"
+import { importProjectTypeScript, type TypeScriptApi } from "./internal/typescript-import.ts"
+
+export interface InferredOpenAPIResponse {
+  readonly description?: string
+  readonly schema?: JsonSchema
+  readonly contentType?: string
+}
+
+export type InferredOpenAPIResponses = Readonly<
+  Record<string, Readonly<Record<string, InferredOpenAPIResponse>>>
+>
+
+export interface OpenAPITypeInferenceResult {
+  readonly responses: InferredOpenAPIResponses
+  readonly warnings: readonly string[]
+}
+
+type Type = TSApi.Type
+type TypeChecker = TSApi.TypeChecker
+
+const hasFlag = (type: Type, flag: number): boolean => (type.flags & flag) !== 0
+
+function schemaForType(
+  ts: TypeScriptApi,
+  checker: TypeChecker,
+  input: Type,
+  seen: Set<Type>,
+  depth: number,
+): JsonSchema | undefined {
+  if (depth > 20 || seen.has(input)) return undefined
+  // Keep `null` in unions: OpenAPI distinguishes `string | null` from `string`. Undefined members
+  // are omitted below because JSON has no undefined value; optional object properties are represented
+  // by the property's optional symbol flag instead.
+  const type = input
+  if (hasFlag(type, ts.TypeFlags.Any) || hasFlag(type, ts.TypeFlags.Unknown)) return undefined
+  if (hasFlag(type, ts.TypeFlags.Never)) return undefined
+  if (hasFlag(type, ts.TypeFlags.Undefined) || hasFlag(type, ts.TypeFlags.Void)) return undefined
+  if (hasFlag(type, ts.TypeFlags.StringLiteral)) {
+    return { const: (type as TSApi.StringLiteralType).value }
+  }
+  if (hasFlag(type, ts.TypeFlags.NumberLiteral)) {
+    return { const: (type as TSApi.NumberLiteralType).value }
+  }
+  if (hasFlag(type, ts.TypeFlags.BooleanLiteral)) {
+    return { const: checker.typeToString(type) === "true" }
+  }
+  if (hasFlag(type, ts.TypeFlags.StringLike)) return { type: "string" }
+  if (hasFlag(type, ts.TypeFlags.NumberLike)) return { type: "number" }
+  if (hasFlag(type, ts.TypeFlags.BooleanLike)) return { type: "boolean" }
+  if (hasFlag(type, ts.TypeFlags.BigIntLike)) return { type: "integer" }
+  if (hasFlag(type, ts.TypeFlags.Null)) return { type: "null" }
+
+  if (type.isUnion()) {
+    const members = type.types
+      .map((member) => schemaForType(ts, checker, member, seen, depth + 1))
+      .filter((schema): schema is JsonSchema => schema !== undefined)
+    if (members.length === 0) return undefined
+    if (members.length === 1) return members[0]
+    return { anyOf: members }
+  }
+
+  if (checker.isTupleType(type)) {
+    const elements = checker
+      .getTypeArguments(type as TSApi.TypeReference)
+      .map((member) => schemaForType(ts, checker, member, seen, depth + 1))
+      .filter((schema): schema is JsonSchema => schema !== undefined)
+    return elements.length === 0 ? undefined : { type: "array", prefixItems: elements }
+  }
+  if (checker.isArrayType(type)) {
+    const [element] = checker.getTypeArguments(type as TSApi.TypeReference)
+    const items =
+      element === undefined ? undefined : schemaForType(ts, checker, element, seen, depth + 1)
+    return items === undefined ? { type: "array" } : { type: "array", items }
+  }
+
+  if (type.symbol?.name === "Date") return { type: "string", format: "date-time" }
+  if ((type.flags & ts.TypeFlags.Object) === 0) return undefined
+
+  seen.add(type)
+  try {
+    const properties: Record<string, JsonSchema> = {}
+    const required: string[] = []
+    for (const property of checker.getPropertiesOfType(type)) {
+      const declaration = property.valueDeclaration ?? property.declarations?.[0]
+      if (declaration === undefined) continue
+      const propertyType = checker.getTypeOfSymbolAtLocation(property, declaration)
+      // Methods are implementation details, not JSON fields. Other unsupported property types make
+      // the whole response opaque instead of emitting a partial schema that could falsely promise a
+      // contract to generated clients.
+      if (checker.getSignaturesOfType(propertyType, ts.SignatureKind.Call).length > 0) continue
+      const propertySchema = schemaForType(ts, checker, propertyType, seen, depth + 1)
+      if (propertySchema === undefined) return undefined
+      properties[property.name] = propertySchema
+      if ((property.flags & ts.SymbolFlags.Optional) === 0) required.push(property.name)
+    }
+    if (Object.keys(properties).length === 0) return { type: "object" }
+    return {
+      type: "object",
+      properties,
+      ...(required.length > 0 ? { required } : {}),
+    }
+  } finally {
+    seen.delete(type)
+  }
+}
+
+function symbolNamed(
+  checker: TypeChecker,
+  source: TSApi.SourceFile,
+  name: string,
+  flags: number,
+): TSApi.Symbol | undefined {
+  return checker.getSymbolsInScope(source, flags).find((symbol) => symbol.name === name)
+}
+
+function propertyType(checker: TypeChecker, type: Type, name: string): Type | undefined {
+  const property = type.getProperty(name)
+  if (property === undefined) return undefined
+  const declaration =
+    property.valueDeclaration ?? property.declarations?.[0] ?? type.symbol?.valueDeclaration
+  return declaration === undefined
+    ? checker.getDeclaredTypeOfSymbol(property)
+    : checker.getTypeOfSymbolAtLocation(property, declaration)
+}
+
+function responseEntries(
+  ts: TypeScriptApi,
+  checker: TypeChecker,
+  location: TSApi.Node,
+  responseMap: Type,
+  warnings: string[],
+): Record<string, InferredOpenAPIResponse> {
+  const output: Record<string, InferredOpenAPIResponse> = {}
+  for (const property of responseMap.getProperties()) {
+    if (!/^[1-5][0-9]{2}$/.test(property.name)) continue
+    const bodyType = checker.getTypeOfSymbolAtLocation(property, location)
+    const schema = schemaForType(ts, checker, bodyType, new Set(), 0)
+    if (schema === undefined) {
+      const bodylessStatus =
+        property.name === "204" || property.name === "205" || property.name === "304"
+      const bodylessType =
+        hasFlag(bodyType, ts.TypeFlags.Undefined) || hasFlag(bodyType, ts.TypeFlags.Void)
+      if (bodylessStatus && bodylessType) {
+        output[property.name] = {}
+        continue
+      }
+      warnings.push(
+        `response ${property.name} has an unsupported or opaque TypeScript body (${checker.typeToString(bodyType)})`,
+      )
+      continue
+    }
+    output[property.name] = { schema }
+  }
+  return output
+}
+
+/** Infer response schemas from `<root>/backend.ts` without affecting runtime application loading. */
+export async function inferOpenAPIResponses(root: string): Promise<OpenAPITypeInferenceResult> {
+  const warnings: string[] = []
+  const backendPath = resolve(root, "backend.ts")
+  if (!existsSync(backendPath)) return { responses: {}, warnings }
+
+  const ts = await importProjectTypeScript(root)
+  if (ts === undefined) {
+    warnings.push("TypeScript is not installed; response inference was skipped")
+    return { responses: {}, warnings }
+  }
+
+  const temp = await mkdtemp(join(tmpdir(), "nifra-openapi-"))
+  const probePath = join(temp, "probe.ts")
+  const probe = [
+    'import type { Server as __NifraServer } from "@nifrajs/core/server"',
+    `import { backend as __nifra_backend } from ${JSON.stringify(backendPath)}`,
+    "type __NifraRegistry = typeof __nifra_backend extends __NifraServer<infer R, any, any> ? R : never",
+    "declare const __nifra_registry: __NifraRegistry",
+  ].join("\n")
+
+  try {
+    await writeFile(probePath, probe, "utf8")
+    const configPath = ts.findConfigFile(root, ts.sys.fileExists, "tsconfig.json")
+    let options: TSApi.CompilerOptions = {
+      noEmit: true,
+      skipLibCheck: true,
+      moduleResolution: ts.ModuleResolutionKind.Bundler,
+    }
+    let fileNames = [backendPath]
+    if (configPath !== undefined) {
+      const config = ts.readConfigFile(configPath, ts.sys.readFile)
+      if (config.error) {
+        warnings.push(
+          `could not read tsconfig.json: ${ts.flattenDiagnosticMessageText(config.error.messageText, " ")}`,
+        )
+      } else {
+        const parsed = ts.parseJsonConfigFileContent(config.config, ts.sys, dirname(configPath))
+        options = { ...parsed.options, noEmit: true, skipLibCheck: true }
+        fileNames = parsed.fileNames.length > 0 ? parsed.fileNames : fileNames
+      }
+    }
+    const host = ts.createCompilerHost(options, true)
+    const program = ts.createProgram(
+      [...new Set([...fileNames, backendPath, probePath])],
+      options,
+      host,
+    )
+    const source = program.getSourceFile(probePath)
+    if (source === undefined) {
+      warnings.push("could not create the TypeScript response-inference probe")
+      return { responses: {}, warnings }
+    }
+    const checker = program.getTypeChecker()
+    const registrySymbol = symbolNamed(
+      checker,
+      source,
+      "__nifra_registry",
+      ts.SymbolFlags.BlockScopedVariable,
+    )
+    if (registrySymbol === undefined) {
+      warnings.push("backend does not expose a typed Nifra server registry")
+      return { responses: {}, warnings }
+    }
+    const registry = checker.getTypeOfSymbolAtLocation(registrySymbol, source)
+    const responses: Record<string, Record<string, InferredOpenAPIResponse>> = {}
+    for (const pathSymbol of registry.getProperties()) {
+      const routePath = pathSymbol.name
+      const methods = checker.getTypeOfSymbolAtLocation(pathSymbol, source)
+      for (const methodSymbol of methods.getProperties()) {
+        if (methodSymbol.name === "WS") continue
+        const info = checker.getTypeOfSymbolAtLocation(methodSymbol, source)
+        const responseType = propertyType(checker, info, "responses")
+        if (responseType === undefined) continue
+        const routeResponses = responseEntries(
+          ts,
+          checker,
+          source,
+          checker.getNonNullableType(responseType),
+          warnings,
+        )
+        if (Object.keys(routeResponses).length > 0) {
+          responses[`${methodSymbol.name.toUpperCase()} ${routePath}`] = routeResponses
+        }
+      }
+    }
+    return { responses, warnings }
+  } finally {
+    await rm(temp, { recursive: true, force: true })
+  }
+}

package/src/port.ts

@@ -312,10 +312,11 @@ async function walkPortSource(
   cwd: string,
   visit: (rel: string, content: string) => void,
 ): Promise<void> {
-  for await (const rel of new Glob("**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}").scan({
+  for await (const rawRel of new Glob("**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}").scan({
     cwd,
     dot: false,
   })) {
+    const rel = rawRel.replaceAll("\\", "/")
     if (IGNORED.test(rel)) continue
     visit(rel, await Bun.file(join(cwd, rel)).text())
   }

package/src/project-facts.ts

@@ -1,13 +1,11 @@
 import type { CapabilityProjectReport } from "./capabilities-tool.ts"
+import type { CheckAssuranceContext, CheckConfig, CheckDiagnostic } from "./check-diagnostics.ts"
 import type {
-  CheckAssuranceContext,
-  CheckConfig,
-  CheckDiagnostic,
   ManifestDriftFinding,
   SourceFinding,
   StaticRouteFinding,
   TransitiveServerImportFinding,
-} from "./check.ts"
+} from "./check-scan.ts"
 import type { DoctorResult } from "./doctor.ts"
 import type { PipelineReport } from "./pipeline-report.ts"
 import type { RulePack, SourceIndex } from "./rules/index.ts"

package/src/release-verification.ts

@@ -8,8 +8,14 @@
 import { mkdtempSync, readFileSync, realpathSync, rmSync } from "node:fs"
 import { tmpdir } from "node:os"
 import { dirname, join, relative, resolve, sep } from "node:path"
-
-export type ReleaseVerificationMode = "default" | "release"
+import {
+  omittedVerificationGateIds,
+  type VerificationGateSpec,
+  type VerificationPlanMode,
+  verificationPlan,
+} from "./verification-plan.ts"
+
+export type ReleaseVerificationMode = VerificationPlanMode
 export type ReleaseGateStatus = "pass" | "fail" | "skipped"
 
 export interface ReleaseGateResult {
@@ -25,6 +31,8 @@ export interface ReleaseVerificationResult {
   readonly ok: boolean
   readonly mode: ReleaseVerificationMode
   readonly gates: readonly ReleaseGateResult[]
+  /** Release gates intentionally absent from the selected shorter plan. */
+  readonly omittedReleaseGateIds: readonly string[]
 }
 
 export interface ReleaseCommandResult {
@@ -44,164 +52,6 @@ export interface ReleaseVerificationOptions {
   readonly runCommand?: (spec: ReleaseCommandSpec) => Promise<ReleaseCommandResult>
 }
 
-interface ReleaseGateSpec {
-  readonly id: string
-  readonly commands: readonly (readonly string[])[]
-  readonly remediation: string
-}
-
-const DEFAULT_GATES: readonly ReleaseGateSpec[] = [
-  {
-    id: "lint",
-    commands: [["run", "lint"]],
-    remediation: "Run `bun run lint` and fix the reported lint findings.",
-  },
-  {
-    id: "typecheck",
-    commands: [["run", "typecheck"]],
-    remediation: "Run `bun run typecheck` and fix the reported TypeScript errors.",
-  },
-  {
-    id: "tests",
-    commands: [["run", "test"]],
-    remediation: "Run `bun run test` and fix the first failing test.",
-  },
-  {
-    id: "docs",
-    commands: [["run", "check:docs"]],
-    remediation: "Run `bun run check:docs` and update the failing documentation example.",
-  },
-  {
-    id: "api-corpus",
-    commands: [["run", "check:api"]],
-    remediation: "Run `bun run gen:api` and review the generated API reference.",
-  },
-  {
-    id: "cards-corpus",
-    commands: [["run", "check:cards"]],
-    remediation: "Run `bun run gen:cards` and review the generated package cards.",
-  },
-  {
-    id: "node-outcome-corpus",
-    commands: [["run", "check:node-outcome"]],
-    remediation: "Run `bun run gen:node-outcome` and review the generated Node outcome contract.",
-  },
-  {
-    id: "sitemap",
-    commands: [["run", "check:sitemap"]],
-    remediation: "Run `bun run gen:sitemap` and review the generated sitemap.",
-  },
-  {
-    id: "public-boundary",
-    commands: [["run", "check:public-boundary"]],
-    remediation:
-      "Run `bun run check:public-boundary` and remove the reported public-boundary violation.",
-  },
-  {
-    id: "size",
-    commands: [["run", "check:size"]],
-    remediation:
-      "Run `bun run check:size` and either reduce the bundle or update the reviewed budget.",
-  },
-  // Appended, not inserted: RELEASE_GATES below composes this list BY INDEX
-  // (`slice(0, 3)`, `[3]`), so a gate added in the middle would silently re-point those.
-  {
-    id: "changesets",
-    commands: [["run", "check:changesets"]],
-    remediation:
-      "Run `bun run changeset` and name every package whose source changed, so the release documents it.",
-  },
-]
-
-const RELEASE_GATES: readonly ReleaseGateSpec[] = [
-  {
-    id: "build",
-    commands: [["run", "build"]],
-    remediation: "Run `bun run build` and fix the first package build failure.",
-  },
-  ...DEFAULT_GATES.slice(0, 3),
-  {
-    id: "coverage",
-    commands: [
-      ["run", "test:coverage"],
-      ["run", "check:coverage"],
-    ],
-    remediation:
-      "Run `bun run test:coverage` first, then `bun run check:coverage`, and fix the reported coverage regression.",
-  },
-  {
-    id: "corpus",
-    commands: [["run", "check:corpus"]],
-    remediation:
-      "Run `bun run gen:llms`, `bun run gen:api`, and `bun run gen:cards`, then rerun the corpus gate.",
-  },
-  DEFAULT_GATES[3] as ReleaseGateSpec,
-  {
-    id: "public-boundary",
-    commands: [["run", "check:public-boundary"]],
-    remediation:
-      "Run `bun run check:public-boundary` and remove the reported public-boundary violation.",
-  },
-  {
-    id: "size",
-    commands: [["run", "check:size"]],
-    remediation:
-      "Run `bun run check:size` and either reduce the bundle or update the reviewed budget.",
-  },
-  {
-    id: "core-performance",
-    commands: [["run", "check:core-performance"]],
-    remediation:
-      "Run `bun run check:core-performance` and investigate the measured performance regression.",
-  },
-  {
-    id: "publish",
-    commands: [["run", "check:publish"]],
-    remediation:
-      "Run `bun run check:publish` and fix the publish-consumer metadata or type-surface failure.",
-  },
-  {
-    id: "consumer",
-    commands: [["run", "check:consumers"]],
-    remediation: "Run `bun run check:consumers` and fix the isolated consumer failure.",
-  },
-  {
-    id: "cold-start",
-    commands: [["run", "check:cold-start"]],
-    remediation:
-      "Run `bun run check:cold-start` and fix the fresh scaffold install or build failure.",
-  },
-  {
-    id: "cross-runtime-deno",
-    commands: [
-      ["run", "test:deno"],
-      ["run", "check:deno-tarball"],
-    ],
-    remediation:
-      "Run `bun run test:deno` and `bun run check:deno-tarball`, then fix the first Deno compatibility failure.",
-  },
-  {
-    id: "cross-runtime-node",
-    commands: [["run", "test:node"]],
-    remediation: "Run `bun run test:node` and fix the Node runtime adapter failure.",
-  },
-  {
-    id: "pipeline-parity",
-    commands: [["run", "check:pipeline-parity"]],
-    remediation:
-      "Run `bun run check:pipeline-parity` and fix the development and production manifest drift.",
-  },
-  // Last in release mode on purpose: this is the gate on what the release SAYS, and it is the only
-  // one whose failure is invisible afterwards - a shipped version cannot grow the changelog line it
-  // never had.
-  {
-    id: "changesets",
-    commands: [["run", "check:changesets"]],
-    remediation:
-      "Run `bun run changeset` and name every package whose source changed, so the release documents it.",
-  },
-]
-
 const runBunCommand = async (spec: ReleaseCommandSpec): Promise<ReleaseCommandResult> => {
   const child = Bun.spawn([process.execPath, ...spec.args], {
     cwd: spec.cwd,
@@ -278,14 +128,14 @@ export async function resolveVerificationRoot(start: string): Promise<string> {
   }
 }
 
-const gatePlan = (mode: ReleaseVerificationMode): readonly ReleaseGateSpec[] =>
-  mode === "release" ? RELEASE_GATES : DEFAULT_GATES
+const gatePlan = (mode: ReleaseVerificationMode): readonly VerificationGateSpec[] =>
+  verificationPlan(mode)
 
 const commandLabel = (args: readonly string[]): string => `bun ${args.join(" ")}`
 
 const runGate = async (
   root: string,
-  gate: ReleaseGateSpec,
+  gate: VerificationGateSpec,
   runCommand: (spec: ReleaseCommandSpec) => Promise<ReleaseCommandResult>,
   fixtureRoot: string,
 ): Promise<ReleaseGateResult> => {
@@ -322,7 +172,7 @@ const runGate = async (
   }
 }
 
-const skippedGate = (gate: ReleaseGateSpec, failedId: string): ReleaseGateResult => ({
+const skippedGate = (gate: VerificationGateSpec, failedId: string): ReleaseGateResult => ({
   id: gate.id,
   status: "skipped",
   commands: gate.commands.map(commandLabel),
@@ -358,6 +208,7 @@ export async function collectReleaseVerification(
     ok: gates.every((gate) => gate.status === "pass"),
     mode,
     gates,
+    omittedReleaseGateIds: omittedVerificationGateIds(mode),
   }
 }
 
@@ -369,6 +220,13 @@ export function renderReleaseVerification(result: ReleaseVerificationResult): st
     if (gate.message !== undefined) lines.push(`  ${gate.message}`)
     if (gate.status !== "pass") lines.push(`  fix: ${gate.remediation}`)
   }
+  if (result.omittedReleaseGateIds.length > 0) {
+    lines.push(
+      "",
+      `note: default verification omits release gates: ${result.omittedReleaseGateIds.join(", ")}`,
+      "      run `bun run check:release` for the full release gate.",
+    )
+  }
   lines.push("", result.ok ? "✓ verification passed" : "✗ verification failed")
   return lines.join("\n")
 }

package/src/rules/codes.ts

@@ -20,6 +20,10 @@ export const RULE_CODES = Object.freeze({
   "NF-C017": "Rule pack validation",
   "NF-C018": "Reserved client segment check",
   "NF-C019": "Duplicate route registration check",
+  "NF-C020": "Island enhancer cleanup check",
+  "NF-C021": "nano binding cleanup check",
+  "NF-C022": "nano bindList key check",
+  "NF-C023": "nano computed deps check",
   "NF-D001": "Doctor check",
   "NF-A001": "Assurance bundle check",
   "NF-H001": "Hydration mismatch",