@octanejs/cli 0.1.0 → 0.2.1

package/src/commands/analyze/strong-coverage.js

@@ -115,6 +115,26 @@ export async function loadStrongPolicy(project, { required }) {
 	};
 }
 
+/**
+ * The installed compiler's leading `@jsxImportSource` scanner, for deciding
+ * which `.tsx` modules are Octane JSX when no Strong policy was loaded. `null`
+ * when the installed octane predates it.
+ *
+ * @param {string} root
+ * @returns {Promise<Pick<StrongPolicy, 'jsxPragma'> | null>}
+ */
+export async function loadJsxPragma(root) {
+	try {
+		const require = createRequire(path.join(root, 'noop.js'));
+		const bundler = await import(pathToFileURL(require.resolve('octane/compiler/bundler')).href);
+		return typeof bundler.findLeadingJsxImportSourcePragma === 'function'
+			? { jsxPragma: bundler.findLeadingJsxImportSourcePragma }
+			: null;
+	} catch {
+		return null;
+	}
+}
+
 /**
  * An import of octane or one of its subpaths, capturing its clause. The clause
  * may span lines but never reaches into the next `import`, so a semicolon-free
@@ -166,7 +186,7 @@ function isOctaneJsxSource(source) {
  * @param {string} absolute
  * @param {string} source
  * @param {string | undefined} jsxImportSource from tsconfig
- * @param {StrongPolicy} policy
+ * @param {Pick<StrongPolicy, 'jsxPragma'>} policy
  */
 export function isOctaneModule(absolute, source, jsxImportSource, policy) {
 	if (absolute.endsWith('.d.ts')) return false;

package/src/commands/explain.js

@@ -28,6 +28,69 @@ export function parseErrorReference(input) {
 	return { code: code[1] ?? code[2], args };
 }
 
+/**
+ * Find a Strong compiler diagnostic in what the user pasted: the code itself,
+ * the code without its `OCTANE_STRONG_` prefix, a whole compile error, or its
+ * documentation link.
+ *
+ * @param {string} input
+ * @returns {string | null} the full code, whether or not it is known
+ */
+export function parseStrongReference(input) {
+	const code = /\bOCTANE_[A-Z0-9_]+\b/i.exec(input);
+	if (code) return code[0].toUpperCase();
+	const anchor = /#(octane-[a-z0-9-]+)/i.exec(input);
+	if (anchor) return anchor[1].toUpperCase().replaceAll('-', '_');
+	const short = /^\s*([A-Z][A-Z0-9]*(?:_[A-Z0-9]+)+)\s*$/i.exec(input);
+	return short ? `OCTANE_STRONG_${short[1].toUpperCase()}` : null;
+}
+
+/**
+ * @param {import('../kernel/context.js').Ctx} ctx
+ * @param {string} code
+ */
+function explainStrong(ctx, code) {
+	const entry = DATA.strongDiagnostics?.diagnostics?.[code];
+	if (!entry) {
+		throw new CliError(`Unknown Strong diagnostic ${code}.`, {
+			hint: 'Upgrade @octanejs/cli if the code is newer, or see https://octanejs.dev/docs/strong-mode#diagnostic-reference',
+		});
+	}
+	/** @typedef {{ id: string, title: string, react: string, strong: string, codes: string[] }} Recipe */
+	/** @type {Recipe[]} */
+	const recipes = (DATA.strongDiagnostics.recipes ?? []).filter((/** @type {Recipe} */ recipe) =>
+		recipe.codes.includes(code),
+	);
+
+	ctx.ui.intro(code);
+	ctx.ui.log('');
+	ctx.ui.log(`  ${entry.detects}`);
+	ctx.ui.log('');
+	ctx.ui.log(`  ${ctx.ui.colors.bold('Replacement:')} ${entry.replacement}`);
+	for (const recipe of recipes) {
+		ctx.ui.log('');
+		ctx.ui.log(`  ${ctx.ui.colors.bold(recipe.title)}`);
+		ctx.ui.log(`    ${ctx.ui.colors.dim('React: ')} ${recipe.react}`);
+		ctx.ui.log(`    ${ctx.ui.colors.dim('Strong:')} ${recipe.strong}`);
+	}
+	if (entry.severity === 'hint') {
+		ctx.ui.log('');
+		ctx.ui.log(`  ${ctx.ui.colors.dim('severity: hint')}`);
+	}
+	ctx.ui.outro(entry.url);
+
+	return {
+		json: {
+			code,
+			severity: entry.severity,
+			detects: entry.detects,
+			replacement: entry.replacement,
+			recipes,
+			url: entry.url,
+		},
+	};
+}
+
 /**
  * @param {string} template
  * @param {string[]} args
@@ -40,8 +103,9 @@ function fill(template, args) {
 
 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.',
+		'Look up an Octane runtime error or Strong compiler diagnostic. Accepts a bare\n' +
+		'code, the whole minified message a production build prints, arguments\n' +
+		'included, or a Strong code such as OCTANE_STRONG_RENDER_REF_READ.',
 	positionals: [
 		{ name: 'error', description: 'An error code, URL, or pasted message.', required: true },
 	],
@@ -50,6 +114,13 @@ export default defineCommand({
 		const raw = input.positionals.join(' ').trim();
 		if (!raw) throw usageError('Nothing to explain.', 'Try: octane explain 3');
 
+		// Runtime errors are numbered and Strong diagnostics are named, so a
+		// pasted message names at most one kind.
+		const strong = parseStrongReference(raw);
+		if (strong !== null && (/\bOCTANE_/i.test(raw) || parseErrorReference(raw) === null)) {
+			return explainStrong(ctx, strong);
+		}
+
 		const reference = parseErrorReference(raw);
 		if (!reference) {
 			throw usageError(`Could not find an error code in "${raw}".`, 'Try: octane explain 3');

package/src/commands/init/index.js

@@ -4,6 +4,7 @@ import { defineCommand } from '../../kernel/command.js';
 import { setCompilerOption } from '../../kernel/edit.js';
 import { CliError, EXIT } from '../../kernel/errors.js';
 import { PACKAGE_MANAGERS, PNPM_ALLOWED_BUILDS, installPackages } from '../../kernel/install.js';
+import { readInstalled } from '../../kernel/project.js';
 import {
 	MODES,
 	PRETTIER_CONFIG_FILES,
@@ -425,10 +426,16 @@ export async function applyInit(ctx, project, options) {
 	const declared = project.declaredDependencies;
 	const dependencies = integration.dependencies.filter((name) => !declared[name]);
 	const devDependencies = integration.devDependencies.filter((name) => !declared[name]);
+	const needsParser = !declared['@tsrx/oxc'];
 
 	ctx.ui.intro(options.title);
 
-	if (changes.length === 0 && dependencies.length === 0 && devDependencies.length === 0) {
+	if (
+		changes.length === 0 &&
+		dependencies.length === 0 &&
+		devDependencies.length === 0 &&
+		!needsParser
+	) {
 		ctx.ui.outro('Already set up. Run `octane doctor` to confirm.');
 		return { json: { ok: true, mode, changes: [], installed: [] } };
 	}
@@ -439,10 +446,11 @@ export async function applyInit(ctx, project, options) {
 			? changes.map((c) => `${c.file}  ${ctx.ui.colors.dim(c.summary)}`)
 			: ['nothing'],
 	);
-	if (dependencies.length + devDependencies.length > 0) {
+	if (dependencies.length + devDependencies.length > 0 || needsParser) {
 		ctx.ui.note('Will install', [
 			...dependencies,
 			...devDependencies.map((name) => `${name} (dev)`),
+			...(needsParser ? ['@tsrx/oxc (dev)'] : []),
 		]);
 	}
 
@@ -463,7 +471,10 @@ export async function applyInit(ctx, project, options) {
 	const warn = (/** @type {string[]} */ lines) => {
 		for (const line of lines) if (!manual.includes(line)) manual.push(line);
 	};
