@nifrajs/cli 3.5.0 → 4.0.2

package/src/fix-recipes.ts

@@ -31,35 +31,27 @@ registerFixRecipe({
   description: "Replace a direct secret comparison with a length check and timing-safe comparison.",
   verify: "nifra check --lints-only",
   async apply(root, diagnostic) {
-    if (diagnostic.file === undefined || diagnostic.line === undefined) return []
+    if (diagnostic.file === undefined) return []
     const path = await resolveInsideProject(root, diagnostic.file)
     if (path === undefined) return []
-    const lines = (await readFile(path, "utf8")).split("\n")
-    const index = diagnostic.line - 1
-    const original = lines[index]
-    if (original === undefined || original.includes("@nifra-gate-reviewed")) return []
-    const comparison = /\b([A-Za-z_$][\w$]*)\s*(===|!==|==|!=)\s*([A-Za-z_$][\w$]*)/.exec(original)
-    if (comparison === null) return []
-    const left = comparison[1] as string
-    const operator = comparison[2] as string
-    const right = comparison[3] as string
-    const expression = `nifraTimingSafeEqual(${left}, ${right})`
-    const replacement = operator === "!==" || operator === "!=" ? `!${expression}` : expression
-    lines[index] = original.replace(comparison[0], replacement)
-    if (!lines.some((line) => line.includes("function nifraTimingSafeEqual"))) {
-      lines.unshift(
-        'import { timingSafeEqual } from "node:crypto"',
-        "",
-        "function nifraTimingSafeEqual(left: string, right: string): boolean {",
-        "  const leftBytes = Buffer.from(left)",
-        "  const rightBytes = Buffer.from(right)",
-        "  return leftBytes.length === rightBytes.length && timingSafeEqual(leftBytes, rightBytes)",
-        "}",
-        "",
+    const { loadProjectTypeScript } = await import("./internal/typescript-import.ts")
+    const loaded = await loadProjectTypeScript(root)
+    if (loaded.unsupported !== undefined) throw loaded.unsupported
+    if (loaded.compiler === undefined)
+      throw new Error(
+        "[nifra] the timing-safe fix finds each comparison in the syntax tree, so it needs TypeScript - run `bun add -d typescript`, then rerun the fix",
       )
+    try {
+      const { rewriteSecretComparisons } = await import("./rules/security.ts")
+      const source = await readFile(path, "utf8")
+      // Every site in the file at once, so the rest of that file's diagnostics find nothing left.
+      const rewritten = rewriteSecretComparisons(loaded.compiler, diagnostic.file, source)
+      if (rewritten === source) return []
+      await writeFile(path, rewritten, "utf8")
+      return [diagnostic.file]
+    } finally {
+      await loaded.session?.close()
     }
-    await writeFile(path, lines.join("\n"), "utf8")
-    return [diagnostic.file]
   },
 })
 
@@ -70,7 +62,15 @@ registerFixRecipe({
   async apply(root) {
     const { syncServerManifests } = await import("./sync-manifest.ts")
     const results = await syncServerManifests(root)
-    return results.filter((result) => result.changed).map((result) => result.file)
+    const changed = results.filter((result) => result.changed).map((result) => result.file)
+    const failed = results.filter((result) => result.error !== undefined)
+    if (failed.length > 0) {
+      const synced = changed.length === 0 ? "" : `synced ${changed.join(", ")}; `
+      throw new Error(
+        `[nifra] ${synced}cannot sync ${failed.map((result) => `${result.file}: ${result.error}`).join("; ")}`,
+      )
+    }
+    return changed
   },
 })
 
@@ -101,7 +101,7 @@ registerFixRecipe({
     // Refusing is a result the caller has to see. Returning "changed nothing" made `nifra fix
     // --code NF-C010` a silent no-op on the only findings that produce it.
     if (!linked.ok) throw new Error(`[nifra] cannot rebuild ${packageName}: ${linked.reason}`)
-    const proc = Bun.spawn(["bun", "run", linked.buildScript], {
+    const proc = Bun.spawn([process.execPath, "run", linked.buildScript], {
       cwd: linked.dir,
       stdout: "ignore",
       stderr: "pipe",
@@ -117,6 +117,24 @@ registerFixRecipe({
   },
 })
 
+registerFixRecipe({
+  id: "imports.moved-export",
+  description: "Import a name that moved to a subpath from the module that now exports it.",
+  verify: "nifra check --lints-only",
+  async apply(root, diagnostic) {
+    if (diagnostic.file === undefined) return []
+    const path = await resolveInsideProject(root, diagnostic.file)
+    if (path === undefined) return []
+    const { rewriteMovedExports } = await import("./check-scan.ts")
+    const source = await readFile(path, "utf8")
+    // Rewrites every site in the file at once, so the rest of that file's diagnostics find nothing left.
+    const rewritten = rewriteMovedExports(source)
+    if (rewritten === source) return []
+    await writeFile(path, rewritten, "utf8")
+    return [diagnostic.file]
+  },
+})
+
 /**
  * How many typecheck passes the reserved-segment codemod will run. A nested collision
  * (`/api/delete/then`) only reveals its second site once the first is rewritten, so one pass is not
@@ -147,11 +165,14 @@ registerFixRecipe({
     const changed = new Set<string>()
     const skipped: string[] = []
     for (let pass = 0; pass < RESERVED_SEGMENT_PASSES; pass += 1) {
-      const proc = Bun.spawn(["bun", tscBin, "--noEmit", "--pretty", "false", "-p", tsconfig], {
-        cwd: root,
-        stdout: "pipe",
-        stderr: "pipe",
-      })
+      const proc = Bun.spawn(
+        [process.execPath, tscBin, "--noEmit", "--pretty", "false", "-p", tsconfig],
+        {
+          cwd: root,
+          stdout: "pipe",
+          stderr: "pipe",
+        },
+      )
       const [stdout, stderr] = await Promise.all([
         new Response(proc.stdout).text(),
         new Response(proc.stderr).text(),

package/src/frontend-guidance.ts

@@ -52,11 +52,11 @@ export const FRONTEND_GUIDANCE: readonly GuidanceEntry[] = [
     symptom:
       "A client component crashes at build or runtime with a missing Node built-in, a leaked secret, or 'module not found in the browser'.",
     cause:
-      "A server-only module (the DB, a secret, `node:*`, the backend file) is imported at the top level of a component, so the bundler tries to ship it to the browser.",
-    fix: "Move the access into a server-only `loader`/`action` and read the result in the component. Reach the backend through the typed `api` argument, never a top-level server-only import.",
+      "Browser code (a page, `frontend/` or `shared/`) imports backend code - `backend/`, a route's `.backend.ts` half, the DB, a secret, `node:*` - so the browser build refuses it.",
+    fix: "Move the access into the route's `.backend.ts` half (`loader`/`action` with `loaderOutput`/`actionOutput`) and read the result as `data` in the page. Reach the backend through the typed `api` argument; put code both sides need in `shared/`.",
     verify:
       "nifra_check - its transitive server-import scan flags the exact import chain into a client module.",
-    seeAlso: "loader action server-only import boundary",
+    seeAlso: "project structure route backend half import rules",
   },
   {
     id: "hydration-mismatch",
@@ -88,10 +88,10 @@ export const FRONTEND_GUIDANCE: readonly GuidanceEntry[] = [
       "Loader data is typed `any` in the page, or a hand-written interface silently drifts from what the loader actually returns.",
     cause:
       "The component types its props by hand instead of inferring them from the loader, so a change to the loader is not a type error at the use site.",
-    fix: "Type the page from the loader: `props: { data: LoaderData<typeof loader> }`. Call the backend through the typed `api` so the request/response shape is inferred, not restated.",
+    fix: 'Type the page from its generated route types: `import type { Route } from "./+types/<name>"` and `props: Route.ComponentProps`. Its `data` is the `loaderOutput` schema\'s type - what actually reaches the browser - while `LoaderData<typeof loader>` also types fields the schema strips. Call the backend through the typed `api` (`Route.LoaderArgs`) so the request/response shape is inferred, not restated.',
     verify:
       "nifra_context prints the exact loader shape and typed call form; nifra_check fails on drift.",
-    seeAlso: "LoaderData typed client loader inference",
+    seeAlso: "route types Route.ComponentProps loaderOutput typed client",
   },
   {
     id: "list-key",

package/src/i18n-check.ts

@@ -0,0 +1,179 @@
+/**
+ * `nifra i18n check [entry]` - runs `checkCatalogs()` from `@nifrajs/i18n/check` over an app's locale
+ * registry and catalogs. Unlike `nifra check`, this IMPORTS app code: the entry module, which exports
+ * `locales` (from `defineLocales`) and `catalogs` (by locale key: a catalog, or a function returning
+ * one or a promise of one, such as `() => import("./messages/fr.json")`), plus an optional `ignore`.
+ * The default entry is the first of {@link DEFAULT_ENTRIES} that exists.
+ */
+import { existsSync } from "node:fs"
+import { relative, resolve } from "node:path"
+import { pathToFileURL } from "node:url"
+import type { MessageTree } from "@nifrajs/i18n"
+import type { CatalogCheckOptions, CatalogCheckResult, CatalogFinding } from "@nifrajs/i18n/check"
+
+export const DEFAULT_ENTRIES = [
+  "shared/i18n.ts",
+  "i18n.ts",
+  "lib/i18n.ts",
+  "src/i18n.ts",
+  "src/lib/i18n.ts",
+  "app/i18n.ts",
+] as const
+
+export interface I18nCheckOutput {
+  /** The entry module, relative to the project directory. */
+  readonly entry: string
+  readonly result: CatalogCheckResult
+}
+
+const isObject = (value: unknown): value is Record<string, unknown> =>
+  value !== null && typeof value === "object"
+
+/** A loaded module's default export when the value is a module namespace (`import("./fr.json")`). */
+const unwrapModule = (value: unknown): unknown =>
+  isObject(value) && Object.prototype.toString.call(value) === "[object Module]"
+    ? value.default
+    : value
+
+const isRegistry = (value: unknown): value is CatalogCheckOptions["locales"] =>
+  isObject(value) &&
+  typeof value.default === "string" &&
+  Array.isArray(value.all) &&
+  typeof value.get === "function" &&
+  typeof value.chain === "function"
+
+function resolveEntry(cwd: string, entry: string | undefined): string {
+  if (entry !== undefined) {
+    const path = resolve(cwd, entry)
+    if (!existsSync(path)) throw new Error(`i18n check: ${entry} does not exist`)
+    return path
+  }
+  for (const candidate of DEFAULT_ENTRIES) {
+    const path = resolve(cwd, candidate)
+    if (existsSync(path)) return path
+  }
+  throw new Error(
+    `i18n check: no entry module found (looked for ${DEFAULT_ENTRIES.join(", ")}). Pass one: nifra i18n check <entry>, a module exporting \`locales\` and \`catalogs\`.`,
+  )
+}
+
+/** Import the entry, load every catalog it names, and check them. */
+export async function runI18nCheck(
+  cwd: string,
+  options: { readonly entry?: string | undefined } = {},
+): Promise<I18nCheckOutput> {
+  const path = resolveEntry(cwd, options.entry)
+  const mod = (await import(pathToFileURL(path).href)) as Record<string, unknown>
+  const source = isObject(mod.default) && mod.locales === undefined ? mod.default : mod
+  const { locales, catalogs, ignore } = source
+  const entry = relative(cwd, path).replaceAll("\\", "/") || path
+  if (!isRegistry(locales)) {
+    throw new Error(
+      `i18n check: ${entry} must export \`locales\`, the registry defineLocales() returns`,
+    )
+  }
+  if (!isObject(catalogs)) {
+    throw new Error(
+      `i18n check: ${entry} must export \`catalogs\`, an object of catalogs by locale key`,
+    )
+  }
+  if (ignore !== undefined && !isObject(ignore)) {
+    throw new Error(`i18n check: \`ignore\` in ${entry} must be an object of key patterns by check`)
+  }
+  const loaded: Record<string, MessageTree | undefined> = {}
+  for (const key of Object.keys(catalogs)) {
+    let value = catalogs[key]
+    if (typeof value === "function") value = (value as () => unknown)()
+    loaded[key] = unwrapModule(await value) as MessageTree | undefined
+  }
+  // Loaded on use: the command catalog imports this module on every CLI start.
+  const { checkCatalogs } = await import("@nifrajs/i18n/check")
+  return {
+    entry,
+    result: checkCatalogs({
+      locales,
+      catalogs: loaded,
+      ignore: ignore as CatalogCheckOptions["ignore"],
+    }),
+  }
+}
+
+const MARK = { error: "✖", warning: "⚠", info: "•" } as const
+// Per-key findings that are lists rather than problems one by one: grouped per locale in the text.
+const GROUPED = new Set(["missing-key", "unused-key", "untranslated"])
+const SHOWN_KEYS = 6
+
+// Catalog keys and text reach the terminal: control and bidi-override characters print as escapes, so
+// a key can neither drive the terminal nor reorder what the line appears to say.
+const unprintable = (code: number): boolean =>
+  code <= 0x1f ||
+  (code >= 0x7f && code <= 0x9f) ||
+  code === 0x200e ||
+  code === 0x200f ||
+  (code >= 0x202a && code <= 0x202e) ||
+  (code >= 0x2066 && code <= 0x2069)
+const printable = (line: string): string => {
+  let out = ""
+  for (const char of line) {
+    const code = char.codePointAt(0) ?? 0
+    out += unprintable(code) ? `\\u${code.toString(16).padStart(4, "0")}` : char
+  }
+  return out
+}
+
+const percent = (share: number): string => `${(share * 100).toFixed(share === 1 ? 0 : 1)}%`
+
+/** The human report: a coverage table, then findings, grouped where they are key lists. */
+export function renderI18nCheck(out: I18nCheckOutput): readonly string[] {
+  const { result } = out
+  const lines = [`nifra i18n check - ${out.entry}`, ""]
+  const width = Math.max(6, ...result.coverage.map((row) => row.locale.length))
+  for (const row of result.coverage) {
+    const label = row.default ? "default" : row.draft ? "draft" : ""
+    const counts = row.default
+      ? `${row.total} messages`
+      : `${row.translated}/${row.total} (${percent(row.coverage)})${row.own === row.translated ? "" : `, ${row.own} own`}`
+    lines.push(`  ${row.locale.padEnd(width)}  ${label.padEnd(7)}  ${counts}`)
+  }
+  if (result.coverage.length > 0) lines.push("")
+
+  const groups = new Map<string, CatalogFinding[]>()
+  for (const finding of result.findings) {
+    if (!GROUPED.has(finding.code) || finding.key === undefined) {
+      lines.push(`${MARK[finding.severity]} ${finding.locale}  ${finding.code}: ${finding.message}`)
+      continue
+    }
+    const id = `${finding.severity}\u0000${finding.locale}\u0000${finding.code}`
+    const group = groups.get(id)
+    if (group === undefined) groups.set(id, [finding])
+    else group.push(finding)
+  }
+  for (const group of groups.values()) {
+    const first = group[0] as CatalogFinding
+    const keys = group.map((finding) => finding.key as string)
+    const shown = keys.slice(0, SHOWN_KEYS).join(", ")
+    const more = keys.length > SHOWN_KEYS ? `, +${keys.length - SHOWN_KEYS} more` : ""
+    lines.push(
+      `${MARK[first.severity]} ${first.locale}  ${first.code} (${keys.length}): ${shown}${more}`,
+    )
+  }
+
+  const count = (severity: CatalogFinding["severity"]): number =>
+    result.findings.filter((finding) => finding.severity === severity).length
+  const errors = count("error")
+  const warnings = count("warning")
+  if (result.findings.length > 0) lines.push("")
+  lines.push(
+    errors === 0 && warnings === 0
+      ? "✓ catalogs are complete and consistent"
+      : `${errors} error${errors === 1 ? "" : "s"}, ${warnings} warning${warnings === 1 ? "" : "s"}${errors === 0 ? " - pass --strict to fail on warnings" : ""}`,
+  )
+  return lines.map(printable)
+}
+
+/** Errors fail the run; with `strict`, warnings do too. Info never does. */
+export function i18nCheckPassed(out: I18nCheckOutput, strict: boolean): boolean {
+  return out.result.findings.every(
+    (finding) => finding.severity === "info" || (finding.severity === "warning" && !strict),
+  )
+}