@nifrajs/cli 2.2.0 → 2.4.0

package/src/upgrade.ts

@@ -1,20 +1,20 @@
 /**
- * `nifra upgrade <version>` — an executable, per-release upgrade runner. Framework and shared-package
+ * `nifra upgrade <version>` - an executable, per-release upgrade runner. Framework and shared-package
  * bumps otherwise spread the same mechanical edits across every consuming app by hand; a recipe turns
  * them into `detect → transform → verify`:
  *
- *   1. **pin sweep** — set every matching dependency to the target version across the workspace's
+ *   1. **pin sweep** - set every matching dependency to the target version across the workspace's
  *      package.json files, preserving the caret/tilde/exact style and skipping `workspace:`/`link:` specs.
- *   2. **dependency moves** — replace removed packages with their supported successor without
+ *   2. **dependency moves** - replace removed packages with their supported successor without
  *      reserializing package.json or leaving duplicate dependency keys.
- *   3. **import moves** — rewrite exact import specifiers to their updated module paths.
- *   4. **verify** — reuse the existing `nifra check` gate; no new verification surface.
+ *   3. **import moves** - rewrite exact import specifiers to their updated module paths.
+ *   4. **verify** - reuse the existing `nifra check` gate; no new verification surface.
  *
  * Dry-run by default (prints the plan, writes nothing); `--write` applies. Fail-closed on an unknown
  * target version or a missing package.json, and deterministic (same repo + target → same edits).
  *
  * Deliberately NOT a codemod engine: transforms are string/specifier-level only. Structural (AST)
- * transforms are a future addition — a recipe that needs one is the signal to add the engine, not before.
+ * transforms are a future addition - a recipe that needs one is the signal to add the engine, not before.
  */
 
 import { readFileSync, writeFileSync } from "node:fs"
