Skip to content

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

TypeScript

fix(cli): skip protected files that do not parse instead of failing upgrade (#7991)

EJ Hammond339779097f00
diff --git a/.changeset/codemod-skip-unparseable-protected.md b/.changeset/codemod-skip-unparseable-protected.md
new file mode 100644
index 0000000000..1130454116
--- /dev/null
+++ b/.changeset/codemod-skip-unparseable-protected.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/cli': patch
+---
+
+[fix] `astryx upgrade` no longer fails when a protected file (vendored, generated, or ignored) does not parse, such as a vendored bundle written for another toolchain. It skips the file, lists it under `declinedCandidates` with the parse error's location, and completes the rest of the upgrade. A file upgrade owns that does not parse still fails the run, and protected files that parse are still checked and reported.
+
+@ejhammond
diff --git a/packages/cli/api/upgrade/run/failure-receipt.test.mjs b/packages/cli/api/upgrade/run/failure-receipt.test.mjs
index e2520083bc..f52656080b 100644
--- a/packages/cli/api/upgrade/run/failure-receipt.test.mjs
+++ b/packages/cli/api/upgrade/run/failure-receipt.test.mjs
@@ -29,6 +29,15 @@ vi.mock('../../../assets/codemods/registry.mjs', async importOriginal => {
/** @param {{source: string}} file */
transform: file => file.source.replace(/foo/g, 'bar'),
},
+ {
+ name: 'parse-js',
+ meta: {title: 'Parse JavaScript', fileExtensions: ['.js']},
+ /** @param {{source: string}} file @param {{jscodeshift: (source: string) => unknown}} api */
+ transform(file, api) {
+ api.jscodeshift(file.source);
+ return undefined;
+ },
+ },
{
name: 'fail-on-boom',
meta: {title: 'Fail on boom', fileExtensions: ['.ts']},
@@ -110,6 +119,54 @@ describe('a failed upgrade', () => {
);
});
+ it('lists a protected file a codemod could not parse in the receipt', async () => {
+ write('.gitattributes', 'src/vendor/** linguist-vendored\n');
+ write('src/vendor/bundle.js', 'export const x = {;\n');
+
+ const err = await rejection(
+ upgrade({from: '0.1.0', apply: true, path: 'src'}, {cwd: dir}),
+ );
+
+ expect(err.code).toBe('ERR_CODEMOD_FAILED');
+ expect(err.receipt.errors).toEqual([
+ expect.objectContaining({file: 'src/broken.ts'}),
+ ]);
+ expect(err.receipt.declinedCandidates).toEqual([
+ {
+ file: 'src/vendor/bundle.js',
+ location: '1:19',
+ reason: expect.stringMatching(
+ /^unparseable protected file \(vendored\): /,
+ ),
+ },
+ ]);
+ });
+
+ it('names a declined file from the folder the command ran in, with no root-relative path in its reason', async () => {
+ write('.gitattributes', 'src/vendor/** linguist-vendored\n');
+ write('src/vendor/bundle.js', 'export const x = {;\n');
+
+ const err = await rejection(
+ upgrade(
+ {from: '0.1.0', apply: true, path: '.'},
+ {cwd: path.join(dir, 'src')},
+ ),
+ );
+
+ expect(err.receipt.declinedCandidates).toEqual([
+ {
+ file: 'vendor/bundle.js',
+ location: '1:19',
+ reason: expect.stringMatching(
+ /^unparseable protected file \(vendored\): /,
+ ),
+ },
+ ]);
+ expect(err.receipt.declinedCandidates[0].reason).not.toContain(
+ '.gitattributes',
+ );
+ });
+
it('names receipt files from the folder the command ran in', async () => {
const err = await rejection(
upgrade(
diff --git a/packages/cli/api/upgrade/run/run.mjs b/packages/cli/api/upgrade/run/run.mjs
index 705ca3aca4..fb270a8ba2 100644
--- a/packages/cli/api/upgrade/run/run.mjs
+++ b/packages/cli/api/upgrade/run/run.mjs
@@ -61,6 +61,7 @@ import {
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.
@@ -93,6 +94,55 @@ function summarizeProtectedFiles(rows) {
.sort((a, b) => a.file.localeCompare(b.file));
}
+/**
+ * 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.
+ * @param {Array<{file: string, codemod: string, location?: string, reason: string}>} rows
+ * @param {Array<{file: string}>} [protectedRows]
+ * @returns {Array<{file: string, location?: string, reason: string}>}
+ */
+function summarizeDeclinedCandidates(rows, protectedRows = []) {
+ /** @type {Map<string, {file: string, location?: string, reason: string}>} */
+ const byFile = new Map();
+ for (const {file, location, reason} of withoutProtected(
+ rows,
+ protectedRows,
+ )) {
+ if (byFile.has(file)) continue;
+ byFile.set(file, {file, ...(location ? {location} : {}), reason});
+ }
+ return [...byFile.values()].sort((a, b) => a.file.localeCompare(b.file));
+}
+
+/**
+ * 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.
+ * @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:`,
+ );
+ for (const {file, location, reason} of declined) {
+ logger.warn(` ${file}${location ? `:${location}` : ''} - ${reason}`);
+ }
+}
+
+/**
+ * @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 {
@@ -116,7 +166,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}>, 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}>, 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({
@@ -130,6 +180,7 @@ function stoppedReceipt({
transformsApplied,
protectedRows,
errors,
+ declinedRows = [],
errorCode,
cliBehindCore,
registryCompositions,
@@ -156,7 +207,9 @@ function stoppedReceipt({
transformsApplied,
modifiedFiles,
protectedFiles: summarizeProtectedFiles(protectedRows),
- declinedCandidates: [],
+ declinedCandidates: logged(
+ summarizeDeclinedCandidates(declinedRows, protectedRows),
+ ),
complete: false,
errorCode,
errors,
@@ -405,7 +458,12 @@ export async function run(options = {}, {cwd = process.cwd(), origin} = {}) {
path.relative(cwd, file).split(path.sep).join('/'),
),
protectedFiles,
- declinedCandidates: [],
+ declinedCandidates: logged(
+ summarizeDeclinedCandidates(
+ coreResult?.declinedCandidates ?? [],
+ allProtected,
+ ),
+ ),
complete: false,
errorCode: 'ERR_CODEMOD_PROTECTED',
errors: coreResult?.errors ?? [],
@@ -459,6 +517,7 @@ export async function run(options = {}, {cwd = process.cwd(), origin} = {}) {
...(coreResult?.errors ?? []),
{file: '.', codemod: 'config', error: configErr.message},
],
+ declinedRows: coreResult?.declinedCandidates ?? [],
errorCode: ERROR_CODES.ERR_INVALID_ARGUMENT,
cliBehindCore,
});
@@ -678,6 +737,10 @@ export async function run(options = {}, {cwd = process.cwd(), origin} = {}) {
...mergedErrors,
{file: '.', codemod: 'post-codemod-hook', error: msg},
],
+ declinedRows: [
+ ...(coreResult?.declinedCandidates ?? []),
+ ...(integrationResult?.declinedCandidates ?? []),
+ ],
errorCode: ERROR_CODES.ERR_CODEMOD_FAILED,
cliBehindCore,
...(registryResult
@@ -709,6 +772,10 @@ export async function run(options = {}, {cwd = process.cwd(), origin} = {}) {
// 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 ?? []),
+ ];
if (apply && shouldRunHooks && !hookFailure) {
let refreshedProtection;
try {
@@ -731,6 +798,10 @@ export async function run(options = {}, {cwd = process.cwd(), origin} = {}) {
...mergedErrors,
{file: '.', codemod: 'file-protection', error: err.message},
],
+ declinedRows: [
+ ...(coreResult?.declinedCandidates ?? []),
+ ...(integrationResult?.declinedCandidates ?? []),
+ ],
errorCode: err.code,
cliBehindCore,
...(registryResult
@@ -789,6 +860,12 @@ export async function run(options = {}, {cwd = process.cwd(), origin} = {}) {
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 ?? []),
+ ];
finalErrors = [
...mergedErrors,
...(checkedCore?.errors ?? []),
@@ -804,7 +881,9 @@ 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 = [];
+ receipt.declinedCandidates = logged(
+ summarizeDeclinedCandidates(remainingDeclined, remainingProtected),
+ );
receipt.complete = protectedFiles.length === 0 && finalErrors.length === 0;
if (protectedFiles.length > 0) {
receipt.errorCode = 'ERR_CODEMOD_PROTECTED';
diff --git a/packages/cli/api/upgrade/upgrade.type.mjs b/packages/cli/api/upgrade/upgrade.type.mjs
index d36a807f69..529de7ecb6 100644
--- a/packages/cli/api/upgrade/upgrade.type.mjs
+++ b/packages/cli/api/upgrade/upgrade.type.mjs
@@ -136,7 +136,7 @@
* @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. 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. 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 {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/__tests__/runner.unparseable.test.mjs b/packages/cli/assets/codemods/__tests__/runner.unparseable.test.mjs
new file mode 100644
index 0000000000..19edbef4ee
--- /dev/null
+++ b/packages/cli/assets/codemods/__tests__/runner.unparseable.test.mjs
@@ -0,0 +1,457 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file A protected file a codemod cannot parse is declined for manual review
+ * instead of failing the run; every other codemod error still fails it.
+ */
+
+import {afterEach, beforeEach, describe, expect, it} from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {runCodemods} from '../runner.mjs';
+import {parseCss, processSelector} from '../parse.mjs';
+import validateDataTokenOwnership, {
+ meta as validateDataTokenOwnershipMeta,
+} from '../transforms/v0.7.0/validate-data-token-ownership.mjs';
+import migrateThemeSelectors, {
+ meta as migrateThemeSelectorsMeta,
+} from '../transforms/v0.6.0/migrate-astryx-theme-selectors-to-data-attrs.mjs';
+import migrateDeprecatedThemeSurface, {
+ meta as migrateDeprecatedThemeSurfaceMeta,
+} from '../transforms/v0.7.0/migrate-deprecated-theme-surface.mjs';
+
+let tmpDir;
+let originalCwd;
+
+beforeEach(() => {
+ originalCwd = process.cwd();
+ tmpDir = fs.mkdtempSync(path.join(process.cwd(), '.astryx-runner-test-'));
+ process.chdir(tmpDir);
+});
+
+afterEach(() => {
+ process.chdir(originalCwd);
+ fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+describe('runCodemods — protected files that do not parse', () => {
+ // A transform that parses every file it is handed, like real codemods do.
+ const manifests = [
+ {
+ version: '0.1.3',
+ transforms: [
+ {
+ name: 'rename-foo',
+ meta: {title: 'rename foo'},
+ transform: (file, {jscodeshift: j}) => {
+ const root = j(file.source);
+ root.find(j.Identifier, {name: 'foo'}).forEach(p => {
+ p.node.name = 'bar';
+ });
+ return root.toSource();
+ },
+ },
+ ],
+ },
+ ];
+ const BROKEN = 'export const foo = {;\n';
+
+ function seedVendored() {
+ fs.mkdirSync(path.join(tmpDir, 'src'), {recursive: true});
+ fs.mkdirSync(path.join(tmpDir, 'vendor'), {recursive: true});
+ fs.writeFileSync(
+ path.join(tmpDir, '.gitattributes'),
+ 'vendor/** linguist-vendored\n',
+ );
+ fs.writeFileSync(path.join(tmpDir, 'src', 'owned.ts'), 'const foo = 1;\n');
+ fs.writeFileSync(path.join(tmpDir, 'vendor', 'bundle.js'), BROKEN);
+ }
+
+ it('declines a vendored file that does not parse and completes the owned edits', async () => {
+ seedVendored();
+
+ const r = await runCodemods(manifests, {
+ apply: true,
+ path: '.',
+ silent: true,
+ });
+
+ expect(r.errors).toEqual([]);
+ expect(r.protectedFiles).toEqual([]);
+ expect(r.declinedCandidates).toEqual([
+ {
+ file: path.join('vendor', 'bundle.js'),
+ codemod: 'core:rename-foo',
+ location: '1:21',
+ reason: expect.stringMatching(
+ /^unparseable protected file \(vendored\): /,
+ ),
+ },
+ ]);
+ expect(fs.readFileSync(path.join(tmpDir, 'src', 'owned.ts'), 'utf-8')).toBe(
+ 'const bar = 1;\n',
+ );
+ expect(
+ fs.readFileSync(path.join(tmpDir, 'vendor', 'bundle.js'), 'utf-8'),
+ ).toBe(BROKEN);
+ });
+
+ it('declines the same file in a dry run', async () => {
+ seedVendored();
+
+ const r = await runCodemods(manifests, {
+ apply: false,
+ path: '.',
+ silent: true,
+ });
+
+ expect(r.errors).toEqual([]);
+ expect(r.declinedCandidates.map(item => item.file)).toEqual([
+ path.join('vendor', 'bundle.js'),
+ ]);
+ expect(r.changedFiles.map(f => path.basename(f))).toEqual(['owned.ts']);
+ });
+
+ it('declines an unparseable file under an ignore rule or a generated marker', async () => {
+ fs.mkdirSync(path.join(tmpDir, 'src'), {recursive: true});
+ fs.writeFileSync(path.join(tmpDir, '.gitignore'), 'ignored/\n');
+ fs.mkdirSync(path.join(tmpDir, 'ignored'), {recursive: true});
+ fs.writeFileSync(path.join(tmpDir, 'ignored', 'a.js'), BROKEN);
+ fs.writeFileSync(
+ path.join(tmpDir, 'src', 'gen.js'),
+ `// @generated\n${BROKEN}`,
+ );
+
+ const r = await runCodemods(manifests, {
+ apply: true,
+ path: '.',
+ silent: true,
+ });
+
+ expect(r.errors).toEqual([]);
+ expect(r.declinedCandidates.map(item => item.file).sort()).toEqual([
+ path.join('ignored', 'a.js'),
+ path.join('src', 'gen.js'),
+ ]);
+ });
+
+ it('still analyses a protected file that parses and reports its required change', async () => {
+ seedVendored();
+ fs.writeFileSync(
+ path.join(tmpDir, 'vendor', 'parsed.js'),
+ 'export const foo = 1;\n',
+ );
+
+ const r = await runCodemods(manifests, {
+ apply: true,
+ path: '.',
+ silent: true,
+ });
+
+ expect(r.protectedFiles).toEqual([
+ expect.objectContaining({
+ file: path.join('vendor', 'parsed.js'),
+ reason: 'vendored',
+ }),
+ ]);
+ expect(r.declinedCandidates.map(item => item.file)).toEqual([
+ path.join('vendor', 'bundle.js'),
+ ]);
+ });
+
+ it('still fails on owned source that does not parse', async () => {
+ fs.mkdirSync(path.join(tmpDir, 'src'), {recursive: true});
+ fs.writeFileSync(path.join(tmpDir, 'src', 'broken.js'), BROKEN);
+
+ const r = await runCodemods(manifests, {
+ apply: true,
+ path: '.',
+ silent: true,
+ });
+
+ expect(r.declinedCandidates).toEqual([]);
+ expect(r.errors).toEqual([
+ expect.objectContaining({
+ file: path.join('src', 'broken.js'),
+ codemod: 'core:rename-foo',
+ }),
+ ]);
+ });
+
+ it('still fails when a transform throws on a protected file that parses', async () => {
+ seedVendored();
+ fs.writeFileSync(
+ path.join(tmpDir, 'vendor', 'bundle.js'),
+ 'const x = 1;\n',
+ );
+ const throwing = [
+ {
+ version: '0.1.3',
+ transforms: [
+ {
+ name: 'throws',
+ meta: {title: 'throws'},
+ transform: file => {
+ if (file.path.endsWith('bundle.js')) throw new Error('boom');
+ return null;
+ },
+ },
+ ],
+ },
+ ];
+
+ const r = await runCodemods(throwing, {
+ apply: true,
+ path: '.',
+ silent: true,
+ });
+
+ expect(r.declinedCandidates).toEqual([]);
+ expect(r.errors).toEqual([
+ {
+ file: path.join('vendor', 'bundle.js'),
+ codemod: 'core:throws',
+ error: 'boom',
+ },
+ ]);
+ });
+
+ it('keeps a CSS codemod error on a generated stylesheet that parses', async () => {
+ fs.mkdirSync(path.join(tmpDir, 'src'), {recursive: true});
+ const theme =
+ '/* @generated by `astryx theme build` */\n' +
+ ':root {\n --color-data-1: #000;\n}\n';
+ fs.writeFileSync(path.join(tmpDir, 'src', 'theme.css'), theme);
+
+ const r = await runCodemods(
+ [
+ {
+ version: '0.7.0',
+ transforms: [
+ {
+ name: 'validate-data-token-ownership',
+ transform: validateDataTokenOwnership,
+ meta: validateDataTokenOwnershipMeta,
+ },
+ ],
+ },
+ ],
+ {apply: true, path: '.', silent: true},
+ );
+
+ expect(r.declinedCandidates).toEqual([]);
+ expect(r.errors).toEqual([
+ {
+ file: path.join('src', 'theme.css'),
+ codemod: 'core:validate-data-token-ownership',
+ error: expect.stringContaining('astryx theme build'),
+ },
+ ]);
+ expect(
+ fs.readFileSync(path.join(tmpDir, 'src', 'theme.css'), 'utf-8'),
+ ).toBe(theme);
+ });
+
+ it('declines a protected stylesheet that does not parse as CSS', async () => {
+ fs.mkdirSync(path.join(tmpDir, 'vendor'), {recursive: true});
+ fs.writeFileSync(
+ path.join(tmpDir, '.gitattributes'),
+ 'vendor/** linguist-vendored\n',
+ );
+ fs.writeFileSync(path.join(tmpDir, 'vendor', 'broken.css'), 'a {\n');
+
+ const r = await runCodemods(
+ [
+ {
+ version: '0.1.3',
+ transforms: [
+ {
+ name: 'css',
+ meta: {title: 'css', fileExtensions: ['.css']},
+ transform: file => parseCss(file.source).toString(),
+ },
+ ],
+ },
+ ],
+ {apply: true, path: '.', silent: true},
+ );
+
+ expect(r.errors).toEqual([]);
+ expect(r.declinedCandidates).toEqual([
+ {
+ file: path.join('vendor', 'broken.css'),
+ codemod: 'core:css',
+ location: '1:1',
+ reason: 'unparseable protected file (vendored): Unclosed block',
+ },
+ ]);
+ });
+
+ it('declines a vendored stylesheet whose selector the real theme codemod cannot parse', async () => {
+ fs.mkdirSync(path.join(tmpDir, 'vendor'), {recursive: true});
+ fs.writeFileSync(
+ path.join(tmpDir, '.gitattributes'),
+ 'vendor/** linguist-vendored\n',
+ );
+ const bundle = 'a:: { color: red; }\n';
+ fs.writeFileSync(path.join(tmpDir, 'vendor', 'bundle.css'), bundle);
+
+ const r = await runCodemods(
+ [
+ {
+ version: '0.7.0',
+ transforms: [
+ {
+ name: 'migrate-deprecated-theme-surface',
+ transform: migrateDeprecatedThemeSurface,
+ meta: migrateDeprecatedThemeSurfaceMeta,
+ },
+ ],
+ },
+ ],
+ {apply: true, path: '.', silent: true},
+ );
+
+ expect(r.errors).toEqual([]);
+ expect(r.protectedFiles).toEqual([]);
+ expect(r.declinedCandidates).toEqual([
+ {
+ file: path.join('vendor', 'bundle.css'),
+ codemod: 'core:migrate-deprecated-theme-surface',
+ location: '1:3',
+ reason:
+ 'unparseable protected file (vendored): Expected a pseudo-class or pseudo-element.',
+ },
+ ]);
+ expect(
+ fs.readFileSync(path.join(tmpDir, 'vendor', 'bundle.css'), 'utf-8'),
+ ).toBe(bundle);
+ });
+
+ it('keeps an error a transform throws after the file parses', async () => {
+ fs.mkdirSync(path.join(tmpDir, 'vendor'), {recursive: true});
+ fs.writeFileSync(
+ path.join(tmpDir, '.gitattributes'),
+ 'vendor/** linguist-vendored\n',
+ );
+ fs.writeFileSync(
+ path.join(tmpDir, 'vendor', 'a.css'),
+ 'a { color: red; }\n',
+ );
+
+ const r = await runCodemods(
+ [
+ {
+ version: '0.1.3',
+ transforms: [
+ {
+ name: 'walks',
+ meta: {title: 'walks', fileExtensions: ['.css']},
+ transform: file => {
+ parseCss(file.source).walkRules(rule =>
+ processSelector(rule.selector, () => {
+ throw new Error('callback failed');
+ }),
+ );
+ return null;
+ },
+ },
+ ],
+ },
+ ],
+ {apply: true, path: '.', silent: true},
+ );
+
+ expect(r.declinedCandidates).toEqual([]);
+ expect(r.errors).toEqual([
+ {
+ file: path.join('vendor', 'a.css'),
+ codemod: 'core:walks',
+ error: 'callback failed',
+ },
+ ]);
+ });
+
+ it('lists a file another codemod still needs to change under protectedFiles only', async () => {
+ fs.mkdirSync(path.join(tmpDir, 'vendor'), {recursive: true});
+ fs.writeFileSync(
+ path.join(tmpDir, '.gitattributes'),
+ 'vendor/** linguist-vendored\n',
+ );
+ fs.writeFileSync(
+ path.join(tmpDir, 'vendor', 'bundle.css'),
+ 'a:: { color: red; }\n',
+ );
+
+ const r = await runCodemods(
+ [
+ {
+ version: '0.6.0',
+ transforms: [
+ {
+ name: 'migrate-astryx-theme-selectors-to-data-attrs',
+ transform: migrateThemeSelectors,
+ meta: migrateThemeSelectorsMeta,
+ },
+ ],
+ },
+ {
+ version: '0.7.0',
+ transforms: [
+ {
+ name: 'migrate-deprecated-theme-surface',
+ transform: migrateDeprecatedThemeSurface,
+ meta: migrateDeprecatedThemeSurfaceMeta,
+ },
+ ],
+ },
+ ],
+ {apply: true, path: '.', silent: true},
+ );
+
+ expect(r.errors).toEqual([]);
+ expect(r.protectedFiles.map(item => item.file)).toEqual([
+ 'vendor/bundle.css',
+ ]);
+ expect(r.declinedCandidates).toEqual([]);
+ });
+
+ it('gives a rejected @scope prelude its position in the stylesheet', async () => {
+ fs.mkdirSync(path.join(tmpDir, 'vendor'), {recursive: true});
+ fs.writeFileSync(
+ path.join(tmpDir, '.gitattributes'),
+ 'vendor/** linguist-vendored\n',
+ );
+ fs.writeFileSync(
+ path.join(tmpDir, 'vendor', 'bundle.css'),
+ '.x { color: blue; }\n\n@scope (a::) {\n b { color: red; }\n}\n',
+ );
+
+ const r = await runCodemods(
+ [
+ {
+ version: '0.7.0',
+ transforms: [
+ {
+ name: 'migrate-deprecated-theme-surface',
+ transform: migrateDeprecatedThemeSurface,
+ meta: migrateDeprecatedThemeSurfaceMeta,
+ },
+ ],
+ },
+ ],
+ {apply: true, path: '.', silent: true},
+ );
+
+ expect(r.errors).toEqual([]);
+ expect(r.declinedCandidates).toEqual([
+ {
+ file: path.join('vendor', 'bundle.css'),
+ codemod: 'core:migrate-deprecated-theme-surface',
+ location: '3:9',
+ reason:
+ 'unparseable protected file (vendored): Expected a pseudo-class or pseudo-element.',
+ },
+ ]);
+ });
+});
diff --git a/packages/cli/assets/codemods/integration-runner.mjs b/packages/cli/assets/codemods/integration-runner.mjs
index f0379b6152..c944d43bae 100644
--- a/packages/cli/assets/codemods/integration-runner.mjs
+++ b/packages/cli/assets/codemods/integration-runner.mjs
@@ -24,6 +24,7 @@ import {
runCodeCodemod,
runConfigCodemod,
} from './run-codemod.mjs';
+import {withoutProtected} from './runner.mjs';
import {createFileProtectionResolver} from '../../foundation/fs/file-protection.mjs';
/**
@@ -44,7 +45,7 @@ import {createFileProtectionResolver} from '../../foundation/fs/file-protection.
* @param {string} [options.root]
* @param {Map<string, string>} [options.contents] staged bytes from earlier dry-run phases
* @param {{root: string, classify: (file: string) => import('../../foundation/fs/file-protection.mjs').FileProtection[]}} [options.protection]
- * @returns {{totalFilesChanged: number, totalTransformsApplied: number, changedFiles: string[], writtenFiles: string[], stagedContents: Map<string, string>, protectedFiles: import('../../authoring/codemod/type').CodemodRunResult['protectedFiles'], errors: Array<{file: string, codemod: string, error: string}>, skippedOptional: Array<import('../../authoring/codemod/type').CodemodEntry>}}
+ * @returns {{totalFilesChanged: number, totalTransformsApplied: 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<import('../../authoring/codemod/type').CodemodEntry>}}
*/
export function runIntegrationCodemods(
versionGroups,
@@ -74,6 +75,8 @@ export function runIntegrationCodemods(
const writtenFiles = [];
/** @type {import('../../authoring/codemod/type').CodemodRunResult['protectedFiles']} */
const protectedFiles = [];
+ /** @type {NonNullable<import('../../authoring/codemod/type').CodemodRunResult['declinedCandidates']>} */
+ const declinedCandidates = [];
/** @type {Array<{file: string, codemod: string, error: string}>} */
const errors = [];
/** @type {Array<import('../../authoring/codemod/type').CodemodEntry>} */
@@ -147,9 +150,11 @@ export function runIntegrationCodemods(
changedFiles.push(...r.changedFiles);
writtenFiles.push(...r.writtenFiles);
protectedFiles.push(...r.protectedFiles);
+ declinedCandidates.push(...(r.declinedCandidates ?? []));
errors.push(...r.errors);
}
}
+ const reportedDeclined = withoutProtected(declinedCandidates, protectedFiles);
// A file several codemods changed is one file; transforms count each change.
const totalFilesChanged = new Set(changedFiles).size;
@@ -161,6 +166,7 @@ export function runIntegrationCodemods(
writtenFiles,
stagedContents: virtualContents,
protectedFiles,
+ declinedCandidates: reportedDeclined,
errors,
skippedOptional,
};
diff --git a/packages/cli/assets/codemods/integration-runner.protection.test.mjs b/packages/cli/assets/codemods/integration-runner.protection.test.mjs
index ffaba2c743..7e4865bf36 100644
--- a/packages/cli/assets/codemods/integration-runner.protection.test.mjs
+++ b/packages/cli/assets/codemods/integration-runner.protection.test.mjs
@@ -150,4 +150,57 @@ describe('integration codemod file protection', () => {
}),
]);
});
+
+ it('declines a protected file that does not parse, as the core runner does', async () => {
+ write('.gitattributes', 'src/vendor/** linguist-vendored\n');
+ write('src/owned.js', "export const value = 'old';\n");
+ write('src/vendor/bundle.js', 'export const value = {;\n');
+ write('src/broken.js', 'export const value = {;\n');
+
+ const groups = [
+ {
+ version: '1.0.0',
+ codemods: [
+ {
+ id: 'code',
+ type: 'code',
+ package: '@acme/integration',
+ codemod: {
+ title: 'code',
+ fileExtensions: ['.js'],
+ transform: (file, {jscodeshift: j}) => {
+ const ast = j(file.source);
+ ast.find(j.Identifier, {name: 'value'}).forEach(p => {
+ p.node.name = 'renamed';
+ });
+ return ast.toSource();
+ },
+ },
+ },
+ ],
+ },
+ ];
+ const jscodeshift = (await import('jscodeshift')).default;
+ const result = runIntegrationCodemods(groups, {
+ apply: true,
+ path: path.join(root, 'src'),
+ root,
+ jscodeshift,
+ silent: true,
+ });
+
+ expect(fs.readFileSync(path.join(root, 'src/owned.js'), 'utf8')).toContain(
+ 'renamed',
+ );
+ expect(result.declinedCandidates).toEqual([
+ expect.objectContaining({
+ file: path.join('src', 'vendor', 'bundle.js'),
+ codemod: '@acme/integration:code',
+ location: '1:23',
+ }),
+ ]);
+ expect(result.errors).toEqual([
+ expect.objectContaining({file: path.join('src', 'broken.js')}),
+ ]);
+ });
});
diff --git a/packages/cli/assets/codemods/parse.mjs b/packages/cli/assets/codemods/parse.mjs
new file mode 100644
index 0000000000..e0a55f8b1e
--- /dev/null
+++ b/packages/cli/assets/codemods/parse.mjs
@@ -0,0 +1,94 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Parse entry points that mark their own failures.
+ *
+ * @input Source text a codemod reads: a file's JavaScript or TypeScript, a
+ * stylesheet, or one CSS selector.
+ * @output The parsed tree; a parse failure is rethrown with
+ * `code: 'ERR_CODEMOD_PARSE'`.
+ * @position Shared by the codemod runner and the core CSS codemods. The runner
+ * skips a protected file only when its error carries this code, so any other
+ * error a codemod throws still fails the run.
+ */
+
+import postcss from 'postcss';
+import selectorParser from 'postcss-selector-parser';
+
+export const CODEMOD_PARSE_ERROR = 'ERR_CODEMOD_PARSE';
+
+/**
+ * Mark an error as a parse failure and return it.
+ * @template T
+ * @param {T} err
+ * @returns {T}
+ */
+export function markParseError(err) {
+ if (err && typeof err === 'object') {
+ /** @type {any} */ (err).code = CODEMOD_PARSE_ERROR;
+ }
+ return err;
+}
+
+/**
+ * @param {unknown} err
+ * @returns {boolean}
+ */
+export function isCodemodParseError(err) {
+ return /** @type {any} */ (err)?.code === CODEMOD_PARSE_ERROR;
+}
+
+/**
+ * `postcss.parse`, with a failure marked as a parse error.
+ * @param {string} source
+ * @param {import('postcss').ProcessOptions} [options]
+ */
+export function parseCss(source, options) {
+ try {
+ return postcss.parse(source, options);
+ } catch (err) {
+ throw markParseError(err);
+ }
+}
+
+/**
+ * Parse one selector, hand its tree to `callback`, and return the tree as
+ * text, like `selectorParser(callback).processSync(selector, {lossless:
+ * true})`. Pass the PostCSS rule rather than its selector text when there is
+ * one: a failure then reports its line and column in the stylesheet. Only a
+ * failure to parse is marked; an error `callback` throws is passed through
+ * unchanged.
+ * @param {string | import('postcss').Rule} selector selector text, or the rule that holds it
+ * @param {(root: import('postcss-selector-parser').Root) => void} callback
+ * @returns {string}
+ */
+export function processSelector(selector, callback) {
+ let root;
+ try {
+ root = selectorParser().astSync(selector, {lossless: true});
+ } catch (err) {
+ throw markParseError(err);
+ }
+ callback(root);
+ return root.toString();
+}
+
+/**
+ * The jscodeshift a code codemod receives for one file. Parsing that file's
+ * own source (`j(file.source)`) marks a failure as a parse error; every other
+ * call and property behaves as jscodeshift does.
+ * @param {any} j jscodeshift bound to the file's parser
+ * @param {string} source the file's source
+ * @returns {any}
+ */
+export function markingSourceParseErrors(j, source) {
+ return new Proxy(j, {
+ apply(target, thisArg, args) {
+ try {
+ return Reflect.apply(target, thisArg, args);
+ } catch (err) {
+ throw args[0] === source ? markParseError(err) : err;
+ }
+ },
+ });
+}
diff --git a/packages/cli/assets/codemods/run-codemod.mjs b/packages/cli/assets/codemods/run-codemod.mjs
index d7368d63f0..2462d32ecc 100644
--- a/packages/cli/assets/codemods/run-codemod.mjs
+++ b/packages/cli/assets/codemods/run-codemod.mjs
@@ -38,6 +38,7 @@ import {
isIgnoredLinkedDirectory,
} from './runner.mjs';
import {createFileProtectionResolver} from '../../foundation/fs/file-protection.mjs';
+import {isCodemodParseError, markingSourceParseErrors} from './parse.mjs';
export const DEFAULT_CODE_EXTENSIONS = [
'.tsx',
@@ -72,6 +73,69 @@ function protectedResult(filePath, name, protection) {
}));
}
+/**
+ * @typedef {{file: string, codemod: string, location?: string, reason: string}} DeclinedCandidate
+ */
+
+/**
+ * Where a parse error points, as 1-based `line:column`, and its message
+ * without the position Babel appends. Babel reports a 0-based column on
+ * `loc`; PostCSS reports 1-based `line` and `column`.
+ * @param {any} err
+ * @returns {{message: string, location?: string}}
+ */
+function describeParseError(err) {
+ if (err?.name === 'CssSyntaxError') {
+ return {
+ message: String(err.reason ?? err.message),
+ ...(typeof err.line === 'number'
+ ? {location: `${err.line}:${err.column ?? 1}`}
+ : {}),
+ };
+ }
+ const loc = err?.loc;
+ return {
+ message: String(err?.message ?? err).replace(/\s*\(\d+:\d+\)$/, ''),
+ ...(loc && typeof loc.line === 'number'
+ ? {location: `${loc.line}:${(loc.column ?? 0) + 1}`}
+ : {}),
+ };
+}
+
+/**
+ * Decline a protected file a codemod could not parse. A codemod can prove
+ * nothing in bytes it cannot parse, and the file is never written anyway, so
+ * it is listed for manual review instead of failing the run. Only an error a
+ * parse entry point marked (see `parse.mjs`) counts: owned source that does
+ * not parse, and every other error a codemod throws, still fail.
+ * @param {unknown} err
+ * @param {string} filePath
+ * @param {string} relativePath
+ * @param {string} name
+ * @param {{root: string, classify: (file: string) => import('../../foundation/fs/file-protection.mjs').FileProtection[]}} protection
+ * @returns {DeclinedCandidate|null}
+ */
+function declineUnparseableProtected(
+ err,
+ filePath,
+ relativePath,
+ name,
+ protection,
+) {
+ if (!isCodemodParseError(err)) return null;
+ const protections = protection.classify(filePath);
+ if (protections.length === 0) return null;
+ const {message, location} = describeParseError(err);
+ return {
+ file: relativePath,
+ codemod: name,
+ ...(location ? {location} : {}),
+ // The category, not the declaration: a declaration names its source
+ // file from the project root, and `file` may be rebased elsewhere.
+ reason: `unparseable protected file (${[...new Set(protections.map(item => item.reason))].join(', ')}): ${message}`,
+ };
+}
+
/**
* Print one blocked candidate without implying that the protected bytes changed.
* @param {import('../../authoring/codemod/type').CliLog} log
@@ -299,6 +363,8 @@ export function runCodeCodemod(
const protectedFiles = [];
/** @type {Array<{file: string, codemod: string, error: string}>} */
const errors = [];
+ /** @type {DeclinedCandidate[]} */
+ const declinedCandidates = [];
/** @type {Array<{filePath: string, relativePath: string, result: string}>} */
const candidates = [];
@@ -314,7 +380,11 @@ export function runCodeCodemod(
contents?.get(filePath) ?? fs.readFileSync(filePath, 'utf-8');
const parser = ext === '.tsx' || ext === '.ts' ? 'tsx' : 'babel';
const j = jscodeshift.withParser(parser);
- const api = {jscodeshift: j, stats: () => {}, report: () => {}};
+ const api = {
+ jscodeshift: markingSourceParseErrors(j, source),
+ stats: () => {},
+ report: () => {},
+ };
let result = codemod.transform({source, path: filePath}, api);
if (result == null || result === source) continue;
@@ -334,6 +404,19 @@ export function runCodeCodemod(
}
candidates.push({filePath, relativePath, result});
} catch (err) {
+ const declined = declineUnparseableProtected(
+ err,
+ filePath,
+ relativePath,
+ name,
+ resolver,
+ );
+ if (declined) {
+ // Printed by the caller once every codemod has run: a later codemod
+ // can still make this file a protected one, listed only as such.
+ declinedCandidates.push(declined);
+ continue;
+ }
const message = /** @type {any} */ (err).message;
log.error(` ✗ ${relativePath} — ${message}`);
errors.push({file: relativePath, codemod: name, error: message});
@@ -386,5 +469,12 @@ export function runCodeCodemod(
}
}
- return {filesChanged, changedFiles, writtenFiles, protectedFiles, errors};
+ return {
+ filesChanged,
+ changedFiles,
+ writtenFiles,
+ protectedFiles,
+ declinedCandidates,
+ errors,
+ };
}
diff --git a/packages/cli/assets/codemods/runner.mjs b/packages/cli/assets/codemods/runner.mjs
index 1489a68505..b592c46c20 100644
--- a/packages/cli/assets/codemods/runner.mjs
+++ b/packages/cli/assets/codemods/runner.mjs
@@ -215,6 +215,22 @@ function findSourceFiles(dir, root = dir) {
return results.sort();
}
+/**
+ * The declined candidates that are not also protected files the run reports.
+ * A file another codemod still requires a change to is listed once, under
+ * `protectedFiles`, which already makes the run incomplete.
+ * @template {{file: string}} T
+ * @param {T[]} declined
+ * @param {Array<{file: string}>} protectedRows
+ * @returns {T[]}
+ */
+export function withoutProtected(declined, protectedRows) {
+ /** @param {string} file */
+ const key = file => file.split(path.sep).join('/');
+ const blocked = new Set(protectedRows.map(item => key(item.file)));
+ return declined.filter(item => !blocked.has(key(item.file)));
+}
+
/**
* Validate transform output before writing to disk.
*
@@ -492,7 +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.
- * @returns {Promise<{totalFilesChanged: number, totalTransformsApplied: number, totalValidationBlocked: number, changedFiles: string[], writtenFiles: string[], stagedContents: Map<string, string>, protectedFiles: import('../../authoring/codemod/type').CodemodRunResult['protectedFiles'], 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}>}
+ * @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(
versionManifests,
@@ -573,6 +589,8 @@ export async function runCodemods(
const writtenFiles = [];
/** @type {import('../../authoring/codemod/type').CodemodRunResult['protectedFiles']} */
const protectedFiles = [];
+ /** @type {NonNullable<import('../../authoring/codemod/type').CodemodRunResult['declinedCandidates']>} */
+ const declinedCandidates = [];
/** @type {Array<{name: string, meta: {title: string, description?: string, fileExtensions?: string[], codemodType?: string}, version: string}>} */
const skippedOptional = [];
for (const {version, transforms} of versionManifests) {
@@ -662,6 +680,7 @@ export async function runCodemods(
);
errors.push(...result.errors);
protectedFiles.push(...result.protectedFiles);
+ declinedCandidates.push(...(result.declinedCandidates ?? []));
changedFiles.push(...result.changedFiles);
writtenFiles.push(...result.writtenFiles);
totalTransformsApplied += result.filesChanged;
@@ -713,10 +732,15 @@ 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);
+
if (
totalFilesChanged === 0 &&
errors.length === 0 &&
- protectedFiles.length === 0
+ protectedFiles.length === 0 &&
+ reportedDeclined.length === 0
) {
// Codemods that stop before the installed target cannot vouch for the
// code; the caller says what is missing.
@@ -766,6 +790,7 @@ export async function runCodemods(
changedFiles,
writtenFiles,
protectedFiles,
+ declinedCandidates: reportedDeclined,
stagedContents: virtualContents,
errors,
skippedOptional,
diff --git a/packages/cli/assets/codemods/transforms/v0.6.0/migrate-astryx-theme-selectors-to-data-attrs.mjs b/packages/cli/assets/codemods/transforms/v0.6.0/migrate-astryx-theme-selectors-to-data-attrs.mjs
index 3b2175e1cf..94f5faae03 100644
--- a/packages/cli/assets/codemods/transforms/v0.6.0/migrate-astryx-theme-selectors-to-data-attrs.mjs
+++ b/packages/cli/assets/codemods/transforms/v0.6.0/migrate-astryx-theme-selectors-to-data-attrs.mjs
@@ -15,6 +15,7 @@
import path from 'node:path';
import postcss from 'postcss';
import selectorParser from 'postcss-selector-parser';
+import {parseCss, processSelector} from '../../parse.mjs';
import {
V054_THEME_SELECTOR_DYNAMIC_AXES,
V054_THEME_SELECTOR_TARGETS,
@@ -555,7 +556,7 @@ function migrateSelectorTextWithContext(
) {
/** @type {TargetContext} */
let context = {guaranteed: [], possible: []};
- const text = selectorParser(selectors => {
+ const text = processSelector(selector, selectors => {
/** @type {TargetContext[]} */
const branchContexts = [];
selectors.each(selectorNode => {
@@ -593,7 +594,7 @@ function migrateSelectorTextWithContext(
});
});
context = combineSelectorListContexts(branchContexts);
- }).processSync(selector, {lossless: true});
+ });
return {text, context};
}
@@ -677,7 +678,7 @@ export function migrateAstryxThemeSelectors(source, from = 'styles.css', data) {
/** @param {string} source @param {string} from @returns {string} */
function migrateWithActiveTables(source, from) {
- const root = postcss.parse(source, {from});
+ const root = parseCss(source, {from});
const existingComments = new Set();
root.walkComments(comment => {
existingComments.add(comment.text.trim());
diff --git a/packages/cli/assets/codemods/transforms/v0.7.0/migrate-deprecated-theme-surface.mjs b/packages/cli/assets/codemods/transforms/v0.7.0/migrate-deprecated-theme-surface.mjs
index d3f1db35f2..b3522ee670 100644
--- a/packages/cli/assets/codemods/transforms/v0.7.0/migrate-deprecated-theme-surface.mjs
+++ b/packages/cli/assets/codemods/transforms/v0.7.0/migrate-deprecated-theme-surface.mjs
@@ -27,6 +27,12 @@ import {
importedComponents,
resolveImportedComponent,
} from '../../transform-prop.mjs';
+import {
+ isCodemodParseError,
+ markParseError,
+ parseCss,
+ processSelector,
+} from '../../parse.mjs';
import {migrateAstryxThemeSelectors} from '../v0.6.0/migrate-astryx-theme-selectors-to-data-attrs.mjs';
import {
V06_THEME_SELECTOR_DYNAMIC_AXES,
@@ -204,7 +210,7 @@ function ownerScope(owner) {
function unclassifiedBareClasses(selectorText) {
/** @type {Set<string>} */
const found = new Set();
- selectorParser(selectors => {
+ processSelector(selectorText, selectors => {
selectors.walk((/** @type {any} */ node) => {
if (node.type !== 'selector') return;
/** @type {any[][]} */
@@ -232,19 +238,23 @@ function unclassifiedBareClasses(selectorText) {
}
}
});
- }).processSync(selectorText, {lossless: true});
+ });
return [...found].sort();
}
-/** @param {string} selector */
+/** @param {string | import('postcss').Rule} selector selector text, or the rule that holds it */
function finishSelectorText(selector) {
- return selectorParser(selectors => {
+ return processSelector(selector, selectors => {
selectors.each(finishSelectorMigration);
- }).processSync(selector, {lossless: true});
+ });
}
-/** @param {string} params */
-function finishScopeParams(params) {
+/**
+ * Migrate each parenthesized selector group of an `@scope` prelude.
+ * @param {string} params
+ * @param {(selector: string, start: number) => string} [finish] migrates one group; `start` is its offset in `params`
+ */
+function finishScopeParams(params, finish = finishSelectorText) {
let result = '';
let last = 0;
let depth = 0;
@@ -281,7 +291,7 @@ function finishScopeParams(params) {
if (char === ')' && depth > 0) {
depth--;
if (depth === 0 && groupStart >= 0) {
- result += finishSelectorText(params.slice(groupStart, index));
+ result += finish(params.slice(groupStart, index), groupStart);
result += ')';
last = index + 1;
groupStart = -1;
@@ -293,15 +303,39 @@ function finishScopeParams(params) {
/** @param {string} source @param {string} from */
function migrateCss(source, from) {
+ // Parse every selector of the stylesheet as written first, so one the
+ // selector parser rejects is reported at its line and column in the file,
+ // not in the migrated text below.
+ const original = parseCss(source, {from});
+ original.walkRules(rule => {
+ processSelector(rule, () => {});
+ });
+ original.walkAtRules('scope', atRule => {
+ const offset =
+ `@${atRule.name}`.length + (atRule.raws.afterName ?? '').length;
+ finishScopeParams(atRule.params, (selector, start) => {
+ try {
+ processSelector(selector, () => {});
+ } catch (err) {
+ if (!isCodemodParseError(err)) throw err;
+ throw markParseError(
+ atRule.error(/** @type {Error} */ (err).message, {
+ index: offset + start,
+ }),
+ );
+ }
+ return selector;
+ });
+ });
const migrated = migrateAstryxThemeSelectors(source, from, SELECTOR_DATA);
- const root = postcss.parse(migrated, {from});
+ const root = parseCss(migrated, {from});
/** @type {Set<string>} */
const existingComments = new Set();
root.walkComments(comment => {
existingComments.add(comment.text.trim());
});
root.walkRules(rule => {
- rule.selector = finishSelectorText(rule.selector);
+ rule.selector = finishSelectorText(rule);
const tokens = unclassifiedBareClasses(rule.selector);
if (tokens.length === 0) return;
const list = tokens.map(token => `.${token}`).join(', ');
diff --git a/packages/cli/authoring/codemod/type.ts b/packages/cli/authoring/codemod/type.ts
index a947a817f6..44bec2765b 100644
--- a/packages/cli/authoring/codemod/type.ts
+++ b/packages/cli/authoring/codemod/type.ts
@@ -141,6 +141,16 @@ export interface CodemodRunResult {
generated: boolean;
command?: string;
}>;
+ /**
+ * Protected files left for manual review because their own source does not
+ * parse, so no change can be proven in them. They do not fail the run.
+ */
+ declinedCandidates?: Array<{
+ file: string;
+ codemod: string;
+ location?: string;
+ reason: string;
+ }>;
errors: Array<{file: string; codemod: string; error: string}>;
}
diff --git a/packages/cli/clients/cli/commands/upgrade.doc.mjs b/packages/cli/clients/cli/commands/upgrade.doc.mjs
index dda9a1a700..88ec7e6283 100644
--- a/packages/cli/clients/cli/commands/upgrade.doc.mjs
+++ b/packages/cli/clients/cli/commands/upgrade.doc.mjs
@@ -201,6 +201,16 @@ export const doc = {
'`Command:` line in its header, such as `// Command: pnpm run gen:panel`; upgrade prints it as ' +
'`Regenerate with: <command>` and lists it in `commands`.',
},
+ {
+ type: 'prose',
+ text:
+ 'A protected file a codemod cannot parse, such as a vendored bundle written for another toolchain, cannot need a ' +
+ 'change the codemod can prove, and upgrade never writes it. upgrade skips it, lists it under ' +
+ '`declinedCandidates` with the parse error and where it occurred, and carries on; on its own it does not fail the run. ' +
+ 'If another codemod in the same upgrade still requires a change to that file (the 0.6.0 theme selector migration, for one, ' +
+ '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: 'A failed codemod'},
{
type: 'prose',
diff --git a/packages/cli/clients/cli/commands/upgrade.file-protection.test.mjs b/packages/cli/clients/cli/commands/upgrade.file-protection.test.mjs
index b772ae067d..cddaa96619 100644
--- a/packages/cli/clients/cli/commands/upgrade.file-protection.test.mjs
+++ b/packages/cli/clients/cli/commands/upgrade.file-protection.test.mjs
@@ -255,4 +255,150 @@ describe('upgrade protected-file contract', () => {
expect(second.envelope.data.complete).toBe(true);
expect(second.envelope.data.filesChanged).toBe(0);
});
+
+ it('skips a vendored file that does not parse and completes the upgrade', () => {
+ seed();
+ write('.gitattributes', 'vendor/** linguist-vendored\n');
+ const bundle =
+ "/* minified */ import {useResizable} from '@astryxdesign/core';\n" +
+ 'export const x = useResizable({minSizePx: 200;\n';
+ write('vendor/bundle.js', bundle);
+ rmGenerated();
+
+ const applied = run([...ARGS, '--apply']);
+
+ expect(applied.status, applied.stderr).toBe(0);
+ expect(applied.envelope).toMatchObject({
+ type: 'upgrade.run',
+ data: {
+ complete: true,
+ modifiedFiles: ['src/owned.tsx'],
+ protectedFiles: [],
+ declinedCandidates: [
+ {
+ file: 'vendor/bundle.js',
+ location: '2:46',
+ reason:
+ 'unparseable protected file (vendored): Unexpected token, expected ","',
+ },
+ ],
+ },
+ });
+ expect(applied.envelope.data.errors ?? []).toEqual([]);
+ expect(fs.readFileSync(path.join(root, 'src/owned.tsx'), 'utf8')).toContain(
+ 'minSize: 200',
+ );
+ expect(fs.readFileSync(path.join(root, 'vendor/bundle.js'), 'utf8')).toBe(
+ bundle,
+ );
+
+ const text = spawnSync(process.execPath, [CLI, 'upgrade', ...ARGS], {
+ cwd: root,
+ encoding: 'utf8',
+ timeout: 60_000,
+ env: {...process.env, FORCE_COLOR: '0', CI: ''},
+ });
+ expect(text.status, text.stderr).toBe(0);
+ expect(`${text.stdout}${text.stderr}`).toContain(
+ '1 protected file was skipped because it does not parse',
+ );
+ const declinedLine = `${text.stdout}${text.stderr}`
+ .split('\n')
+ .find(line => line.includes('vendor/bundle.js:2:46'));
+ expect(declinedLine).toMatch(/^ {2}vendor\/bundle\.js:2:46 - /);
+ // cli-surface output is plain ASCII.
+ expect(declinedLine).toMatch(/^[\x20-\x7e]*$/);
+ });
+
+ it('still fails when an owned file does not parse', () => {
+ seed();
+ write(
+ 'lib/broken.js',
+ "import {useResizable} from '@astryxdesign/core';\n" +
+ 'export const x = useResizable({minSizePx: 200;\n',
+ );
+ rmGenerated();
+
+ const applied = run([...ARGS, '--apply']);
+
+ expect(applied.status).toBe(1);
+ expect(applied.envelope).toMatchObject({code: 'ERR_CODEMOD_FAILED'});
+ });
+
+ it('reports a stylesheet the 0.6 and 0.7 theme codemods both need once, as protected', () => {
+ write('package.json', JSON.stringify({name: 'consumer', private: true}));
+ write(
+ 'node_modules/@astryxdesign/core/package.json',
+ JSON.stringify({name: '@astryxdesign/core', version: CLI_VERSION}),
+ );
+ write('.gitattributes', 'vendor/** linguist-vendored\n');
+ write('vendor/bundle.css', 'a:: { color: red; }\n');
+
+ const result = run(['--from', '0.5.4', '--path', '.']);
+ const text = spawnSync(
+ process.execPath,
+ [CLI, 'upgrade', '--from', '0.5.4', '--path', '.'],
+ {
+ cwd: root,
+ encoding: 'utf8',
+ timeout: 60_000,
+ env: {...process.env, FORCE_COLOR: '0', CI: ''},
+ },
+ );
+ const output = `${text.stdout}${text.stderr}`;
+ expect(text.status).toBe(1);
+ expect(output).toContain('ERR_CODEMOD_PROTECTED');
+ expect(output).toMatch(/^ {2}vendor\/bundle\.css — /m);
+ expect(output).not.toContain('skipped because');
+ expect(output).not.toContain('unparseable protected file');
+
+ expect(result.status).toBe(1);
+ expect(result.envelope).toMatchObject({
+ type: 'upgrade.run',
+ data: {
+ complete: false,
+ errorCode: 'ERR_CODEMOD_PROTECTED',
+ protectedFiles: [expect.objectContaining({file: 'vendor/bundle.css'})],
+ declinedCandidates: [],
+ },
+ });
+ });
+
+ it('lists a generated file the hook regenerates into bytes that do not parse', () => {
+ seed();
+ const broken =
+ "// @generated\nimport {useResizable} from '@astryxdesign/core';\n" +
+ 'export const usePanel = () => useResizable({minSizePx: 200;\n';
+ write(
+ 'astryx.config.mjs',
+ `export default {hooks: {postCodemod: [{name: 'regenerate', buildCommand: () => ({command: process.execPath, args: ['-e', ${JSON.stringify(`require('node:fs').writeFileSync('generated/panel.tsx', ${JSON.stringify(broken)})`)}]})}]}};\n`,
+ );
+
+ const applied = run([...ARGS, '--apply']);
+
+ expect(applied.status, applied.stderr).toBe(0);
+ expect(applied.envelope).toMatchObject({
+ type: 'upgrade.run',
+ data: {
+ complete: true,
+ protectedFiles: [],
+ declinedCandidates: [
+ {
+ file: 'generated/panel.tsx',
+ location: expect.stringMatching(/^3:\d+$/),
+ reason: expect.stringMatching(
+ /^unparseable protected file \(generated\): /,
+ ),
+ },
+ ],
+ },
+ });
+ expect(
+ fs.readFileSync(path.join(root, 'generated/panel.tsx'), 'utf8'),
+ ).toBe(broken);
+ });
});
+
+function rmGenerated() {
+ fs.rmSync(path.join(root, 'generated'), {recursive: true, force: true});
+}