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.mdnew file mode 100644index 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.++@ejhammonddiff --git a/packages/cli/README.md b/packages/cli/README.mdindex 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.mjsindex 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.mjsnew file mode 100644index 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsnew file mode 100644index 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.mjsnew file mode 100644index 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsnew file mode 100644index 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.mjsindex 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