@octanejs/cli 0.1.0 → 0.2.0

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');