@octanejs/cli 0.0.12 → 0.2.0

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

@@ -0,0 +1,324 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { CliError } from '../../kernel/errors.js';
+import { resolveConfigLoader } from '../../kernel/octane-config.js';
+
+/**
+ * The checked-in list of modules allowed to compile without Strong mode.
+ *
+ * Strong is opt-in per module or per application, so the cheapest way around
+ * a Strong diagnostic is to stop being Strong: delete `"use strong"`, turn
+ * `compiler.strong` off, or move the code into another package. Each of those
+ * is a one-line change that is easy to miss in review. With this file in the
+ * project, every module Octane compiles has to be Strong or be named here, and
+ * `octane analyze` only ever removes names. A new exception therefore shows up
+ * as an edit to this one file, which a team can route to an owner.
+ */
+export const BASELINE_FILE = 'octane-strong-baseline.json';
+
+export const REGRESSION = 'OCTANE_STRONG_COVERAGE_REGRESSION';
+export const STALE = 'OCTANE_STRONG_COVERAGE_STALE';
+
+/**
+ * @typedef {{ strong: boolean, directive: boolean, config: boolean }} StrongStatus
+ *
+ * @typedef {Object} StrongPolicy
+ * @property {boolean} configured `compiler.strong` from octane.config
+ * @property {(source: string, absolute: string) => StrongStatus} status
+ * @property {(source: string) => string | null} jsxPragma the leading
+ *   `@jsxImportSource` module, read by the compiler's own scanner
+ *
+ * @typedef {Object} CoverageModule
+ * @property {string} file project-relative, `/`-separated
+ * @property {string} absolute
+ * @property {StrongStatus} status
+ *
+ * @typedef {Object} Baseline
+ * @property {string} path
+ * @property {string} text
+ * @property {string[]} exceptions
+ */
+
+/**
+ * The project's Strong policy, decided by the project's own compiler.
+ *
+ * `compiler.strong` comes from evaluating octane.config, and the per-module
+ * answer comes from the installed bundler compiler's `strongModuleStatus`, the
+ * same decision its `transform` makes. Nothing here re-derives the directive
+ * prologue or the package-boundary rule.
+ *
+ * `required` is set when the answer is about to gate a run (a baseline exists
+ * or one is being written). A policy that cannot be determined then fails the
+ * run. Otherwise the policy only decides whether `compiler.strong` reaches a
+ * module, so a project without it needs nothing more (`{ policy: null }`), and
+ * one whose setting cannot be applied gets the `reason` to show beside the
+ * diagnostics it could still produce.
+ *
+ * @param {import('../../kernel/project.js').Project} project
+ * @param {{ required: boolean }} options
+ * @returns {Promise<{ policy: StrongPolicy | null, reason?: string }>}
+ */
+export async function loadStrongPolicy(project, { required }) {
+	/** @param {string} reason */
+	const unavailable = (reason) => {
+		if (required) throw new CliError(reason);
+		return { policy: null, reason };
+	};
+
+	let configured = false;
+	if (project.octaneConfigPath !== null) {
+		const file = path.basename(project.octaneConfigPath);
+		const load = await resolveConfigLoader(project.root);
+		if (!load) {
+			return unavailable(
+				`${file} could not be evaluated because @octanejs/app-core is not installed, so its compiler.strong setting is unknown.`,
+			);
+		}
+		try {
+			configured = (await load(project.root)).compiler?.strong === true;
+		} catch (error) {
+			return unavailable(
+				`${file} failed to load, so its compiler.strong setting is unknown: ${
+					error instanceof Error ? error.message : String(error)
+				}`,
+			);
+		}
+	}
+
+	if (!required && !configured) return { policy: null };
+
+	let bundler;
+	try {
+		const require = createRequire(path.join(project.root, 'noop.js'));
+		bundler = await import(pathToFileURL(require.resolve('octane/compiler/bundler')).href);
+	} catch {
+		return unavailable('Could not resolve `octane/compiler/bundler` from this project.');
+	}
+	const compiler = bundler.createOctaneCompiler?.({ root: project.root, strong: configured });
+	if (
+		typeof compiler?.strongModuleStatus !== 'function' ||
+		typeof bundler.findLeadingJsxImportSourcePragma !== 'function'
+	) {
+		return unavailable(
+			'The installed octane cannot report which modules compile under Strong mode. Update octane.',
+		);
+	}
+
+	return {
+		policy: {
+			configured,
+			status: (source, absolute) => compiler.strongModuleStatus(source, absolute),
+			jsxPragma: bundler.findLeadingJsxImportSourcePragma,
+		},
+	};
+}
+
+/**
+ * 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
+ * module cannot borrow a later import's specifier.
+ */
+const OCTANE_IMPORT =
+	/^\s*import\s+((?:(?!\bimport\b)[^;])*?)\s*\bfrom\s*['"]octane(?:\/[^'"]*)?['"]/gm;
+
+/**
+ * Does the module import a runtime binding from octane? TypeScript erases an
+ * `import type` clause and a named clause whose every specifier is
+ * `type`-marked, so neither leaves anything for the compiler to slot. A
+ * default or namespace binding, or any unmarked specifier, survives. Comments
+ * in the clause are not specifiers, so they are dropped before it is read.
+ *
+ * @param {string} source
+ */
+function importsOctaneAtRuntime(source) {
+	for (const [, authored] of source.matchAll(OCTANE_IMPORT)) {
+		const clause = authored.replace(/\/\*[\s\S]*?\*\/|\/\/[^\n]*/g, ' ').trim();
+		if (/^type\b/.test(clause)) continue;
+		const named = /^\{([\s\S]*)\}$/.exec(clause);
+		if (named === null) return true;
+		const specifiers = named[1]
+			.split(',')
+			.map((specifier) => specifier.trim())
+			.filter(Boolean);
+		if (!specifiers.every((specifier) => /^type\s/.test(specifier))) return true;
+	}
+	return false;
+}
+
+/**
+ * @param {string | undefined} source a JSX import source
+ */
+function isOctaneJsxSource(source) {
+	return source === 'octane' || source === 'octane/strong' || !!source?.startsWith('@octanejs/');
+}
+
+/**
+ * Is this a module Octane compiles, and so one Strong can reach?
+ *
+ * `.tsrx` always is. A `.tsx` module is unless its own leading pragma, or the
+ * tsconfig `jsxImportSource`, hands its JSX to another library, as a
+ * React-hosted project does. A plain `.ts`/`.js` module is when it imports
+ * octane at runtime, which is when the compiler slots its hooks. Declaration
+ * files and other extensions never are.
+ *
+ * @param {string} absolute
+ * @param {string} source
+ * @param {string | undefined} jsxImportSource from tsconfig
+ * @param {Pick<StrongPolicy, 'jsxPragma'>} policy
+ */
+export function isOctaneModule(absolute, source, jsxImportSource, policy) {
+	if (absolute.endsWith('.d.ts')) return false;
+	const extension = path.extname(absolute);
+	if (extension === '.tsrx') return true;
+	if (extension === '.tsx') {
+		const pragma = policy.jsxPragma(source);
+		if (pragma !== null) return isOctaneJsxSource(pragma);
+		return jsxImportSource === undefined || isOctaneJsxSource(jsxImportSource);
+	}
+	if (extension === '.ts' || extension === '.js') return importsOctaneAtRuntime(source);
+	return false;
+}
+
+/**
+ * @param {string} root
+ * @param {string} absolute
+ */
+export function projectPath(root, absolute) {
+	return path.relative(root, absolute).split(path.sep).join('/');
+}
+
+/**
+ * @param {string} root
+ * @returns {Baseline | null}
+ */
+export function readBaseline(root) {
+	const file = path.join(root, BASELINE_FILE);
+	if (!existsSync(file)) return null;
+	const text = readFileSync(file, 'utf8');
+	let parsed;
+	try {
+		parsed = JSON.parse(text);
+	} catch (error) {
+		throw new CliError(
+			`${BASELINE_FILE} is not valid JSON: ${error instanceof Error ? error.message : error}`,
+		);
+	}
+	if (
+		parsed?.version !== 1 ||
+		!Array.isArray(parsed.exceptions) ||
+		parsed.exceptions.some((/** @type {unknown} */ entry) => typeof entry !== 'string')
+	) {
+		throw new CliError(
+			`${BASELINE_FILE} must be { "version": 1, "exceptions": [<project-relative paths>] }.`,
+		);
+	}
+	return { path: file, text, exceptions: parsed.exceptions };
+}
+
+/**
+ * Sorted and deduplicated, so the file only changes when its contents do.
+ *
+ * @param {string} root
+ * @param {Iterable<string>} exceptions
+ */
+export function writeBaseline(root, exceptions) {
+	const body = { version: 1, exceptions: [...new Set(exceptions)].sort() };
+	writeFileSync(path.join(root, BASELINE_FILE), `${JSON.stringify(body, null, '\t')}\n`);
+}
+
+/**
+ * Compare the measured modules with the recorded exceptions.
+ *
+ * A non-Strong module that is not listed is a regression: something new, or
+ * something that stopped being Strong. A listed module that is Strong, gone, or
+ * no longer compiled by Octane is stale, and is an error too, because a stale
+ * name is a pre-approved slot for the next regression. Staleness is only known
+ * when every module was measured.
+ *
+ * @param {{
+ *   modules: CoverageModule[],
+ *   baseline: Baseline,
+ *   policy: StrongPolicy,
+ *   complete: boolean,
+ *   unmeasured: ReadonlySet<string>,
+ *   display: (absolute: string) => string,
+ * }} input
+ */
+export function compareCoverage({ modules, baseline, policy, complete, unmeasured, display }) {
+	const listed = new Set(baseline.exceptions);
+	const measured = new Map(modules.map((module) => [module.file, module]));
+	const baselineDisplay = display(baseline.path);
+
+	/** @type {import('./index.js').Finding[]} */
+	const findings = [];
+	/** @type {string[]} */
+	const regressions = [];
+	for (const module of modules) {
+		if (module.status.strong || listed.has(module.file)) continue;
+		regressions.push(module.file);
+		const fix =
+			policy.configured && !module.status.config
+				? 'compiler.strong in octane.config does not reach modules of another package, so add "use strong" before its imports'
+				: 'Add "use strong" before its imports, or enable compiler.strong in octane.config,';
+		findings.push({
+			file: display(module.absolute),
+			line: 1,
+			column: 1,
+			severity: 'error',
+			code: REGRESSION,
+			message: `This module compiles without Strong mode and is not a recorded exception. ${fix} and fix what Strong then reports. A new exception is a reviewed edit to ${BASELINE_FILE}; octane analyze never adds one.`,
+			suggestions: [],
+		});
+	}
+
+	/** @type {string[]} */
+	const stale = [];
+	if (complete) {
+		const lines = baseline.text.split('\n');
+		for (const entry of baseline.exceptions) {
+			const module = measured.get(entry);
+			if (unmeasured.has(entry) || (module !== undefined && !module.status.strong)) continue;
+			stale.push(entry);
+			const why =
+				module !== undefined
+					? 'now compiles with Strong mode'
+					: existsSync(path.join(path.dirname(baseline.path), entry))
+						? 'is not a module Octane compiles'
+						: 'no longer exists';
+			const index = lines.findIndex((line) => line.includes(JSON.stringify(entry)));
+			findings.push({
+				file: baselineDisplay,
+				line: index === -1 ? 1 : index + 1,
+				column: 1,
+				severity: 'error',
+				code: STALE,
+				message: `${entry} ${why}, so it is no longer an exception. Run \`octane analyze --strong-baseline update\` to remove it.`,
+				suggestions: [],
+			});
+		}
+	}
+
+	return { findings, regressions, stale };
+}

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

@@ -1,7 +1,6 @@
 import { existsSync } from 'node:fs';
-import { createRequire } from 'node:module';
 import path from 'node:path';
-import { pathToFileURL } from 'node:url';
+import { resolveConfigLoader } from '../../../kernel/octane-config.js';
 import { readInstalled } from '../../../kernel/project.js';
 import { fail, pass, skip, warn } from '../check.js';
 
@@ -10,45 +9,6 @@ const ADAPTERS = {
 	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

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