An open source design system that's fully customizable and agent ready
TypeScript
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
* @file upgrade.run leaf — the terminal, side-effecting run receipt.
*
* Orchestrates the non-list upgrade pipeline over the shared `_adapter.mjs`
* machinery and returns the run receipt. It also OWNS the two mid-pipeline
* short-circuits that resolve to `upgrade.status` (no_codemods, config_fixable)
* plus the early up_to_date exit — each delegated to the `status` leaf so the
* status envelope + its human lines live in one place.
*
* Pipeline (--apply): detect installed core → run CORE codemods (before
* Project.load, so a core CONFIG codemod can repair an otherwise-invalid
* config) → load config → discover + run INTEGRATION codemods → reconcile
* ShadCN-copied compositions → post-codemod hooks → render + refresh agent docs
* from final post-upgrade state. Integration DISCOVERY errors skip that
* integration; execution errors abort before the agent-doc write.
*
* Core codemods ship inside the CLI, so a CLI older than the installed Core
* has none for the releases after its own version. Every result past the
* up-to-date exit then carries `cliBehindCore`, and no human line says the
* upgrade finished; the warning names the same upgrade on the matching CLI.
*/
import * as fs from 'node:fs';
import * as path from 'node:path';
import {
detectInstalledTargetVersion,
detectCliBehindCore,
prepareAgentDocsRefresh,
applyAgentDocsRefresh,
inspectAgentDocs,
uniqueFiles,
runPostCodemodHooks,
getCoreVersionManifests,
ensureCodemodDeps,
runCoreCodemods,
loadProjectContext,
warnIntegrationIssues,
selectIntegrationCodemodsFor,
runIntegrationCodemodsStep,
withCodemodOutcomes,
} from '../_adapter.mjs';
import {
logRegistryCompositionSummary,
reconcileRegistryCompositions,
} from '../registry/registry.mjs';
import {
statusUpToDate,
statusNoCodemods,
statusConfigFixable,
logCliBehindCore,
} from '../status/status.mjs';
import {semverGte} from '../../../foundation/env/semver.mjs';
import {getCliInvocation} from '../../../foundation/env/package-manager.mjs';
import {isOutsideProject} from '../../../foundation/env/project-scope.mjs';
import {ERROR_CODES} from '../../../foundation/response/error-codes.mjs';
import {AstryxError} from '../../error.mjs';
import {logger} from '../../logger.mjs';
import {
assertWithin,
PathSafetyError,
} from '../../../foundation/fs/path-safety.mjs';
import {createFileProtectionResolver} from '../../../foundation/fs/file-protection.mjs';
import {withoutProtected} from '../../../assets/codemods/runner.mjs';
/**
* Collapse per-codemod protection hits into one stable row per file.
* @param {Array<{file: string, codemod: string, reason: string, declaration: string, generated: boolean, command?: string}>} rows
*/
function summarizeProtectedFiles(rows) {
const byFile = new Map();
for (const row of rows) {
const current = byFile.get(row.file) ?? {
file: row.file,
codemods: new Set(),
reasons: new Set(),
declarations: new Set(),
commands: new Set(),
};
current.codemods.add(row.codemod);
current.reasons.add(row.reason);
current.declarations.add(row.declaration);
if (row.command) current.commands.add(row.command);
byFile.set(row.file, current);
}
return [...byFile.values()]
.map(item => ({
file: item.file,
codemods: [...item.codemods].sort(),
reasons: [...item.reasons].sort(),
declarations: [...item.declarations].sort(),
commands: [...item.commands].sort(),
}))
.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}>}
*/
export function summarizeDeclinedCandidates(
rows,
protectedRows = [],
sep = path.sep,
) {
/** @type {Map<string, Array<{location?: string, reason: string}>>} */
const byFile = new Map();
for (const {file: raw, location, reason} of withoutProtected(
rows,
protectedRows,
)) {
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.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 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) {
/** @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 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}`);
}
}
}
/**
* @template {Array<{file: string, location?: string, reason: string}>} T
* @param {T} declined
* @returns {T}
*/
function logged(declined) {
logDeclined(declined);
return declined;
}
/** @param {string} cwd */
function loadFileProtection(cwd) {
try {
return createFileProtectionResolver(cwd);
} catch (err) {
const message = err instanceof Error ? err.message : String(err);
logger.error(message);
logger.log('Upgrade failed\n');
throw new AstryxError(
message,
undefined,
ERROR_CODES.ERR_CODEMOD_PROTECTION_SOURCE,
);
}
}
/**
* 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
* receipt (`failWithReceipt`): a caller that reads only the error would
* 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}>, 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({
from,
to,
codemods,
integrations,
sourcePathFound,
cwd,
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,
codemods,
integrations,
agentDocsRefreshed: false,
agentDocs: {
status: 'current',
installedVersion: to,
fromVersions: [],
files: [],
refreshed: false,
action: 'none',
},
sourcePathFound,
filesChanged: modifiedFiles.length,
transformsApplied,
modifiedFiles,
protectedFiles,
declinedCandidates: logged(
summarizeDeclinedCandidates(
[...declinedRows, ...manualDeclinedRows(outcomes)],
protectedRows,
),
),
regenerate,
complete: false,
errorCode,
errors,
...(registryCompositions ? {registryCompositions} : {}),
...(cliBehindCore ? {cliBehindCore} : {}),
});
}
/**
* The error a run throws once codemods have run: the same message and stable
* code as always, plus the run's receipt on `receipt`, so the JSON error
* envelope and a programmatic caller can still see what was written.
* @param {string} message
* @param {string} code
* @param {import('../upgrade.type.mjs').UpgradeRunResponse['data']} receipt
* @returns {AstryxError & {receipt: import('../upgrade.type.mjs').UpgradeRunResponse['data']}}
*/
function failWithReceipt(message, code, receipt) {
const err =
/** @type {AstryxError & {receipt: import('../upgrade.type.mjs').UpgradeRunResponse['data']}} */ (
new AstryxError(message, undefined, code)
);
err.receipt = receipt;
return err;
}
/**
* Run the upgrade pipeline for a validated, non-list invocation. Returns the
* terminal run receipt, or one of the status short-circuits; throws AstryxError
* on failure. Progress is emitted through the shared `logger` (silent by default).
*
* @param {import('../_adapter.mjs').UpgradeOptions} [options]
* @param {{cwd?: string, origin?: string}} [ctx] `origin` is the folder the
* command ran in, when `cwd` is the project root above it
* @returns {Promise<import('../upgrade.type.mjs').UpgradeStatusResponse | import('../upgrade.type.mjs').UpgradeRunResponse>}
*/
export async function run(options = {}, {cwd = process.cwd(), origin} = {}) {
// Resolve the source dir against the API's cwd (not process.cwd()) so a
// programmatic caller in another directory scans the right tree. Confine it to
// cwd: --apply rewrites files in place, so a `..`-escaping or out-of-tree
// absolute --path must be rejected (parity with template/theme/swizzle/layout,
// and this is the most destructive command). allowAbsolute permits an absolute
// path that still resolves inside cwd.
let path_;
try {
path_ = assertWithin(options.path ?? './src', cwd, {
allowAbsolute: true,
label: 'source directory',
});
} catch (err) {
if (err instanceof PathSafetyError) {
logger.error(err.message);
logger.log('Aborted\n');
throw new AstryxError(
err.message,
undefined,
ERROR_CODES.ERR_PATH_TRAVERSAL,
);
}
throw err;
}
const apply = options.apply ?? false;
// One fact about the resolved source directory, captured before anything
// runs. `--path` defaults to `./src`, so a project laid out as `app/` (or a
// typo) skips every code codemod; without this the receipt is byte-identical
// to a clean, fully migrated project.
const sourcePathFound = fs.existsSync(path_);
const currentVersion = /** @type {string} */ (options.from);
// Named first, so a run that stops on the Core lookup below still says which
// folder it searched (spec:AST-040 FR12).
if (origin != null) {
logger.log(`Project root: ${path.relative(origin, cwd) || '.'}`);
logger.log(`Source folder: ${path.relative(origin, path_) || '.'}`);
}
const installed = detectInstalledTargetVersion(cwd);
if (!installed) {
// Outside a project there is no version to install (spec AST-081 FR3).
const msg = isOutsideProject(cwd)
? 'Could not find installed @astryxdesign/core (or legacy @xds/core). This folder is outside a project; upgrade migrates the code of an app project that installs @astryxdesign/core.'
: `Could not find installed @astryxdesign/core (or legacy @xds/core). Install the target version first, then rerun \`${getCliInvocation()} upgrade --from <old-version>\`.`;
logger.error(msg);
logger.log('Aborted\n');
throw new AstryxError(msg, undefined, ERROR_CODES.ERR_VERSION_DETECT);
}
const targetVersion = installed.version;
const reconcileCompositions = async () => {
if (options.codemod) return null;
const result = await reconcileRegistryCompositions(
{apply, path: path_},
{
cwd,
origin,
expectedVersion:
installed.packageName === '@astryxdesign/core'
? targetVersion
: undefined,
requireExpectedVersion: true,
},
);
if (result.summary.found > 0) {
logRegistryCompositionSummary(result.summary);
return result;
}
return null;
};
logger.log(`From version: ${currentVersion}`);
logger.log(`Installed target: ${targetVersion} (${installed.packageName})`);
// Up-to-date check — no codemods will run, safe to render agent docs now.
if (!options.force && semverGte(currentVersion, targetVersion)) {
const registryResult = await reconcileCompositions();
const agentDocsPlan = await prepareAgentDocsRefresh({
cwd,
origin,
installedVersion: targetVersion,
apply,
});
const agentDocs = apply
? applyAgentDocsRefresh(agentDocsPlan)
: agentDocsPlan.summary;
return statusUpToDate({
from: currentVersion,
to: targetVersion,
agentDocs,
...(registryResult ? {registryCompositions: registryResult.summary} : {}),
});
}
// Past the up-to-date exit, codemods are needed through targetVersion. A
// CLI older than that has none for the releases after its own version.
const cliBehindCore = detectCliBehindCore({
from: currentVersion,
to: targetVersion,
packageName: installed.packageName,
options,
cwd,
sourcePath: path_,
});
const versionManifests = await getCoreVersionManifests(
currentVersion,
targetVersion,
);
const coreConfigCodemodNames = [];
for (const {transforms} of versionManifests) {
for (const t of transforms) {
if (options.codemod && t.name !== options.codemod) continue;
if (t.meta?.codemodType === 'config') coreConfigCodemodNames.push(t.name);
}
}
const hasCoreConfigCodemod = coreConfigCodemodNames.length > 0;
const skipCodemods = new Set(options.skipCodemod ?? []);
let totalTransforms = 0;
let totalOptional = 0;
for (const {transforms} of versionManifests) {
for (const t of transforms) {
if (options.codemod && t.name !== options.codemod) continue;
if (skipCodemods.has(t.name)) continue;
if (t.optional && !options.codemod) totalOptional++;
else totalTransforms++;
}
}
// Read and parse all working-tree protection declarations before any
// dependency installation or codemod write. Core and integration runners
// share this exact snapshot.
let protection = loadFileProtection(cwd);
const ready = await ensureCodemodDeps({installDeps: options.installDeps});
if (!ready) {
const msg = 'jscodeshift is required but could not be installed.';
logger.log('Aborted\n');
throw new AstryxError(msg, undefined, ERROR_CODES.ERR_DEP_MISSING);
}
// CORE codemods run FIRST (before loading config) so a core CONFIG codemod can
// 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
: null;
/** @type {Array<import('../../../foundation/integrations/integrations.mjs').LoadedIntegration>} */
let integrations;
/** @type {import('../../../authoring/config/type').PostCodemodHook[]} */
let postCodemodHooks;
/** @type {boolean} */
let iconSets;
try {
const projectContext = await loadProjectContext(
cwd,
options.integration ?? [],
);
postCodemodHooks = projectContext.postCodemodHooks;
integrations = projectContext.integrations;
iconSets = projectContext.iconSets;
} catch (err) {
const configErr = /** @type {Error} */ (err);
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);
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,
);
logRegenerate(regenerate, protectedFiles);
if (cliBehindCore) logCliBehindCore(cliBehindCore, targetVersion);
logger.log('Upgrade incomplete: protected changes remain\n');
return {
type: 'upgrade.run',
data: {
from: currentVersion,
to: targetVersion,
codemods: totalTransforms,
integrations: [],
agentDocsRefreshed: false,
agentDocs: {
status: 'current',
installedVersion: targetVersion,
fromVersions: [],
files: [],
refreshed: false,
action: 'none',
},
sourcePathFound,
filesChanged: coreResult?.totalFilesChanged ?? 0,
transformsApplied: coreResult?.totalTransformsApplied ?? 0,
modifiedFiles: uniqueFiles(coreResult?.changedFiles).map(file =>
path.relative(cwd, file).split(path.sep).join('/'),
),
protectedFiles,
declinedCandidates: logged(
summarizeDeclinedCandidates(
[
...(coreResult?.declinedCandidates ?? []),
...manualDeclinedRows(initialOutcomes.outcomes),
],
allProtected,
),
),
regenerate,
complete: false,
errorCode: 'ERR_CODEMOD_PROTECTED',
errors: [
...(coreResult?.errors ?? []),
...staleErrors,
{file: '.', codemod: 'config', error: configErr.message},
],
...(cliBehindCore ? {cliBehindCore} : {}),
},
};
}
// Graceful dry-run catch: a config that fails strict validation is expected
// & fixable ONLY when dry-run AND a pending core config codemod previewed a
// change (the codemod that would repair it).
const codemodWouldFixConfig =
hasCoreConfigCodemod && (coreResult?.totalFilesChanged ?? 0) > 0;
if (!apply && codemodWouldFixConfig) {
// Lightweight inspection — no config/Project load (config is still broken
// in dry-run; the codemod previewed a fix but did not write it).
const inspection = inspectAgentDocs(cwd, targetVersion);
return statusConfigFixable({
from: currentVersion,
to: targetVersion,
configError: configErr.message,
configCodemods: coreConfigCodemodNames,
cliBehindCore,
agentDocs:
/** @type {import('../upgrade.type.mjs').AgentDocsSummary} */ ({
status: inspection.status,
installedVersion: targetVersion,
fromVersions: inspection.blockVersions,
files: inspection.staleFiles,
refreshed: false,
action: inspection.status === 'missing' ? 'nudge-init' : 'none',
}),
});
}
// Genuine config error: abort.
logger.error(configErr.message);
logger.log('Aborted\n');
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,
to: targetVersion,
codemods: totalTransforms,
integrations: [],
sourcePathFound,
cwd,
changedFiles: coreResult?.changedFiles ?? [],
transformsApplied: coreResult?.totalTransformsApplied ?? 0,
protectedRows: [],
outcomes: initialOutcomes.outcomes,
errors: [
...(coreResult?.errors ?? []),
...staleErrors,
{file: '.', codemod: 'config', error: configErr.message},
],
declinedRows: coreResult?.declinedCandidates ?? [],
errorCode: ERROR_CODES.ERR_INVALID_ARGUMENT,
cliBehindCore,
});
throw failWithReceipt(
configErr.message,
ERROR_CODES.ERR_INVALID_ARGUMENT,
stopped,
);
}
throw new AstryxError(
configErr.message,
undefined,
ERROR_CODES.ERR_INVALID_ARGUMENT,
);
}
if (integrations.length > 0) {
logger.log(
`Integrations: ${integrations.map(i => i.name ?? i.__spec).join(', ')}`,
);
}
// Non-blocking nudge for integration validation issues (suppressed for
// programmatic/--json callers, i.e. the silent logger).
await warnIntegrationIssues(integrations, {iconSets});
const integrationVersionGroups = await selectIntegrationCodemodsFor(
integrations,
currentVersion,
targetVersion,
);
const hasIntegrationCodemods = integrationVersionGroups.some(
g => g.codemods.length > 0,
);
for (const {codemods} of integrationVersionGroups) {
for (const c of codemods) {
if (options.codemod && c.id !== options.codemod) continue;
if (skipCodemods.has(c.id)) continue;
if (c.codemod.isOptional && !options.codemod) totalOptional++;
else totalTransforms++;
}
}
if (versionManifests.length === 0 && !hasIntegrationCodemods) {
const registryResult = await reconcileCompositions();
// No codemods in range — safe to render agent docs from current state.
const agentDocsPlan = await prepareAgentDocsRefresh({
cwd,
origin,
installedVersion: targetVersion,
apply,
});
const agentDocs = apply
? applyAgentDocsRefresh(agentDocsPlan)
: agentDocsPlan.summary;
return statusNoCodemods({
from: currentVersion,
to: targetVersion,
agentDocs,
...(registryResult ? {registryCompositions: registryResult.summary} : {}),
cliBehindCore,
});
}
if (totalTransforms === 0 && totalOptional === 0) {
const msg = `Codemod "${options.codemod}" not found. Use --list to see available codemods.`;
logger.error(msg);
logger.log('Aborted\n');
throw new AstryxError(msg, undefined, ERROR_CODES.ERR_UNKNOWN_CODEMOD);
}
if (totalTransforms > 0) {
logger.log(
`${totalTransforms} codemod${totalTransforms === 1 ? '' : 's'} to run${apply ? '' : ' (dry run)'}`,
);
} else {
logger.log('No automatic codemods to run for this version range.');
}
/** @type {import('../upgrade.type.mjs').UpgradeRunResponse['data']} */
const receipt = {
from: currentVersion,
to: targetVersion,
codemods: totalTransforms,
integrations: integrations.map(i => i.name ?? i.__spec),
agentDocsRefreshed: false,
agentDocs: /** @type {import('../upgrade.type.mjs').AgentDocsSummary} */ ({
status: 'current',
installedVersion: targetVersion,
fromVersions: [],
files: [],
refreshed: false,
action: 'none',
}),
// A missing source directory is the one way this command can migrate
// nothing and still look complete: every codemod is skipped, filesChanged
// stays 0, and errors stays empty. The receipt carries the fact so a
// machine consumer can tell "nothing needed changing" from "nothing was
// ever read" — the human text says so via the runner's own error line.
sourcePathFound,
};
let integrationResult = null;
if (hasIntegrationCodemods) {
const coreStagedContents = coreResult?.stagedContents;
if (
(coreResult?.writtenFiles.length ?? 0) > 0 ||
(coreStagedContents?.size ?? 0) > 0
) {
protection = createFileProtectionResolver(cwd, {
overrides: coreStagedContents,
});
}
logger.log('Applying integration codemods...');
integrationResult = await runIntegrationCodemodsStep(
integrationVersionGroups,
{
apply,
path: path_,
codemod: options.codemod,
skipCodemods,
root: cwd,
protection,
contents: coreStagedContents,
},
);
}
const registryResult = await reconcileCompositions();
// A file a core codemod AND an integration codemod both changed is one file.
const mergedFilesChanged = new Set([
...(coreResult?.changedFiles ?? []),
...(integrationResult?.changedFiles ?? []),
]).size;
const mergedTransformsApplied =
(coreResult?.totalTransformsApplied ?? 0) +
(integrationResult?.totalTransformsApplied ?? 0);
const mergedChangedFiles = [
...(coreResult?.changedFiles ?? []),
...(integrationResult?.changedFiles ?? []),
...(registryResult?.writtenFiles ?? []),
];
const mergedErrors = [
...(coreResult?.errors ?? []),
...(integrationResult?.errors ?? []),
];
let finalErrors = mergedErrors;
/** @type {string|undefined} */
let hookFailure;
const initialProtected = [
...(coreResult?.protectedFiles ?? []),
...(integrationResult?.protectedFiles ?? []),
];
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 ||
reportedRegeneration.length > 0);
/** @type {Map<string, Buffer>} */
const protectedBeforeHooks = new Map();
if (apply && shouldRunHooks) {
for (const item of [...initialProtected, ...reportedRegeneration]) {
const absolute = path.resolve(cwd, item.file);
const relative = path.relative(cwd, absolute);
if (
relative.startsWith(`..${path.sep}`) ||
relative === '..' ||
path.isAbsolute(relative)
)
continue;
try {
if (fs.lstatSync(absolute).isFile()) {
protectedBeforeHooks.set(absolute, fs.readFileSync(absolute));
}
} catch {
// A candidate can disappear between planning and regeneration.
}
}
}
/** @type {string[]} */
const hookModifiedFiles = [];
if (shouldRunHooks) {
const files = uniqueFiles(mergedChangedFiles).map(file =>
path.relative(cwd, file),
);
try {
await runPostCodemodHooks(postCodemodHooks, {
packageDir: cwd,
files,
apply: apply || false,
});
} catch (err) {
const hookErr = /** @type {Error} */ (err);
const msg = `Post-codemod hook failed: ${hookErr.message}`;
logger.error(msg);
const protectedRegeneration = regenerationProtectionRows(
initialOutcomes.outcomes,
protection,
cwd,
);
if (initialProtected.length === 0 && protectedRegeneration.length === 0) {
logger.log('Upgrade failed\n');
throw failWithReceipt(
msg,
ERROR_CODES.ERR_CODEMOD_FAILED,
stoppedReceipt({
from: currentVersion,
to: targetVersion,
codemods: totalTransforms,
integrations: receipt.integrations,
sourcePathFound,
cwd,
changedFiles: mergedChangedFiles,
transformsApplied: mergedTransformsApplied,
protectedRows: [],
outcomes: initialOutcomes.outcomes,
errors: [
...mergedErrors,
...regenerationErrors(initialOutcomes.outcomes, protection, cwd),
{file: '.', codemod: 'post-codemod-hook', error: msg},
],
declinedRows: [
...(coreResult?.declinedCandidates ?? []),
...(integrationResult?.declinedCandidates ?? []),
],
errorCode: ERROR_CODES.ERR_CODEMOD_FAILED,
cliBehindCore,
...(registryResult
? {registryCompositions: registryResult.summary}
: {}),
}),
);
}
hookFailure = msg;
finalErrors = [
...mergedErrors,
{file: '.', codemod: 'post-codemod-hook', error: msg},
];
logger.log('Regeneration failed; protected changes remain\n');
}
if (apply) {
for (const [file, before] of protectedBeforeHooks) {
try {
if (!before.equals(fs.readFileSync(file)))
hookModifiedFiles.push(file);
} catch {
hookModifiedFiles.push(file);
}
}
}
}
// A successful apply hook may have regenerated protected outputs. Rerun the
// selected codemods in preview mode against fresh bytes and fresh declarations
// to distinguish resolved outputs from changes that remain blocked.
let remainingProtected = initialProtected;
let remainingDeclined = [
...(coreResult?.declinedCandidates ?? []),
...(integrationResult?.declinedCandidates ?? []),
];
let finalOutcomes = initialOutcomes.outcomes;
let finalProtection = protection;
if (apply && shouldRunHooks && !hookFailure) {
let refreshedProtection;
try {
refreshedProtection = loadFileProtection(cwd);
} catch (err) {
if (!(err instanceof AstryxError)) throw err;
// The hooks ran after the codemods wrote; the error carries their receipt.
if (cliBehindCore) logCliBehindCore(cliBehindCore, targetVersion);
const stopped = stoppedReceipt({
from: currentVersion,
to: targetVersion,
codemods: totalTransforms,
integrations: receipt.integrations,
sourcePathFound,
cwd,
changedFiles: [...mergedChangedFiles, ...hookModifiedFiles],
transformsApplied: mergedTransformsApplied,
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: [
...(coreResult?.declinedCandidates ?? []),
...(integrationResult?.declinedCandidates ?? []),
],
errorCode: err.code,
cliBehindCore,
...(registryResult
? {registryCompositions: registryResult.summary}
: {}),
});
throw failWithReceipt(err.message, err.code, stopped);
}
const recheckOutcomes = withCodemodOutcomes(versionManifests, cwd);
const coreCheck = await runCoreCodemods(recheckOutcomes.versionManifests, {
apply: false,
path: path_,
codemod: options.codemod,
skipCodemods,
root: cwd,
protection: refreshedProtection,
silent: true,
});
const checkedCore =
coreCheck && 'totalFilesChanged' in coreCheck ? coreCheck : null;
const recheckProtection =
(checkedCore?.stagedContents.size ?? 0) > 0
? createFileProtectionResolver(cwd, {
overrides: checkedCore?.stagedContents,
})
: refreshedProtection;
const integrationCheck = hasIntegrationCodemods
? await runIntegrationCodemodsStep(integrationVersionGroups, {
apply: false,
path: path_,
codemod: options.codemod,
skipCodemods,
root: cwd,
protection: recheckProtection,
contents: checkedCore?.stagedContents,
silent: true,
})
: null;
const recheckedProtected = [
...(checkedCore?.protectedFiles ?? []),
...(integrationCheck?.protectedFiles ?? []),
];
const recheckedChangedFiles = [
...(checkedCore?.changedFiles ?? []),
...(integrationCheck?.changedFiles ?? []),
].map(file => path.relative(cwd, file).split(path.sep).join('/'));
const initialByFile = new Map();
for (const item of initialProtected) {
const rows = initialByFile.get(item.file) ?? [];
rows.push(item);
initialByFile.set(item.file, rows);
}
// A hook that removes a protection marker without regenerating the bytes
// does not make the required change disappear. Retain the original
// declaration for that still-pending file.
for (const file of recheckedChangedFiles) {
recheckedProtected.push(...(initialByFile.get(file) ?? []));
}
remainingProtected = recheckedProtected;
// Regenerated bytes decide what a codemod could not parse, as they decide
// what is still protected.
remainingDeclined = [
...(checkedCore?.declinedCandidates ?? []),
...(integrationCheck?.declinedCandidates ?? []),
];
finalOutcomes = recheckOutcomes.outcomes;
finalProtection = refreshedProtection;
finalErrors = [
...mergedErrors,
...(checkedCore?.errors ?? []),
...(integrationCheck?.errors ?? []),
];
}
const protectedFiles = summarizeProtectedFiles([
...remainingProtected,
...regenerationProtectionRows(finalOutcomes, finalProtection, cwd),
]);
receipt.filesChanged = mergedFilesChanged;
receipt.transformsApplied = mergedTransformsApplied;
receipt.modifiedFiles = uniqueFiles([
...mergedChangedFiles,
...hookModifiedFiles,
]).map(file => path.relative(cwd, file).split(path.sep).join('/'));
receipt.protectedFiles = protectedFiles;
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.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).
receipt.errorCode = 'ERR_CODEMOD_FAILED';
}
receipt.errors = finalErrors;
if (registryResult) receipt.registryCompositions = registryResult.summary;
if (cliBehindCore) receipt.cliBehindCore = cliBehindCore;
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 && !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
// failure stays changed, and the caller keeps or reverts them knowingly.
throw failWithReceipt(
msg,
ERROR_CODES.ERR_CODEMOD_FAILED,
/** @type {import('../upgrade.type.mjs').UpgradeRunResponse['data']} */ (
/** @type {unknown} */ (receipt)
),
);
}
// Only refresh managed docs after all required codemod changes are complete.
if (receipt.complete) {
const agentDocsPlan = await prepareAgentDocsRefresh({
cwd,
origin,
installedVersion: targetVersion,
apply,
fresh: true,
});
const completedAgentDocs = apply
? applyAgentDocsRefresh(agentDocsPlan)
: agentDocsPlan.summary;
receipt.agentDocs = completedAgentDocs;
receipt.agentDocsRefreshed = completedAgentDocs.refreshed;
}
const registryOk = receipt.registryCompositions?.ok ?? true;
if (cliBehindCore) logCliBehindCore(cliBehindCore, targetVersion);
const done = cliBehindCore
? 'Upgrade incomplete'
: 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 + 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 {
type: 'upgrade.run',
data: /** @type {import('../upgrade.type.mjs').UpgradeRunResponse['data']} */ (
/** @type {unknown} */ (receipt)
),
};
}