Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

feat(cli): report manual migrations and regeneration apart from codemod failures (#7995)

EJ Hammonde8ef708e77f8
diff --git a/.changeset/upgrade-manual-and-regenerate-outcomes.md b/.changeset/upgrade-manual-and-regenerate-outcomes.md
new file mode 100644
index 0000000000..63dd9fa492
--- /dev/null
+++ b/.changeset/upgrade-manual-and-regenerate-outcomes.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/cli': patch
+---
+
+[feat] `astryx upgrade` now reports stale generated files in a new `regenerate` receipt field, and reports code a codemod can identify but not migrate safely in the existing `declinedCandidates` list instead of failing. A manual migration is a `declinedCandidates` row with the file, its line as `location` when known, and a `reason` that starts with `manual migration needed (<codemod>):` followed by what to change (a file with several declined findings keeps one row listing each, with its own prefix, joined by `; `); it is printed after the run, does not fail the upgrade, and the run completes and exits 0. A generated file that must be rebuilt, such as stale theme CSS that `validate-data-token-ownership` reports and `astryx theme build` regenerates, is listed in `regenerate` with its rebuild command until it is rebuilt; a `hooks.postCodemod` command that rebuilds it clears it. When the project protects the file (for example an `@generated` header), the run is incomplete exactly as for a protected file (`complete: false`, `errorCode: "ERR_CODEMOD_PROTECTED"`, exit 1); when nothing protects it, it stays a codemod error (`ERR_CODEMOD_FAILED`, as before), now with the rebuild command in `regenerate`. Protected generated files also appear in `regenerate` with their header's `Command:`, and a reported file the project marks generated also appears in `protectedFiles` with the rule that protects it. A real codemod failure keeps its `ERR_CODEMOD_FAILED` error, and the `receipt` it carries lists both too.
+
+@ejhammond
diff --git a/packages/cli/README.md b/packages/cli/README.md
index 8860c10903..86fb485ad4 100644
--- a/packages/cli/README.md
+++ b/packages/cli/README.md
@@ -522,7 +522,7 @@ Every response has a `type` discriminant. The full set is below (generated from
| `upgrade.list` | Every available codemod, oldest→newest, as {name, package, title, version, optional}; returned for --list without running anything. |
| `upgrade.registry` | The copied-composition receipt for --registry: applied, ok, the counts (found, current, wouldUpdate, updated, wouldMerge, merged, wouldRefreshReceipt, receiptsRefreshed, conflicts, missing, invalid, failed), and items. |
| `upgrade.status` | A short-circuit outcome with no codemods run (up_to_date, no_codemods, or config_fixable), each carrying the agent-docs summary. no_codemods and config_fixable carry cliBehindCore ({cliVersion, command}) when the installed Core is newer than the CLI, which then has no codemods for the releases after its own version. |
-| `upgrade.run` | The run receipt: from/to versions, codemod count, integrations processed, the agent-docs summary, sourcePathFound (false when the resolved source directory does not exist, so no source file was read), and (apply mode) filesChanged, transformsApplied, and per-codemod errors. When the installed Core is newer than the CLI, it also carries cliBehindCore ({cliVersion, command}): codemods for the releases after cliVersion did not run. |
+| `upgrade.run` | The run receipt: from/to versions, codemod count, integrations processed, the agent-docs summary, sourcePathFound (false when the resolved source directory does not exist, so no source file was read), and (apply mode) filesChanged, transformsApplied, and per-codemod errors. regenerate lists generated files to rebuild, each with its codemods, commands and messages. When the installed Core is newer than the CLI, it also carries cliBehindCore ({cliVersion, command}): codemods for the releases after cliVersion did not run. |
| `manifest` | The CLI capability manifest: name, version, apiVersion, description, globalOptions, commands (each name, description, arguments, options, json, aliases?, responseTypes?, examples?, exitCodes? as [{code, when}], outsideProject? (same, refuse, or own; absent on a group), subcommands?), jsonSupported, globalMode ({docs, summary}: what a run may do beyond its command, such as the hand-off to the project's own CLI, the daily update check, and the agent skill file, and the docs topic that explains it), and the flat responseTypes index. |
| `help` | Help, in one of two shapes. A bare `astryx --json` returns the root manifest: name, version, commands (the command names), jsonSupported, and manifest (the full payload `astryx manifest --json` returns). `--help --json` on any command, or `astryx help [command] --json`, returns that command's help: command, description, usage, options (each flags, description, and defaultValue and choices when set), and subcommands (each name and description). data.manifest marks the first shape; data.usage marks the second. |
| `version` | The CLI version, for `astryx --version --json`: {version}. |
diff --git a/packages/cli/api/upgrade/_adapter.mjs b/packages/cli/api/upgrade/_adapter.mjs
index a0bff6727d..df8e4c9197 100644
--- a/packages/cli/api/upgrade/_adapter.mjs
+++ b/packages/cli/api/upgrade/_adapter.mjs
@@ -24,6 +24,7 @@ import {
latestVersion,
} from '../../assets/codemods/registry.mjs';
import {runCodemods} from '../../assets/codemods/runner.mjs';
+import {codemodOutcome} from '../../assets/codemods/outcome.mjs';
import {
discoverIntegrationCodemods,
selectIntegrationCodemods,
@@ -141,7 +142,12 @@ export function relativeToOrigin(result, {cwd: root, origin}) {
};
}
if (data.modifiedFiles) data.modifiedFiles = data.modifiedFiles.map(rebase);
- for (const key of ['protectedFiles', 'declinedCandidates', 'errors']) {
+ for (const key of [
+ 'protectedFiles',
+ 'declinedCandidates',
+ 'errors',
+ 'regenerate',
+ ]) {
if (data[key]) {
data[key] = data[key].map(
(/** @type {{file: string, declarations?: string[]}} */ entry) => ({
@@ -599,11 +605,59 @@ export async function ensureCodemodDeps({installDeps} = {}) {
return ensureJscodeshift({installDeps, silent: logger.silent});
}
+/**
+ * @typedef {{kind: 'manual', file: string, codemod: string, message: string, line?: number} | {kind: 'regenerate', file: string, codemod: string, message: string, commands: string[]}} CodemodOutcomeRecord
+ */
+
+/**
+ * Wrap each core code and config transform so the non-failure outcomes it
+ * throws (`assets/codemods/outcome.mjs`) are recorded instead of reaching the
+ * runner as errors. The wrapped transform leaves that file unchanged, exactly
+ * as the throw did. Project codemods keep their own contract. One wrapper per
+ * pass: the regeneration re-check takes a fresh one, so an outcome a hook
+ * resolved does not linger.
+ *
+ * @template {{version: string, transforms: Array<{name: string, transform: any, meta?: {codemodType?: string}}>}} M
+ * @param {M[]} versionManifests
+ * @param {string} root project root; recorded files are relative to it
+ * @returns {{versionManifests: M[], outcomes: CodemodOutcomeRecord[]}}
+ */
+export function withCodemodOutcomes(versionManifests, root) {
+ /** @type {CodemodOutcomeRecord[]} */
+ const outcomes = [];
+ const wrapped = versionManifests.map(manifest => ({
+ ...manifest,
+ transforms: manifest.transforms.map(entry => {
+ if (entry.meta?.codemodType === 'project') return entry;
+ const {transform, name} = entry;
+ return {
+ ...entry,
+ /** @param {{path: string, source: string}} file @param {unknown} api */
+ transform(file, api) {
+ try {
+ return transform(file, api);
+ } catch (err) {
+ const outcome = codemodOutcome(err);
+ if (!outcome) throw err;
+ outcomes.push({
+ ...outcome,
+ file: path.relative(root, file.path).split(path.sep).join('/'),
+ codemod: `core:${name}`,
+ });
+ return undefined;
+ }
+ },
+ };
+ }),
+ }));
+ return {versionManifests: /** @type {M[]} */ (wrapped), outcomes};
+}
+
/**
* Run the CORE registry codemods. Runs BEFORE the config is loaded so a core
* CONFIG codemod can repair a config the strict loader would otherwise reject.
* @param {CoreVersionManifest[]} versionManifests
- * @param {{apply: boolean, path: string, codemod?: string, skipCodemods: Set<string>, root?: string, protection?: {root: string, classify: (file: string) => import('../../foundation/fs/file-protection.mjs').FileProtection[]}, silent?: boolean, coversTarget?: boolean}} options
+ * @param {{apply: boolean, path: string, codemod?: string, skipCodemods: Set<string>, root?: string, protection?: {root: string, classify: (file: string) => import('../../foundation/fs/file-protection.mjs').FileProtection[]}, silent?: boolean, coversTarget?: boolean, outcomes?: CodemodOutcomeRecord[]}} options
*/
export async function runCoreCodemods(
versionManifests,
@@ -616,6 +670,7 @@ export async function runCoreCodemods(
protection,
silent,
coversTarget,
+ outcomes,
},
) {
return runCodemods(versionManifests, {
@@ -627,6 +682,7 @@ export async function runCoreCodemods(
root,
protection,
coversTarget,
+ outcomes,
});
}
diff --git a/packages/cli/api/upgrade/run/outcomes.test.mjs b/packages/cli/api/upgrade/run/outcomes.test.mjs
new file mode 100644
index 0000000000..e0203b5aba
--- /dev/null
+++ b/packages/cli/api/upgrade/run/outcomes.test.mjs
@@ -0,0 +1,646 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file The upgrade.run receipt keeps codemod outcomes apart from failures:
+ * a core codemod that throws `ManualMigrationRequired` adds a row to
+ * `declinedCandidates` and leaves the run complete; `RegenerationRequired` adds to
+ * `regenerate` and leaves it incomplete; any other throw is still an error and
+ * wins `errorCode`. Core codemods come from a stubbed registry so the receipt
+ * contract is tested apart from any one shipped codemod.
+ */
+
+import {describe, it, expect, beforeEach, afterEach, vi} from 'vitest';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import {
+ ManualMigrationRequired,
+ RegenerationRequired,
+} from '../../../assets/codemods/outcome.mjs';
+import {markParseError} from '../../../assets/codemods/parse.mjs';
+
+vi.mock('../../../assets/codemods/registry.mjs', async importOriginal => {
+ const actual = /** @type {Record<string, unknown>} */ (
+ await importOriginal()
+ );
+ return {
+ ...actual,
+ getTransformsBetween: async () => [
+ {
+ version: '0.2.0',
+ transforms: [
+ {
+ name: 'report-raw',
+ meta: {title: 'Report raw tokens', fileExtensions: ['.ts']},
+ /** @param {{source: string}} file */
+ transform(file) {
+ if (file.source.includes('RAW')) {
+ throw new ManualMigrationRequired('Read it through dataVars.', {
+ line: 2,
+ });
+ }
+ if (file.source.includes('STALE')) {
+ throw new RegenerationRequired('Out of date.', {
+ commands: ['gen theme'],
+ });
+ }
+ return undefined;
+ },
+ },
+ {
+ name: 'report-vague',
+ meta: {title: 'Report vague findings', fileExtensions: ['.ts']},
+ /** @param {{source: string}} file */
+ transform(file) {
+ if (file.source.includes('VAGUE')) {
+ throw new ManualMigrationRequired('Check it by hand.');
+ }
+ return undefined;
+ },
+ },
+ {
+ name: 'report-legacy',
+ meta: {title: 'Report legacy calls', fileExtensions: ['.ts']},
+ /** @param {{source: string}} file */
+ transform(file) {
+ if (file.source.includes('LEGACY')) {
+ throw new ManualMigrationRequired('Call the new API.', {
+ line: 3,
+ });
+ }
+ return undefined;
+ },
+ },
+ {
+ name: 'parse-strict',
+ meta: {title: 'Parse strictly', fileExtensions: ['.ts']},
+ /** @param {{source: string}} file */
+ transform(file) {
+ if (file.source.includes('UNPARSEABLE')) {
+ throw markParseError(
+ Object.assign(new SyntaxError('Unexpected token'), {
+ loc: {line: 4, column: 0},
+ }),
+ );
+ }
+ return undefined;
+ },
+ },
+ {
+ name: 'rename-foo',
+ meta: {title: 'Rename foo', fileExtensions: ['.ts']},
+ /** @param {{source: string}} file */
+ transform: file => file.source.replace(/foo/g, 'bar'),
+ },
+ {
+ name: 'fail-on-boom',
+ meta: {title: 'Fail on boom', fileExtensions: ['.ts']},
+ /** @param {{source: string}} file */
+ transform(file) {
+ if (file.source.includes('boom')) throw new Error('codemod boom');
+ return undefined;
+ },
+ },
+ ],
+ },
+ ],
+ };
+});
+
+const {upgrade} = await import('../upgrade.mjs');
+const {logger} = await import('../../logger.mjs');
+
+let dir;
+
+/** @param {string} rel @param {string} body */
+function write(rel, body) {
+ fs.mkdirSync(path.dirname(path.join(dir, rel)), {recursive: true});
+ fs.writeFileSync(path.join(dir, rel), body);
+}
+
+beforeEach(() => {
+ dir = fs.mkdtempSync(path.join(os.tmpdir(), 'upg-outcomes-'));
+ write(
+ 'package.json',
+ JSON.stringify({name: 'x', dependencies: {'@astryxdesign/core': '0.2.0'}}),
+ );
+ write(
+ 'node_modules/@astryxdesign/core/package.json',
+ JSON.stringify({name: '@astryxdesign/core', version: '0.2.0'}),
+ );
+ write('src/index.ts', 'const foo = 1;\n');
+ write('src/chart.ts', "const a = 1;\nconst b = 'RAW';\n");
+});
+
+afterEach(() => {
+ logger.setSilent(true);
+ vi.restoreAllMocks();
+ fs.rmSync(dir, {recursive: true, force: true});
+});
+
+const APPLY = {from: '0.1.0', apply: true, path: 'src'};
+
+/** @param {Promise<unknown>} promise */
+async function rejection(promise) {
+ try {
+ await promise;
+ } catch (err) {
+ return /** @type {any} */ (err);
+ }
+ throw new Error('expected upgrade() to reject');
+}
+
+describe('manual migrations in the upgrade receipt', () => {
+ it('are listed, never errors, and leave the run complete', async () => {
+ const result = await upgrade(APPLY, {cwd: dir});
+
+ expect(result.type).toBe('upgrade.run');
+ expect(result.data).toMatchObject({
+ complete: true,
+ errors: [],
+ regenerate: [],
+ modifiedFiles: ['src/index.ts'],
+ declinedCandidates: [
+ {
+ file: 'src/chart.ts',
+ location: '2',
+ reason:
+ 'manual migration needed (core:report-raw): Read it through dataVars.',
+ },
+ ],
+ });
+ expect(result.data).not.toHaveProperty('errorCode');
+ expect(result.data).not.toHaveProperty('manualActions');
+ expect(fs.readFileSync(path.join(dir, 'src/chart.ts'), 'utf8')).toContain(
+ 'RAW',
+ );
+ });
+
+ it('are printed after the run, and the last line says how many remain', async () => {
+ logger.setSilent(false);
+ const err = vi.spyOn(console, 'error').mockImplementation(() => {});
+ const out = vi.spyOn(console, 'log').mockImplementation(() => {});
+
+ await upgrade(APPLY, {cwd: dir});
+
+ const stderr = err.mock.calls.map(c => c.join(' ')).join('\n');
+ const stdout = out.mock.calls.map(c => c.join(' ')).join('\n');
+ expect(stderr).toContain(
+ '1 file needs a manual migration that upgrade cannot make; review manually:',
+ );
+ expect(stderr).toContain(
+ ' src/chart.ts:2 - manual migration needed (core:report-raw): Read it through dataVars.',
+ );
+ // Listed with the manual migrations, not as a protected file that does
+ // not parse.
+ expect(stderr).not.toMatch(/skipped because/);
+ expect(stdout).toContain(
+ 'Upgrade complete; 1 manual migration listed above',
+ );
+ expect(stderr).not.toMatch(/ERR_CODEMOD_FAILED/);
+ });
+});
+
+describe('several manual migrations in one file', () => {
+ it('are folded into its one declined row, each keeping its prefix and its line, and all counted', async () => {
+ write('src/chart.ts', "const a = 1;\nconst b = 'RAW';\nLEGACY();\n");
+ logger.setSilent(false);
+ const err = vi.spyOn(console, 'error').mockImplementation(() => {});
+ const out = vi.spyOn(console, 'log').mockImplementation(() => {});
+
+ const result = await upgrade(APPLY, {cwd: dir});
+
+ expect(result.data.complete).toBe(true);
+ expect(result.data.declinedCandidates).toEqual([
+ {
+ file: 'src/chart.ts',
+ location: '2',
+ reason:
+ 'manual migration needed (core:report-raw): Read it through dataVars.; ' +
+ 'manual migration needed (core:report-legacy): Call the new API. (at 3)',
+ },
+ ]);
+ // Each finding keeps the approved prefix, so a parser reads its codemod.
+ const findings = result.data.declinedCandidates[0].reason.split('; ');
+ expect(findings).toHaveLength(2);
+ for (const finding of findings) {
+ expect(finding).toMatch(/^manual migration needed \(core:[a-z-]+\): /);
+ }
+ const stderr = err.mock.calls.map(c => c.join(' ')).join('\n');
+ const stdout = out.mock.calls.map(c => c.join(' ')).join('\n');
+ expect(stderr).toContain('1 file needs a manual migration');
+ expect(stderr).toContain(
+ ' src/chart.ts:2 - manual migration needed (core:report-raw): Read it through dataVars.',
+ );
+ expect(stderr).toContain(
+ ' src/chart.ts:3 - manual migration needed (core:report-legacy): Call the new API.',
+ );
+ expect(stdout).toContain(
+ 'Upgrade complete; 2 manual migrations listed above',
+ );
+ });
+});
+
+describe('a folded finding with no location', () => {
+ it('after one with a line, is marked unknown, never read at that line', async () => {
+ // report-raw (line 2) runs before report-vague (no line).
+ write('src/chart.ts', "const a = 1;\nconst b = 'RAW';\nVAGUE();\n");
+ logger.setSilent(false);
+ const err = vi.spyOn(console, 'error').mockImplementation(() => {});
+ vi.spyOn(console, 'log').mockImplementation(() => {});
+
+ const result = await upgrade(APPLY, {cwd: dir});
+
+ expect(result.data.declinedCandidates).toEqual([
+ {
+ file: 'src/chart.ts',
+ location: '2',
+ reason:
+ 'manual migration needed (core:report-raw): Read it through dataVars.; ' +
+ 'manual migration needed (core:report-vague): Check it by hand. (location unknown)',
+ },
+ ]);
+ const stderr = err.mock.calls.map(c => c.join(' ')).join('\n');
+ expect(stderr).toContain(
+ ' src/chart.ts - manual migration needed (core:report-vague): Check it by hand.',
+ );
+ expect(stderr).not.toMatch(/src\/chart\.ts:2 - [^\n]*report-vague/);
+ });
+
+ it('first, leaves the row without a location and gives the later one its own', async () => {
+ // report-vague (no line) runs before report-legacy (line 3).
+ write('src/chart.ts', 'VAGUE();\nconst a = 1;\nLEGACY();\n');
+ logger.setSilent(false);
+ const err = vi.spyOn(console, 'error').mockImplementation(() => {});
+ vi.spyOn(console, 'log').mockImplementation(() => {});
+
+ const result = await upgrade(APPLY, {cwd: dir});
+
+ expect(result.data.declinedCandidates).toEqual([
+ {
+ file: 'src/chart.ts',
+ reason:
+ 'manual migration needed (core:report-vague): Check it by hand.; ' +
+ 'manual migration needed (core:report-legacy): Call the new API. (at 3)',
+ },
+ ]);
+ const stderr = err.mock.calls.map(c => c.join(' ')).join('\n');
+ expect(stderr).toContain(
+ ' src/chart.ts - manual migration needed (core:report-vague): Check it by hand.',
+ );
+ expect(stderr).toContain(
+ ' src/chart.ts:3 - manual migration needed (core:report-legacy): Call the new API.',
+ );
+ expect(stderr).not.toMatch(/src\/chart\.ts:3 - [^\n]*report-vague/);
+ });
+});
+
+describe('a protected file both unparseable and with a manual finding', () => {
+ it('keeps both findings in its one row, each under its own heading', async () => {
+ write(
+ 'src/vendor.ts',
+ "// @generated\nconst b = 'RAW';\nconst c = 1;\nUNPARSEABLE\n",
+ );
+ logger.setSilent(false);
+ const err = vi.spyOn(console, 'error').mockImplementation(() => {});
+ const out = vi.spyOn(console, 'log').mockImplementation(() => {});
+
+ const result = await upgrade(APPLY, {cwd: dir});
+
+ expect(result.data.complete).toBe(true);
+ const vendor = result.data.declinedCandidates.find(
+ (/** @type {{file: string}} */ row) => row.file === 'src/vendor.ts',
+ );
+ expect(vendor.location).toBe('4:1');
+ const [parse, manual, ...rest] = vendor.reason.split('; ');
+ expect(rest).toEqual([]);
+ expect(parse).toMatch(
+ /^unparseable protected file \([^)]+\): Unexpected token$/,
+ );
+ expect(manual).toBe(
+ 'manual migration needed (core:report-raw): Read it through dataVars. (at 2)',
+ );
+ const stderr = err.mock.calls.map(c => c.join(' ')).join('\n');
+ const stdout = out.mock.calls.map(c => c.join(' ')).join('\n');
+ expect(stderr).toMatch(
+ /1 protected file was skipped because it does not parse; review manually:\n\s+src\/vendor\.ts:4:1 - unparseable protected file/,
+ );
+ expect(stderr).toContain('2 files need a manual migration');
+ expect(stderr).toContain(
+ ' src/vendor.ts:2 - manual migration needed (core:report-raw): Read it through dataVars.',
+ );
+ expect(stdout).toContain(
+ 'Upgrade complete; 2 manual migrations listed above',
+ );
+ });
+});
+
+describe('manual migrations beside other declined candidates', () => {
+ it('leave out a file the run reports as protected, as every declined candidate does', async () => {
+ write('src/chart.ts', "// @generated\nconst a = 1;\nconst b = 'RAW';\n");
+ write('src/gen.ts', '// @generated\nconst foo = 2;\n');
+
+ const result = await upgrade(APPLY, {cwd: dir});
+
+ // chart.ts is protected but needs no change, so it stays declined;
+ // gen.ts is protected and still needs a change, so it is listed once,
+ // under protectedFiles.
+ expect(result.data.protectedFiles).toEqual([
+ expect.objectContaining({file: 'src/gen.ts'}),
+ ]);
+ expect(result.data.declinedCandidates).toEqual([
+ expect.objectContaining({file: 'src/chart.ts', location: '2'}),
+ ]);
+ });
+});
+
+describe('a protected file with both a manual migration and a regeneration', () => {
+ const BOTH = '// @generated\n// STALE\nLEGACY();\n';
+
+ it('is listed once, under protectedFiles, never also declined', async () => {
+ write('src/theme.ts', BOTH);
+ logger.setSilent(false);
+ const err = vi.spyOn(console, 'error').mockImplementation(() => {});
+ vi.spyOn(console, 'log').mockImplementation(() => {});
+
+ const result = await upgrade(APPLY, {cwd: dir});
+
+ expect(result.data.errorCode).toBe('ERR_CODEMOD_PROTECTED');
+ expect(result.data.protectedFiles).toEqual([
+ expect.objectContaining({file: 'src/theme.ts'}),
+ ]);
+ expect(result.data.regenerate).toEqual([
+ expect.objectContaining({file: 'src/theme.ts'}),
+ ]);
+ expect(result.data.declinedCandidates).toEqual([
+ expect.objectContaining({file: 'src/chart.ts'}),
+ ]);
+ const stderr = err.mock.calls.map(c => c.join(' ')).join('\n');
+ expect(stderr).toContain('1 file needs a manual migration');
+ expect(stderr).not.toMatch(/src\/theme\.ts:3 - manual migration needed/);
+ });
+
+ it('is listed once after a post-codemod hook re-checks it', async () => {
+ write('src/theme.ts', BOTH);
+ write(
+ 'astryx.config.mjs',
+ `export default {hooks: {postCodemod: [{name: 'mark', buildCommand: () => ({command: process.execPath, args: ['-e', "require('node:fs').writeFileSync('hook-ran', '')"]})}]}};
+`,
+ );
+
+ const result = await upgrade(APPLY, {cwd: dir});
+
+ // The hook ran, so this receipt comes from the re-check.
+ expect(fs.existsSync(path.join(dir, 'hook-ran'))).toBe(true);
+ expect(result.data.errorCode).toBe('ERR_CODEMOD_PROTECTED');
+ expect(result.data.protectedFiles).toEqual([
+ expect.objectContaining({file: 'src/theme.ts'}),
+ ]);
+ expect(result.data.declinedCandidates).toEqual([
+ expect.objectContaining({file: 'src/chart.ts'}),
+ ]);
+ });
+});
+
+describe('regeneration in the upgrade receipt', () => {
+ it('reports a file nothing protects as a codemod error, never ERR_CODEMOD_PROTECTED', async () => {
+ write('src/theme.ts', '// STALE\n');
+
+ const err = await rejection(upgrade(APPLY, {cwd: dir}));
+
+ // No protected file blocks this change, so ERR_CODEMOD_PROTECTED would
+ // misstate it; it keeps the code a failed required change has.
+ expect(err.code).toBe('ERR_CODEMOD_FAILED');
+ expect(err.receipt).toMatchObject({
+ complete: false,
+ errorCode: 'ERR_CODEMOD_FAILED',
+ protectedFiles: [],
+ errors: [
+ {
+ file: 'src/theme.ts',
+ codemod: 'core:report-raw',
+ error: 'Out of date.',
+ },
+ ],
+ regenerate: [
+ {
+ file: 'src/theme.ts',
+ codemods: ['core:report-raw'],
+ commands: ['gen theme'],
+ messages: ['Out of date.'],
+ },
+ ],
+ declinedCandidates: [expect.objectContaining({file: 'src/chart.ts'})],
+ });
+ });
+
+ it('keeps a file to regenerate in the receipt when astryx.config also fails validation', async () => {
+ fs.rmSync(path.join(dir, 'src/index.ts'));
+ write('src/theme.ts', '// STALE\n');
+ write('astryx.config.mjs', "export default {theme: 'neutral'};\n");
+
+ const err = await rejection(upgrade(APPLY, {cwd: dir}));
+
+ expect(err.code).toBe('ERR_INVALID_ARGUMENT');
+ expect(err.receipt).toMatchObject({
+ complete: false,
+ modifiedFiles: [],
+ regenerate: [
+ expect.objectContaining({
+ file: 'src/theme.ts',
+ commands: ['gen theme'],
+ }),
+ ],
+ errors: expect.arrayContaining([
+ expect.objectContaining({file: 'src/theme.ts'}),
+ expect.objectContaining({codemod: 'config'}),
+ ]),
+ });
+ });
+
+ it('names a file to regenerate and its command in text when astryx.config fails validation', async () => {
+ fs.rmSync(path.join(dir, 'src/index.ts'));
+ write('src/theme.ts', '// STALE\n');
+ write('astryx.config.mjs', "export default {theme: 'neutral'};\n");
+ logger.setSilent(false);
+ const err = vi.spyOn(console, 'error').mockImplementation(() => {});
+ const out = vi.spyOn(console, 'log').mockImplementation(() => {});
+
+ await rejection(upgrade(APPLY, {cwd: dir}));
+
+ const stderr = err.mock.calls.map(c => c.join(' ')).join('\n');
+ const stdout = out.mock.calls.map(c => c.join(' ')).join('\n');
+ expect(stderr).toContain(
+ '1 generated file must be regenerated:\n src/theme.ts — Out of date.',
+ );
+ expect(stdout).toContain('Regenerate with: gen theme');
+ });
+
+ it('prints the command for a protected file to regenerate when astryx.config fails validation', async () => {
+ fs.rmSync(path.join(dir, 'src/index.ts'));
+ write('src/theme.ts', '// @generated\n// STALE\n');
+ write('astryx.config.mjs', "export default {theme: 'neutral'};\n");
+ logger.setSilent(false);
+ const err = vi.spyOn(console, 'error').mockImplementation(() => {});
+ const out = vi.spyOn(console, 'log').mockImplementation(() => {});
+
+ const result = await upgrade(APPLY, {cwd: dir});
+
+ expect(result.data.errorCode).toBe('ERR_CODEMOD_PROTECTED');
+ const stderr = err.mock.calls.map(c => c.join(' ')).join('\n');
+ const stdout = out.mock.calls.map(c => c.join(' ')).join('\n');
+ expect(stderr).toMatch(/src\/theme\.ts — /);
+ expect(stdout).toContain('Regenerate with: gen theme');
+ });
+ it('lists a reported file the project protects in protectedFiles too, with its declaration', async () => {
+ write('src/theme.ts', '// @generated\n// STALE\n');
+
+ const result = await upgrade(APPLY, {cwd: dir});
+
+ expect(result.data).toMatchObject({
+ complete: false,
+ errorCode: 'ERR_CODEMOD_PROTECTED',
+ protectedFiles: [
+ {
+ file: 'src/theme.ts',
+ codemods: ['core:report-raw'],
+ reasons: ['generated'],
+ declarations: [expect.stringContaining('@generated')],
+ commands: ['gen theme'],
+ },
+ ],
+ regenerate: [
+ expect.objectContaining({
+ file: 'src/theme.ts',
+ commands: ['gen theme'],
+ }),
+ ],
+ });
+ });
+
+ it('does not say the code is up to date when the only findings are outcomes', async () => {
+ fs.rmSync(path.join(dir, 'src/index.ts'));
+ write('src/theme.ts', '// @generated\n// STALE\n');
+ logger.setSilent(false);
+ const out = vi.spyOn(console, 'log').mockImplementation(() => {});
+ vi.spyOn(console, 'error').mockImplementation(() => {});
+
+ const result = await upgrade(APPLY, {cwd: dir});
+
+ const stdout = out.mock.calls.map(c => c.join(' ')).join('\n');
+ expect(result.data.filesChanged).toBe(0);
+ expect(stdout).not.toMatch(/No changes needed/);
+ expect(stdout).toMatch(/Upgrade incomplete/);
+ });
+
+ it('does not say Done when another codemod changed a file and a regeneration is pending', async () => {
+ write('src/theme.ts', '// @generated\n// STALE\n');
+ logger.setSilent(false);
+ const out = vi.spyOn(console, 'log').mockImplementation(() => {});
+ const err = vi.spyOn(console, 'error').mockImplementation(() => {});
+
+ const result = await upgrade(APPLY, {cwd: dir});
+
+ const text = [...out.mock.calls, ...err.mock.calls]
+ .map(c => c.join(' '))
+ .join('\n');
+ expect(result.data.modifiedFiles).toEqual(['src/index.ts']);
+ expect(text).not.toMatch(/Done!/);
+ expect(text).toMatch(
+ /Applied 1 owned change across 1 file; generated files to regenerate remain/,
+ );
+ expect(text).toMatch(/Upgrade incomplete/);
+ });
+});
+
+describe('a failure beside outcomes', () => {
+ it('still rejects with ERR_CODEMOD_FAILED, and its receipt keeps the manual actions', async () => {
+ write('src/broken.ts', 'const boom = 1;\n');
+
+ const err = await rejection(upgrade(APPLY, {cwd: dir}));
+
+ expect(err.code).toBe('ERR_CODEMOD_FAILED');
+ expect(err.receipt).toMatchObject({
+ complete: false,
+ errorCode: 'ERR_CODEMOD_FAILED',
+ errors: [
+ {
+ file: 'src/broken.ts',
+ codemod: 'core:fail-on-boom',
+ error: 'codemod boom',
+ },
+ ],
+ declinedCandidates: [
+ expect.objectContaining({file: 'src/chart.ts', location: '2'}),
+ ],
+ regenerate: [],
+ modifiedFiles: ['src/index.ts'],
+ });
+ });
+
+ it('is the same in a dry run, which writes nothing', async () => {
+ write('src/broken.ts', 'const boom = 1;\n');
+
+ const err = await rejection(upgrade({...APPLY, apply: false}, {cwd: dir}));
+
+ expect(err.code).toBe('ERR_CODEMOD_FAILED');
+ expect(err.receipt.declinedCandidates).toEqual([
+ expect.objectContaining({file: 'src/chart.ts', location: '2'}),
+ ]);
+ expect(fs.readFileSync(path.join(dir, 'src/index.ts'), 'utf8')).toBe(
+ 'const foo = 1;\n',
+ );
+ });
+
+ it('with a protected file to regenerate, returns the incomplete receipt as for a protected file', async () => {
+ write('src/theme.ts', '// @generated\n// STALE\n');
+ write('src/broken.ts', 'const boom = 1;\n');
+
+ const result = await upgrade(APPLY, {cwd: dir});
+
+ expect(result.data).toMatchObject({
+ complete: false,
+ errorCode: 'ERR_CODEMOD_PROTECTED',
+ errors: [expect.objectContaining({file: 'src/broken.ts'})],
+ declinedCandidates: [expect.objectContaining({file: 'src/chart.ts'})],
+ regenerate: [expect.objectContaining({file: 'src/theme.ts'})],
+ modifiedFiles: ['src/index.ts'],
+ });
+ });
+});
+
+describe('folding declined rows from different path spellings', () => {
+ it("groups a runner's backslash path with a manual row's / path into one row", async () => {
+ const {summarizeDeclinedCandidates} = await import('./run.mjs');
+
+ const rows = summarizeDeclinedCandidates(
+ [
+ {
+ file: 'src\\vendor.ts',
+ codemod: 'core:parse-strict',
+ location: '4:1',
+ reason: 'unparseable protected file (generated): Unexpected token',
+ },
+ {
+ file: 'src/vendor.ts',
+ codemod: 'core:report-raw',
+ location: '2',
+ reason:
+ 'manual migration needed (core:report-raw): Read it through dataVars.',
+ },
+ ],
+ [],
+ '\\',
+ );
+
+ expect(rows).toEqual([
+ {
+ file: 'src/vendor.ts',
+ location: '4:1',
+ reason:
+ 'unparseable protected file (generated): Unexpected token; ' +
+ 'manual migration needed (core:report-raw): Read it through dataVars. (at 2)',
+ },
+ ]);
+ });
+});
diff --git a/packages/cli/api/upgrade/run/run.mjs b/packages/cli/api/upgrade/run/run.mjs
index fb270a8ba2..9174c09b46 100644
--- a/packages/cli/api/upgrade/run/run.mjs
+++ b/packages/cli/api/upgrade/run/run.mjs
@@ -39,6 +39,7 @@ import {
warnIntegrationIssues,
selectIntegrationCodemodsFor,
runIntegrationCodemodsStep,
+ withCodemodOutcomes,
} from '../_adapter.mjs';
import {
logRegistryCompositionSummary,
@@ -94,42 +95,222 @@ function summarizeProtectedFiles(rows) {
.sort((a, b) => a.file.localeCompare(b.file));
}
+/** Every declined finding for a manual migration starts with this. */
+const MANUAL_MIGRATION_REASON = 'manual migration needed';
+
+/**
+ * Where one declined finding ends and the next begins inside a folded
+ * `reason`: `; ` before a finding's own prefix.
+ */
+const NEXT_FINDING =
+ /; (?=(?:unparseable protected file|manual migration needed) \()/;
+
+/** The suffix of a folded finding that has no location of its own. */
+const LOCATION_UNKNOWN = '(location unknown)';
+
/**
* Collapse per-codemod declined candidates into one row per file, in the
* receipt's `{file, location?, reason}` shape. A file the receipt lists under
* `protectedFiles` is left out: a codemod still requires a change to it, and
* that already makes the run incomplete.
+ *
+ * Every distinct finding for a file is kept, whatever its kind: a single
+ * finding is the row as it arrived; several are folded into the one row,
+ * each keeping its own prefix (`unparseable protected file (<category>): ...`
+ * or `manual migration needed (<codemod>): ...`), joined by `; ` in arrival
+ * order. `location` is the first finding's own location (absent when it has
+ * none). A later finding whose own location differs from the row's says so at
+ * its end: ` (at <location>)` when known, ` (location unknown)` when not; a
+ * later finding without a suffix is at the row's location. So no finding is
+ * ever read at another finding's location.
+ *
+ * Rows are grouped by their `/`-separated path, which is also the spelling
+ * the row carries: a runner's row keeps the platform separator (backslashes on
+ * Windows), while a manual row already uses `/`.
* @param {Array<{file: string, codemod: string, location?: string, reason: string}>} rows
* @param {Array<{file: string}>} [protectedRows]
+ * @param {string} [sep] The platform path separator (a parameter for tests).
* @returns {Array<{file: string, location?: string, reason: string}>}
*/
-function summarizeDeclinedCandidates(rows, protectedRows = []) {
- /** @type {Map<string, {file: string, location?: string, reason: string}>} */
+export function summarizeDeclinedCandidates(
+ rows,
+ protectedRows = [],
+ sep = path.sep,
+) {
+ /** @type {Map<string, Array<{location?: string, reason: string}>>} */
const byFile = new Map();
- for (const {file, location, reason} of withoutProtected(
+ for (const {file: raw, location, reason} of withoutProtected(
rows,
protectedRows,
)) {
- if (byFile.has(file)) continue;
- byFile.set(file, {file, ...(location ? {location} : {}), reason});
+ const file = raw.split(sep).join('/');
+ const findings = byFile.get(file) ?? [];
+ if (!findings.some(f => f.reason === reason && f.location === location)) {
+ findings.push({...(location ? {location} : {}), reason});
+ }
+ byFile.set(file, findings);
}
- return [...byFile.values()].sort((a, b) => a.file.localeCompare(b.file));
+ return [...byFile.entries()]
+ .map(([file, findings]) => {
+ const location = findings[0].location;
+ return {
+ file,
+ ...(location ? {location} : {}),
+ reason: findings
+ .map((f, index) =>
+ index === 0 || f.location === location
+ ? f.reason
+ : f.location
+ ? `${f.reason} (at ${f.location})`
+ : `${f.reason} ${LOCATION_UNKNOWN}`,
+ )
+ .join('; '),
+ };
+ })
+ .sort((a, b) => a.file.localeCompare(b.file));
+}
+
+/**
+ * The findings a folded declined row carries, each with its own location.
+ * @param {{location?: string, reason: string}} row
+ * @returns {Array<{location?: string, text: string}>}
+ */
+function declinedFindings(row) {
+ return row.reason.split(NEXT_FINDING).map((text, index) => {
+ if (index === 0) {
+ return {...(row.location ? {location: row.location} : {}), text};
+ }
+ if (text.endsWith(` ${LOCATION_UNKNOWN}`)) {
+ return {text: text.slice(0, -LOCATION_UNKNOWN.length - 1)};
+ }
+ const at = / \(at ([^)]+)\)$/.exec(text);
+ return at
+ ? {location: at[1], text: text.slice(0, at.index)}
+ : {...(row.location ? {location: row.location} : {}), text};
+ });
+}
+
+/**
+ * Declined candidates for code a codemod identified but cannot migrate safely
+ * (`ManualMigrationRequired`): one row per finding, in the per-codemod row
+ * shape the runners use, for `summarizeDeclinedCandidates` to fold with the
+ * file's other declined findings. A person makes the change; like every
+ * declined candidate, it never fails the run or makes it incomplete
+ * (spec:AST-040 FR7).
+ * @param {import('../_adapter.mjs').CodemodOutcomeRecord[]} outcomes
+ * @returns {Array<{file: string, codemod: string, location?: string, reason: string}>}
+ */
+function manualDeclinedRows(outcomes) {
+ /** @type {Array<{file: string, codemod: string, location?: string, reason: string}>} */
+ const rows = [];
+ for (const outcome of outcomes) {
+ if (outcome.kind !== 'manual') continue;
+ rows.push({
+ file: outcome.file,
+ codemod: outcome.codemod,
+ ...(typeof outcome.line === 'number'
+ ? {location: String(outcome.line)}
+ : {}),
+ reason: `${MANUAL_MIGRATION_REASON} (${outcome.codemod}): ${outcome.message}`,
+ });
+ }
+ return rows;
+}
+
+/**
+ * How many manual migrations the declined rows carry: every finding, not every
+ * file (a folded row lists several).
+ * @param {Array<{location?: string, reason: string}>} declined
+ */
+function countManualMigrations(declined) {
+ return declined
+ .flatMap(declinedFindings)
+ .filter(f => f.text.startsWith(MANUAL_MIGRATION_REASON)).length;
}
/**
- * Print the protected files the run skipped because a codemod could not parse
- * them, from the final declined list (files it reports as protected are
- * already left out), so the text output carries what the receipt lists.
+ * Print the final declined list (files it reports as protected are already
+ * left out), so the text output carries what the receipt lists: protected
+ * files the run skipped because a codemod could not parse them, and code a
+ * codemod could not migrate. Each finding of a folded row is printed under
+ * its own kind.
* @param {Array<{file: string, location?: string, reason: string}>} declined
*/
function logDeclined(declined) {
- if (declined.length === 0) return;
- const n = declined.length;
- logger.warn(
- `${n} protected file${n === 1 ? ' was' : 's were'} skipped because ${n === 1 ? 'it does' : 'they do'} not parse; review manually:`,
+ /** @type {Array<{file: string, location?: string, text: string}>} */
+ const manual = [];
+ /** @type {Array<{file: string, location?: string, text: string}>} */
+ const unparseable = [];
+ for (const row of declined) {
+ for (const finding of declinedFindings(row)) {
+ (finding.text.startsWith(MANUAL_MIGRATION_REASON)
+ ? manual
+ : unparseable
+ ).push({file: row.file, ...finding});
+ }
+ }
+ /** @param {Array<{file: string, location?: string, text: string}>} rows */
+ const lines = rows => {
+ for (const {file, location, text} of rows) {
+ logger.warn(` ${file}${location ? `:${location}` : ''} - ${text}`);
+ }
+ };
+ /** @param {Array<{file: string}>} rows */
+ const files = rows => new Set(rows.map(row => row.file)).size;
+ if (unparseable.length > 0) {
+ const n = files(unparseable);
+ logger.warn(
+ `${n} protected file${n === 1 ? ' was' : 's were'} skipped because ${n === 1 ? 'it does' : 'they do'} not parse; review manually:`,
+ );
+ lines(unparseable);
+ }
+ if (manual.length > 0) {
+ const n = files(manual);
+ logger.warn(
+ `${n} file${n === 1 ? ' needs' : 's need'} a manual migration that upgrade cannot make; review manually:`,
+ );
+ lines(manual);
+ }
+}
+
+/**
+ * Print protected files that still require a codemod change, each with the
+ * declarations that protect it and the commands that rebuild it.
+ * @param {string} header
+ * @param {import('../upgrade.type.mjs').ProtectedCodemodFile[]} protectedFiles
+ */
+function logProtectedFiles(header, protectedFiles) {
+ if (protectedFiles.length === 0) return;
+ logger.error(header);
+ for (const item of protectedFiles) {
+ logger.error(` ${item.file} — ${item.declarations.join('; ')}`);
+ for (const command of item.commands) {
+ logger.log(` Regenerate with: ${command}`);
+ }
+ }
+}
+
+/**
+ * Print the generated files to rebuild, each with why and the commands that
+ * rebuild it, so the text output carries what `regenerate` lists. Files
+ * already printed with their commands (protected files) are skipped.
+ * @param {import('../upgrade.type.mjs').RegenerateFile[]} regenerate
+ * @param {Array<{file: string}>} [printed]
+ */
+function logRegenerate(regenerate, printed = []) {
+ const skip = new Set(printed.map(item => item.file));
+ const rows = regenerate.filter(item => !skip.has(item.file));
+ if (rows.length === 0) return;
+ logger.error(
+ `${rows.length} generated file${rows.length === 1 ? '' : 's'} must be regenerated:`,
);
- for (const {file, location, reason} of declined) {
- logger.warn(` ${file}${location ? `:${location}` : ''} - ${reason}`);
+ for (const item of rows) {
+ logger.error(
+ ` ${item.file}${item.messages.length > 0 ? ` — ${item.messages.join(' ')}` : ''}`,
+ );
+ for (const command of item.commands) {
+ logger.log(` Regenerate with: ${command}`);
+ }
}
}
@@ -159,6 +340,118 @@ function loadFileProtection(cwd) {
}
}
+/**
+ * Generated files that must be rebuilt before the upgrade is complete, one row
+ * per file: protected generated files a codemod still needs to change, and
+ * generated outputs a codemod reported out of date. `commands` are the exact
+ * rebuild commands known for the file (its header's `Command:` line, or the
+ * command the codemod names).
+ * @param {Array<{file: string, codemods: string[], reasons: string[], commands: string[]}>} protectedFiles
+ * @param {import('../_adapter.mjs').CodemodOutcomeRecord[]} outcomes
+ * @returns {import('../upgrade.type.mjs').RegenerateFile[]}
+ */
+function summarizeRegenerate(protectedFiles, outcomes) {
+ /** @type {Map<string, {codemods: Set<string>, commands: Set<string>, messages: Set<string>}>} */
+ const byFile = new Map();
+ /** @param {string} file */
+ const row = file => {
+ const current = byFile.get(file) ?? {
+ codemods: new Set(),
+ commands: new Set(),
+ messages: new Set(),
+ };
+ byFile.set(file, current);
+ return current;
+ };
+ for (const item of protectedFiles) {
+ if (!item.reasons.includes('generated')) continue;
+ const current = row(item.file);
+ for (const codemod of item.codemods) current.codemods.add(codemod);
+ for (const command of item.commands) current.commands.add(command);
+ }
+ for (const outcome of outcomes) {
+ if (outcome.kind !== 'regenerate') continue;
+ const current = row(outcome.file);
+ current.codemods.add(outcome.codemod);
+ for (const command of outcome.commands) current.commands.add(command);
+ current.messages.add(outcome.message);
+ }
+ return [...byFile.entries()]
+ .map(([file, item]) => ({
+ file,
+ codemods: [...item.codemods].sort(),
+ commands: [...item.commands].sort(),
+ messages: [...item.messages].sort(),
+ }))
+ .sort((a, b) => a.file.localeCompare(b.file));
+}
+
+/**
+ * Protection rows for generated outputs a codemod reported out of date, from
+ * the run's protection resolver, in the shape the runners report blocked
+ * protected candidates. A reported file the project protects (an `@generated`
+ * header, `linguist-generated`, ...) is a protected file that still requires a
+ * change, so it is listed in `protectedFiles` with the declaration that
+ * protects it (spec:AST-040 FR6), and the command the codemod names is one of
+ * its `commands`. A reported file nothing protects gets no row here: it is a
+ * codemod error (`regenerationErrors`) and stays in `regenerate`.
+ * @param {import('../_adapter.mjs').CodemodOutcomeRecord[]} outcomes
+ * @param {{classify: (file: string) => import('../../../foundation/fs/file-protection.mjs').FileProtection[]}} protection
+ * @param {string} cwd
+ * @returns {Array<{file: string, codemod: string, reason: string, declaration: string, generated: boolean, command?: string}>}
+ */
+function regenerationProtectionRows(outcomes, protection, cwd) {
+ /** @type {Array<{file: string, codemod: string, reason: string, declaration: string, generated: boolean, command?: string}>} */
+ const rows = [];
+ for (const outcome of outcomes) {
+ if (outcome.kind !== 'regenerate') continue;
+ for (const item of protection.classify(path.resolve(cwd, outcome.file))) {
+ const base = {
+ file: item.file,
+ codemod: outcome.codemod,
+ reason: item.reason,
+ declaration: item.declaration,
+ generated: item.reason === 'generated',
+ };
+ const commands = [
+ ...(item.command ? [item.command] : []),
+ ...outcome.commands,
+ ];
+ if (commands.length === 0) rows.push(base);
+ for (const command of commands) rows.push({...base, command});
+ }
+ }
+ return rows;
+}
+
+/**
+ * Error rows for generated outputs a codemod reported out of date that nothing
+ * protects. No protected consumer file blocks such a change, so it is not an
+ * ERR_CODEMOD_PROTECTED outcome: the codemod required a change it could not
+ * make, which is a codemod failure (ERR_CODEMOD_FAILED), as it was before the
+ * outcome was typed. The file stays in `regenerate` with its command.
+ * @param {import('../_adapter.mjs').CodemodOutcomeRecord[]} outcomes
+ * @param {{classify: (file: string) => import('../../../foundation/fs/file-protection.mjs').FileProtection[]}} protection
+ * @param {string} cwd
+ * @returns {Array<{file: string, codemod: string, error: string}>}
+ */
+function regenerationErrors(outcomes, protection, cwd) {
+ /** @type {Array<{file: string, codemod: string, error: string}>} */
+ const rows = [];
+ for (const outcome of outcomes) {
+ if (outcome.kind !== 'regenerate') continue;
+ if (protection.classify(path.resolve(cwd, outcome.file)).length > 0) {
+ continue;
+ }
+ rows.push({
+ file: outcome.file,
+ codemod: outcome.codemod,
+ error: outcome.message,
+ });
+ }
+ return rows;
+}
+
/**
* The receipt of a run that stopped after codemods ran. Whatever the codemods
* already wrote stays on disk, so the error the run throws carries this
@@ -166,7 +459,7 @@ function loadFileProtection(cwd) {
* report nothing changed while the files it lists remain modified
* (spec:AST-040 FR7).
*
- * @param {{from: string, to: string, codemods: number, integrations: string[], sourcePathFound: boolean, cwd: string, changedFiles: string[], transformsApplied: number, protectedRows: Array<{file: string, codemod: string, reason: string, declaration: string, generated: boolean, command?: string}>, errors: Array<{file: string, codemod: string, error: string}>, declinedRows?: Array<{file: string, codemod: string, location?: string, reason: string}>, errorCode: string, cliBehindCore?: import('../upgrade.type.mjs').CliBehindCore | null, registryCompositions?: import('../upgrade.type.mjs').RegistryCompositionSummary}} facts
+ * @param {{from: string, to: string, codemods: number, integrations: string[], sourcePathFound: boolean, cwd: string, changedFiles: string[], transformsApplied: number, protectedRows: Array<{file: string, codemod: string, reason: string, declaration: string, generated: boolean, command?: string}>, outcomes?: import('../_adapter.mjs').CodemodOutcomeRecord[], errors: Array<{file: string, codemod: string, error: string}>, declinedRows?: Array<{file: string, codemod: string, location?: string, reason: string}>, errorCode: string, cliBehindCore?: import('../upgrade.type.mjs').CliBehindCore | null, registryCompositions?: import('../upgrade.type.mjs').RegistryCompositionSummary}} facts
* @returns {import('../upgrade.type.mjs').UpgradeRunResponse['data']}
*/
function stoppedReceipt({
@@ -179,15 +472,20 @@ function stoppedReceipt({
changedFiles,
transformsApplied,
protectedRows,
+ outcomes = [],
errors,
declinedRows = [],
errorCode,
cliBehindCore,
registryCompositions,
}) {
+ const protectedFiles = summarizeProtectedFiles(protectedRows);
const modifiedFiles = uniqueFiles(changedFiles).map(file =>
path.relative(cwd, file).split(path.sep).join('/'),
);
+ const regenerate = summarizeRegenerate(protectedFiles, outcomes);
+ // The run stopped early; the text still names every file to rebuild.
+ logRegenerate(regenerate);
return /** @type {import('../upgrade.type.mjs').UpgradeRunResponse['data']} */ ({
from,
to,
@@ -206,10 +504,14 @@ function stoppedReceipt({
filesChanged: modifiedFiles.length,
transformsApplied,
modifiedFiles,
- protectedFiles: summarizeProtectedFiles(protectedRows),
+ protectedFiles,
declinedCandidates: logged(
- summarizeDeclinedCandidates(declinedRows, protectedRows),
+ summarizeDeclinedCandidates(
+ [...declinedRows, ...manualDeclinedRows(outcomes)],
+ protectedRows,
+ ),
),
+ regenerate,
complete: false,
errorCode,
errors,
@@ -393,16 +695,22 @@ export async function run(options = {}, {cwd = process.cwd(), origin} = {}) {
}
// CORE codemods run FIRST (before loading config) so a core CONFIG codemod can
- // repair a config the strict loader would otherwise reject.
- const codemodResult = await runCoreCodemods(versionManifests, {
- apply,
- path: path_,
- codemod: options.codemod,
- skipCodemods,
- root: cwd,
- protection,
- coversTarget: !cliBehindCore,
- });
+ // repair a config the strict loader would otherwise reject. Manual-migration
+ // and regeneration outcomes they report are collected, not counted as errors.
+ const initialOutcomes = withCodemodOutcomes(versionManifests, cwd);
+ const codemodResult = await runCoreCodemods(
+ initialOutcomes.versionManifests,
+ {
+ apply,
+ path: path_,
+ codemod: options.codemod,
+ skipCodemods,
+ root: cwd,
+ protection,
+ coversTarget: !cliBehindCore,
+ outcomes: initialOutcomes.outcomes,
+ },
+ );
const coreResult =
codemodResult && 'totalFilesChanged' in codemodResult
? codemodResult
@@ -424,15 +732,30 @@ export async function run(options = {}, {cwd = process.cwd(), origin} = {}) {
iconSets = projectContext.iconSets;
} catch (err) {
const configErr = /** @type {Error} */ (err);
- const allProtected = coreResult?.protectedFiles ?? [];
+ const allProtected = [
+ ...(coreResult?.protectedFiles ?? []),
+ ...regenerationProtectionRows(initialOutcomes.outcomes, protection, cwd),
+ ];
+ const staleErrors = regenerationErrors(
+ initialOutcomes.outcomes,
+ protection,
+ cwd,
+ );
+ // A protected file to regenerate blocks the run like any protected file,
+ // so it keeps this incomplete result rather than the config error.
if (allProtected.length > 0) {
const protectedFiles = summarizeProtectedFiles(allProtected);
- logger.error(
+ const regenerate = summarizeRegenerate(
+ protectedFiles,
+ initialOutcomes.outcomes,
+ );
+ // The protected result wins, but the config error stays visible.
+ logger.error(configErr.message);
+ logProtectedFiles(
`${ERROR_CODES.ERR_CODEMOD_PROTECTED}: protected codemod changes remain while loading the Astryx config.`,
+ protectedFiles,
);
- for (const item of protectedFiles) {
- logger.error(` ${item.file} — ${item.declarations.join('; ')}`);
- }
+ logRegenerate(regenerate, protectedFiles);
if (cliBehindCore) logCliBehindCore(cliBehindCore, targetVersion);
logger.log('Upgrade incomplete: protected changes remain\n');
return {
@@ -460,13 +783,21 @@ export async function run(options = {}, {cwd = process.cwd(), origin} = {}) {
protectedFiles,
declinedCandidates: logged(
summarizeDeclinedCandidates(
- coreResult?.declinedCandidates ?? [],
+ [
+ ...(coreResult?.declinedCandidates ?? []),
+ ...manualDeclinedRows(initialOutcomes.outcomes),
+ ],
allProtected,
),
),
+ regenerate,
complete: false,
errorCode: 'ERR_CODEMOD_PROTECTED',
- errors: coreResult?.errors ?? [],
+ errors: [
+ ...(coreResult?.errors ?? []),
+ ...staleErrors,
+ {file: '.', codemod: 'config', error: configErr.message},
+ ],
...(cliBehindCore ? {cliBehindCore} : {}),
},
};
@@ -500,8 +831,12 @@ export async function run(options = {}, {cwd = process.cwd(), origin} = {}) {
// Genuine config error: abort.
logger.error(configErr.message);
logger.log('Aborted\n');
- if ((coreResult?.writtenFiles.length ?? 0) > 0) {
- // Core codemods already wrote: the error carries what they changed.
+ if (
+ (coreResult?.writtenFiles.length ?? 0) > 0 ||
+ initialOutcomes.outcomes.length > 0
+ ) {
+ // Core codemods already wrote, or reported files to regenerate or
+ // migrate by hand: the error carries what they changed and found.
if (cliBehindCore) logCliBehindCore(cliBehindCore, targetVersion);
const stopped = stoppedReceipt({
from: currentVersion,
@@ -513,8 +848,10 @@ export async function run(options = {}, {cwd = process.cwd(), origin} = {}) {
changedFiles: coreResult?.changedFiles ?? [],
transformsApplied: coreResult?.totalTransformsApplied ?? 0,
protectedRows: [],
+ outcomes: initialOutcomes.outcomes,
errors: [
...(coreResult?.errors ?? []),
+ ...staleErrors,
{file: '.', codemod: 'config', error: configErr.message},
],
declinedRows: coreResult?.declinedCandidates ?? [],
@@ -675,15 +1012,21 @@ export async function run(options = {}, {cwd = process.cwd(), origin} = {}) {
];
const registryFilesChanged = registryResult?.writtenFiles.length ?? 0;
const generatedChangeBlocked = initialProtected.some(item => item.generated);
+ // Generated outputs a codemod reported out of date: the project's declared
+ // regeneration may rebuild them, exactly like a blocked generated change.
+ const reportedRegeneration = initialOutcomes.outcomes.filter(
+ outcome => outcome.kind === 'regenerate',
+ );
const shouldRunHooks =
postCodemodHooks.length > 0 &&
(mergedFilesChanged > 0 ||
registryFilesChanged > 0 ||
- generatedChangeBlocked);
+ generatedChangeBlocked ||
+ reportedRegeneration.length > 0);
/** @type {Map<string, Buffer>} */
const protectedBeforeHooks = new Map();
if (apply && shouldRunHooks) {
- for (const item of initialProtected) {
+ for (const item of [...initialProtected, ...reportedRegeneration]) {
const absolute = path.resolve(cwd, item.file);
const relative = path.relative(cwd, absolute);
if (
@@ -718,7 +1061,12 @@ export async function run(options = {}, {cwd = process.cwd(), origin} = {}) {
const hookErr = /** @type {Error} */ (err);
const msg = `Post-codemod hook failed: ${hookErr.message}`;
logger.error(msg);
- if (initialProtected.length === 0) {
+ const protectedRegeneration = regenerationProtectionRows(
+ initialOutcomes.outcomes,
+ protection,
+ cwd,
+ );
+ if (initialProtected.length === 0 && protectedRegeneration.length === 0) {
logger.log('Upgrade failed\n');
throw failWithReceipt(
msg,
@@ -733,8 +1081,10 @@ export async function run(options = {}, {cwd = process.cwd(), origin} = {}) {
changedFiles: mergedChangedFiles,
transformsApplied: mergedTransformsApplied,
protectedRows: [],
+ outcomes: initialOutcomes.outcomes,
errors: [
...mergedErrors,
+ ...regenerationErrors(initialOutcomes.outcomes, protection, cwd),
{file: '.', codemod: 'post-codemod-hook', error: msg},
],
declinedRows: [
@@ -776,6 +1126,8 @@ export async function run(options = {}, {cwd = process.cwd(), origin} = {}) {
...(coreResult?.declinedCandidates ?? []),
...(integrationResult?.declinedCandidates ?? []),
];
+ let finalOutcomes = initialOutcomes.outcomes;
+ let finalProtection = protection;
if (apply && shouldRunHooks && !hookFailure) {
let refreshedProtection;
try {
@@ -793,9 +1145,18 @@ export async function run(options = {}, {cwd = process.cwd(), origin} = {}) {
cwd,
changedFiles: [...mergedChangedFiles, ...hookModifiedFiles],
transformsApplied: mergedTransformsApplied,
- protectedRows: initialProtected,
+ protectedRows: [
+ ...initialProtected,
+ ...regenerationProtectionRows(
+ initialOutcomes.outcomes,
+ protection,
+ cwd,
+ ),
+ ],
+ outcomes: initialOutcomes.outcomes,
errors: [
...mergedErrors,
+ ...regenerationErrors(initialOutcomes.outcomes, protection, cwd),
{file: '.', codemod: 'file-protection', error: err.message},
],
declinedRows: [
@@ -810,7 +1171,8 @@ export async function run(options = {}, {cwd = process.cwd(), origin} = {}) {
});
throw failWithReceipt(err.message, err.code, stopped);
}
- const coreCheck = await runCoreCodemods(versionManifests, {
+ const recheckOutcomes = withCodemodOutcomes(versionManifests, cwd);
+ const coreCheck = await runCoreCodemods(recheckOutcomes.versionManifests, {
apply: false,
path: path_,
codemod: options.codemod,
@@ -866,6 +1228,8 @@ export async function run(options = {}, {cwd = process.cwd(), origin} = {}) {
...(checkedCore?.declinedCandidates ?? []),
...(integrationCheck?.declinedCandidates ?? []),
];
+ finalOutcomes = recheckOutcomes.outcomes;
+ finalProtection = refreshedProtection;
finalErrors = [
...mergedErrors,
...(checkedCore?.errors ?? []),
@@ -873,7 +1237,10 @@ export async function run(options = {}, {cwd = process.cwd(), origin} = {}) {
];
}
- const protectedFiles = summarizeProtectedFiles(remainingProtected);
+ const protectedFiles = summarizeProtectedFiles([
+ ...remainingProtected,
+ ...regenerationProtectionRows(finalOutcomes, finalProtection, cwd),
+ ]);
receipt.filesChanged = mergedFilesChanged;
receipt.transformsApplied = mergedTransformsApplied;
receipt.modifiedFiles = uniqueFiles([
@@ -881,11 +1248,28 @@ export async function run(options = {}, {cwd = process.cwd(), origin} = {}) {
...hookModifiedFiles,
]).map(file => path.relative(cwd, file).split(path.sep).join('/'));
receipt.protectedFiles = protectedFiles;
- receipt.declinedCandidates = logged(
- summarizeDeclinedCandidates(remainingDeclined, remainingProtected),
+ const declinedCandidates = logged(
+ summarizeDeclinedCandidates(
+ [...remainingDeclined, ...manualDeclinedRows(finalOutcomes)],
+ // The complete final set, regeneration rows included: a file listed
+ // under protectedFiles is never also declined.
+ protectedFiles,
+ ),
);
- receipt.complete = protectedFiles.length === 0 && finalErrors.length === 0;
- if (protectedFiles.length > 0) {
+ receipt.declinedCandidates = declinedCandidates;
+ const regenerate = summarizeRegenerate(protectedFiles, finalOutcomes);
+ receipt.regenerate = regenerate;
+ // A protected file to rebuild blocks the run like any protected file
+ // (spec:AST-040 FR6). An unprotected one is a required change the codemod
+ // could not make: a codemod error. A declined candidate, a manual
+ // migration included, never blocks (FR7).
+ finalErrors = [
+ ...finalErrors,
+ ...regenerationErrors(finalOutcomes, finalProtection, cwd),
+ ];
+ const blocked = protectedFiles.length > 0;
+ receipt.complete = !blocked && finalErrors.length === 0;
+ if (blocked) {
receipt.errorCode = 'ERR_CODEMOD_PROTECTED';
} else if (finalErrors.length > 0) {
// Only on the receipt the thrown error carries (below).
@@ -895,19 +1279,15 @@ export async function run(options = {}, {cwd = process.cwd(), origin} = {}) {
if (registryResult) receipt.registryCompositions = registryResult.summary;
if (cliBehindCore) receipt.cliBehindCore = cliBehindCore;
- if (protectedFiles.length > 0) {
- logger.error(
- `${ERROR_CODES.ERR_CODEMOD_PROTECTED}: ${protectedFiles.length} protected file${protectedFiles.length === 1 ? '' : 's'} still require${protectedFiles.length === 1 ? 's' : ''} a codemod change:`,
- );
- for (const item of protectedFiles) {
- logger.error(` ${item.file} — ${item.declarations.join('; ')}`);
- for (const command of item.commands) {
- logger.log(` Regenerate with: ${command}`);
- }
- }
- }
+ logProtectedFiles(
+ `${ERROR_CODES.ERR_CODEMOD_PROTECTED}: ${protectedFiles.length} protected file${protectedFiles.length === 1 ? '' : 's'} still require${protectedFiles.length === 1 ? 's' : ''} a codemod change:`,
+ protectedFiles,
+ );
+ // Generated outputs a codemod reported out of date, beyond the protected
+ // files already listed above.
+ logRegenerate(regenerate, protectedFiles);
- if (finalErrors.length > 0 && protectedFiles.length === 0) {
+ if (finalErrors.length > 0 && !blocked) {
const msg = `Upgrade completed with ${finalErrors.length} codemod error${finalErrors.length === 1 ? '' : 's'}.`;
logger.log('Upgrade failed\n');
// The error carries the receipt: every file the codemods wrote before the
@@ -944,14 +1324,19 @@ export async function run(options = {}, {cwd = process.cwd(), origin} = {}) {
: apply
? 'Upgrade complete'
: 'Dry run complete';
+ const manualCount = countManualMigrations(declinedCandidates);
+ const manualNote =
+ manualCount > 0
+ ? `; ${manualCount} manual migration${manualCount === 1 ? '' : 's'} listed above`
+ : '';
logger.log(
protectedFiles.length > 0
? 'Upgrade incomplete: protected changes remain\n'
: !registryOk
? 'Upgrade finished with unresolved registry items\n'
: sourcePathFound
- ? done + '\n'
- : `${done}, but ${path.relative(cwd, path_) || '.'} does not exist, so no source files were scanned. ` +
+ ? done + manualNote + '\n'
+ : `${done}${manualNote}, but ${path.relative(cwd, path_) || '.'} does not exist, so no source files were scanned. ` +
`Pass --path <your source directory> if your code does not live in ./src.\n`,
);
return {
diff --git a/packages/cli/api/upgrade/upgrade.doc.mjs b/packages/cli/api/upgrade/upgrade.doc.mjs
index 41a3a23631..c799b99da6 100644
--- a/packages/cli/api/upgrade/upgrade.doc.mjs
+++ b/packages/cli/api/upgrade/upgrade.doc.mjs
@@ -128,7 +128,7 @@ export const doc = {
{
type: 'upgrade.run',
description:
- 'The terminal run receipt: from, to, codemods (count), integrations, agentDocs, agentDocsRefreshed, registryCompositions (when receipts are found), sourcePathFound (false when the resolved `path` does not exist, so nothing was scanned), filesChanged, transformsApplied, modifiedFiles, protectedFiles, declinedCandidates, errors, and complete. When a protected file still requires a change, complete is false and errorCode is ERR_CODEMOD_PROTECTED; the CLI exits nonzero while preserving the structured receipt. A run that fails after its codemods ran throws instead (see throws), and the thrown AstryxError carries the same receipt on `receipt`, with complete false and errorCode set to its code. When the installed Core is newer than the CLI, it also carries cliBehindCore ({cliVersion, command}): codemods for the releases after cliVersion did not run, and command runs the same upgrade with the matching CLI.',
+ 'The terminal run receipt: from, to, codemods (count), integrations, agentDocs, agentDocsRefreshed, registryCompositions (when receipts are found), sourcePathFound (false when the resolved `path` does not exist, so nothing was scanned), filesChanged, transformsApplied, modifiedFiles, protectedFiles, declinedCandidates (left unchanged for manual review, including code a codemod identified but cannot migrate; never incomplete), regenerate (generated files to rebuild, with their commands), errors, and complete. When a protected file still requires a change, including a protected file in regenerate, complete is false and errorCode is ERR_CODEMOD_PROTECTED; the CLI exits nonzero while preserving the structured receipt. A run that fails after its codemods ran throws instead (see throws), and the thrown AstryxError carries the same receipt on `receipt`, with complete false and errorCode set to its code. A file in regenerate that nothing protects is such a failure: it is also in errors, and the run throws ERR_CODEMOD_FAILED. When the installed Core is newer than the CLI, it also carries cliBehindCore ({cliVersion, command}): codemods for the releases after cliVersion did not run, and command runs the same upgrade with the matching CLI.',
},
],
throws: [
@@ -155,7 +155,7 @@ export const doc = {
},
{
code: 'ERR_CODEMOD_FAILED',
- when: "one or more codemods failed, or a post-codemod hook failed, and no protected file still needs a change (otherwise an upgrade.run receipt with complete: false is returned). The error carries the run's receipt on `receipt`: the files already changed, each failure in errors, complete: false",
+ when: "one or more codemods failed (including a generated file to regenerate that nothing protects), or a post-codemod hook failed, and no protected file still needs a change (otherwise an upgrade.run receipt with complete: false is returned). The error carries the run's receipt on `receipt`: the files already changed, each failure in errors, complete: false",
},
{
code: 'ERR_CODEMOD_PROTECTION_SOURCE',
diff --git a/packages/cli/api/upgrade/upgrade.type.mjs b/packages/cli/api/upgrade/upgrade.type.mjs
index 529de7ecb6..5fb4d857ba 100644
--- a/packages/cli/api/upgrade/upgrade.type.mjs
+++ b/packages/cli/api/upgrade/upgrade.type.mjs
@@ -108,6 +108,17 @@
* @property {string[]} commands Exact regeneration commands found in generated headers, when present.
*/
+/**
+ * A generated file that must be rebuilt before the upgrade is complete: a
+ * protected generated file a codemod still needs to change (also listed in
+ * `protectedFiles`), or a generated output a codemod reported out of date.
+ * @typedef {object} RegenerateFile
+ * @property {string} file Path relative to the folder the command ran in.
+ * @property {string[]} codemods Codemods that need the rebuild.
+ * @property {string[]} commands Exact commands that rebuild the file, when known: the generated header's `Command:` line, or the command the codemod names (such as `astryx theme build`).
+ * @property {string[]} messages Why a codemod reported the file out of date; empty for a protected generated file that no codemod reported out of date, whose `protectedFiles` entry carries its declarations.
+ */
+
/**
* Present only when the installed `@astryxdesign/core` (the response's `to`) is
* newer than the running CLI. Core codemods ship inside the CLI, so this CLI
@@ -131,14 +142,15 @@
* @property {AgentDocsSummary} data.agentDocs
* @property {boolean} data.sourcePathFound Whether the resolved source directory (`path`, default `./src`) exists. False means no source file was read, so a zero `filesChanged` says nothing about the project being migrated.
* @property {RegistryCompositionSummary} [data.registryCompositions]
- * @property {boolean} [data.complete] False when protected required changes remain. Also false on the receipt a failed run's error carries (`UpgradeFailureReceipt`).
+ * @property {boolean} [data.complete] False when protected required changes remain, including a protected file in `regenerate`. Declined candidates alone never make it false. Also false on the receipt a failed run's error carries (`UpgradeFailureReceipt`).
+ * @property {RegenerateFile[]} [data.regenerate] Generated files to rebuild, with their commands; rebuild them, then run the same upgrade again. A listed file the project protects (for example with an `@generated` header) is also in `protectedFiles`, with the declaration that protects it and the same commands, and makes the run incomplete with `ERR_CODEMOD_PROTECTED`. A listed file nothing protects is a codemod error: it is also in `errors`, and the run fails with `ERR_CODEMOD_FAILED` (`UpgradeFailureReceipt`).
* @property {string} [data.errorCode] Stable incomplete-result code when complete is false: `ERR_CODEMOD_PROTECTED` on a returned receipt; on the receipt a failed run's error carries, the error's own code.
* @property {number} [data.filesChanged] Distinct files changed across core + integration codemods (apply mode). One file that four codemods each changed counts once.
* @property {string[]} [data.modifiedFiles] Files changed or previewed, relative to the folder the command ran in.
* @property {ProtectedCodemodFile[]} [data.protectedFiles] Protected files that still require a codemod change after regeneration.
- * @property {Array<{file: string, location?: string, reason: string}>} [data.declinedCandidates] Candidates left unchanged because proof was insufficient, one row per file, for manual review. A protected file whose own source does not parse is listed here, with the parse error's `line:column` as `location` and a `reason` that starts with `unparseable protected file`, instead of failing the run. Declined candidates do not make the run incomplete. Each `file` is relative to the folder the command ran in.
+ * @property {Array<{file: string, location?: string, reason: string}>} [data.declinedCandidates] Candidates left unchanged because proof was insufficient, one row per file, for manual review. A protected file whose own source does not parse is listed here, with the parse error's `line:column` as `location` and a `reason` that starts with `unparseable protected file`, instead of failing the run. Code a codemod identified but cannot migrate safely is listed here too, with its line as `location` when known and a `reason` that starts with `manual migration needed (<codemod>):` followed by what to change. A file with several declined findings, of either kind, keeps one row: each finding keeps its own prefix, they are joined by `; `, unparseable-file findings first, then manual migrations, each in the order found, and `location` is the first finding's own location (absent when it has none). A later finding whose location differs from the row's ends with ` (at <location>)`, or ` (location unknown)` when it has none; one without a suffix is at the row's location. Declined candidates do not make the run incomplete. Each `file` is relative to the folder the command ran in.
* @property {number} [data.transformsApplied] Total codemod changes. A code or config codemod counts once for each file it changed, so one file changed by four of them counts four times; a project codemod counts once, however many files it writes.
- * @property {Array<{file: string, codemod: string, error: string}>} [data.errors] Per-codemod errors, when any codemod failed. On the receipt a failed run's error carries, also a post-codemod hook failure (`codemod: 'post-codemod-hook'`) or the error that stopped the run after codemods wrote files. Each `file` is relative to the folder the command ran in.
+ * @property {Array<{file: string, codemod: string, error: string}>} [data.errors] Per-codemod errors, when any codemod failed. On the receipt a failed run's error carries, also a post-codemod hook failure (`codemod: 'post-codemod-hook'`) or the error that stopped the run after codemods wrote files. A returned `ERR_CODEMOD_PROTECTED` result lists them too when a protected file wins over them: a post-codemod hook failure, or an `astryx.config` that fails validation (`{file: '.', codemod: 'config', error}`). Each `file` is relative to the folder the command ran in.
* @property {CliBehindCore} [data.cliBehindCore] Present only when the installed Core is newer than this CLI: codemods for the releases after `cliBehindCore.cliVersion` did not run.
*/
diff --git a/packages/cli/assets/codemods/outcome.mjs b/packages/cli/assets/codemods/outcome.mjs
new file mode 100644
index 0000000000..c371e50499
--- /dev/null
+++ b/packages/cli/assets/codemods/outcome.mjs
@@ -0,0 +1,79 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Codemod outcomes that are not failures.
+ *
+ * A core transform throws one of these, instead of a plain Error, when a file
+ * needs a change the codemod cannot make itself:
+ *
+ * - `ManualMigrationRequired`: a person must migrate the code (the codemod can
+ * identify it but has no safe rewrite). Reported in the upgrade receipt's
+ * `declinedCandidates`; it does not fail the run.
+ * - `RegenerationRequired`: a generated file is out of date and its generator
+ * must rebuild it. Reported in `regenerate` with the command that does; the
+ * run is incomplete until it is rebuilt.
+ *
+ * Anything else a transform throws is still a codemod failure. The upgrade
+ * leaf (`api/upgrade/_adapter.mjs` `withCodemodOutcomes`) catches these around
+ * each core transform, so the codemod runners never see them.
+ *
+ * @input A message, and the source line or regeneration commands
+ * @output Error subclasses tagged with a stable outcome kind
+ * @position Shared by core codemod transforms and the upgrade leaf
+ */
+
+const OUTCOME = Symbol.for('astryx.codemod.outcome');
+
+/** A person must migrate this code; the codemod has no safe rewrite. */
+export class ManualMigrationRequired extends Error {
+ /**
+ * @param {string} message What to change, and how.
+ * @param {{line?: number | null}} [options] 1-based source line, when known.
+ */
+ constructor(message, {line} = {}) {
+ super(message);
+ this.name = 'ManualMigrationRequired';
+ /** @type {number | undefined} */
+ this.line = typeof line === 'number' ? line : undefined;
+ Object.defineProperty(this, OUTCOME, {value: 'manual'});
+ }
+}
+
+/** A generated file is out of date; its generator must rebuild it. */
+export class RegenerationRequired extends Error {
+ /**
+ * @param {string} message Why the file is out of date.
+ * @param {{commands: string[]}} options Commands that rebuild it.
+ */
+ constructor(message, {commands}) {
+ super(message);
+ this.name = 'RegenerationRequired';
+ /** @type {string[]} */
+ this.commands = [...commands];
+ Object.defineProperty(this, OUTCOME, {value: 'regenerate'});
+ }
+}
+
+/**
+ * The outcome a thrown value reports, or null for an ordinary failure.
+ * @param {unknown} err
+ * @returns {{kind: 'manual', message: string, line?: number} | {kind: 'regenerate', message: string, commands: string[]} | null}
+ */
+export function codemodOutcome(err) {
+ if (!err || typeof err !== 'object') return null;
+ const kind = /** @type {any} */ (err)[OUTCOME];
+ const message = /** @type {Error} */ (err).message;
+ if (kind === 'manual') {
+ const line = /** @type {ManualMigrationRequired} */ (err).line;
+ return {kind, message, ...(typeof line === 'number' ? {line} : {})};
+ }
+ if (kind === 'regenerate') {
+ const commands = /** @type {RegenerationRequired} */ (err).commands;
+ return {
+ kind,
+ message,
+ commands: Array.isArray(commands) ? [...commands] : [],
+ };
+ }
+ return null;
+}
diff --git a/packages/cli/assets/codemods/outcome.test.mjs b/packages/cli/assets/codemods/outcome.test.mjs
new file mode 100644
index 0000000000..397d54ec0b
--- /dev/null
+++ b/packages/cli/assets/codemods/outcome.test.mjs
@@ -0,0 +1,40 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, expect, it} from 'vitest';
+import {
+ ManualMigrationRequired,
+ RegenerationRequired,
+ codemodOutcome,
+} from './outcome.mjs';
+
+describe('codemodOutcome', () => {
+ it('reads a manual migration with and without its line', () => {
+ expect(codemodOutcome(new ManualMigrationRequired('m', {line: 3}))).toEqual(
+ {kind: 'manual', message: 'm', line: 3},
+ );
+ expect(codemodOutcome(new ManualMigrationRequired('m'))).toEqual({
+ kind: 'manual',
+ message: 'm',
+ });
+ });
+
+ it('reads a regeneration with its commands', () => {
+ expect(
+ codemodOutcome(new RegenerationRequired('r', {commands: ['gen']})),
+ ).toEqual({kind: 'regenerate', message: 'r', commands: ['gen']});
+ });
+
+ it('treats anything else as an ordinary failure', () => {
+ expect(codemodOutcome(new Error('boom'))).toBeNull();
+ expect(
+ codemodOutcome(Object.assign(new Error('x'), {kind: 'manual'})),
+ ).toBeNull();
+ expect(codemodOutcome('boom')).toBeNull();
+ expect(codemodOutcome(undefined)).toBeNull();
+ });
+
+ it('stays an Error, so a runner without the wrapper still reports it', () => {
+ expect(new ManualMigrationRequired('m')).toBeInstanceOf(Error);
+ expect(new RegenerationRequired('r', {commands: []})).toBeInstanceOf(Error);
+ });
+});
diff --git a/packages/cli/assets/codemods/runner.mjs b/packages/cli/assets/codemods/runner.mjs
index b592c46c20..3f295c0218 100644
--- a/packages/cli/assets/codemods/runner.mjs
+++ b/packages/cli/assets/codemods/runner.mjs
@@ -508,6 +508,7 @@ async function runProjectCodemod(
* @param {string} [options.root] - Project root a project codemod reads (default: the process cwd)
* @param {{root: string, classify: (file: string) => import('../../foundation/fs/file-protection.mjs').FileProtection[]}} [options.protection] - Preloaded protection resolver
* @param {boolean} [options.coversTarget] - False when these codemods stop before the installed target (the CLI is older than Core), so a run with no changes does not say the code is up to date. Default true.
+ * @param {unknown[]} [options.outcomes] - Findings the transforms reported instead of changing a file (manual migrations, files to regenerate), filled while the run goes. A run with any does not say the code is up to date; the caller lists them.
* @returns {Promise<{totalFilesChanged: number, totalTransformsApplied: number, totalValidationBlocked: number, changedFiles: string[], writtenFiles: string[], stagedContents: Map<string, string>, protectedFiles: import('../../authoring/codemod/type').CodemodRunResult['protectedFiles'], declinedCandidates: NonNullable<import('../../authoring/codemod/type').CodemodRunResult['declinedCandidates']>, errors: Array<{file: string, codemod: string, error: string}>, skippedOptional: Array<{name: string, meta: {title: string, description?: string, fileExtensions?: string[], codemodType?: string}, version: string}>} | {ok: false, reason: string, resolvedPath: string}>}
*/
export async function runCodemods(
@@ -521,6 +522,7 @@ export async function runCodemods(
root = process.cwd(),
protection: providedProtection,
coversTarget = true,
+ outcomes,
},
) {
// No-op stub object so silent mode skips log output entirely without
@@ -735,6 +737,12 @@ export async function runCodemods(
// A later codemod can block a file an earlier one declined. The caller
// prints declined files once it has reconciled every runner's results.
const reportedDeclined = withoutProtected(declinedCandidates, protectedFiles);
+ // A generated file a transform reported out of date keeps the run from
+ // looking done, as a blocked protected file does.
+ const pendingRegeneration = (outcomes ?? []).some(
+ outcome =>
+ /** @type {{kind?: string} | null} */ (outcome)?.kind === 'regenerate',
+ );
if (
totalFilesChanged === 0 &&
@@ -744,12 +752,12 @@ export async function runCodemods(
) {
// Codemods that stop before the installed target cannot vouch for the
// code; the caller says what is missing.
- if (coversTarget) {
+ if (coversTarget && !(outcomes && outcomes.length > 0)) {
log.success('No changes needed — your code is already up to date!');
}
- } else if (apply && protectedFiles.length > 0) {
+ } else if (apply && (protectedFiles.length > 0 || pendingRegeneration)) {
log.warn(
- `Applied ${totalTransformsApplied} owned change${totalTransformsApplied === 1 ? '' : 's'} across ${totalFilesChanged} file${totalFilesChanged === 1 ? '' : 's'}; protected changes remain.`,
+ `Applied ${totalTransformsApplied} owned change${totalTransformsApplied === 1 ? '' : 's'} across ${totalFilesChanged} file${totalFilesChanged === 1 ? '' : 's'}; ${protectedFiles.length > 0 ? 'protected changes remain' : 'generated files to regenerate remain'}.`,
);
} else if (apply) {
log.success(
diff --git a/packages/cli/assets/codemods/transforms/v0.7.0/__tests__/validate-data-token-ownership.test.mjs b/packages/cli/assets/codemods/transforms/v0.7.0/__tests__/validate-data-token-ownership.test.mjs
index e137baa958..69512953f7 100644
--- a/packages/cli/assets/codemods/transforms/v0.7.0/__tests__/validate-data-token-ownership.test.mjs
+++ b/packages/cli/assets/codemods/transforms/v0.7.0/__tests__/validate-data-token-ownership.test.mjs
@@ -5,6 +5,7 @@ import * as os from 'node:os';
import * as path from 'node:path';
import {afterAll, describe, expect, it} from 'vitest';
import transform, {meta} from '../validate-data-token-ownership.mjs';
+import {codemodOutcome} from '../../../outcome.mjs';
import {upgrade} from '../../../../../api/upgrade/upgrade.mjs';
const SLOW = 30_000;
@@ -76,10 +77,20 @@ describe('validate-data-token-ownership', () => {
expect(meta.fileExtensions).toEqual(['.css']);
});
- it('fails on stale generated theme CSS with root data defaults', () => {
+ it('reports stale generated theme CSS with root data defaults as a regeneration', () => {
expect(() => transform({source: STALE_THEME, path: 'theme.css'})).toThrow(
/Rebuild it with `astryx theme build`/,
);
+ let thrown;
+ try {
+ transform({source: STALE_THEME, path: 'theme.css'});
+ } catch (err) {
+ thrown = err;
+ }
+ expect(codemodOutcome(thrown)).toMatchObject({
+ kind: 'regenerate',
+ commands: ['astryx theme build'],
+ });
});
it('passes raw data-token uses with or without a fallback', () => {
@@ -136,11 +147,20 @@ describe('validate-data-token-ownership', () => {
);
it(
- 'fails `astryx upgrade --apply` on stale generated theme CSS',
+ 'leaves `astryx upgrade --apply` incomplete on stale generated theme CSS, naming the rebuild',
async () => {
const root = project({...PREBUILT, 'src/theme.css': STALE_THEME});
- await expect(runUpgrade(root)).rejects.toMatchObject({
- code: 'ERR_CODEMOD_FAILED',
+ const res = await runUpgrade(root);
+ expect(res.data).toMatchObject({
+ complete: false,
+ errorCode: 'ERR_CODEMOD_PROTECTED',
+ errors: [],
+ regenerate: [
+ expect.objectContaining({
+ file: 'src/theme.css',
+ commands: ['astryx theme build'],
+ }),
+ ],
});
},
SLOW,
diff --git a/packages/cli/assets/codemods/transforms/v0.7.0/validate-data-token-ownership.mjs b/packages/cli/assets/codemods/transforms/v0.7.0/validate-data-token-ownership.mjs
index ad56b8dd62..29a4a8e64e 100644
--- a/packages/cli/assets/codemods/transforms/v0.7.0/validate-data-token-ownership.mjs
+++ b/packages/cli/assets/codemods/transforms/v0.7.0/validate-data-token-ownership.mjs
@@ -4,8 +4,9 @@
* @file Reject stale generated theme CSS that still owns data-token defaults.
*
* @input Generated theme CSS
- * @output No rewritten source; an upgrade error for a generated theme
- * stylesheet that still declares data-color defaults at `:root`
+ * @output No rewritten source; a regeneration report (`RegenerationRequired`,
+ * with `astryx theme build`) for a generated theme stylesheet that still
+ * declares data-color defaults at `:root`
* @position Next-release upgrade validation for spec:AST-066 FR19
*
* Raw `var(--color-data-*)` uses are not checked: prebuilt
@@ -15,6 +16,7 @@
*/
import * as path from 'node:path';
+import {RegenerationRequired} from '../../outcome.mjs';
export const meta = {
title: 'Validate data-token ownership',
@@ -36,8 +38,9 @@ export default function validateDataTokenOwnership(file) {
file.source.includes(GENERATED_THEME_HEADER) &&
ROOT_DATA_DECLARATION.test(file.source)
) {
- throw new Error(
+ throw new RegenerationRequired(
'This generated theme CSS still emits canonical data defaults at :root. Rebuild it with `astryx theme build`; defaults come from @astryxdesign/core/astryx.css in prebuilt mode, and in a source build from the @astryxdesign/build PostCSS integration or dataVars imports.',
+ {commands: ['astryx theme build']},
);
}
return undefined;
diff --git a/packages/cli/clients/cli/commands/upgrade.doc.mjs b/packages/cli/clients/cli/commands/upgrade.doc.mjs
index 88ec7e6283..9528d15088 100644
--- a/packages/cli/clients/cli/commands/upgrade.doc.mjs
+++ b/packages/cli/clients/cli/commands/upgrade.doc.mjs
@@ -108,14 +108,17 @@ export const doc = {
],
outsideProject: 'own',
exitCodes: [
- {code: 0, when: 'success, including complete dry-run previews'},
+ {
+ code: 0,
+ when: 'success, including complete dry-run previews and runs whose only findings are manual migrations',
+ },
{
code: 1,
when:
'missing or invalid --from, --registry with --list or a migration flag, a --path escape, ' +
'no installed @astryxdesign/core (or legacy @xds/core), jscodeshift missing and not installed by --install-deps, ' +
'an astryx.config that fails validation and that no pending config codemod repairs, ' +
- 'an unreadable or invalid protection declaration, a protected file that still requires a codemod change, ' +
+ 'an unreadable or invalid protection declaration, a protected file that still requires a codemod change, a generated file that must be regenerated, ' +
'an unknown codemod, a codemod or post-codemod hook failure, or unresolved registry items',
},
],
@@ -211,6 +214,21 @@ export const doc = {
'adds a TODO comment above a selector it cannot parse), the file is listed once, under `protectedFiles`, and the run is ' +
'incomplete as for any protected file. A file upgrade owns that does not parse still fails the run with ERR_CODEMOD_FAILED.',
},
+ {type: 'heading', level: 3, text: 'Manual migrations and regeneration'},
+ {
+ type: 'prose',
+ text:
+ 'Some changes a codemod can find but not make. upgrade lists them in the result, so a script can keep the rest of the run and act on each. ' +
+ 'Code a codemod can identify but cannot migrate safely is a manual migration: upgrade lists each file with its line, ' +
+ 'the codemod and what to change, finishes the run, and exits 0. With --json they are in `declinedCandidates`, one row per file (each finding in `reason` starts with `manual migration needed (<codemod>):`, and a file with several findings lists them all, joined by `; `), and `complete` stays true. ' +
+ 'A generated file that must be rebuilt is listed in `regenerate` with the command that rebuilds it, such as `astryx theme build`: a protected generated file a codemod still needs to change ' +
+ '(also in `protectedFiles`), or a generated output a codemod found out of date (also in `protectedFiles`, with the rule that protects it, when the project marks it generated). With --apply, upgrade runs your `hooks.postCodemod` commands and checks again. ' +
+ 'If a protected file still needs rebuilding, the run is incomplete exactly as for any protected file: it exits 1 and the result says `complete: false` and `errorCode: "ERR_CODEMOD_PROTECTED"`. ' +
+ 'If a file nothing protects still needs rebuilding, no protected file is in the way: the codemod could not make a required change, so it is also in `errors` and the run fails with `ERR_CODEMOD_FAILED`, as described below. ' +
+ 'Either way, rebuild it, then run the same upgrade again. ' +
+ 'When a codemod also failed, the failure is reported as below, and the receipt it carries still lists `declinedCandidates` and `regenerate`, ' +
+ 'unless a protected file to regenerate also remains, in which case the run returns `ERR_CODEMOD_PROTECTED` with the failure in `errors`.',
+ },
{type: 'heading', level: 3, text: 'A failed codemod'},
{
type: 'prose',
diff --git a/packages/cli/clients/cli/commands/upgrade.outcomes.test.mjs b/packages/cli/clients/cli/commands/upgrade.outcomes.test.mjs
new file mode 100644
index 0000000000..fdddea2cf9
--- /dev/null
+++ b/packages/cli/clients/cli/commands/upgrade.outcomes.test.mjs
@@ -0,0 +1,350 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx upgrade` end to end: generated files to rebuild are listed in
+ * `regenerate` with their commands. A file the project protects keeps the run
+ * incomplete (ERR_CODEMOD_PROTECTED, as for any protected file); one nothing
+ * protects stays a codemod error (ERR_CODEMOD_FAILED). A declared
+ * regeneration clears them, and a real codemod failure keeps its
+ * ERR_CODEMOD_FAILED error.
+ * Manual migrations are covered at the API level in
+ * `api/upgrade/run/outcomes.test.mjs`.
+ */
+
+import {afterEach, beforeEach, describe, expect, it} from 'vitest';
+import {spawnSync} from 'node:child_process';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {CLI_VERSION} from '../../../test-utils/release-fixtures.mjs';
+
+const CLI = path.resolve(
+ path.dirname(fileURLToPath(import.meta.url)),
+ '..',
+ 'bin',
+ 'astryx.mjs',
+);
+const CODEMOD = 'core:validate-data-token-ownership';
+const STALE_THEME =
+ '/* @generated by `astryx theme build` */\n' +
+ '@layer astryx-base {\n :root { --color-data-categorical-green: #008000; }\n}\n';
+const FRESH_THEME = '/* @generated by `astryx theme build` */\n.theme {}\n';
+// The generated block below authored rules: the marker is not in the leading
+// comment block, so nothing protects this file (spec:AST-040 FR3).
+const UNPROTECTED_STALE_THEME = `.app { color: red; }\n${STALE_THEME}`;
+
+let root;
+
+function write(relative, contents) {
+ const file = path.join(root, relative);
+ fs.mkdirSync(path.dirname(file), {recursive: true});
+ fs.writeFileSync(file, contents);
+}
+
+function read(relative) {
+ return fs.readFileSync(path.join(root, relative), 'utf8');
+}
+
+function run(args, {json = true, cwd = root} = {}) {
+ const result = spawnSync(
+ process.execPath,
+ [CLI, ...(json ? ['--json'] : []), 'upgrade', ...args],
+ {
+ cwd,
+ encoding: 'utf8',
+ timeout: 60_000,
+ env: {...process.env, FORCE_COLOR: '0', CI: ''},
+ },
+ );
+ return {...result, envelope: json ? JSON.parse(result.stdout) : null};
+}
+
+/** @param {{config?: string}} [options] */
+function seed({config = 'export default {};\n'} = {}) {
+ write(
+ 'package.json',
+ JSON.stringify({
+ name: 'consumer',
+ private: true,
+ dependencies: {'@astryxdesign/core': CLI_VERSION},
+ }),
+ );
+ write(
+ 'node_modules/@astryxdesign/core/package.json',
+ JSON.stringify({name: '@astryxdesign/core', version: CLI_VERSION}),
+ );
+ write('astryx.config.mjs', config);
+}
+
+const ONLY = ['--from', '0.6.0', '--codemod', 'validate-data-token-ownership'];
+
+beforeEach(() => {
+ root = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-upgrade-outcomes-'));
+});
+
+afterEach(() => {
+ fs.rmSync(root, {recursive: true, force: true});
+});
+
+describe('generated files to regenerate', () => {
+ it('are listed with the rebuild command, and in protectedFiles with the declaration that protects them', () => {
+ seed();
+ write('app/theme.css', STALE_THEME);
+
+ const applied = run([...ONLY, '--path', '.', '--apply']);
+
+ expect(applied.status).toBe(1);
+ expect(applied.envelope).toMatchObject({
+ type: 'upgrade.run',
+ data: {
+ complete: false,
+ errorCode: 'ERR_CODEMOD_PROTECTED',
+ errors: [],
+ declinedCandidates: [],
+ // The stale theme carries an @generated header, so it is a protected
+ // file that still requires a change, with its declaration.
+ protectedFiles: [
+ {
+ file: 'app/theme.css',
+ codemods: [CODEMOD],
+ reasons: ['generated'],
+ declarations: [expect.stringContaining('@generated')],
+ commands: ['astryx theme build'],
+ },
+ ],
+ regenerate: [
+ {
+ file: 'app/theme.css',
+ codemods: [CODEMOD],
+ commands: ['astryx theme build'],
+ messages: [expect.stringContaining('Rebuild it')],
+ },
+ ],
+ },
+ });
+ expect(read('app/theme.css')).toBe(STALE_THEME);
+ });
+
+ it('read as incomplete in text, never as up to date', () => {
+ seed();
+ write('app/theme.css', STALE_THEME);
+
+ const text = run([...ONLY, '--path', '.', '--apply'], {json: false});
+
+ expect(text.status).toBe(1);
+ expect(text.stderr).toMatch(
+ /ERR_CODEMOD_PROTECTED: 1 protected file still requires a codemod change:\n\s+app\/theme\.css — .*@generated/,
+ );
+ expect(text.stdout).toMatch(/Regenerate with: astryx theme build/);
+ expect(text.stdout).toMatch(/Upgrade incomplete/);
+ expect(`${text.stdout}\n${text.stderr}`).not.toMatch(/No changes needed/);
+ });
+
+ it('keep the incomplete result, not a config error, when astryx.config fails validation too', () => {
+ seed({config: "export default {theme: 'neutral'};\n"});
+ write('app/theme.css', STALE_THEME);
+
+ const applied = run([...ONLY, '--path', '.', '--apply']);
+
+ expect(applied.status).toBe(1);
+ expect(applied.envelope).toMatchObject({
+ type: 'upgrade.run',
+ data: {
+ complete: false,
+ errorCode: 'ERR_CODEMOD_PROTECTED',
+ protectedFiles: [expect.objectContaining({file: 'app/theme.css'})],
+ regenerate: [
+ expect.objectContaining({
+ file: 'app/theme.css',
+ commands: ['astryx theme build'],
+ }),
+ ],
+ // The config's own error is still listed, as main reports it.
+ errors: [
+ {
+ file: '.',
+ codemod: 'config',
+ error: expect.stringContaining('astryx.config'),
+ },
+ ],
+ },
+ });
+
+ const configError = applied.envelope.data.errors[0].error;
+ const text = run([...ONLY, '--path', '.', '--apply'], {json: false});
+ expect(text.status).toBe(1);
+ expect(text.stderr).toContain(configError);
+ expect(text.stdout).toMatch(/Upgrade incomplete: protected changes remain/);
+ });
+
+ it('include protected generated files with their header command, alongside protectedFiles', () => {
+ seed();
+ write('.gitattributes', 'generated/** linguist-generated=true\n');
+ write(
+ 'generated/panel.tsx',
+ '// @generated\n// Command: pnpm run gen:panel\n' +
+ "import {useResizable} from '@astryxdesign/core';\n" +
+ 'export const usePanel = () => useResizable({minSizePx: 200});\n',
+ );
+
+ const applied = run([
+ '--from',
+ '0.5.0',
+ '--codemod',
+ 'rename-resizable-pixel-bounds',
+ '--path',
+ '.',
+ '--apply',
+ ]);
+
+ expect(applied.status).toBe(1);
+ expect(applied.envelope.data).toMatchObject({
+ complete: false,
+ errorCode: 'ERR_CODEMOD_PROTECTED',
+ protectedFiles: [expect.objectContaining({file: 'generated/panel.tsx'})],
+ regenerate: [
+ {
+ file: 'generated/panel.tsx',
+ codemods: ['core:rename-resizable-pixel-bounds'],
+ commands: ['pnpm run gen:panel'],
+ messages: [],
+ },
+ ],
+ });
+ });
+
+ it('clear once the declared regeneration rebuilds the file', () => {
+ const rebuild = `require('node:fs').writeFileSync('app/theme.css', ${JSON.stringify(FRESH_THEME)})`;
+ seed({
+ config: `export default {hooks: {postCodemod: [{name: 'theme', buildCommand: () => ({command: process.execPath, args: ['-e', ${JSON.stringify(rebuild)}]})}]}};\n`,
+ });
+ write('app/theme.css', STALE_THEME);
+
+ const applied = run([...ONLY, '--path', '.', '--apply']);
+
+ expect(applied.status, applied.stderr).toBe(0);
+ expect(applied.envelope.data).toMatchObject({
+ complete: true,
+ regenerate: [],
+ modifiedFiles: ['app/theme.css'],
+ });
+ expect(read('app/theme.css')).toBe(FRESH_THEME);
+ });
+
+ it('report one nothing protects as a codemod error, not ERR_CODEMOD_PROTECTED', () => {
+ seed();
+ write('app/theme.css', UNPROTECTED_STALE_THEME);
+
+ const applied = run([...ONLY, '--path', '.', '--apply']);
+
+ expect(applied.status).toBe(1);
+ expect(applied.envelope).not.toHaveProperty('type');
+ expect(applied.envelope).toMatchObject({
+ code: 'ERR_CODEMOD_FAILED',
+ receipt: {
+ complete: false,
+ errorCode: 'ERR_CODEMOD_FAILED',
+ protectedFiles: [],
+ errors: [
+ expect.objectContaining({
+ file: 'app/theme.css',
+ codemod: CODEMOD,
+ error: expect.stringContaining('Rebuild it'),
+ }),
+ ],
+ regenerate: [
+ expect.objectContaining({
+ file: 'app/theme.css',
+ commands: ['astryx theme build'],
+ }),
+ ],
+ },
+ });
+
+ const text = run([...ONLY, '--path', '.', '--apply'], {json: false});
+ expect(text.status).toBe(1);
+ expect(text.stderr).toMatch(
+ /1 generated file must be regenerated:\n\s+app\/theme\.css — /,
+ );
+ expect(text.stderr).not.toMatch(/ERR_CODEMOD_PROTECTED/);
+ expect(text.stdout).toMatch(/Regenerate with: astryx theme build/);
+ expect(text.stdout).toMatch(/Upgrade failed/);
+ expect(`${text.stdout}\n${text.stderr}`).not.toMatch(
+ /No changes needed|Done!/,
+ );
+ });
+
+ it('name files from the folder the command runs in', () => {
+ seed();
+ write('app/theme.css', STALE_THEME);
+
+ const applied = run([...ONLY, '--path', '.', '--apply'], {
+ cwd: path.join(root, 'app'),
+ });
+
+ expect(applied.envelope.data).toMatchObject({
+ regenerate: [expect.objectContaining({file: 'theme.css'})],
+ });
+ });
+});
+
+describe('a real failure beside them', () => {
+ function seedFailing() {
+ seed({config: "export default {integrations: ['@acme/widgets']};\n"});
+ write(
+ 'node_modules/@acme/widgets/package.json',
+ JSON.stringify({name: '@acme/widgets', version: '1.0.0'}),
+ );
+ write(
+ 'node_modules/@acme/widgets/astryx.integration.mjs',
+ "export default {codemods: './codemods'};\n",
+ );
+ write(
+ 'node_modules/@acme/widgets/codemods/0.7.0/fail.mjs',
+ "export default {type: 'code', title: 'Fail on boom', transform: file => { if (file.source.includes('boom')) throw new Error('codemod boom'); return undefined; }};\n",
+ );
+ write('src/broken.ts', 'export const boom = 1;\n');
+ }
+
+ it('keeps the ERR_CODEMOD_FAILED error, whose receipt carries both lists', () => {
+ seedFailing();
+
+ const applied = run(['--from', '0.6.0', '--path', 'src', '--apply']);
+
+ expect(applied.status).toBe(1);
+ expect(applied.envelope).toMatchObject({
+ code: 'ERR_CODEMOD_FAILED',
+ receipt: {
+ complete: false,
+ errorCode: 'ERR_CODEMOD_FAILED',
+ errors: [
+ expect.objectContaining({
+ file: 'src/broken.ts',
+ codemod: '@acme/widgets:fail',
+ }),
+ ],
+ declinedCandidates: [],
+ regenerate: [],
+ },
+ });
+ });
+
+ it('with a protected file to regenerate, returns the incomplete receipt as for a protected file', () => {
+ seedFailing();
+ write('src/theme.css', STALE_THEME);
+
+ const applied = run(['--from', '0.6.0', '--path', 'src', '--apply']);
+
+ expect(applied.status).toBe(1);
+ expect(applied.envelope).toMatchObject({
+ type: 'upgrade.run',
+ data: {
+ complete: false,
+ errorCode: 'ERR_CODEMOD_PROTECTED',
+ errors: [expect.objectContaining({file: 'src/broken.ts'})],
+ regenerate: [expect.objectContaining({file: 'src/theme.css'})],
+ },
+ });
+ });
+});
diff --git a/packages/cli/foundation/response/response-types.doc.mjs b/packages/cli/foundation/response/response-types.doc.mjs
index 2f36be5d50..980338eaad 100644
--- a/packages/cli/foundation/response/response-types.doc.mjs
+++ b/packages/cli/foundation/response/response-types.doc.mjs
@@ -388,7 +388,7 @@ export const doc = {
{
value: 'upgrade.run',
description:
- 'The run receipt: from/to versions, codemod count, integrations processed, the agent-docs summary, sourcePathFound (false when the resolved source directory does not exist, so no source file was read), and (apply mode) filesChanged, transformsApplied, and per-codemod errors. When the installed Core is newer than the CLI, it also carries cliBehindCore ({cliVersion, command}): codemods for the releases after cliVersion did not run.',
+ 'The run receipt: from/to versions, codemod count, integrations processed, the agent-docs summary, sourcePathFound (false when the resolved source directory does not exist, so no source file was read), and (apply mode) filesChanged, transformsApplied, and per-codemod errors. regenerate lists generated files to rebuild, each with its codemods, commands and messages. When the installed Core is newer than the CLI, it also carries cliBehindCore ({cliVersion, command}): codemods for the releases after cliVersion did not run.',
},
// manifest