@timber-js/app 0.2.0-alpha.20 → 0.2.0-alpha.201

package/src/cli-check.ts

@@ -0,0 +1,507 @@
+/**
+ * `timber check` — the implementation behind the CLI command.
+ *
+ * Two passes, in order:
+ *
+ * 1. **Routes.** Resolve the project through Vite — so root, `appDir`, and
+ *    `pageExtensions` are the ones `timber build` uses, including config
+ *    passed inline to `timber()` — then scan, run the convention linter, and
+ *    write the route codegen (`.timber/timber-routes.d.ts`,
+ *    `.timber/segment-types.d.ts`, `timber-env.d.ts`).
+ *
+ *    Codegen runs *before* the type pass on purpose: those
+ *    files are what give `<Link href>`, `useSegmentParams()` and
+ *    `MiddlewareContext` their per-route types (design/09-typescript.md
+ *    §"Typed Routes"), and they are build artifacts — a fresh clone that has
+ *    never run `timber dev` or `timber build` does not have them, so a type
+ *    pass on its own would report errors about correct code. A clone whose
+ *    routes changed since the last build has the same problem with stale ones.
+ * 2. **Types.** `tsgo --noEmit` over the project.
+ *
+ * tsgo is spawned as `node <@typescript/native-preview>/lib/tsgo.js`, never as
+ * a bare `tsgo` off PATH — the package is an *optional peer dependency*, so
+ * there is no reason for its shim to be on a user's PATH, and the shim is a
+ * `.cmd` on Windows which cannot be spawned without a shell. `shell: true`
+ * would then concatenate the argv into an unescaped command string, so a
+ * project path containing a space would break on exactly the platform the
+ * shell was there to support. This mirrors `scripts/build-types.js`, whose
+ * header comment is the specification for the pattern.
+ *
+ * Design docs: 11-platform.md §CLI, 09-typescript.md, 28-npm-packaging.md
+ */
+
+import { createRequire } from 'node:module';
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { scanRoutes } from './routing/scanner.ts';
+import { lintConventions, formatConventionWarnings } from './routing/convention-lint.ts';
+import { writeRouteCodegen, CODEGEN_OUTPUT, ENV_DTS_FILENAME } from './routing/codegen-write.ts';
+import { isTimberPluginApi } from './plugin-context.ts';
+
+/** The plugin that publishes timber's resolved context on its Vite `api`. */
+const TIMBER_ROOT_SYNC_PLUGIN = 'timber-root-sync';
+
+/** The npm package that provides tsgo. Named in the missing-tool message. */
+const TSGO_PACKAGE = '@typescript/native-preview';
+
+/**
+ * The two generated declaration paths, relative to the project root, as they
+ * appear in a resolved tsconfig file list. Derived from the writer's own
+ * constants — a rename there cannot leave this check hunting for a file nothing
+ * writes.
+ */
+const GENERATED_TYPE_PATHS = [ENV_DTS_FILENAME, CODEGEN_OUTPUT];
+
+/**
+ * Run the compiler to completion.
+ *
+ * Resolves with its exit status (`null` when a signal killed it) and rejects
+ * only when the process could not be started — the two outcomes `runTypeCheck`
+ * has to keep apart. The seam is this narrow on purpose: a test double is a
+ * plain async function, with no `ChildProcess` shape to imitate.
+ */
+export type RunTsgo = (command: string, args: string[], cwd: string) => Promise<number | null>;
+
+/**
+ * Run the compiler and capture its stdout — used for `--showConfig`, whose
+ * output is data we read rather than diagnostics the user reads.
+ */
+export type ReadTsgoConfig = (command: string, args: string[], cwd: string) => Promise<string>;
+
+/**
+ * Vite's own `resolveConfig`, narrowed to what this module passes and reads.
+ *
+ * The seam sits at `resolveConfig` rather than at "give me the plugins" so the
+ * *arguments* are the thing under test: which config file, which command, and
+ * which mode defaults. Those arguments have been wrong three separate times
+ * (TIM-1332 rounds 4-6), and a double that answered "here are the plugins"
+ * could not see any of it. The double returns what Vite returns — plugins with
+ * an opaque `api` — so the lookup and narrowing under test stay the real ones.
+ */
+export type ResolveViteConfig = (
+  inlineConfig: { configFile: string | undefined },
+  command: 'build',
+  defaultMode: string,
+  defaultNodeEnv: string
+) => Promise<{ plugins: readonly PluginWithApi[] }>;
+
+/** @internal Dependency injection for testing. */
+export interface CheckDeps {
+  /**
+   * Resolve tsgo's own JS entry point. Throws when the package is not
+   * installed — the caller turns that into an install instruction.
+   */
+  resolveTsgoEntry?: () => string;
+  runTsgo?: RunTsgo;
+  readTsgoConfig?: ReadTsgoConfig;
+  resolveViteConfig?: ResolveViteConfig;
+}
+
+export interface CheckOptions {
+  /** Project root, for resolving tsgo. Defaults to `process.cwd()`. */
+  root?: string;
+  /**
+   * Path to a **tsconfig**, forwarded to tsgo as `--project` and sourced from
+   * the CLI's own `--project`. The route pass takes no part in it: it resolves
+   * the app's configuration through Vite, as `timber build` does.
+   */
+  config?: string;
+}
+
+/**
+ * Locate `@typescript/native-preview`'s JS entry.
+ *
+ * Resolution is attempted from this package first (it is declared an optional
+ * peer dependency, so a package manager links it here when the user installs
+ * it) and then from the project root (covering a hoisted install, or a user who
+ * added it without the peer link). Throws if neither finds it.
+ */
+export function resolveTsgoEntry(
+  root: string,
+  resolveFrom: (from: string, specifier: string) => string = (from, specifier) =>
+    createRequire(from).resolve(specifier)
+): string {
+  // `createRequire` takes a filename or a file URL; a plain absolute path is
+  // the portable spelling for the project root (a `file://` prefix on a Windows
+  // path is not a valid URL). Same form as `checkPeerDependencies`.
+  const candidates = [import.meta.url, join(root, 'package.json')];
+  let lastError: unknown;
+
+  for (const from of candidates) {
+    try {
+      // The package exports no subpath for its entry, so resolve the manifest
+      // and walk to the module its `bin/tsgo` shim imports.
+      const manifest = resolveFrom(from, `${TSGO_PACKAGE}/package.json`);
+      return join(dirname(manifest), 'lib', 'tsgo.js');
+    } catch (err) {
+      lastError = err;
+    }
+  }
+
+  throw new Error(
+    `[timber] Cannot find ${TSGO_PACKAGE}, which \`timber check\` uses to type-check.\n\n` +
+      `  Install it as a dev dependency:\n\n` +
+      `    pnpm add -D ${TSGO_PACKAGE}\n\n` +
+      `  (resolution failed: ${lastError instanceof Error ? lastError.message : String(lastError)})`
+  );
+}
+
+/** What the route pass needs from the command line. */
+export interface RouteOptions {
+  /**
+   * Path to a **Vite** config file, from `--config`. Undefined means Vite's own
+   * discovery, the same as `timber dev`/`build` without the flag. A project
+   * that builds with a custom Vite config has to be checkable with it too, or
+   * `check` resolves a different app than `build` does (TIM-1332, round 4).
+   */
+  viteConfigFile?: string;
+}
+
+/** Everything the route scan needs, as the build itself resolves it. */
+export interface RouteInputs {
+  root: string;
+  appDir: string;
+  pageExtensions: string[] | undefined;
+}
+
+/** The subset of a resolved Vite plugin this module reads. */
+export interface PluginWithApi {
+  name: string;
+  api?: unknown;
+}
+
+/**
+ * Ask Vite for the resolved config, which is what carries timber's context.
+ *
+ * `resolveConfig` runs the whole config pipeline — config file discovery,
+ * `config` and `configResolved` hooks — so the context it produces is the one
+ * `timber build` would use. Measured at ~300-400ms on a real app; the type pass
+ * it precedes costs far more.
+ */
+const defaultResolveViteConfig: ResolveViteConfig = async (
+  inlineConfig,
+  command,
+  defaultMode,
+  defaultNodeEnv
+) => {
+  const { resolveConfig } = await import('vite');
+  return resolveConfig(inlineConfig, command, defaultMode, defaultNodeEnv);
+};
+
+/**
+ * The mode defaults `timber build` resolves under.
+ *
+ * `resolveConfig`'s own defaults are `'development'` for both, but nothing
+ * reaches it with those on a build: `createBuilder` goes through Vite's
+ * internal `resolveConfigToBuild`, which calls
+ * `resolveConfig(inlineConfig, 'build', 'production', 'production')`. A config
+ * written as `defineConfig(({ mode }) => …)`, or one that loads `.env.production`,
+ * therefore resolves to a *different* app under the two. Passing the defaults
+ * explicitly is what makes "check validates what build builds" true rather than
+ * true-by-coincidence for configs that ignore mode (TIM-1332, round 6).
+ */
+const BUILD_MODE_DEFAULTS = ['production', 'production'] as const;
+
+/**
+ * Resolve root, appDir and pageExtensions the way `timber build` resolves them.
+ *
+ * Reading `timber.config.ts` directly is **not** equivalent, which is the whole
+ * reason this goes through Vite (TIM-1332, review round 3):
+ *
+ * - Config passed inline — `timber({ pageExtensions: [...] })` in
+ *   `vite.config.ts` — lives only in the plugin's closure. Nothing that
+ *   re-reads the config file can see it, so a scan built that way silently uses
+ *   default page extensions and writes a route map missing the app's pages.
+ *   `examples/next-playground-migration` is exactly this shape.
+ * - `root` is Vite's resolved root, not the caller's cwd, and the two differ in
+ *   the monorepo layouts TIM-498 describes. `appDir` resolves against it.
+ *
+ * There is no fallback to a second, hand-rolled resolution. A project whose
+ * Vite config does not produce the timber plugin cannot be built either, so a
+ * check that quietly proceeded on a guessed tree would report a verdict about
+ * an app that does not exist.
+ */
+export async function resolveRouteInputs(
+  options: RouteOptions = {},
+  deps: CheckDeps = {}
+): Promise<RouteInputs> {
+  const resolveViteConfig = deps.resolveViteConfig ?? defaultResolveViteConfig;
+  // `configFile: undefined` is Vite's own "discover it" value, so the default
+  // path stays exactly what Vite does for `timber build` without `--config`.
+  const { plugins } = await resolveViteConfig(
+    { configFile: options.viteConfigFile },
+    'build',
+    ...BUILD_MODE_DEFAULTS
+  );
+
+  const rootSync = plugins.find((plugin) => plugin.name === TIMBER_ROOT_SYNC_PLUGIN);
+  if (!rootSync || !isTimberPluginApi(rootSync.api)) {
+    throw new Error(
+      `[timber] Could not read the resolved timber configuration from your Vite config.\n\n` +
+        `  \`timber check\` resolves your project through Vite so it validates the same\n` +
+        `  routes \`timber build\` builds — including config passed inline to timber().\n\n` +
+        `  Check that vite.config.ts exists and lists the timber plugin:\n\n` +
+        `    import { timber } from '@timber-js/app';\n` +
+        `    export default { plugins: [timber()] };\n`
+    );
+  }
+
+  const ctx = rootSync.api.getContext();
+  return { root: ctx.root, appDir: ctx.appDir, pageExtensions: ctx.config.pageExtensions };
+}
+
+/**
+ * Resolve the app directory, scan it, fail on proven-fatal route
+ * misconfigurations, print warnings, and write the route codegen the type pass
+ * depends on.
+ *
+ * Error-level lint findings throw rather than print, matching what
+ * `plugins/routing.ts` does at build time: the tree is not fit to publish, so
+ * it must not reach codegen either. Warnings are printed and do not fail the
+ * command — same severity contract as dev and build, so `timber check` cannot
+ * disagree with them about what a valid app is.
+ */
+export async function checkRoutes(
+  options: RouteOptions = {},
+  deps: CheckDeps = {}
+): Promise<RouteInputs> {
+  const inputs = await resolveRouteInputs(options, deps);
+  const { root, appDir, pageExtensions } = inputs;
+
+  const tree = scanRoutes(appDir, { pageExtensions });
+
+  const warnings = lintConventions(tree, appDir);
+  const fatal = warnings.filter((w) => w.level === 'error');
+  if (fatal.length > 0) {
+    throw new Error(formatConventionWarnings(fatal, { color: false }));
+  }
+  if (warnings.length > 0) {
+    process.stderr.write(`${formatConventionWarnings(warnings)}\n`);
+  }
+
+  // Awaited, unlike the dev/build path: the type pass reads these files, so a
+  // failed write would be reported as type errors in the user's own code.
+  // Reported as a codegen failure rather than surfaced as a bare `EROFS`/
+  // `EACCES` from somewhere unnamed — the raw error says which path could not
+  // be written but not which pass wanted it.
+  try {
+    await writeRouteCodegen(tree, appDir, root);
+  } catch (err) {
+    throw new Error(
+      `[timber] Failed to write the generated route types, which the type check reads: ` +
+        `${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+
+  verifyCodegenImports(root);
+
+  // Returned so the type pass runs against the same root these files landed in.
+  return inputs;
+}
+
+/**
+ * Verify that the import specifiers in the generated route types resolve on the
+ * filesystem. A `.d.ts` whose import fails does NOT produce a TypeScript error —
+ * every type that depends on it silently becomes `any`. The generated file
+ * contains type-level `_AssertSchemaNotAny` / `_AssertCodecTypeNotAny` guards
+ * that catch this at typecheck time, but a diagnostic here fires earlier and
+ * names the exact import that is broken rather than leaving the user to decode
+ * a constraint error.
+ */
+export function verifyCodegenImports(root: string): void {
+  const dtsPath = join(root, CODEGEN_OUTPUT);
+  let content: string;
+  try {
+    content = readFileSync(dtsPath, 'utf-8');
+  } catch {
+    return;
+  }
+
+  const dtsDir = dirname(dtsPath);
+
+  // Check relative imports (default imports only — the generated codegen uses
+  // `import type schema from '...'` for relative paths). Named imports from
+  // relative paths are not emitted today; if codegen adds them, extend this.
+  const RELATIVE_IMPORT_RE = /^import\s+type\s+\w+\s+from\s+'(\.\.?\/[^']+)'/gm;
+  const EXTENSIONS = ['.ts', '.tsx', '.js', '.jsx', '/index.ts', '/index.tsx'];
+  let match;
+  while ((match = RELATIVE_IMPORT_RE.exec(content)) !== null) {
+    const specifier = match[1];
+    const base = join(dtsDir, specifier);
+    const resolves = existsSync(base) || EXTENSIONS.some((ext) => existsSync(base + ext));
+    if (!resolves) {
+      process.stderr.write(
+        `[timber] WARNING: the generated ${CODEGEN_OUTPUT} imports '${specifier}',\n` +
+          `  but no file resolves at ${base}{${EXTENSIONS.join(',')}}.\n` +
+          `  Every type that depends on this import will silently become \`any\`.\n\n` +
+          `  Check that your app/ directory is where timber expects it.\n\n`
+      );
+    }
+  }
+
+  // Bare-specifier imports (`@timber-js/app/params`) are NOT checked here.
+  // They are all dependencies of @timber-js/app itself — if timber is installed,
+  // they resolve. And createRequire uses CJS resolution which cannot follow
+  // ESM-only subpath exports, producing false warnings (TIM-1348 review).
+}
+
+/**
+ * The production `RunTsgo`: spawn the compiler with its stdio inherited, so its
+ * diagnostics stream to the terminal as they are produced (and are not capped
+ * by a buffer, as `execFile` output would be).
+ */
+const spawnTsgo: RunTsgo = async (command, args, cwd) => {
+  const { spawn } = await import('node:child_process');
+  return new Promise<number | null>((resolve, reject) => {
+    // No `shell: true`: Node would concatenate the argv into an unescaped
+    // command string, so a project path containing a space would break.
+    const child = spawn(command, args, { stdio: 'inherit', cwd });
+    child.on('error', reject);
+    child.on('close', (code) => resolve(code));
+  });
+};
+
+/**
+ * The production `ReadTsgoConfig`: `--showConfig`, with stdout captured.
+ *
+ * `maxBuffer` is raised well past `execFile`'s 1 MB default because the output
+ * is one line per file in the program — a large app can exceed that, and
+ * overflowing it would make this advisory go quiet on exactly the projects
+ * where a misconfigured `include` costs the most. A size-dependent silence is
+ * indistinguishable from "everything is fine".
+ */
+const execTsgoConfig: ReadTsgoConfig = async (command, args, cwd) => {
+  const { execFile } = await import('node:child_process');
+  return new Promise<string>((resolve, reject) => {
+    execFile(command, args, { cwd, maxBuffer: 64 * 1024 * 1024 }, (err, stdout) =>
+      err ? reject(err) : resolve(stdout)
+    );
+  });
+};
+
+/**
+ * Warn when the generated route declarations will not reach the type checker.
+ *
+ * Writing `.timber/timber-routes.d.ts` and `timber-env.d.ts` is only half the
+ * job: TypeScript loads them only if the project's `include`/`files` actually
+ * pull `timber-env.d.ts` in (it is what `/// <reference>`s the route map). A
+ * tsconfig with an explicit `include` that lists only source directories —
+ * `["app", "*.config.ts"]`, which is what `create-timber-app` shipped before
+ * TIM-1332 — silently omits it, and every `<Link href>` then type-checks
+ * against the empty placeholder instead of the generated route union. The
+ * check would pass while answering the wrong question.
+ *
+ * The resolved file list comes from `tsgo --showConfig` rather than from our
+ * own reading of the tsconfig: `include`, `exclude`, `files`, and `extends`
+ * compose in ways that are the compiler's to decide, and a second
+ * implementation of them would be a duplicate that drifts. `--showConfig` only
+ * resolves globs, so it costs no type checking.
+ *
+ * This warns rather than fails. An app that never uses typed routes is
+ * correct without those declarations, and a hard error would refuse it — the
+ * one outcome a check must not produce for a working project. When the answer
+ * cannot be determined (tsgo errored, output was not the expected JSON), the
+ * warning is skipped: an advisory that fires on an unknown is noise.
+ */
+async function warnIfRouteTypesUnreachable(
+  tsgoEntry: string,
+  configArgs: string[],
+  cwd: string,
+  readConfig: ReadTsgoConfig
+): Promise<void> {
+  let files: unknown;
+  try {
+    const raw = await readConfig(process.execPath, [tsgoEntry, '--showConfig', ...configArgs], cwd);
+    files = (JSON.parse(raw) as { files?: unknown }).files;
+  } catch {
+    return;
+  }
+  if (!Array.isArray(files)) return;
+
+  // Suffix match, not path resolution: `--showConfig` prints paths relative to
+  // whichever tsconfig the compiler *found*, which for a bare `timber check`
+  // is a directory we never learn. Over-matching only suppresses an advisory.
+  //
+  // The bare form is matched as well as the `/`-prefixed one. tsgo emits
+  // `./timber-env.d.ts` today, but a leading `./` is cosmetic and an emitter
+  // that dropped it would turn this into a warning printed at every correctly
+  // configured project — the failure direction that trains people to ignore it.
+  const reaches = files.some((file) => {
+    if (typeof file !== 'string') return false;
+    const normalized = file.replace(/\\/g, '/');
+    return GENERATED_TYPE_PATHS.some(
+      (path) => normalized === path || normalized.endsWith(`/${path}`)
+    );
+  });
+  if (reaches) return;
+
+  process.stderr.write(
+    `[timber] The generated route types are not part of this TypeScript project, so\n` +
+      `  \`<Link href>\` and \`useSegmentParams()\` are being checked against empty\n` +
+      `  placeholders. Your tsconfig's "include" does not pull in timber-env.d.ts.\n\n` +
+      `  To fix: add it to "include":\n\n` +
+      `    "include": ["app", "*.config.ts", "timber-env.d.ts"]\n\n`
+  );
+}
+
+/**
+ * Run `tsgo --noEmit`, streaming its output.
+ *
+ * Rejects with the real numeric exit status on type errors. A failure to *start*
+ * the compiler is reported separately — the historical bug this replaces
+ * surfaced ENOENT as "Type check failed with exit code undefined", which read
+ * as a type error and sent users looking at their own code.
+ */
+export async function runTypeCheck(
+  options: CheckOptions = {},
+  deps: CheckDeps = {}
+): Promise<void> {
+  // The *resolved* root, handed over by the route pass — not `process.cwd()`.
+  // The two differ whenever `--config` names a Vite config elsewhere, and the
+  // route pass wrote `.timber/*` and `timber-env.d.ts` under the resolved one.
+  // Running tsgo from cwd would then discover a different tsconfig entirely and
+  // type-check a different project than the one just validated (TIM-1332, round
+  // 5) — routes checked for the app, types checked for the monorepo around it.
+  const root = options.root ?? process.cwd();
+  const tsgoEntry = (deps.resolveTsgoEntry ?? (() => resolveTsgoEntry(root)))();
+  const runTsgo = deps.runTsgo ?? spawnTsgo;
+
+  // An explicit `--project` is a path the user typed at their own prompt, so it
+  // is resolved against *their* cwd before the compiler is moved to the project
+  // root. Without `--project`, tsgo discovers `tsconfig.json` from `root`,
+  // which is where the declarations it needs were just written.
+  const configArgs = options.config ? ['--project', resolve(process.cwd(), options.config)] : [];
+
+  // Before checking: say so if the declarations the route pass just wrote will
+  // not be part of the program. Otherwise the check passes while `<Link href>`
+  // is measured against a placeholder. Same root and same argv as the check
+  // itself, or it would inspect a different program than the one tsgo reads.
+  await warnIfRouteTypesUnreachable(
+    tsgoEntry,
+    configArgs,
+    root,
+    deps.readTsgoConfig ?? execTsgoConfig
+  );
+
+  let code: number | null;
+  try {
+    code = await runTsgo(process.execPath, [tsgoEntry, '--noEmit', ...configArgs], root);
+  } catch (err) {
+    // Could not start the compiler at all. Kept distinct from a nonzero exit:
+    // the version this replaced reported ENOENT as "Type check failed with
+    // exit code undefined", which reads as a verdict on the user's types.
+    throw new Error(
+      `[timber] Failed to start the type checker: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+
+  if (code === 0) return;
+
+  // A null code means a signal killed the process rather than it exiting.
+  // Say so instead of printing "exit code null".
+  throw new Error(
+    code === null
+      ? 'Type check terminated before it finished'
+      : `Type check failed with exit code ${code}`
+  );
+}