@octanejs/cli 0.0.0

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

@@ -0,0 +1,183 @@
+import { readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { fail, pass, skip, warn } from '../check.js';
+import { findNestedProperty, setCompilerOption } from '../../../kernel/edit.js';
+
+const TSRX_PLUGIN = '@tsrx/typescript-plugin';
+const WILDCARD_DECL = /^\s*declare\s+module\s+['"]\*\.tsrx['"]/;
+const LEGACY_RESOLUTION = new Set(['node', 'node10', 'classic']);
+// `tsc` as its own command word. `\btsc\b` also matches the tail of `vue-tsc`
+// and `svelte-tsc`, which would fail a healthy script and, under --fix, rewrite
+// it to `vue-tsrx-tsc`. Quotes count as delimiters because the --fix path
+// splices the raw JSON value, quotes included.
+const BARE_TSC = /(^|[\s;&|("'])tsc(?=[\s;&|)"']|$)/;
+const BARE_TSC_GLOBAL = new RegExp(BARE_TSC.source, 'g');
+
+/**
+ * @param {import('../../../kernel/project.js').Project} project
+ * @returns {boolean}
+ */
+const hasTsconfig = (project) => project.tsconfig !== null;
+
+/**
+ * @param {import('../../../kernel/project.js').Project} project
+ * @param {string} key
+ * @param {unknown} value
+ * @returns {import('../check.js').FixOutcome}
+ */
+function applyCompilerOption(project, key, value) {
+	const file = /** @type {NonNullable<typeof project.tsconfig>} */ (project.tsconfig).path;
+	const source = readFileSync(file, 'utf8');
+	const edited = setCompilerOption(source, key, value);
+
+	if (!edited) {
+		return {
+			changed: false,
+			message: `Could not edit ${path.basename(file)} safely; set "${key}" by hand.`,
+		};
+	}
+	if (!edited.changed) return { changed: false, message: `"${key}" is already set.` };
+
+	writeFileSync(file, edited.text);
+	return {
+		changed: true,
+		message: `Set "${key}": ${JSON.stringify(value)}`,
+		files: [path.relative(project.root, file)],
+	};
+}
+
+/** @type {import('../check.js').Check[]} */
+export const typescriptChecks = [
+	{
+		id: 'ts.jsx-import-source',
+		title: 'JSX import source',
+		category: 'typescript',
+		severity: 'error',
+		applies: hasTsconfig,
+		run(ctx, project) {
+			const options = project.tsconfig?.config.compilerOptions ?? {};
+			if (options.jsxImportSource === 'octane') return pass('jsxImportSource is "octane"');
+			return fail(
+				options.jsxImportSource
+					? `jsxImportSource is "${options.jsxImportSource}", not "octane"`
+					: 'jsxImportSource is not set',
+				{ detail: ["Octane JSX resolves through its own runtime, not React's."] },
+			);
+		},
+		fix: (ctx, project) => applyCompilerOption(project, 'jsxImportSource', 'octane'),
+	},
+	{
+		id: 'ts.tsrx-plugin',
+		title: 'TSRX language service',
+		category: 'typescript',
+		severity: 'error',
+		applies: (project) => hasTsconfig(project) && project.tsrxFiles.length > 0,
+		run(ctx, project) {
+			const plugins = project.tsconfig?.config.compilerOptions?.plugins;
+			if (Array.isArray(plugins) && plugins.some((plugin) => plugin?.name === TSRX_PLUGIN)) {
+				return pass(`${TSRX_PLUGIN} is registered`);
+			}
+			return fail(`${TSRX_PLUGIN} is not in compilerOptions.plugins`, {
+				detail: [
+					'Without it the editor cannot resolve .tsrx modules, so every import is `any`.',
+					`Add: "plugins": [{ "name": "${TSRX_PLUGIN}" }]`,
+				],
+			});
+		},
+		fix(ctx, project) {
+			const plugins = project.tsconfig?.config.compilerOptions?.plugins;
+			if (Array.isArray(plugins) && plugins.length > 0) {
+				return {
+					changed: false,
+					message: `compilerOptions.plugins already has entries; add { "name": "${TSRX_PLUGIN}" } by hand.`,
+				};
+			}
+			return applyCompilerOption(project, 'plugins', [{ name: TSRX_PLUGIN }]);
+		},
+	},
+	{
+		id: 'ts.module-resolution',
+		title: 'Module resolution',
+		category: 'typescript',
+		severity: 'warning',
+		applies: hasTsconfig,
+		run(ctx, project) {
+			const resolution = project.tsconfig?.config.compilerOptions?.moduleResolution;
+			if (!resolution) return warn('moduleResolution is not set; "bundler" is expected');
+			if (LEGACY_RESOLUTION.has(String(resolution).toLowerCase())) {
+				return warn(`moduleResolution is "${resolution}"`, {
+					detail: ['Octane packages publish export maps; use "bundler", "node16", or "nodenext".'],
+				});
+			}
+			return pass(`moduleResolution is "${resolution}"`);
+		},
+	},
+	{
+		id: 'ts.typecheck-script',
+		title: 'Typecheck script',
+		category: 'typescript',
+		severity: 'warning',
+		applies: (project) => project.tsrxFiles.length > 0,
+		run(ctx, project) {
+			const script = project.manifest.scripts?.typecheck;
+			if (!script) return skip('No typecheck script');
+			if (script.includes('tsrx-tsc')) return pass('typecheck runs tsrx-tsc');
+			if (!BARE_TSC.test(script)) return skip(`typecheck runs "${script}"`);
+			return fail('typecheck runs plain tsc', {
+				detail: [
+					'Plain tsc cannot read .tsrx. Any program containing them must use tsrx-tsc.',
+					`Current: ${script}`,
+				],
+			});
+		},
+		fix(ctx, project) {
+			const file = path.join(project.root, 'package.json');
+			const source = readFileSync(file, 'utf8');
+			const range = findNestedProperty(source, ['scripts', 'typecheck']);
+			if (!range) return { changed: false, message: 'Could not locate the typecheck script.' };
+
+			const current = source.slice(range.valueStart, range.valueEnd);
+			const replaced = current.replace(BARE_TSC_GLOBAL, (_m, before) => `${before}tsrx-tsc`);
+			if (replaced === current) return { changed: false, message: 'Nothing to replace.' };
+
+			writeFileSync(
+				file,
+				source.slice(0, range.valueStart) + replaced + source.slice(range.valueEnd),
+			);
+			return {
+				changed: true,
+				message: 'Rewrote typecheck to use tsrx-tsc',
+				files: ['package.json'],
+			};
+		},
+	},
+	{
+		id: 'ts.wildcard-tsrx-decl',
+		title: 'No wildcard .tsrx declaration',
+		category: 'typescript',
+		severity: 'error',
+		run(ctx, project) {
+			const offenders = project.sourceFiles.filter((file) => {
+				if (!/\.(?:[cm]?tsx?|d\.ts)$/.test(file)) return false;
+				try {
+					return readFileSync(file, 'utf8')
+						.split('\n')
+						.some((line) => WILDCARD_DECL.test(line));
+				} catch {
+					return false;
+				}
+			});
+
+			if (offenders.length === 0) return pass('No wildcard .tsrx module declaration');
+
+			return fail(`declare module '*.tsrx' found in ${offenders.length} file(s)`, {
+				detail: [
+					'This silences .tsrx resolution instead of fixing it, so every import it covers',
+					'resolves to `any`, including your own components.',
+					'Remove it, then install @tsrx/typescript-plugin and typecheck with tsrx-tsc.',
+					...offenders.map((file) => `  ${path.relative(project.root, file)}`),
+				],
+			});
+		},
+	},
+];

package/src/commands/doctor/index.js

@@ -0,0 +1,118 @@
+import { defineCommand } from '../../kernel/command.js';
+import { EXIT, usageError } from '../../kernel/errors.js';
+import { summarizeProject } from '../../kernel/project.js';
+import { fail, skip } from './check.js';
+import { CATEGORIES, CHECKS } from './registry.js';
+import { hasErrors, isRepairable, renderFindings, renderSummary, toJson } from './report.js';
+
+/**
+ * @param {import('../../kernel/context.js').Ctx} ctx
+ * @param {import('../../kernel/project.js').Project} project
+ * @param {import('./check.js').Check} check
+ * @returns {Promise<import('./check.js').CheckResult>}
+ */
+async function runCheck(ctx, project, check) {
+	if (check.applies && !check.applies(project)) return skip('Does not apply to this project');
+	try {
+		return await check.run(ctx, project);
+	} catch (error) {
+		// One broken check must not hide the other twenty.
+		return fail(`Check failed to run: ${error instanceof Error ? error.message : String(error)}`);
+	}
+}
+
+export default defineCommand({
+	description:
+		'Inspect the project for the configuration and dependency mistakes that break Octane\n' +
+		'quietly: a duplicated runtime, a missing JSX source, plain tsc over .tsrx.',
+	flags: {
+		fix: { type: 'boolean', description: 'Apply the repairs that are mechanical and unambiguous.' },
+		only: {
+			type: 'string',
+			repeatable: true,
+			placeholder: '<id>',
+			description: 'Run a single check by id. Repeatable.',
+		},
+		category: {
+			type: 'string',
+			placeholder: '<name>',
+			choices: CATEGORIES,
+			description: 'Run only one category of checks.',
+		},
+	},
+
+	async run(ctx, input) {
+		const selected = CHECKS.filter((check) => {
+			if (input.flags.category && check.category !== input.flags.category) return false;
+			if (input.flags.only?.length > 0 && !input.flags.only.includes(check.id)) return false;
+			return true;
+		});
+
+		if (selected.length === 0) {
+			throw usageError('No checks matched.', 'Run `octane doctor --help` to see the filters.');
+		}
+
+		const project = ctx.project();
+		ctx.ui.intro('octane doctor');
+
+		const spinner = ctx.ui.spinner(`Checking ${project.root}`);
+		/** @type {import('./report.js').Finding[]} */
+		const findings = [];
+		for (const check of selected) {
+			findings.push({ check, result: await runCheck(ctx, project, check) });
+		}
+		spinner.stop(`Ran ${selected.length} check(s)`);
+
+		if (input.flags.fix) await applyFixes(ctx, project, findings);
+
+		renderFindings(ctx, findings);
+		renderSummary(ctx, findings);
+
+		return {
+			exitCode: hasErrors(findings) ? EXIT.DIAGNOSTIC : EXIT.OK,
+			json: toJson(findings, summarizeProject(project)),
+		};
+	},
+});
+
+/**
+ * Repair what can be repaired, then re-run those checks so the report shows the
+ * state after the edit rather than the state that prompted it.
+ *
+ * @param {import('../../kernel/context.js').Ctx} ctx
+ * @param {import('../../kernel/project.js').Project} project
+ * @param {import('./report.js').Finding[]} findings
+ */
+async function applyFixes(ctx, project, findings) {
+	const repairable = findings.filter(isRepairable);
+	if (repairable.length === 0) return;
+
+	if (ctx.dryRun) {
+		for (const finding of repairable) {
+			finding.fixed = { changed: false, message: 'would be fixed (--dry-run)' };
+		}
+		return;
+	}
+
+	const confirmed = await ctx.ui.confirm({
+		message: `Apply ${repairable.length} fix(es) to this project?`,
+		flag: '--yes',
+		initial: true,
+	});
+	if (!confirmed) return;
+
+	for (const finding of repairable) {
+		const fix = /** @type {NonNullable<typeof finding.check.fix>} */ (finding.check.fix);
+		try {
+			finding.fixed = await fix(ctx, project);
+		} catch (error) {
+			finding.fixed = {
+				changed: false,
+				message: `fix failed: ${error instanceof Error ? error.message : String(error)}`,
+			};
+		}
+		if (finding.fixed.changed) {
+			finding.result = await runCheck(ctx, ctx.refreshProject(), finding.check);
+		}
+	}
+}

package/src/commands/doctor/registry.js

@@ -0,0 +1,32 @@
+import { bundlerChecks } from './checks/bundler.js';
+import { configChecks } from './checks/config.js';
+import { dependencyChecks } from './checks/dependencies.js';
+import { environmentChecks } from './checks/environment.js';
+import { sourceChecks } from './checks/source.js';
+import { typescriptChecks } from './checks/typescript.js';
+
+/**
+ * Report order, cheapest and most fundamental first: a wrong Node version or a
+ * duplicated runtime explains failures further down the list, so it is shown
+ * before them.
+ *
+ * @type {import('./check.js').Check['category'][]}
+ */
+export const CATEGORIES = [
+	'environment',
+	'dependencies',
+	'bundler',
+	'typescript',
+	'config',
+	'source',
+];
+
+/** @type {import('./check.js').Check[]} */
+export const CHECKS = [
+	...environmentChecks,
+	...dependencyChecks,
+	...bundlerChecks,
+	...typescriptChecks,
+	...configChecks,
+	...sourceChecks,
+];

package/src/commands/doctor/report.js

@@ -0,0 +1,158 @@
+import { SYMBOLS } from '../../kernel/ui.js';
+import { CATEGORIES } from './registry.js';
+
+/**
+ * @typedef {Object} Finding
+ * @property {import('./check.js').Check} check
+ * @property {import('./check.js').CheckResult} result
+ * @property {import('./check.js').FixOutcome} [fixed]
+ */
+
+/**
+ * A check reports what it found; its severity decides how much that counts.
+ * Everything downstream (glyph, summary, exit code) reads this one function, so
+ * the report can never show a red mark next to a count that calls it a warning.
+ *
+ * @param {Finding} finding
+ * @returns {'pass' | 'fail' | 'warn' | 'skip'}
+ */
+export function level({ check, result }) {
+	if (result.status === 'pass' || result.status === 'skip') return result.status;
+	return result.status === 'fail' && check.severity === 'error' ? 'fail' : 'warn';
+}
+
+/**
+ * @param {Finding[]} findings
+ * @returns {{ pass: number, fail: number, warn: number, skip: number }}
+ */
+export function summarize(findings) {
+	const totals = { pass: 0, fail: 0, warn: 0, skip: 0 };
+	for (const finding of findings) totals[level(finding)]++;
+	return totals;
+}
+
+/**
+ * Only an `error`-severity finding makes the run itself unsuccessful. Warnings
+ * are advice, and a `skip` means the check did not apply.
+ *
+ * @param {Finding[]} findings
+ * @returns {boolean}
+ */
+export function hasErrors(findings) {
+	return findings.some((finding) => level(finding) === 'fail');
+}
+
+/**
+ * A finding is worth repairing when it reported a problem and its check knows
+ * how to fix it.
+ *
+ * @param {Finding} finding
+ * @returns {boolean}
+ */
+export function isRepairable(finding) {
+	return (
+		(finding.result.status === 'fail' || finding.result.status === 'warn') &&
+		Boolean(finding.check.fix)
+	);
+}
+
+/**
+ * @param {import('../../kernel/ui.js').Ui} ui
+ * @param {Finding} finding
+ * @returns {string}
+ */
+function glyph(ui, finding) {
+	const { colors } = ui;
+	switch (level(finding)) {
+		case 'pass':
+			return colors.green(SYMBOLS.pass);
+		case 'skip':
+			return colors.dim(SYMBOLS.skip);
+		case 'warn':
+			return colors.yellow(SYMBOLS.warn);
+		default:
+			return colors.red(SYMBOLS.fail);
+	}
+}
+
+/**
+ * @param {import('../../kernel/context.js').Ctx} ctx
+ * @param {Finding[]} findings
+ */
+export function renderFindings(ctx, findings) {
+	const { ui } = ctx;
+	const visible = ctx.verbose ? findings : findings.filter((f) => f.result.status !== 'skip');
+	const width = visible.reduce((max, f) => Math.max(max, f.check.title.length), 0);
+
+	for (const category of CATEGORIES) {
+		const group = visible.filter((f) => f.check.category === category);
+		if (group.length === 0) continue;
+
+		ui.log('');
+		ui.log(ui.colors.bold(category));
+
+		for (const finding of group) {
+			const { check, result, fixed } = finding;
+			const title = check.title.padEnd(width);
+			ui.log(`  ${glyph(ui, finding)} ${title}  ${ui.colors.dim(result.message)}`);
+
+			if (result.status !== 'pass' && result.status !== 'skip') {
+				for (const line of result.detail ?? []) ui.log(`      ${ui.colors.dim(line)}`);
+			}
+			if (fixed?.changed) ui.log(`      ${ui.colors.green(`fixed: ${fixed.message}`)}`);
+			else if (fixed) ui.log(`      ${ui.colors.yellow(fixed.message)}`);
+		}
+	}
+}
+
+/**
+ * @param {import('../../kernel/context.js').Ctx} ctx
+ * @param {Finding[]} findings
+ */
+export function renderSummary(ctx, findings) {
+	const { colors } = ctx.ui;
+	const totals = summarize(findings);
+	/** @type {string[]} */
+	const parts = [];
+
+	if (totals.fail > 0) parts.push(colors.red(`${totals.fail} failing`));
+	if (totals.warn > 0)
+		parts.push(colors.yellow(`${totals.warn} warning${totals.warn === 1 ? '' : 's'}`));
+	parts.push(colors.green(`${totals.pass} passing`));
+	if (totals.skip > 0 && ctx.verbose) parts.push(colors.dim(`${totals.skip} skipped`));
+
+	ctx.ui.log('');
+	ctx.ui.log(parts.join(colors.dim(' · ')));
+
+	const fixable = findings.filter((finding) => isRepairable(finding) && !finding.fixed);
+	if (fixable.length > 0) {
+		const noun = fixable.length === 1 ? 'finding' : 'findings';
+		ctx.ui.log(colors.dim(`\`octane doctor --fix\` can repair ${fixable.length} ${noun}.`));
+	}
+}
+
+/**
+ * @param {Finding[]} findings
+ * @param {Record<string, unknown>} project
+ * @returns {Record<string, unknown>}
+ */
+export function toJson(findings, project) {
+	return {
+		ok: !hasErrors(findings),
+		summary: summarize(findings),
+		project,
+		checks: findings.map(({ check, result, fixed }) => ({
+			id: check.id,
+			title: check.title,
+			category: check.category,
+			severity: check.severity,
+			status: result.status,
+			message: result.message,
+			detail: result.detail ?? [],
+			fixable: Boolean(check.fix),
+			...(fixed
+				? { fixed: { changed: fixed.changed, message: fixed.message, files: fixed.files ?? [] } }
+				: {}),
+		})),
+	};
+}

package/src/commands/explain.js

@@ -0,0 +1,95 @@
+import { defineCommand } from '../kernel/command.js';
+import { DATA, ERROR_DOCS_URL } from '../data/index.js';
+import { CliError, usageError } from '../kernel/errors.js';
+
+/**
+ * Pull the code and any encoded arguments out of whatever the user pasted.
+ *
+ * A production build reports `Minified Octane error #3; visit
+ * https://octanejs.dev/errors/3?args[]=...`, which hides the real message and
+ * its arguments behind a URL. Accepting that string verbatim is the whole point
+ * of this command, so a bare number, a `#3`, and the full sentence all work.
+ *
+ * @param {string} input
+ * @returns {{ code: string, args: string[] } | null}
+ */
+export function parseErrorReference(input) {
+	const code = /(?:#|errors\/)(\d+)|^\s*(\d+)\s*$/.exec(input);
+	if (!code) return null;
+
+	const args = [...input.matchAll(/args\[\]=([^&\s]*)/g)].map(([, value]) => {
+		try {
+			return decodeURIComponent(value);
+		} catch {
+			return value;
+		}
+	});
+
+	return { code: code[1] ?? code[2], args };
+}
+
+/**
+ * @param {string} template
+ * @param {string[]} args
+ * @returns {string}
+ */
+function fill(template, args) {
+	let index = 0;
+	return template.replace(/%s/g, () => (index < args.length ? args[index++] : '%s'));
+}
+
+export default defineCommand({
+	description:
+		'Look up an Octane runtime error. Accepts a bare code, or the whole minified\n' +
+		'message a production build prints, arguments included.',
+	positionals: [
+		{ name: 'error', description: 'An error code, URL, or pasted message.', required: true },
+	],
+
+	async run(ctx, input) {
+		const raw = input.positionals.join(' ').trim();
+		if (!raw) throw usageError('Nothing to explain.', 'Try: octane explain 3');
+
+		const reference = parseErrorReference(raw);
+		if (!reference) {
+			throw usageError(`Could not find an error code in "${raw}".`, 'Try: octane explain 3');
+		}
+
+		const entry = DATA.errorCodes[reference.code];
+		if (!entry) {
+			throw new CliError(`Unknown Octane error code ${reference.code}.`, {
+				hint: `This CLI knows codes 1 to ${Object.keys(DATA.errorCodes).length}. Upgrade @octanejs/cli if the code is newer.`,
+			});
+		}
+
+		const message = fill(entry.message, reference.args);
+		const url = `${ERROR_DOCS_URL}${reference.code}`;
+
+		ctx.ui.intro(`Octane error #${reference.code}`);
+		ctx.ui.log('');
+		ctx.ui.log(`  ${message}`);
+		ctx.ui.log('');
+		ctx.ui.log(`  ${ctx.ui.colors.dim(`runtime: ${entry.runtime.join(', ')}`)}`);
+		if (entry.status !== 'active') {
+			ctx.ui.log(`  ${ctx.ui.colors.yellow(`status: ${entry.status}`)}`);
+		}
+		if (entry.message.includes('%s') && reference.args.length === 0) {
+			ctx.ui.log(
+				`  ${ctx.ui.colors.dim('Paste the whole error message to have its arguments filled in.')}`,
+			);
+		}
+		ctx.ui.outro(url);
+
+		return {
+			json: {
+				code: Number(reference.code),
+				message,
+				template: entry.message,
+				args: reference.args,
+				runtime: entry.runtime,
+				status: entry.status,
+				url,
+			},
+		};
+	},
+});

package/src/commands/info.js

@@ -0,0 +1,54 @@
+import { defineCommand } from '../kernel/command.js';
+import { summarizeProject } from '../kernel/project.js';
+
+/**
+ * @param {unknown} value
+ * @returns {string}
+ */
+function show(value) {
+	if (value === null || value === undefined) return '-';
+	if (Array.isArray(value)) return value.length === 0 ? '-' : String(value.length);
+	return String(value);
+}
+
+export default defineCommand({
+	description: 'Print the environment and project details worth pasting into a bug report.',
+
+	async run(ctx) {
+		const project = ctx.project();
+		const summary = summarizeProject(project);
+
+		const environment = {
+			cli: ctx.version,
+			node: process.versions.node,
+			platform: `${process.platform} ${process.arch}`,
+		};
+
+		ctx.ui.note('Environment', [
+			`CLI       ${environment.cli}`,
+			`Node      ${environment.node}`,
+			`Platform  ${environment.platform}`,
+		]);
+
+		ctx.ui.note('Project', [
+			`Name      ${show(summary.name)}`,
+			`Root      ${show(summary.root)}`,
+			`Manager   ${show(summary.packageManager)}`,
+			`Bundler   ${show(summary.bundler)}${summary.bundlerConfig ? ` (${summary.bundlerConfig})` : ''}`,
+			`Octane    ${show(summary.octane)}`,
+			`Config    ${show(summary.octaneConfig)}`,
+			`tsconfig  ${show(summary.tsconfig)}`,
+			`.tsrx     ${show(summary.tsrxFileCount)} file(s)`,
+		]);
+
+		const bindings = /** @type {{ name: string, version: string | null }[]} */ (summary.bindings);
+		if (bindings.length > 0) {
+			ctx.ui.note(
+				'Bindings',
+				bindings.map((binding) => `${binding.name}@${binding.version ?? 'not installed'}`),
+			);
+		}
+
+		return { json: { environment, project: summary } };
+	},
+});