@octanejs/cli 0.0.0

package/src/commands/doctor/check.js

@@ -0,0 +1,43 @@
+/**
+ * @typedef {'pass' | 'fail' | 'warn' | 'skip'} CheckStatus
+ */
+
+/**
+ * @typedef {Object} CheckResult
+ * @property {CheckStatus} status
+ * @property {string} message one line, present tense, states the finding
+ * @property {string[]} [detail] evidence and the remedy, shown under the message
+ * @property {string} [docs] documentation slug, appended to the docs base URL
+ */
+
+/**
+ * @typedef {Object} FixOutcome
+ * @property {boolean} changed
+ * @property {string} message
+ * @property {string[]} [files] paths written, relative to the project root
+ */
+
+/**
+ * @typedef {Object} Check
+ * @property {string} id stable, dot-separated: `<category>.<subject>`
+ * @property {string} title
+ * @property {'environment' | 'dependencies' | 'bundler' | 'typescript' | 'config' | 'source'} category
+ * @property {'error' | 'warning' | 'info'} severity how a `fail` is scored
+ * @property {(project: import('../../kernel/project.js').Project) => boolean} [applies]
+ * @property {(ctx: import('../../kernel/context.js').Ctx, project: import('../../kernel/project.js').Project) => CheckResult | Promise<CheckResult>} run
+ * @property {(ctx: import('../../kernel/context.js').Ctx, project: import('../../kernel/project.js').Project) => FixOutcome | Promise<FixOutcome>} [fix]
+ *   Present only when the repair is mechanical and unambiguous. A check without
+ *   `fix` reports the remedy in `detail` instead of guessing at the edit.
+ */
+
+/** @type {(message: string, extra?: Partial<CheckResult>) => CheckResult} */
+export const pass = (message, extra) => ({ status: 'pass', message, ...extra });
+
+/** @type {(message: string, extra?: Partial<CheckResult>) => CheckResult} */
+export const fail = (message, extra) => ({ status: 'fail', message, ...extra });
+
+/** @type {(message: string, extra?: Partial<CheckResult>) => CheckResult} */
+export const warn = (message, extra) => ({ status: 'warn', message, ...extra });
+
+/** @type {(message: string, extra?: Partial<CheckResult>) => CheckResult} */
+export const skip = (message, extra) => ({ status: 'skip', message, ...extra });

package/src/commands/doctor/checks/bundler.js

@@ -0,0 +1,104 @@
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fail, pass, skip, warn } from '../check.js';
+
+/**
+ * The two supported ways to compile Octane, and how to recognise each in a
+ * bundler config. `octane/compiler/*` compiles components only; the
+ * `@octanejs/*-plugin` packages add routing, SSR, and the production build.
+ */
+const INTEGRATIONS = [
+	{ specifier: 'octane/compiler/vite', mode: 'spa', bundler: 'vite' },
+	{ specifier: 'octane/compiler/bundler', mode: 'spa', bundler: 'rspack' },
+	{ specifier: '@octanejs/vite-plugin', mode: 'fullstack', bundler: 'vite' },
+	{ specifier: '@octanejs/rspack-plugin', mode: 'fullstack', bundler: 'rspack' },
+	{ specifier: '@octanejs/rsbuild-plugin', mode: 'fullstack', bundler: 'rsbuild' },
+	{ specifier: '@octanejs/rspeedy-plugin', mode: 'fullstack', bundler: 'rspeedy' },
+];
+
+/**
+ * @param {import('../../../kernel/project.js').Project} project
+ * @returns {string | null}
+ */
+function readBundlerConfig(project) {
+	if (!project.bundlerConfigPath) return null;
+	try {
+		return readFileSync(project.bundlerConfigPath, 'utf8');
+	} catch {
+		return null;
+	}
+}
+
+/** @type {import('../check.js').Check[]} */
+export const bundlerChecks = [
+	{
+		id: 'bundler.plugin-present',
+		title: 'Octane bundler plugin',
+		category: 'bundler',
+		severity: 'error',
+		run(ctx, project) {
+			if (!project.bundlerConfigPath) {
+				return project.tsrxFiles.length > 0
+					? fail('No bundler config found', {
+							detail: [
+								'.tsrx files only compile through an Octane bundler plugin.',
+								'Create a vite.config.ts that registers octane() from octane/compiler/vite.',
+							],
+						})
+					: skip('No bundler config found');
+			}
+
+			const source = readBundlerConfig(project);
+			if (source === null)
+				return skip(`Could not read ${path.basename(project.bundlerConfigPath)}`);
+
+			const matched = INTEGRATIONS.filter((entry) => source.includes(entry.specifier));
+			const file = path.relative(project.root, project.bundlerConfigPath);
+
+			if (matched.length === 0) {
+				return fail(`No Octane plugin registered in ${file}`, {
+					detail: [
+						"For a client-only app:  import { octane } from 'octane/compiler/vite';",
+						"For routing and SSR:    import { octane } from '@octanejs/vite-plugin';",
+					],
+				});
+			}
+
+			if (matched.length > 1) {
+				return warn(`${matched.length} Octane integrations referenced in ${file}`, {
+					detail: [
+						'Register exactly one. The compiler plugin and the metaframework plugin both',
+						'compile .tsrx, so running them together compiles every component twice.',
+						...matched.map((entry) => `  ${entry.specifier}`),
+					],
+				});
+			}
+
+			const [only] = matched;
+			return pass(
+				only.mode === 'fullstack'
+					? `${only.specifier} (routing, SSR, production build)`
+					: `${only.specifier} (client-only compilation)`,
+			);
+		},
+	},
+	{
+		id: 'bundler.build-target',
+		title: 'Build target',
+		category: 'bundler',
+		severity: 'warning',
+		applies: (project) => project.bundlerConfigPath !== null,
+		run(ctx, project) {
+			const source = readBundlerConfig(project);
+			if (source === null) return skip('Could not read the bundler config');
+
+			const match = /\btarget\s*:\s*['"]([^'"]+)['"]/.exec(source);
+			if (!match) return skip('No explicit build target; the bundler default applies');
+			if (match[1] === 'esnext') return pass('target is "esnext"');
+
+			return warn(`Build target is "${match[1]}"`, {
+				detail: ['Octane emits modern output; "esnext" avoids a redundant downlevel pass.'],
+			});
+		},
+	},
+];