-	if (options.install !== false && dependencies.length + devDependencies.length > 0) {
+	if (
+		options.install !== false &&
+		(dependencies.length + devDependencies.length > 0 || needsParser)
+	) {
 		const spinner = ctx.ui.spinner(`Installing with ${installing.packageManager ?? 'npm'}`);
 		try {
 			for (const [names, dev] of [
@@ -479,6 +490,23 @@ export async function applyInit(ctx, project, options) {
 				installed.push(.../** @type {string[]} */ (names));
 			}
 
+			if (needsParser) {
+				const octane = readInstalled(project.root, 'octane');
+				const range =
+					octane?.manifest.peerDependencies?.['@tsrx/oxc'] ??
+					octane?.manifest.dependencies?.['@tsrx/oxc'];
+				if (typeof range !== 'string' || range === '' || range.startsWith('catalog:')) {
+					manual.push('Install @tsrx/oxc at the range declared by octane.');
+				} else {
+					const ran = await installPackages(ctx, installing, [`@tsrx/oxc@${range}`], {
+						dev: true,
+						allowBuilds: PNPM_ALLOWED_BUILDS,
+					});
+					warn(ran.warnings);
+					installed.push('@tsrx/oxc');
+				}
+			}
+
 			// Now that the plugin is on disk it can say which TypeScript it runs
 			// under. A package manager that installs required peers has already
 			// put one there and this pins the same range explicitly; one that does
@@ -501,14 +529,17 @@ export async function applyInit(ctx, project, options) {
 			throw error;
 		}
 		spinner.stop(`Installed ${installed.length} package(s)`);
-	} else if (dependencies.length + devDependencies.length > 0) {
+	} else if (dependencies.length + devDependencies.length > 0 || needsParser) {
 		// The range lives in the plugin, which is not installed yet, so it cannot
 		// be quoted here. Naming the package without one would send people to the
 		// newest major, which `tsrx-tsc` cannot start under.
-		manual.push(
-			`Install: ${[...dependencies, ...devDependencies].join(' ')}`,
-			'then typescript, at the range @tsrx/typescript-plugin declares as its peer.',
-		);
+		if (dependencies.length + devDependencies.length > 0) {
+			manual.push(
+				`Install: ${[...dependencies, ...devDependencies].join(' ')}`,
+				'then typescript, at the range @tsrx/typescript-plugin declares as its peer.',
+			);
+		}
+		if (needsParser) manual.push('Install @tsrx/oxc at the range declared by octane.');
 	}
 
 	if (manual.length > 0) ctx.ui.note('Do this by hand', manual);