@octanejs/cli 0.0.12 → 0.2.0

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
 ```
 
 ```
@@ -88,6 +92,41 @@ A file that will not parse is reported as an error and does not stop the rest of
 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. 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
+
+`octane analyze --strong-baseline init` records every module that compiles
+without Strong mode in `octane-strong-baseline.json`. While that file exists,
+every run fails on a module that is neither Strong nor listed
+(`OCTANE_STRONG_COVERAGE_REGRESSION`), such as one whose `"use strong"` was
+deleted, and on a listed name that is now Strong or gone
+(`OCTANE_STRONG_COVERAGE_STALE`). `--strong-baseline update` removes stale
+names and never adds one, so a new exception is always a reviewed edit to the
+file. See
+[Keeping modules Strong](https://github.com/octanejs/octane/blob/main/docs/strong-compiler-checks.md#keeping-modules-strong).
+
 ## For agents and CI
 
 Every command is fully drivable by flags and emits a single JSON document under

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@octanejs/cli",
-  "version": "0.0.12",
+  "version": "0.2.0",
   "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}`;
+		},
+	);
+}