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.mdnew file mode 100644index 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.++@ejhammonddiff --git a/packages/cli/api/upgrade/run/failure-receipt.test.mjs b/packages/cli/api/upgrade/run/failure-receipt.test.mjsindex 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.mjsindex 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.mjsindex 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.mjsnew file mode 100644index 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.mjsindex 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.mjsindex 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.mjsnew file mode 100644index 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.tsindex 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.mjsindex 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.mjsindex 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});+}