@@ -33,6 +33,8 @@ export interface UpgradeOptions {
   readonly list?: boolean
   /** After `--write`, run `nifra check` and fail the command if it fails. Default true. */
   readonly verify?: boolean
+  /** Permit a target BELOW the installed version (a rollback). Default false → fail-closed. */
+  readonly allowDowngrade?: boolean
 }
 
 export interface PinChange {
@@ -65,6 +67,8 @@ export interface UpgradePlan {
   readonly pins: readonly PinChange[]
   readonly dependencyMoves: readonly DependencyMoveChange[]
   readonly importMoves: readonly ImportChange[]
+  /** Pins refused because the target is BELOW the installed version (a rollback). Empty when allowed. */
+  readonly downgrades: readonly PinChange[]
   readonly notes: readonly string[]
 }
 
@@ -75,10 +79,10 @@ const DEP_FIELDS = [
   "optionalDependencies",
 ] as const
 
-// Only a bare semver spec is rewritten. Anything else — workspace:*, link:/file:, npm: aliases, git
-// urls, "*", "latest", or a multi-part range — is intentionally left untouched (skipped, not guessed).
+// Only a bare semver spec is rewritten. Anything else - workspace:*, link:/file:, npm: aliases, git
+// urls, "*", "latest", or a multi-part range - is intentionally left untouched (skipped, not guessed).
 const SEMVER_SPEC =
-  /^([\^~]|>=|<=|>|<|=)?\s*(\d+)\.(\d+)\.(\d+)(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/
+  /^([\^~]|>=|<=|>|<|=)?\s*(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/
 
 /**
  * Rewrite a dependency version spec to `toVersion`, preserving the range operator (`^`, `~`, …).
@@ -92,25 +96,92 @@ export function rewriteVersionSpec(spec: string, toVersion: string): string | nu
   return next === spec ? null : next
 }
 
+/** Numeric core (major, minor, patch) of a semver spec, ignoring the range operator + prerelease/build. */
+export function specVersionTuple(spec: string): readonly [number, number, number] | null {
+  const match = SEMVER_SPEC.exec(spec.trim())
+  if (!match) return null
+  return [Number(match[2]), Number(match[3]), Number(match[4])]
+}
+
+interface ParsedSpecVersion {
+  readonly core: readonly [number, number, number]
+  readonly prerelease: readonly (number | string)[]
+}
+
+function parseSpecVersion(spec: string): ParsedSpecVersion | null {
+  const match = SEMVER_SPEC.exec(spec.trim())
+  if (!match) return null
+  const prerelease = (match[5] ?? "").split(".")
+  return {
+    core: [Number(match[2]), Number(match[3]), Number(match[4])],
+    prerelease:
+      match[5] === undefined
+        ? []
+        : prerelease.map((part) => (/^\d+$/.test(part) ? Number(part) : part)),
+  }
+}
+
+/** Compare two semver cores: <0 when a<b, 0 equal, >0 when a>b. */
+export function compareSemverCore(
+  a: readonly [number, number, number],
+  b: readonly [number, number, number],
+): number {
+  return a[0] - b[0] || a[1] - b[1] || a[2] - b[2]
+}
+
+/** Compare full semver precedence, including prereleases (`2.3.0-beta` < `2.3.0`). */
+export function compareSemverSpec(a: string, b: string): number {
+  const left = parseSpecVersion(a)
+  const right = parseSpecVersion(b)
+  if (left === null || right === null) return 0
+  const core = compareSemverCore(left.core, right.core)
+  if (core !== 0) return core
+  if (left.prerelease.length === 0 || right.prerelease.length === 0) {
+    return left.prerelease.length === right.prerelease.length
+      ? 0
+      : left.prerelease.length === 0
+        ? 1
+        : -1
+  }
+  const length = Math.max(left.prerelease.length, right.prerelease.length)
+  for (let i = 0; i < length; i++) {
+    const x = left.prerelease[i]
+    const y = right.prerelease[i]
+    if (x === undefined || y === undefined) return x === undefined ? -1 : 1
+    if (typeof x === "number" && typeof y === "number") {
+      if (x !== y) return x - y
+    } else if (typeof x === "number") return -1
+    else if (typeof y === "number") return 1
+    else if (x !== y) return x < y ? -1 : 1
+  }
+  return 0
+}
+
 const escapeRegExp = (value: string): string => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
 
 /**
- * Apply pin rules to one package.json's TEXT (format-preserving — targeted string replaces, never a
+ * Apply pin rules to one package.json's TEXT (format-preserving - targeted string replaces, never a
  * JSON re-serialize that would reorder keys or drop comments-as-formatting). Returns the new text and
  * the changes made.
  */
 export function pinSweepText(
   text: string,
   rules: readonly { match: string; to: string }[],
-): { text: string; changes: Array<Omit<PinChange, "file">> } {
+  allowDowngrade = false,
+): {
+  text: string
+  changes: Array<Omit<PinChange, "file">>
+  downgrades: Array<Omit<PinChange, "file">>
+} {
   let parsed: Record<string, unknown>
   try {
     parsed = JSON.parse(text) as Record<string, unknown>
   } catch {
-    return { text, changes: [] }
+    return { text, changes: [], downgrades: [] }
   }
   let out = text
   const changes: Array<Omit<PinChange, "file">> = []
+  const downgrades: Array<Omit<PinChange, "file">> = []
   for (const field of DEP_FIELDS) {
     const deps = parsed[field]
     if (typeof deps !== "object" || deps === null) continue
@@ -122,6 +193,19 @@ export function pinSweepText(
       if (!rule) continue
       const next = rewriteVersionSpec(rawSpec, rule.to)
       if (next === null) continue
+      // Refuse a rollback: `upgrade <version>` pins an exact target, so an OLD target on a newer install
+      // walks dependencies backward (e.g. ^2.3.0 → ^2.0.0) and can break a shared-package peer range.
+      const current = specVersionTuple(rawSpec)
+      const target = specVersionTuple(rule.to)
+      if (
+        !allowDowngrade &&
+        current !== null &&
+        target !== null &&
+        compareSemverSpec(rawSpec, rule.to) > 0
+      ) {
+        downgrades.push({ field, name, from: rawSpec, to: next })
+        continue
+      }
       // Replace exactly `"name"<ws>:<ws>"spec"`, preserving the surrounding whitespace.
       const pattern = new RegExp(`("${escapeRegExp(name)}"\\s*:\\s*")${escapeRegExp(rawSpec)}(")`)
       const replaced = out.replace(pattern, `$1${next}$2`)
@@ -131,7 +215,7 @@ export function pinSweepText(
       }
     }
   }
-  return { text: out, changes }
+  return { text: out, changes, downgrades }
 }
 
 function dependencyObjectRange(
@@ -289,10 +373,16 @@ function scan(cwd: string, pattern: string): string[] {
 }
 
 /** Compute the plan (and, when `write`, apply it) for a target recipe against `cwd`. */
-export function computeUpgrade(cwd: string, recipe: UpgradeRecipe, write: boolean): UpgradePlan {
+export function computeUpgrade(
+  cwd: string,
+  recipe: UpgradeRecipe,
+  write: boolean,
+  allowDowngrade = false,
+): UpgradePlan {
   const pins: PinChange[] = []
   const dependencyMoves: DependencyMoveChange[] = []
   const importMoves: ImportChange[] = []
+  const downgrades: PinChange[] = []
 
   if ((recipe.dependencyMoves?.length ?? 0) > 0 || recipe.pins.length > 0) {
     for (const rel of scan(cwd, "**/package.json")) {
@@ -300,8 +390,9 @@ export function computeUpgrade(cwd: string, recipe: UpgradeRecipe, write: boolea
       const original = readFileSync(abs, "utf8")
       const moved = moveDependenciesText(original, recipe.dependencyMoves ?? [])
       for (const change of moved.changes) dependencyMoves.push({ file: rel, ...change })
-      const pinned = pinSweepText(moved.text, recipe.pins)
+      const pinned = pinSweepText(moved.text, recipe.pins, allowDowngrade)
       for (const change of pinned.changes) pins.push({ file: rel, ...change })
+      for (const d of pinned.downgrades) downgrades.push({ file: rel, ...d })
       if (write && pinned.text !== original) writeFileSync(abs, pinned.text)
     }
   }
@@ -322,6 +413,7 @@ export function computeUpgrade(cwd: string, recipe: UpgradeRecipe, write: boolea
     pins,
     dependencyMoves,
     importMoves,
+    downgrades,
     notes: recipe.notes ?? [],
   }
 }
@@ -336,7 +428,7 @@ function renderPlan(plan: UpgradePlan, write: boolean): string {
     plan.dependencyMoves.length === 0 &&
     plan.importMoves.length === 0
   ) {
-    lines.push("Already up to date — no changes.")
+    lines.push("Already up to date - no changes.")
     return lines.join("\n")
   }
   if (plan.dependencyMoves.length > 0) {
@@ -366,6 +458,19 @@ function renderPlan(plan: UpgradePlan, write: boolean): string {
   return lines.join("\n").trimEnd()
 }
 
+/** Explain a refused rollback: which pins would roll back, why it's blocked, and the escape hatch. */
+function renderDowngradeRefusal(version: string, downgrades: readonly PinChange[]): string {
+  return [
+    `nifra upgrade → ${version}: refusing to DOWNGRADE ${downgrades.length} pin(s) below what's installed.`,
+    "",
+    ...downgrades.map((d) => `  ${d.file}  ${d.name}: ${d.from} → ${d.to}  (would roll back)`),
+    "",
+    "`nifra upgrade <version>` sets each pin to exactly <version>; an older target on a newer install",
+    "rolls dependencies backward and can violate a shared-package peer range. Target a version >= the",
+    "installed one, or pass --allow-downgrade if the rollback is intended.",
+  ].join("\n")
+}
+
 /** CLI entry. Returns false (→ non-zero exit) on an unknown version, no project, or a failed verify. */
 export async function runUpgrade(cwd: string, options: UpgradeOptions): Promise<boolean> {
   if (options.list) {
@@ -393,13 +498,26 @@ export async function runUpgrade(cwd: string, options: UpgradeOptions): Promise<
     readFileSync(join(cwd, "package.json"), "utf8")
   } catch {
     console.error(
-      `[nifra] no package.json in ${relative(process.cwd(), cwd) || "."} — run from a project root`,
+      `[nifra] no package.json in ${relative(process.cwd(), cwd) || "."} - run from a project root`,
     )
     return false
   }
 
   const write = options.write === true
-  const plan = computeUpgrade(cwd, recipe, write)
+  const allowDowngrade = options.allowDowngrade === true
+
+  // Fail-closed on rollback: a dry pass writes nothing, so we can refuse before any package.json is touched.
+  const preview = computeUpgrade(cwd, recipe, false, allowDowngrade)
+  if (preview.downgrades.length > 0) {
+    if (options.json) {
+      console.log(JSON.stringify({ ...preview, write: false, refused: "downgrade" }, null, 2))
+    } else {
+      console.error(renderDowngradeRefusal(recipe.version, preview.downgrades))
+    }
+    return false
+  }
+
+  const plan = write ? computeUpgrade(cwd, recipe, true, allowDowngrade) : preview
 
   if (options.json) {
     console.log(JSON.stringify({ ...plan, write }, null, 2))
@@ -413,7 +531,7 @@ export async function runUpgrade(cwd: string, options: UpgradeOptions): Promise<
     const ok = await runCheck(cwd, { json: false })
     if (!ok) {
       if (!options.json)
-        console.error("\n[nifra] upgrade applied but `nifra check` failed — review above.")
+        console.error("\n[nifra] upgrade applied but `nifra check` failed - review above.")
       return false
     }
   }

package/src/verification.ts

@@ -0,0 +1,123 @@
+/**
+ * One project verification, four commands. `nifra check`, `nifra assure`, `nifra levels`, and
+ * `nifra capabilities` are not separate audits - they are renderings of the same reflected project: the
+ * typed-contract scan, the route-assurance evaluation, and the static capability provenance. Historically
+ * each command re-derived the slice it needed, so a caller had to know which command ran which policy (and
+ * `levels` paid for the capability walk twice). `collectProjectVerification` runs each underlying policy
+ * exactly once and hands back a single value; the commands become thin formatters over subsets of it -
+ * `check`/`assure`/`levels` read their view directly, and `capabilities snapshot`/`check` read the same
+ * capability report before writing or diffing the lockfile.
+ *
+ * The typed-contract check is the one heavy pass (source walk + optional `tsc`), and `nifra assure`
+ * never needs it, so it is exposed as a lazily-invoked `check()` rather than computed up front.
+ */
+
+import { existsSync } from "node:fs"
+import { resolve } from "node:path"
+import {
+  type AssuranceConfig,
+  type AssuranceReport,
+  evaluateRouteAssurance,
+} from "@nifrajs/core/assurance"
+import {
+  type CapabilityProjectReport,
+  collectCapabilityProjectReport,
+} from "./capabilities-tool.ts"
+import { type CheckAssuranceContext, type CheckResult, collectCheckResult } from "./check.ts"
+
+export interface CollectProjectVerificationOptions {
+  /** Assurance config path, default `nifra.assurance.ts`. Honored by the assurance + levels views. */
+  readonly config?: string
+  /** Skip the `tsc` pass in the check view (the agent inner-loop mode). */
+  readonly lintsOnly?: boolean
+  /** Cancels the check view's typecheck. */
+  readonly signal?: AbortSignal
+  /** Cap the check view's diagnostics (the `levels` L0 and MCP paths set this). */
+  readonly maxDiagnostics?: number
+}
+
+export interface ProjectVerification {
+  readonly cwd: string
+  /** Whether `nifra.assurance.ts` (or the requested `config` path) exists. */
+  readonly assuranceConfigPresent: boolean
+  /** The loaded assurance config, when it loaded cleanly. */
+  readonly config?: AssuranceConfig
+  /** The error from loading/evaluating the config, if any; the assurance views surface or throw it. */
+  readonly configError?: unknown
+  /** `evaluateRouteAssurance` over the config's source + policy. Present whenever {@link config} is. */
+  readonly routeAssurance?: AssuranceReport
+  /** Static capability provenance, when the config declares a capabilities policy. */
+  readonly capability?: CapabilityProjectReport
+  /**
+   * The typed-contract check (scanners + typecheck + the assurance-fed capability/manifest diagnostics).
+   * Lazy and memoized: `nifra assure` never calls it, so that command pays nothing for the source walk.
+   */
+  check(): Promise<CheckResult>
+}
+
+/**
+ * Run each verification policy once and return the unified value. The config is loaded (and reflected)
+ * a single time; the resulting route-assurance + capability evidence is both returned for the assurance
+ * views and fed into the check view, so nothing is computed twice.
+ */
+export async function collectProjectVerification(
+  cwd: string,
+  options: CollectProjectVerificationOptions = {},
+): Promise<ProjectVerification> {
+  const { loadAssuranceConfig, DEFAULT_ASSURANCE_CONFIG } = await import("./assure.ts")
+  const configPath = resolve(cwd, options.config ?? DEFAULT_ASSURANCE_CONFIG)
+  const assuranceConfigPresent = existsSync(configPath)
+
+  let config: AssuranceConfig | undefined
+  let configError: unknown
+  let routeAssurance: AssuranceReport | undefined
+  let capability: CapabilityProjectReport | undefined
+  // One try mirrors `check`'s single catch: any failure to load or reflect the config becomes the
+  // `configError` each view then renders in its own idiom (a diagnostic, a throw, a failed rung).
+  try {
+    config = await loadAssuranceConfig(cwd, options.config)
+    routeAssurance = evaluateRouteAssurance(config.source, config.policy, {
+      ...(config.capabilities !== undefined
+        ? { definitions: config.capabilities.definitions }
+        : {}),
+    })
+    if (config.capabilities !== undefined) {
+      capability = await collectCapabilityProjectReport(cwd, config.source, config.capabilities)
+    }
+  } catch (error) {
+    configError = error
+    config = undefined
+    routeAssurance = undefined
+    capability = undefined
+  }
+
+  // The check view's assurance inputs. Fed to `check()` only when no custom config path was requested,
+  // so `nifra check` (which always reads the default `nifra.assurance.ts`) and `levels` L0 keep reading
+  // exactly the config they read before; a `--config` override stays a route-assurance/levels concern.
+  const checkContext: CheckAssuranceContext = {
+    present: assuranceConfigPresent,
+    ...(config !== undefined ? { config } : {}),
+    ...(configError !== undefined ? { error: configError } : {}),
+    ...(routeAssurance !== undefined ? { routeAssurance } : {}),
+    ...(capability !== undefined ? { capability } : {}),
+  }
+
+  let checkResult: Promise<CheckResult> | undefined
+  return Object.freeze({
+    cwd,
+    assuranceConfigPresent,
+    ...(config !== undefined ? { config } : {}),
+    ...(configError !== undefined ? { configError } : {}),
+    ...(routeAssurance !== undefined ? { routeAssurance } : {}),
+    ...(capability !== undefined ? { capability } : {}),
+    check(): Promise<CheckResult> {
+      checkResult ??= collectCheckResult(cwd, {
+        lintsOnly: options.lintsOnly ?? false,
+        ...(options.signal !== undefined ? { signal: options.signal } : {}),
+        ...(options.maxDiagnostics !== undefined ? { maxDiagnostics: options.maxDiagnostics } : {}),
+        ...(options.config === undefined ? { assurance: checkContext } : {}),
+      })
+      return checkResult
+    },
+  })
+}