package/src/commands/doctor/checks/config.js

@@ -0,0 +1,184 @@
+import { existsSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { readInstalled } from '../../../kernel/project.js';
+import { fail, pass, skip, warn } from '../check.js';
+
+const ADAPTERS = {
+	vercel: '@octanejs/adapter-vercel',
+	cloudflare: '@octanejs/adapter-cloudflare',
+};
+
+/**
+ * Load the project's own config loader rather than shipping a second one.
+ *
+ * `@octanejs/app-core` is usually a transitive dependency of the bundler
+ * plugin, not a direct one, so a plain resolve from the project root misses it.
+ * Falling back to a resolve rooted at the plugin reproduces exactly the lookup
+ * the plugin itself performs.
+ *
+ * @param {string} root
+ * @returns {Promise<((root: string) => Promise<any>) | null>}
+ */
+async function resolveConfigLoader(root) {
+	const fromProject = createRequire(path.join(root, 'noop.js'));
+	const specifier = '@octanejs/app-core/config-loader';
+
+	/** @type {string | null} */
+	let entry = null;
+	try {
+		entry = fromProject.resolve(specifier);
+	} catch {
+		for (const plugin of [
+			'@octanejs/vite-plugin',
+			'@octanejs/rspack-plugin',
+			'@octanejs/rsbuild-plugin',
+		]) {
+			try {
+				entry = createRequire(fromProject.resolve(plugin)).resolve(specifier);
+				break;
+			} catch {
+				// Try the next plugin.
+			}
+		}
+	}
+
+	if (!entry) return null;
+	const module = await import(pathToFileURL(entry).href);
+	return module.loadOctaneConfig ?? null;
+}
+
+/**
+ * Loading the config means running esbuild over `octane.config.ts`. All three
+ * config checks need the same result, so it is computed once instead of three
+ * times per `doctor` run.
+ *
+ * Keyed on the project object rather than its path: `ctx.refreshProject()`
+ * hands out a new object after `--fix` writes, so a refreshed project reloads
+ * instead of serving a stale parse, and the entry dies with the project.
+ *
+ * @type {WeakMap<object, Promise<{ config: any } | { error: string }>>}
+ */
+const loaded = new WeakMap();
+
+/**
+ * @param {import('../../../kernel/project.js').Project} project
+ * @returns {Promise<{ config: any } | { error: string }>}
+ */
+function loadConfig(project) {
+	let pending = loaded.get(project);
+	if (!pending) {
+		pending = (async () => {
+			const load = await resolveConfigLoader(project.root);
+			if (!load) return { error: 'unresolved' };
+			try {
+				return { config: await load(project.root) };
+			} catch (error) {
+				return { error: error instanceof Error ? error.message : String(error) };
+			}
+		})();
+		loaded.set(project, pending);
+	}
+	return pending;
+}
+
+/**
+ * Evaluating `octane.config.ts` means executing it, and it imports the very
+ * packages a not-yet-installed project is missing. Reporting that as a config
+ * error would just restate `deps.octane-installed` in a more confusing way.
+ *
+ * @type {(project: import('../../../kernel/project.js').Project) => boolean}
+ */
+const hasOctaneConfig = (project) =>
+	project.octaneConfigPath !== null && readInstalled(project.root, 'octane') !== null;
+
+/** @type {import('../check.js').Check[]} */
+export const configChecks = [
+	{
+		id: 'config.loads',
+		title: 'octane.config loads',
+		category: 'config',
+		severity: 'error',
+		applies: hasOctaneConfig,
+		async run(ctx, project) {
+			const file = path.basename(/** @type {string} */ (project.octaneConfigPath));
+			const loaded = await loadConfig(project);
+
+			if ('error' in loaded) {
+				return loaded.error === 'unresolved'
+					? skip('@octanejs/app-core is not installed, so the config was not evaluated')
+					: fail(`${file} failed to load`, { detail: [loaded.error] });
+			}
+
+			const routes = loaded.config.router?.routes ?? [];
+			return pass(`${file} loads with ${routes.length} route(s)`);
+		},
+	},
+	{
+		id: 'config.routes-resolve',
+		title: 'Route entries',
+		category: 'config',
+		severity: 'error',
+		applies: hasOctaneConfig,
+		async run(ctx, project) {
+			const loaded = await loadConfig(project);
+			if ('error' in loaded) return skip('The config could not be evaluated');
+
+			const routes = loaded.config.router?.routes ?? [];
+			if (routes.length === 0) return skip('The config declares no routes');
+
+			/** @type {string[]} */
+			const problems = [];
+			/** @type {Map<string, number>} */
+			const seen = new Map();
+
+			for (const route of routes) {
+				const entry = Array.isArray(route.entry) ? route.entry[1] : route.entry;
+				if (typeof entry === 'string' && !existsSync(path.join(project.root, entry))) {
+					problems.push(`${route.path} points at a missing entry: ${entry}`);
+				}
+				seen.set(route.path, (seen.get(route.path) ?? 0) + 1);
+			}
+
+			for (const [routePath, count] of seen) {
+				if (count > 1) problems.push(`${routePath} is declared ${count} times`);
+			}
+
+			const preHydrate = loaded.config.router?.preHydrate;
+			if (typeof preHydrate === 'string' && !existsSync(path.join(project.root, preHydrate))) {
+				problems.push(`preHydrate points at a missing file: ${preHydrate}`);
+			}
+
+			return problems.length === 0
+				? pass(`${routes.length} route entr(ies) resolve`)
+				: fail(`${problems.length} route problem(s)`, {
+						detail: problems.map((line) => `  ${line}`),
+					});
+		},
+	},
+	{
+		id: 'config.adapter-installed',
+		title: 'Deployment adapter',
+		category: 'config',
+		severity: 'warning',
+		applies: hasOctaneConfig,
+		async run(ctx, project) {
+			const loaded = await loadConfig(project);
+			if ('error' in loaded) return skip('The config could not be evaluated');
+
+			const adapter = loaded.config.adapter;
+			const name = typeof adapter === 'string' ? adapter : adapter?.name;
+			if (!name) return skip('No deployment adapter configured');
+
+			const expected = ADAPTERS[/** @type {keyof typeof ADAPTERS} */ (name)];
+			if (!expected) return pass(`Adapter "${name}"`);
+
+			return readInstalled(project.root, expected)
+				? pass(`Adapter "${name}" (${expected})`)
+				: warn(`Adapter "${name}" is configured but ${expected} is not installed`, {
+						detail: [`Add it with: pnpm add -D ${expected}`],
+					});
+		},
+	},
+];

package/src/commands/doctor/checks/dependencies.js

@@ -0,0 +1,120 @@
+import path from 'node:path';
+import { findCopies, readInstalled } from '../../../kernel/project.js';
+import { satisfies } from '../../../kernel/semver.js';
+import { fail, pass, skip, warn } from '../check.js';
+
+/** @type {import('../check.js').Check[]} */
+export const dependencyChecks = [
+	{
+		id: 'deps.octane-installed',
+		title: 'Octane runtime',
+		category: 'dependencies',
+		severity: 'error',
+		run(ctx, project) {
+			const installed = readInstalled(project.root, 'octane');
+			if (installed) return pass(`octane ${installed.version}`);
+			return fail('octane is not installed', {
+				detail: [
+					project.declaredDependencies.octane
+						? 'It is declared in package.json but missing from node_modules. Install dependencies.'
+						: 'Add it with: pnpm add octane',
+				],
+			});
+		},
+	},
+	{
+		id: 'deps.octane-duplicates',
+		title: 'Single Octane runtime',
+		category: 'dependencies',
+		severity: 'error',
+		run(ctx, project) {
+			const copies = findCopies(project.root, 'octane');
+			if (copies.length <= 1) return pass('One copy of octane in the tree');
+
+			return fail(`${copies.length} copies of octane are installed`, {
+				detail: [
+					'Hooks and context are keyed per runtime instance, so a second copy breaks',
+					'them without raising an error. Deduplicate before debugging anything else.',
+					...copies.map((copy) => `  ${copy.version} via ${copy.via} (${copy.realPath})`),
+				],
+			});
+		},
+	},
+	{
+		id: 'deps.vite-peer',
+		title: 'Vite peer range',
+		category: 'dependencies',
+		severity: 'error',
+		applies: (project) => project.bundler === 'vite',
+		run(ctx, project) {
+			const octane = readInstalled(project.root, 'octane');
+			const vite = readInstalled(project.root, 'vite');
+			if (!octane || !vite) return skip('octane or vite is not installed');
+
+			const range = octane.manifest.peerDependencies?.vite;
+			if (!range) return skip('octane declares no vite peer');
+
+			const ok = satisfies(vite.version, range);
+			if (ok === null) return warn(`Could not evaluate vite ${vite.version} against "${range}"`);
+			return ok
+				? pass(`vite ${vite.version} satisfies ${range}`)
+				: fail(`vite ${vite.version} does not satisfy octane's peer range ${range}`, {
+						detail: [`Install a matching Vite: pnpm add -D vite@"${range}"`],
+					});
+		},
+	},
+	{
+		id: 'deps.binding-peers',
+		title: 'Binding peer ranges',
+		category: 'dependencies',
+		severity: 'error',
+		applies: (project) => project.bindings.length > 0,
+		run(ctx, project) {
+			const octane = readInstalled(project.root, 'octane');
+			if (!octane) return skip('octane is not installed');
+
+			/** @type {string[]} */
+			const mismatched = [];
+			let checked = 0;
+
+			for (const name of project.bindings) {
+				const binding = readInstalled(project.root, name);
+				const range = binding?.manifest.peerDependencies?.octane;
+				if (!range) continue;
+				const ok = satisfies(octane.version, range);
+				if (ok === null) continue;
+				checked++;
+				if (!ok) mismatched.push(`${name}@${binding.version} wants octane ${range}`);
+			}
+
+			if (mismatched.length > 0) {
+				return fail(`${mismatched.length} binding(s) disagree with octane ${octane.version}`, {
+					detail: mismatched.map((line) => `  ${line}`),
+				});
+			}
+			return checked > 0
+				? pass(`${checked} binding(s) agree with octane ${octane.version}`)
+				: skip('No binding declares a comparable octane peer range');
+		},
+	},
+	{
+		id: 'deps.tsrx-toolchain',
+		title: 'TSRX toolchain',
+		category: 'dependencies',
+		severity: 'error',
+		applies: (project) => project.tsrxFiles.length > 0,
+		run(ctx, project) {
+			if (readInstalled(project.root, '@tsrx/typescript-plugin')) {
+				return pass('@tsrx/typescript-plugin is installed');
+			}
+			const sample = path.relative(project.root, project.tsrxFiles[0]);
+			return fail('@tsrx/typescript-plugin is not installed', {
+				detail: [
+					`This project has ${project.tsrxFiles.length} .tsrx file(s), starting with ${sample}.`,
+					'It supplies the tsrx-tsc binary and the editor language service.',
+					'Add it with: pnpm add -D @tsrx/typescript-plugin',
+				],
+			});
+		},
+	},
+];

package/src/commands/doctor/checks/environment.js

@@ -0,0 +1,38 @@
+import { fail, pass, warn } from '../check.js';
+
+const MINIMUM_NODE_MAJOR = 22;
+
+/** @type {import('../check.js').Check[]} */
+export const environmentChecks = [
+	{
+		id: 'env.node-version',
+		title: 'Node.js version',
+		category: 'environment',
+		severity: 'error',
+		run(ctx) {
+			const version = ctx.env.OCTANE_DOCTOR_NODE ?? process.versions.node;
+			const major = Number(version.split('.')[0]);
+			return major >= MINIMUM_NODE_MAJOR
+				? pass(`Node ${version}`)
+				: fail(`Node ${version} is below the supported baseline`, {
+						detail: [
+							`Every published Octane package declares "engines": { "node": ">=${MINIMUM_NODE_MAJOR}" }.`,
+						],
+					});
+		},
+	},
+	{
+		id: 'env.package-manager',
+		title: 'Package manager',
+		category: 'environment',
+		severity: 'warning',
+		run(ctx, project) {
+			if (!project.packageManager) {
+				return warn('No lockfile found', {
+					detail: ['Install dependencies so the doctor can inspect the resolved tree.'],
+				});
+			}
+			return pass(`${project.packageManager}${project.lockfile ? ` (${project.lockfile})` : ''}`);
+		},
+	},
+];

package/src/commands/doctor/checks/source.js

@@ -0,0 +1,108 @@
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fail, pass, skip, warn } from '../check.js';
+
+const IMPORTS_OCTANE = /from\s*['"]octane['"]/;
+const OCTANE_PRAGMA = /@jsxImportSource\s+octane/;
+const FORWARD_REF_FROM_OCTANE = /import\s*\{[^}]*\bforwardRef\b[^}]*\}\s*from\s*['"]octane['"]/;
+const REACT_NODE = /\bReact\.ReactNode\b|\bReactNode\b/;
+
+const REPORT_LIMIT = 10;
+
+/**
+ * @param {string} file
+ * @returns {string | null}
+ */
+function read(file) {
+	try {
+		return readFileSync(file, 'utf8');
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * @param {import('../../../kernel/project.js').Project} project
+ * @param {string[]} files
+ * @returns {string[]}
+ */
+function relative(project, files) {
+	const shown = files
+		.slice(0, REPORT_LIMIT)
+		.map((file) => `  ${path.relative(project.root, file)}`);
+	if (files.length > REPORT_LIMIT) shown.push(`  ...and ${files.length - REPORT_LIMIT} more`);
+	return shown;
+}
+
+/** @type {import('../check.js').Check[]} */
+export const sourceChecks = [
+	{
+		id: 'source.jsx-pragma',
+		title: 'JSX pragma on .tsx files',
+		category: 'source',
+		severity: 'error',
+		// Only meaningful when the compiler option is not already project-wide:
+		// with `jsxImportSource: "octane"` in tsconfig, a per-file pragma is
+		// redundant rather than missing.
+		applies: (project) => project.tsconfig?.config.compilerOptions?.jsxImportSource !== 'octane',
+		run(ctx, project) {
+			const candidates = project.sourceFiles.filter((file) => file.endsWith('.tsx'));
+			if (candidates.length === 0) return skip('No .tsx files');
+
+			const missing = candidates.filter((file) => {
+				const source = read(file);
+				return source !== null && IMPORTS_OCTANE.test(source) && !OCTANE_PRAGMA.test(source);
+			});
+
+			if (missing.length === 0) return pass('Every Octane .tsx file declares its JSX source');
+
+			return fail(`${missing.length} .tsx file(s) import octane without the JSX pragma`, {
+				detail: [
+					'Add `/** @jsxImportSource octane */` at the top, or set',
+					'"jsxImportSource": "octane" in tsconfig.json for the whole project.',
+					...relative(project, missing),
+				],
+			});
+		},
+	},
+	{
+		id: 'source.forward-ref',
+		title: 'No forwardRef import',
+		category: 'source',
+		severity: 'error',
+		run(ctx, project) {
+			const offenders = project.sourceFiles.filter((file) => {
+				const source = read(file);
+				return source !== null && FORWARD_REF_FROM_OCTANE.test(source);
+			});
+
+			if (offenders.length === 0) return pass('No forwardRef imported from octane');
+
+			return fail(`${offenders.length} file(s) import forwardRef from octane`, {
+				detail: [
+					'Octane has no forwardRef. Refs are plain props: ref={cb}, ref={obj}, or ref={[a, b]}.',
+					...relative(project, offenders),
+				],
+			});
+		},
+	},
+	{
+		id: 'source.react-node-type',
+		title: 'Renderable type',
+		category: 'source',
+		severity: 'info',
+		applies: (project) => project.tsrxFiles.length > 0,
+		run(ctx, project) {
+			const offenders = project.tsrxFiles.filter((file) => {
+				const source = read(file);
+				return source !== null && REACT_NODE.test(source);
+			});
+
+			if (offenders.length === 0) return pass('Renderables are typed as OctaneNode');
+
+			return warn(`${offenders.length} .tsrx file(s) reference ReactNode`, {
+				detail: ['Use OctaneNode for renderables.', ...relative(project, offenders)],
+			});
+		},
+	},
+];