@octanejs/cli 0.1.0 → 0.2.1

package/README.md

@@ -25,7 +25,7 @@ pnpm dlx @octanejs/cli doctor
 | `octane analyze` | Compile the project and report every Octane compiler diagnostic, with its code and suggested edit. |
 | `octane add <package>` | Install a binding, by its own name or by the React package it ports, and print its divergences. |
 | `octane bindings [query]` | List and search the `@octanejs/*` bindings. |
-| `octane explain <error>` | Decode a runtime error code, including the minified production message. |
+| `octane explain <error>` | Decode a runtime error code, including the minified production message, or explain a Strong diagnostic such as `OCTANE_STRONG_RENDER_REF_READ`. |
 | `octane info` | Environment and project details worth pasting into a bug report. |
 | `octane mcp add` | Register the Octane MCP server with Claude Code, Codex, Cursor, or VS Code. |
 
@@ -66,15 +66,19 @@ Anything else is reported with the exact remedy rather than guessed at.
 ## `octane analyze`
 
 Where `doctor` checks how the project is wired, `analyze` checks the code. It
-compiles every `.tsrx` through the project's own `octane` and reports what the
-compiler found, so the results are exactly what a build would warn about, and
-new compiler diagnostics show up here without a CLI change.
+compiles every `.tsrx`, and every `.tsx` whose JSX goes to Octane, through the
+project's own `octane` and reports what the compiler found, so the results are
+exactly what a build would warn about, and new compiler diagnostics show up here
+without a CLI change. Every Strong violation in a file is reported, not only the
+first one the build stops at.
 
 ```bash
-octane analyze                              # every .tsrx in the project
+octane analyze                              # every Octane module in the project
 octane analyze src/App.tsrx                 # just these
 octane analyze --code OCTANE_HYDRATE_SPLIT_STYLE
 octane analyze --strict                     # warnings fail the run too
+octane analyze --strong-preview             # what Strong mode would reject, by code
+octane analyze --fix                        # apply the compiler's suggested edits
 ```
 
 ```
@@ -89,7 +93,27 @@ the run. Exit code is `3` when anything error-severity was found, or when
 `--strict` and there were warnings.
 
 Modules that `compiler.strong` in `octane.config.ts` reaches are analyzed in
-Strong mode, as the build compiles them.
+Strong mode, as the build compiles them. A `.tsx` module whose leading
+`@jsxImportSource` pragma, or the tsconfig's `jsxImportSource`, names another
+library is left out unless you name it.
+
+### Migrating to Strong mode
+
+`--strong-preview` compiles every module as if Strong mode were on, reports what
+it would reject, and ends with a count per code. Findings in modules that are not
+Strong yet do not fail the run, so it works as an inventory before you opt in.
+
+`--fix` applies the edits the compiler suggests and then reports what remains:
+React's lazy ref initialization (`if (ref.current === null) ref.current = …`)
+becomes `useLazyRef`, `useMemo(() => value, deps)` becomes `value`, and
+`useCallback(fn, deps)` becomes `fn`. With `--dry-run` it reports the fixes
+without writing them. Under `--json`, each finding with a fix carries its
+`edits` as `{ start, end, text }` offsets into the file.
+
+`octane explain <CODE>` prints what a Strong diagnostic detects, its
+replacement, and the migration recipes for it. It also accepts a pasted compile
+error or its docs link. Every code is documented at
+[octanejs.dev/docs/strong-mode](https://octanejs.dev/docs/strong-mode#diagnostic-reference).
 
 ### Strong coverage
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@octanejs/cli",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "type": "module",
   "engines": {
     "node": ">=22.22.2"

package/src/commands/analyze/fix.js

@@ -0,0 +1,88 @@
+/**
+ * Apply the compiler's structured suggestions to a module's source.
+ *
+ * A suggestion's edits are one unit: the lazy-ref rewrite adds an import,
+ * replaces the `useRef` call, and deletes the `if`, and applying only part of
+ * that would leave the module broken. A suggestion is skipped whole when any
+ * of its edits overlaps an edit already accepted; running `--fix` again picks
+ * it up from the rewritten source. An edit identical to an accepted one, such
+ * as two rewrites adding the same import, is applied once.
+ *
+ * @typedef {{ start: number, end: number, text: string }} Edit
+ * @typedef {{ code: string, edits: Edit[] }} Fix
+ */
+
+/**
+ * @param {Edit} a
+ * @param {Edit} b
+ */
+function overlaps(a, b) {
+	if (a.start === a.end && b.start === b.end) return a.start === b.start;
+	return a.start < b.end && b.start < a.end;
+}
+
+/**
+ * @param {string} source
+ * @param {readonly Fix[]} fixes
+ * @returns {{ text: string, applied: Fix[] }}
+ */
+export function applyFixes(source, fixes) {
+	/** @type {Edit[]} */
+	const accepted = [];
+	/** @type {Fix[]} */
+	const applied = [];
+	for (const fix of fixes) {
+		const fresh = fix.edits.filter(
+			(edit) =>
+				!accepted.some(
+					(other) =>
+						other.start === edit.start && other.end === edit.end && other.text === edit.text,
+				),
+		);
+		if (fresh.some((edit) => accepted.some((other) => overlaps(edit, other)))) continue;
+		accepted.push(...fresh);
+		applied.push(fix);
+	}
+	let text = source;
+	for (const edit of accepted.sort((a, b) => b.start - a.start)) {
+		text = text.slice(0, edit.start) + edit.text + text.slice(edit.end);
+	}
+	return { text, applied };
+}
+
+/** The hooks a fix can replace, whose imports it may leave unused. */
+const REPLACED_HOOKS = new Set(['useCallback', 'useMemo', 'useRef']);
+
+const OCTANE_NAMED_IMPORT =
+	/import\s*\{([^}]*)\}\s*from\s*(['"])octane\2([^\S\n]*;)?([^\S\n]*\n)?/g;
+
+/**
+ * Drop `useMemo`, `useCallback`, and `useRef` from the `octane` import when
+ * the fixes removed their last use. A name that still appears anywhere else,
+ * even in a comment, keeps its import: an unused import is harmless, a missing
+ * one is not.
+ *
+ * @param {string} text
+ * @param {readonly string[]} candidates hook names a fix replaced
+ */
+export function pruneImports(text, candidates) {
+	const names = candidates.filter((name) => REPLACED_HOOKS.has(name));
+	if (names.length === 0) return text;
+	return text.replace(
+		OCTANE_NAMED_IMPORT,
+		(statement, /** @type {string} */ list, quote, semicolon = '', newline = '') => {
+			const specifiers = list
+				.split(',')
+				.map((specifier) => specifier.trim())
+				.filter(Boolean);
+			const kept = specifiers.filter((specifier) => {
+				if (!names.includes(specifier)) return true;
+				const uses = text.match(new RegExp(`\\b${specifier}\\b`, 'g'))?.length ?? 0;
+				return uses > 1;
+			});
+			if (kept.length === specifiers.length) return statement;
+			if (kept.length === 0) return '';
+			return `import { ${kept.join(', ')} } from ${quote}octane${quote}${semicolon}${newline}`;
+		},
+	);
+}

package/src/commands/analyze/index.js

@@ -1,7 +1,8 @@
-import { readFileSync } from 'node:fs';
+import { readFileSync, writeFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
+import { DATA } from '../../data/index.js';
 import { defineCommand } from '../../kernel/command.js';
 import { CliError, EXIT, usageError } from '../../kernel/errors.js';
 import { SOURCE_FILE_LIMIT } from '../../kernel/project.js';
@@ -11,11 +12,13 @@ import {
 	STALE,
 	compareCoverage,
 	isOctaneModule,
+	loadJsxPragma,
 	loadStrongPolicy,
 	projectPath,
 	readBaseline,
 	writeBaseline,
 } from './strong-coverage.js';
+import { applyFixes, pruneImports } from './fix.js';
 
 /**
  * @typedef {Object} Finding
@@ -26,6 +29,19 @@ import {
  * @property {string} code
  * @property {string} message
  * @property {string[]} suggestions
+ * @property {{ start: number, end: number, text: string }[]} [edits] the
+ *   source edits `--fix` applies, as offsets into the file's current text
+ * @property {string} [url] where the code is documented
+ * @property {true} [preview] only reported because `--strong-preview`
+ *   compiled a module that is not Strong as if it were
+ */
+
+/**
+ * @typedef {Object} Compiler
+ * @property {(source: string, filename: string, options?: object) => { diagnostics: readonly any[] }} compile
+ * @property {((source: string, filename: string, options?: object) => { diagnostics: any[], error: unknown }) | null} collectDiagnostics
+ *   every diagnostic in a module, where `compile` throws the first error.
+ *   Older compilers do not have it.
  */
 
 /**
@@ -37,7 +53,7 @@ import {
  * that builds the app.
  *
  * @param {string} root
- * @returns {Promise<(source: string, filename: string, options?: object) => { diagnostics: readonly any[] }>}
+ * @returns {Promise<Compiler>}
  */
 async function loadCompiler(root) {
 	const require = createRequire(path.join(root, 'noop.js'));
@@ -53,7 +69,54 @@ async function loadCompiler(root) {
 	if (typeof module.compile !== 'function') {
 		throw new CliError('The installed octane build exposes no compiler.');
 	}
-	return module.compile;
+	return {
+		compile: module.compile,
+		collectDiagnostics:
+			typeof module.collectDiagnostics === 'function' ? module.collectDiagnostics : null,
+	};
+}
+
+/**
+ * Strong codes and the native text `onChange` error Strong promotes, keyed to
+ * their documentation.
+ *
+ * @type {Record<string, { url: string }>}
+ */
+const STRONG_CODES = DATA.strongDiagnostics?.diagnostics ?? {};
+
+/**
+ * @param {any} diagnostic
+ * @param {string} file
+ * @returns {Finding}
+ */
+function findingOf(diagnostic, file) {
+	/** @type {Finding} */
+	const finding = {
+		file,
+		line: diagnostic.start?.line ?? 1,
+		column: (diagnostic.start?.column ?? 0) + 1,
+		severity:
+			diagnostic.severity === 'error'
+				? 'error'
+				: diagnostic.severity === 'hint'
+					? 'hint'
+					: 'warning',
+		code: diagnostic.code,
+		// The compiler prefixes its own code; the report already has a column
+		// for it.
+		message: String(diagnostic.message).replace(`[${diagnostic.code}] `, ''),
+		suggestions: describeSuggestions(diagnostic.suggestions),
+	};
+	/** @type {{ start: number, end: number, text: string }[] | undefined} */
+	const edits = diagnostic.suggestions?.find((/** @type {any} */ suggestion) =>
+		Array.isArray(suggestion?.edits),
+	)?.edits;
+	if (edits?.length) {
+		finding.edits = edits.map(({ start, end, text }) => ({ start, end, text }));
+	}
+	const url = STRONG_CODES[diagnostic.code]?.url;
+	if (url !== undefined) finding.url = url;
+	return finding;
 }
 
 /**
@@ -92,6 +155,14 @@ const TRAILING_LOCATION = /\s*\(([^()\s]+):(\d+):(\d+)\)\s*$/;
  */
 const COMPILER_CODE = /^(?:[^\n]*?:\d+:\d+: )?\[(OCTANE_[A-Z0-9_]+)\] /;
 
+/**
+ * A leading `"use strong"` directive, after any comments such as a JSX pragma.
+ * Only consulted without a Strong policy, when `compiler.strong` is off and
+ * the directive is the one way a module can be Strong.
+ */
+const STRONG_DIRECTIVE =
+	/^(?:\s|\/\/[^\n]*|\/\*[\s\S]*?\*\/)*(?:(['"])use [^'"]*\1\s*;?\s*)*?(['"])use strong\2/;
+
 /**
  * Normalise a thrown compile failure into a finding.
  *
@@ -147,11 +218,27 @@ export default defineCommand({
 	positionals: [
 		{
 			name: 'path',
-			description: 'Files to analyze. Defaults to every .tsrx in the project.',
+			description:
+				'Files to analyze. Defaults to every .tsrx in the project, and every .tsx whose\n' +
+				'JSX belongs to Octane.',
 			variadic: true,
 		},
 	],
 	flags: {
+		fix: {
+			type: 'boolean',
+			description:
+				'Apply the edits the compiler suggests, such as useMemo(() => value, deps) to\n' +
+				"value and React's lazy ref initialization to useLazyRef, then report what\n" +
+				'remains. --dry-run reports the fixes without writing them.',
+		},
+		'strong-preview': {
+			type: 'boolean',
+			description:
+				'Compile every module as if Strong mode were on and report what it would\n' +
+				'reject, counted by code. Findings in modules that are not Strong yet do not\n' +
+				'fail the run.',
+		},
 		code: {
 			type: 'string',
 			repeatable: true,
@@ -173,7 +260,8 @@ export default defineCommand({
 
 	async run(ctx, input) {
 		const project = ctx.project();
-		const compile = await loadCompiler(project.root);
+		const compiler = await loadCompiler(project.root);
+		const preview = input.flags['strong-preview'] === true;
 
 		// Coverage is a property of the whole project: an explicit file list can
 		// show that one of its files regressed, but not that a recorded exception
@@ -198,24 +286,68 @@ export default defineCommand({
 		}
 		const measureCoverage = baseline !== null || write !== undefined;
 		const { policy, reason } = await loadStrongPolicy(project, { required: measureCoverage });
+		const jsxImportSource = project.tsconfig?.config?.compilerOptions?.jsxImportSource;
 
-		const targets =
-			input.positionals.length > 0
-				? input.positionals.map((file) => path.resolve(ctx.cwd, file))
-				: project.tsrxFiles;
+		/** @type {Map<string, string>} */
+		const sources = new Map();
+		/** @param {string} absolute */
+		const read = (absolute) => {
+			let source = sources.get(absolute);
+			if (source === undefined) {
+				source = readFileSync(absolute, 'utf8');
+				sources.set(absolute, source);
+			}
+			return source;
+		};
+
+		/** @type {string[]} */
+		const notes = [];
+		if (reason !== undefined) notes.push(reason);
+		let targets;
+		if (!whole) {
+			targets = input.positionals.map((file) => path.resolve(ctx.cwd, file));
+		} else {
+			// A .tsx module is analyzed when its JSX goes to Octane, by the same
+			// pragma and tsconfig rule the coverage baseline uses. Another
+			// framework's JSX in a mixed project is left alone.
+			const ownership = policy ?? (await loadJsxPragma(project.root));
+			const tsx = project.sourceFiles.filter((file) => file.endsWith('.tsx'));
+			targets = [...project.tsrxFiles];
+			if (ownership === null) {
+				if (tsx.length > 0) {
+					notes.push(
+						'The installed octane cannot say which .tsx modules are Octane JSX, so only .tsrx files were analyzed. Name .tsx files explicitly, or update octane.',
+					);
+				}
+			} else {
+				for (const absolute of tsx) {
+					let source;
+					try {
+						source = read(absolute);
+					} catch {
+						continue;
+					}
+					if (isOctaneModule(absolute, source, jsxImportSource, ownership)) targets.push(absolute);
+				}
+				targets.sort();
+			}
+		}
+		if (compiler.collectDiagnostics === null) {
+			notes.push(
+				'The installed octane reports only the first error in each file. Update octane to see every finding.',
+			);
+		}
 
 		if (targets.length === 0 && !measureCoverage) {
 			ctx.ui.intro('octane analyze');
-			ctx.ui.outro('No .tsrx files found.');
+			ctx.ui.outro('No Octane modules found.');
 			return { json: { ok: true, analyzed: 0, findings: [] } };
 		}
 
 		ctx.ui.intro('octane analyze');
-		if (reason !== undefined) ctx.ui.log(ctx.ui.colors.yellow(`${SYMBOLS.warn} ${reason}`));
+		for (const note of notes) ctx.ui.log(ctx.ui.colors.yellow(`${SYMBOLS.warn} ${note}`));
 		const spinner = ctx.ui.spinner(`Compiling ${targets.length} file(s)`);
 
-		/** @type {Map<string, string>} */
-		const sources = new Map();
 		/** @type {Map<string, import('./strong-coverage.js').StrongStatus>} */
 		const statuses = new Map();
 		// One parse per module answers both the compile options and coverage.
@@ -228,54 +360,99 @@ export default defineCommand({
 			}
 			return status;
 		};
+
+		/**
+		 * Every finding in one module, under the policy the build applies:
+		 * octane.config's compiler.strong reaches a module without a directive
+		 * of its own. `--strong-preview` applies Strong to every module.
+		 *
+		 * @param {string} absolute
+		 * @param {string} source
+		 * @param {string} file
+		 * @returns {Finding[]}
+		 */
+		const analyzeModule = (absolute, source, file) => {
+			let strong = false;
+			try {
+				const status = statusOf(absolute, source);
+				strong = status?.strong ?? STRONG_DIRECTIVE.test(source);
+			} catch {
+				// Unparseable; the compile below reports it in its own terms.
+			}
+			const options = strong || preview ? { strong: true } : {};
+			/** @type {Finding[]} */
+			const found = [];
+			if (compiler.collectDiagnostics !== null) {
+				// A file that will not compile is the most severe thing analyze can
+				// find, and it must not stop the other files being reported.
+				try {
+					const result = compiler.collectDiagnostics(source, absolute, options);
+					for (const diagnostic of result.diagnostics) found.push(findingOf(diagnostic, file));
+					if (result.error != null) found.push(thrownFailure(result.error, file));
+				} catch (error) {
+					found.push(thrownFailure(error, file));
+				}
+			} else {
+				try {
+					for (const diagnostic of compiler.compile(source, absolute, options).diagnostics ?? []) {
+						found.push(findingOf(diagnostic, file));
+					}
+				} catch (error) {
+					found.push(thrownFailure(error, file));
+				}
+			}
+			if (preview && !strong) {
+				for (const finding of found) {
+					if (finding.code in STRONG_CODES) finding.preview = true;
+				}
+			}
+			return found;
+		};
+
 		/** @type {Finding[]} */
 		const findings = [];
+		let fixedFindings = 0;
+		/** @type {string[]} */
+		const fixedFiles = [];
 		for (const absolute of targets) {
 			const file = displayPath(project.root, ctx.cwd, absolute);
 			let source;
 			try {
-				source = readFileSync(absolute, 'utf8');
+				source = read(absolute);
 			} catch (error) {
 				// Unreadable is not unparseable; saying so sends people to the wrong fix.
 				findings.push(thrownFailure(error, file, 'OCTANE_READ_ERROR'));
 				continue;
 			}
-			sources.set(absolute, source);
-
-			// Analyze under the policy the build applies: octane.config's
-			// compiler.strong reaches this module without a directive of its own.
-			let options = {};
-			try {
-				if (statusOf(absolute, source)?.config) options = { strong: true };
-			} catch {
-				// Unparseable; the compile below reports it in its own terms.
-			}
-			try {
-				for (const diagnostic of compile(source, absolute, options).diagnostics ?? []) {
-					findings.push({
-						file,
-						line: diagnostic.start?.line ?? 1,
-						column: (diagnostic.start?.column ?? 0) + 1,
-						severity:
-							diagnostic.severity === 'error'
-								? 'error'
-								: diagnostic.severity === 'hint'
-									? 'hint'
-									: 'warning',
-						code: diagnostic.code,
-						// The compiler prefixes its own code; the report already has a
-						// column for it.
-						message: String(diagnostic.message).replace(`[${diagnostic.code}] `, ''),
-						suggestions: describeSuggestions(diagnostic.suggestions),
-					});
+			let found = analyzeModule(absolute, source, file);
+			if (input.flags.fix) {
+				const fixes = found.flatMap((finding) =>
+					finding.edits ? [{ code: finding.code, edits: finding.edits }] : [],
+				);
+				if (fixes.length > 0) {
+					const { text, applied } = applyFixes(source, fixes);
+					const next = pruneImports(text, ['useCallback', 'useMemo', 'useRef']);
+					if (applied.length > 0 && next !== source) {
+						fixedFindings += applied.length;
+						fixedFiles.push(file);
+						if (!ctx.dryRun) writeFileSync(absolute, next);
+						// Report what the fixed module still has, not what was fixed.
+						sources.set(absolute, next);
+						statuses.delete(absolute);
+						found = analyzeModule(absolute, next, file);
+					}
 				}
-			} catch (error) {
-				// A file that will not compile is the most severe thing analyze can
-				// find, and it must not stop the other files being reported.
-				findings.push(thrownFailure(error, file));
 			}
+			findings.push(...found);
 		}
 		spinner.stop(`Compiled ${targets.length} file(s)`);
+		if (input.flags.fix) {
+			ctx.ui.log(
+				fixedFindings === 0
+					? 'No findings had an automatic fix.'
+					: `${ctx.dryRun ? 'Would fix' : 'Fixed'} ${fixedFindings} finding(s) in ${fixedFiles.length} file(s).`,
+			);
+		}
 
 		/** @type {Record<string, unknown> | undefined} */
 		let strongCoverage;
@@ -285,7 +462,6 @@ export default defineCommand({
 					`The project has more than ${SOURCE_FILE_LIMIT} source files, so Strong coverage cannot be measured completely.`,
 				);
 			}
-			const jsxImportSource = project.tsconfig?.config?.compilerOptions?.jsxImportSource;
 			/** @type {import('./strong-coverage.js').CoverageModule[]} */
 			const modules = [];
 			/** @type {Set<string>} */
@@ -293,14 +469,12 @@ export default defineCommand({
 			for (const absolute of whole ? project.sourceFiles : targets) {
 				const file = projectPath(project.root, absolute);
 				if (file.startsWith('../') || path.isAbsolute(file)) continue;
-				let source = sources.get(absolute);
-				if (source === undefined) {
-					try {
-						source = readFileSync(absolute, 'utf8');
-					} catch {
-						unmeasured.add(file);
-						continue;
-					}
+				let source;
+				try {
+					source = read(absolute);
+				} catch {
+					unmeasured.add(file);
+					continue;
 				}
 				if (!isOctaneModule(absolute, source, jsxImportSource, policy)) continue;
 				try {
@@ -376,11 +550,33 @@ export default defineCommand({
 
 		render(ctx, selected, targets.length);
 
-		const errors = selected.filter((finding) => finding.severity === 'error').length;
-		const warnings = selected.filter((finding) => finding.severity === 'warning').length;
-		const hints = selected.filter((finding) => finding.severity === 'hint').length;
+		// Preview findings describe modules that are not Strong yet. They are an
+		// inventory, not a failure, so they are summarized apart.
+		const enforced = selected.filter((finding) => finding.preview !== true);
+		const errors = enforced.filter((finding) => finding.severity === 'error').length;
+		const warnings = enforced.filter((finding) => finding.severity === 'warning').length;
+		const hints = enforced.filter((finding) => finding.severity === 'hint').length;
 		const failed = errors > 0 || (input.flags.strict && warnings > 0);
 
+		/** @type {Record<string, unknown> | undefined} */
+		let strongPreview;
+		if (preview) {
+			/** @type {Record<string, number>} */
+			const byCode = {};
+			const modules = new Set();
+			for (const finding of selected) {
+				if (finding.preview !== true) continue;
+				byCode[finding.code] = (byCode[finding.code] ?? 0) + 1;
+				modules.add(finding.file);
+			}
+			strongPreview = {
+				findings: Object.values(byCode).reduce((a, b) => a + b, 0),
+				modules: modules.size,
+				byCode,
+			};
+			renderPreview(ctx, byCode, modules.size);
+		}
+
 		return {
 			exitCode: failed ? EXIT.DIAGNOSTIC : EXIT.OK,
 			json: {
@@ -389,6 +585,8 @@ export default defineCommand({
 				summary: { errors, warnings, hints },
 				findings: selected,
 				...(strongCoverage === undefined ? null : { strongCoverage }),
+				...(strongPreview === undefined ? null : { strongPreview }),
+				...(input.flags.fix ? { fixed: { findings: fixedFindings, files: fixedFiles } } : null),
 			},
 		};
 	},
@@ -436,23 +634,52 @@ function render(ctx, findings, analyzed) {
 						? colors.dim('hint')
 						: colors.yellow(SYMBOLS.warn);
 			const where = colors.dim(`${finding.line}:${finding.column}`);
-			ctx.ui.log(`  ${mark} ${where}  ${finding.message}`);
-			ctx.ui.log(`      ${colors.dim(finding.code)}`);
+			ctx.ui.log(`  ${finding.preview ? colors.dim('strong') : mark} ${where}  ${finding.message}`);
+			ctx.ui.log(
+				`      ${colors.dim(finding.url ? `${finding.code}  ${finding.url}` : finding.code)}`,
+			);
 			for (const suggestion of finding.suggestions) {
-				ctx.ui.log(`      ${colors.dim(`suggestion: ${suggestion}`)}`);
+				ctx.ui.log(
+					`      ${colors.dim(`suggestion: ${suggestion}${finding.edits ? ' (--fix)' : ''}`)}`,
+				);
 			}
 		}
 	}
 
-	const errors = findings.filter((finding) => finding.severity === 'error').length;
-	const warnings = findings.filter((finding) => finding.severity === 'warning').length;
-	const hints = findings.filter((finding) => finding.severity === 'hint').length;
+	const enforced = findings.filter((finding) => finding.preview !== true);
+	const errors = enforced.filter((finding) => finding.severity === 'error').length;
+	const warnings = enforced.filter((finding) => finding.severity === 'warning').length;
+	const hints = enforced.filter((finding) => finding.severity === 'hint').length;
+	const previewed = findings.length - enforced.length;
 	/** @type {string[]} */
 	const parts = [];
 	if (errors > 0) parts.push(colors.red(`${errors} error${errors === 1 ? '' : 's'}`));
 	if (warnings > 0) parts.push(colors.yellow(`${warnings} warning${warnings === 1 ? '' : 's'}`));
 	if (hints > 0) parts.push(colors.dim(`${hints} hint${hints === 1 ? '' : 's'}`));
+	if (previewed > 0) parts.push(`${previewed} Strong preview finding${previewed === 1 ? '' : 's'}`);
 
 	ctx.ui.log('');
 	ctx.ui.log(`${parts.join(colors.dim(' · '))} ${colors.dim(`across ${analyzed} file(s)`)}`);
 }
+
+/**
+ * What adopting Strong would take, by code, most frequent first.
+ *
+ * @param {import('../../kernel/context.js').Ctx} ctx
+ * @param {Record<string, number>} byCode
+ * @param {number} modules
+ */
+function renderPreview(ctx, byCode, modules) {
+	const { colors } = ctx.ui;
+	const entries = Object.entries(byCode).sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]));
+	ctx.ui.log('');
+	if (entries.length === 0) {
+		ctx.ui.log(colors.green('Strong preview: nothing to change.'));
+		return;
+	}
+	ctx.ui.log(colors.bold(`Strong preview: ${modules} module(s) need changes`));
+	for (const [code, count] of entries) {
+		ctx.ui.log(`  ${String(count).padStart(4)}  ${code}`);
+	}
+	ctx.ui.log(colors.dim('  Explain a code with `octane explain <CODE>`.'));
+}