@astryxdesign/cli 0.6.3 → 0.6.4-canary.06c8fa3

package/assets/codemods/file-count.test.mjs

@@ -0,0 +1,163 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `filesChanged` counts FILES, not (codemod, file) pairs.
+ *
+ * One source file that four codemods each changed was reported as four files
+ * changed — the total was incremented once per transform per file, so it
+ * equalled `transformsApplied` in every run and the documented meaning of the
+ * field ("Total files changed") was never true. The two numbers answer
+ * different questions and both are in the receipt.
+ */
+
+import {describe, it, expect, beforeEach, afterEach} from 'vitest';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import jscodeshift from 'jscodeshift';
+import {runCodemods} from './runner.mjs';
+import {runIntegrationCodemods} from './integration-runner.mjs';
+
+let dir;
+
+beforeEach(() => {
+  dir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-file-count-'));
+});
+afterEach(() => fs.rmSync(dir, {recursive: true, force: true}));
+
+/** A transform that rewrites one distinctive token, so several can stack. */
+const renaming = (from, to) => (file) =>
+  file.source.includes(from) ? file.source.split(from).join(to) : null;
+
+/** @param {string} name @param {string[]} contents */
+function writeSources(...contents) {
+  return contents.map((content, i) => {
+    const file = path.join(dir, `file${i}.ts`);
+    fs.writeFileSync(file, content);
+    return file;
+  });
+}
+
+describe('core codemod runner — filesChanged counts files', () => {
+  it('reports 1 file for one file changed by four codemods', async () => {
+    writeSources('const a = ONE + TWO + THREE + FOUR;\n');
+
+    const result = await runCodemods(
+      [
+        {
+          version: '0.0.2',
+          transforms: [
+            {name: 'one', transform: renaming('ONE', '1'), meta: {title: 'one'}},
+            {name: 'two', transform: renaming('TWO', '2'), meta: {title: 'two'}},
+            {name: 'three', transform: renaming('THREE', '3'), meta: {title: 'three'}},
+            {name: 'four', transform: renaming('FOUR', '4'), meta: {title: 'four'}},
+          ],
+        },
+      ],
+      {apply: true, path: dir, root: dir, codemod: undefined, skipCodemods: new Set(), silent: true},
+    );
+
+    expect(result.totalTransformsApplied).toBe(4);
+    expect(result.totalFilesChanged).toBe(1);
+    expect(new Set(result.changedFiles).size).toBe(1);
+  });
+
+  it('still counts two files as two', async () => {
+    writeSources('const a = ONE;\n', 'const b = ONE;\n');
+
+    const result = await runCodemods(
+      [
+        {
+          version: '0.0.2',
+          transforms: [
+            {name: 'one', transform: renaming('ONE', '1'), meta: {title: 'one'}},
+          ],
+        },
+      ],
+      {apply: true, path: dir, root: dir, codemod: undefined, skipCodemods: new Set(), silent: true},
+    );
+
+    expect(result.totalTransformsApplied).toBe(2);
+    expect(result.totalFilesChanged).toBe(2);
+  });
+
+  it('reports 0 when nothing matched', async () => {
+    writeSources('const a = 1;\n');
+
+    const result = await runCodemods(
+      [
+        {
+          version: '0.0.2',
+          transforms: [
+            {name: 'one', transform: renaming('ONE', '1'), meta: {title: 'one'}},
+          ],
+        },
+      ],
+      {apply: true, path: dir, root: dir, codemod: undefined, skipCodemods: new Set(), silent: true},
+    );
+
+    expect(result.totalFilesChanged).toBe(0);
+    expect(result.totalTransformsApplied).toBe(0);
+  });
+});
+
+describe('integration codemod runner — filesChanged counts files', () => {
+  it('reports 1 file for one file changed by three integration codemods', () => {
+    writeSources('const a = ONE + TWO + THREE;\n');
+
+    const entry = (id, from, to) => ({
+      id,
+      package: '@acme/widgets',
+      type: 'code',
+      codemod: {title: id, transform: renaming(from, to)},
+    });
+
+    const result = runIntegrationCodemods(
+      [
+        {
+          version: '1.0.0',
+          codemods: [
+            entry('one', 'ONE', '1'),
+            entry('two', 'TWO', '2'),
+            entry('three', 'THREE', '3'),
+          ],
+        },
+      ],
+      {apply: true, path: dir, root: dir, skipCodemods: new Set(), jscodeshift, silent: true},
+    );
+
+    expect(result.totalTransformsApplied).toBe(3);
+    expect(result.totalFilesChanged).toBe(1);
+    expect(new Set(result.changedFiles).size).toBe(1);
+  });
+});
+
+describe('core codemod runner — a project codemod', () => {
+  it('counts every file it writes, and one change', async () => {
+    const result = await runCodemods(
+      [
+        {
+          version: '0.0.2',
+          transforms: [
+            {
+              name: 'project-plan',
+              meta: {title: 'project plan', codemodType: 'project'},
+              transform: async root => ({
+                writes: [
+                  {path: path.join(root, 'a.ts'), contents: 'a\n'},
+                  {path: path.join(root, 'b.ts'), contents: 'b\n'},
+                ],
+                deletes: [],
+                problems: [],
+              }),
+            },
+          ],
+        },
+      ],
+      {apply: true, path: dir, root: dir, codemod: undefined, skipCodemods: new Set(), silent: true},
+    );
+
+    expect(result.totalFilesChanged).toBe(2);
+    expect(result.totalTransformsApplied).toBe(1);
+  });
+});

package/assets/codemods/integration-discovery.mjs

@@ -32,6 +32,40 @@ import {semverCompare} from '../../foundation/env/semver.mjs';
 /** File extensions recognized as codemod modules. */
 const CODEMOD_EXTENSIONS = ['.ts', '.mjs', '.js'];
 
+/**
+ * Directories never walked for codemods: a test directory beside a transform is
+ * the natural place to put its test, and every file found here is loaded and
+ * validated as a codemod.
+ */
+const SKIP_DIRS = new Set([
+  'node_modules',
+  '.git',
+  '__tests__',
+  '__fixtures__',
+]);
+
+/**
+ * Whether a file name is a test or fixture rather than a codemod.
+ *
+ * The trap this closes: EVERY `.ts`/`.mjs`/`.js` under a version folder used to
+ * be loaded as a codemod, so a test file colocated with its transform failed
+ * validation and — because a definition error is a hard error — took every
+ * codemod in that package's version with it. `astryx upgrade` then applied no
+ * transforms and reported success, which is the worst shape a failure can take.
+ *
+ * Core's own codemods never hit this: they are enumerated in a registry, and
+ * their colocated tests are simply not in it. Only integrations are discovered
+ * by walking a directory, so only integrations carry the landmine — which is why
+ * this is a loader fix and not a documentation one. It protects the integrations
+ * that already exist, which no authoring tool can reach.
+ *
+ * @param {string} name a file's base name
+ * @returns {boolean}
+ */
+function isTestFile(name) {
+  return /\.(test|spec)\.[^.]+$/.test(name) || /\.fixture\.[^.]+$/.test(name);
+}
+
 /**
  * Recursively collect codemod module files under a version folder. Returns
  * entries of {id, file} where id is the extension-less relative path
@@ -49,14 +83,18 @@ function collectCodemodFiles(versionDir) {
     for (const entry of entries) {
       const full = path.join(dir, entry.name);
       if (entry.isDirectory()) {
-        if (entry.name === 'node_modules' || entry.name === '.git') continue;
+        if (SKIP_DIRS.has(entry.name)) continue;
         walk(full);
         continue;
       }
       const ext = path.extname(entry.name);
       if (!CODEMOD_EXTENSIONS.includes(ext)) continue;
+      if (isTestFile(entry.name)) continue;
       const rel = path.relative(versionDir, full);
-      const id = rel.slice(0, rel.length - ext.length).split(path.sep).join('/');
+      const id = rel
+        .slice(0, rel.length - ext.length)
+        .split(path.sep)
+        .join('/');
       out.push({id, file: full});
     }
   }
@@ -68,7 +106,7 @@ function collectCodemodFiles(versionDir) {
 /**
  * Discover file-based codemods contributed by configured integrations.
  *
- * @param {Array<{name?: string, codemods?: string, __spec?: string}>} loadedIntegrations
+ * @param {Array<{name?: string, codemods?: string, __spec?: string, __packageDir?: string}>} loadedIntegrations
  * @returns {Promise<Map<string, Array<{id: string, type: 'code'|'config', codemod: object, package: string}>>>}
  *   Map keyed by version string; each value is the list of discovered codemods
  *   for that version (across all integrations).
@@ -107,7 +145,13 @@ export async function discoverIntegrationCodemods(loadedIntegrations = []) {
       const seenInVersion = new Set();
 
       for (const {id, file} of files) {
-        const label = `Integration "${pkgLabel}" codemod ${version}/${id} (${file})`;
+        const shown = integration.__packageDir
+          ? path
+              .relative(integration.__packageDir, file)
+              .split(path.sep)
+              .join('/')
+          : file;
+        const label = `Integration "${pkgLabel}" codemod ${version}/${id} (${shown})`;
 
         if (seenInVersion.has(id)) {
           throw new Error(

package/assets/codemods/integration-discovery.test.mjs

@@ -163,6 +163,21 @@ describe('integration codemod discovery', () => {
     ).rejects.toThrow(/is invalid/i);
   });
 
+  it('names a broken codemod by its path inside the package', async () => {
+    scaffold({
+      '1.1.0/no-default.mjs': `export const nope = 1;\n`,
+    });
+    const project = await Project.load(tmpDir);
+    const failure = await discoverIntegrationCodemods(
+      project.loadedIntegrations,
+    ).then(
+      () => null,
+      error => error,
+    );
+    expect(failure?.message).toContain('(codemods/1.1.0/no-default.mjs)');
+    expect(failure?.message).not.toContain(tmpDir);
+  });
+
   it('fails discovery when default export is not a codemod envelope', async () => {
     scaffold({
       '0.2.0/bad.mjs': `export default { title: 'x', transform: () => null };\n`,
@@ -221,3 +236,61 @@ describe('integration codemod discovery', () => {
     ).rejects.toThrow(/across versions/i);
   });
 });
+
+describe('test files beside a codemod', () => {
+  // The incident this closes: every .ts/.mjs/.js under a version folder was
+  // loaded AND VALIDATED as a codemod, so a test file colocated with its
+  // transform failed validation — and because a definition error is a hard
+  // error, it took every codemod in that version with it. `astryx upgrade`
+  // then applied nothing and reported success. Core is immune because its own
+  // codemods are enumerated in a registry rather than discovered by walking a
+  // directory, so its colocated tests are simply never visited. Only
+  // integrations carry the landmine.
+  const TRANSFORM = `
+    export default {
+      type: 'code',
+      title: 'Drop foo',
+      transform: (file) => file.source.replace(/foo/g, 'bar'),
+    };
+  `;
+  // Not a codemod: no default export of the right shape. Loading it throws.
+  const A_TEST = `
+    import {describe, it, expect} from 'vitest';
+    describe('drop-foo', () => {
+      it('drops foo', () => expect(1).toBe(1));
+    });
+  `;
+
+  it.each([
+    ['a .test. sibling', '0.2.0/drop-foo.test.mjs'],
+    ['a .spec. sibling', '0.2.0/drop-foo.spec.mjs'],
+    ['a fixture sibling', '0.2.0/drop-foo.fixture.mjs'],
+    ['a __tests__ directory', '0.2.0/__tests__/drop-foo.mjs'],
+    ['a __fixtures__ directory', '0.2.0/__fixtures__/input.mjs'],
+  ])('ignores %s and still discovers the codemod', async (_label, testPath) => {
+    scaffold({'0.2.0/drop-foo.mjs': TRANSFORM, [testPath]: A_TEST});
+
+    const project = await Project.load(tmpDir);
+    const byVersion = await discoverIntegrationCodemods(
+      project.loadedIntegrations,
+    );
+
+    expect([...byVersion.keys()]).toEqual(['0.2.0']);
+    expect(byVersion.get('0.2.0').map(entry => entry.id)).toEqual(['drop-foo']);
+  });
+
+  it('a nested helper directory is still walked', async () => {
+    // Only test and fixture names are skipped. A package that organises its
+    // transforms into subdirectories keeps working.
+    scaffold({'0.2.0/imports/drop-foo.mjs': TRANSFORM});
+
+    const project = await Project.load(tmpDir);
+    const byVersion = await discoverIntegrationCodemods(
+      project.loadedIntegrations,
+    );
+
+    expect(byVersion.get('0.2.0').map(entry => entry.id)).toEqual([
+      'imports/drop-foo',
+    ]);
+  });
+});

package/assets/codemods/integration-runner.mjs

@@ -24,6 +24,7 @@ import {
   runCodeCodemod,
   runConfigCodemod,
 } from './run-codemod.mjs';
+import {createFileProtectionResolver} from '../../foundation/fs/file-protection.mjs';
 
 /**
  * Run file-based integration codemods, version-ordered. Config codemods run
@@ -40,18 +41,39 @@ import {
  * @param {Set<string>} [options.skipCodemods] codemod ids to exclude
  * @param {import('../../authoring/codemod/type').JscodeshiftFactory} options.jscodeshift
  * @param {boolean} [options.silent]
- * @returns {{totalFilesChanged: number, totalTransformsApplied: number, writtenFiles: string[], errors: Array<{file: string, codemod: string, error: string}>, skippedOptional: Array<import('../../authoring/codemod/type').CodemodEntry>}}
+ * @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>}}
  */
 export function runIntegrationCodemods(
   versionGroups,
-  {apply, path: srcPath, codemod, skipCodemods, jscodeshift, silent = false},
+  {
+    apply,
+    path: srcPath,
+    codemod,
+    skipCodemods,
+    jscodeshift,
+    silent = false,
+    root = process.cwd(),
+    protection: providedProtection,
+    contents: providedContents,
+  },
 ) {
   const log = makeLog(silent);
+  let protection =
+    providedProtection ?? createFileProtectionResolver(path.resolve(root));
+  let protectionWriteCount = 0;
+  /** In-memory pipeline state keeps ordered dry-runs equivalent to apply. */
+  const virtualContents = new Map(providedContents ?? []);
 
-  let totalFilesChanged = 0;
   let totalTransformsApplied = 0;
   /** @type {string[]} */
+  const changedFiles = [];
+  /** @type {string[]} */
   const writtenFiles = [];
+  /** @type {import('../../authoring/codemod/type').CodemodRunResult['protectedFiles']} */
+  const protectedFiles = [];
   /** @type {Array<{file: string, codemod: string, error: string}>} */
   const errors = [];
   /** @type {Array<import('../../authoring/codemod/type').CodemodEntry>} */
@@ -79,11 +101,23 @@ export function runIntegrationCodemods(
 
   // Config codemods first.
   for (const entry of configEntries) {
+    if (apply && writtenFiles.length !== protectionWriteCount) {
+      protection = createFileProtectionResolver(path.resolve(root));
+      protectionWriteCount = writtenFiles.length;
+    }
     log.info(`  ${entry.codemod.title} (v${entry.version}, ${entry.package})`);
-    const r = runConfigCodemod(entry, {apply, log, jscodeshift});
-    totalFilesChanged += r.filesChanged;
+    const r = runConfigCodemod(entry, {
+      apply,
+      log,
+      jscodeshift,
+      root,
+      protection,
+      contents: virtualContents,
+    });
     totalTransformsApplied += r.filesChanged;
+    changedFiles.push(...r.changedFiles);
     writtenFiles.push(...r.writtenFiles);
+    protectedFiles.push(...r.protectedFiles);
     errors.push(...r.errors);
   }
 
@@ -94,21 +128,39 @@ export function runIntegrationCodemods(
       ? findSourceFiles(resolvedPath)
       : [];
     for (const entry of codeEntries) {
+      if (apply && writtenFiles.length !== protectionWriteCount) {
+        protection = createFileProtectionResolver(path.resolve(root));
+        protectionWriteCount = writtenFiles.length;
+      }
       log.info(
         `  ${entry.codemod.title} (v${entry.version}, ${entry.package})`,
       );
-      const r = runCodeCodemod(entry, files, {apply, log, jscodeshift});
-      totalFilesChanged += r.filesChanged;
+      const r = runCodeCodemod(entry, files, {
+        apply,
+        log,
+        jscodeshift,
+        root,
+        protection,
+        contents: virtualContents,
+      });
       totalTransformsApplied += r.filesChanged;
+      changedFiles.push(...r.changedFiles);
       writtenFiles.push(...r.writtenFiles);
+      protectedFiles.push(...r.protectedFiles);
       errors.push(...r.errors);
     }
   }
 
+  // A file several codemods changed is one file; transforms count each change.
+  const totalFilesChanged = new Set(changedFiles).size;
+
   return {
     totalFilesChanged,
     totalTransformsApplied,
+    changedFiles,
     writtenFiles,
+    stagedContents: virtualContents,
+    protectedFiles,
     errors,
     skippedOptional,
   };

package/assets/codemods/integration-runner.protection.test.mjs

@@ -0,0 +1,153 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {afterEach, beforeEach, describe, expect, it} from 'vitest';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import {runIntegrationCodemods} from './integration-runner.mjs';
+
+let root;
+let originalCwd;
+
+beforeEach(() => {
+  root = fs.mkdtempSync(
+    path.join(os.tmpdir(), 'astryx-integration-protection-'),
+  );
+  originalCwd = process.cwd();
+  process.chdir(root);
+});
+
+afterEach(() => {
+  process.chdir(originalCwd);
+  fs.rmSync(root, {recursive: true, force: true});
+});
+
+function write(relative, contents) {
+  const file = path.join(root, relative);
+  fs.mkdirSync(path.dirname(file), {recursive: true});
+  fs.writeFileSync(file, contents);
+  return file;
+}
+
+describe('integration codemod file protection', () => {
+  it('uses the same resolver for integration config and code codemods', async () => {
+    write(
+      '.gitattributes',
+      [
+        'astryx.config.mjs linguist-generated=true',
+        'src/generated.js linguist-vendored=true',
+        '',
+      ].join('\n'),
+    );
+    write('astryx.config.mjs', "export default {value: 'old'};\n");
+    write('src/generated.js', "export const value = 'old';\n");
+
+    const groups = [
+      {
+        version: '1.0.0',
+        codemods: [
+          {
+            id: 'config',
+            type: 'config',
+            package: '@acme/integration',
+            codemod: {
+              title: 'config',
+              transform: file => file.source.replace('old', 'new'),
+            },
+          },
+          {
+            id: 'code',
+            type: 'code',
+            package: '@acme/integration',
+            codemod: {
+              title: 'code',
+              fileExtensions: ['.js'],
+              transform: file => file.source.replace('old', 'new'),
+            },
+          },
+        ],
+      },
+    ];
+    const jscodeshift = (await import('jscodeshift')).default;
+    const result = runIntegrationCodemods(groups, {
+      apply: true,
+      path: path.join(root, 'src'),
+      root,
+      jscodeshift,
+      silent: true,
+    });
+
+    expect(result.totalFilesChanged).toBe(0);
+    expect(result.protectedFiles.map(item => item.file).sort()).toEqual([
+      'astryx.config.mjs',
+      'src/generated.js',
+    ]);
+    expect(
+      fs.readFileSync(path.join(root, 'astryx.config.mjs'), 'utf8'),
+    ).toContain('old');
+    expect(
+      fs.readFileSync(path.join(root, 'src/generated.js'), 'utf8'),
+    ).toContain('old');
+  });
+
+  it('lets a staged declaration protect another file in the same entry', async () => {
+    write('.gitattributes', '# authored\n');
+    write('src/x.js', "export const value = 'old';\n");
+    const groups = [
+      {
+        version: '1.0.0',
+        codemods: [
+          {
+            id: 'declare-and-change',
+            type: 'code',
+            package: '@acme/integration',
+            codemod: {
+              title: 'declare and change',
+              fileExtensions: ['', '.js'],
+              transform: file =>
+                path.basename(file.path) === '.gitattributes'
+                  ? 'src/x.js linguist-generated\n'
+                  : file.source.replace('old', 'new'),
+            },
+          },
+        ],
+      },
+    ];
+    const jscodeshift = (await import('jscodeshift')).default;
+
+    const preview = runIntegrationCodemods(groups, {
+      apply: false,
+      path: root,
+      root,
+      jscodeshift,
+      silent: true,
+    });
+    expect(preview.protectedFiles).toEqual([
+      expect.objectContaining({file: 'src/x.js', reason: 'generated'}),
+    ]);
+    expect(fs.readFileSync(path.join(root, '.gitattributes'), 'utf8')).toBe(
+      '# authored\n',
+    );
+
+    const result = runIntegrationCodemods(groups, {
+      apply: true,
+      path: root,
+      root,
+      jscodeshift,
+      silent: true,
+    });
+
+    expect(fs.readFileSync(path.join(root, '.gitattributes'), 'utf8')).toBe(
+      'src/x.js linguist-generated\n',
+    );
+    expect(fs.readFileSync(path.join(root, 'src/x.js'), 'utf8')).toContain(
+      'old',
+    );
+    expect(result.protectedFiles).toEqual([
+      expect.objectContaining({
+        file: 'src/x.js',
+        reason: 'generated',
+      }),
+    ]);
+  });
+});

package/assets/codemods/registry.mjs

@@ -29,6 +29,7 @@ const registry = new Map([
   ['0.4.0', () => import('./transforms/v0.4.0/index.mjs')],
   ['0.5.0', () => import('./transforms/v0.5.0/index.mjs')],
   ['0.6.0', () => import('./transforms/v0.6.0/index.mjs')],
+  ['0.6.4', () => import('./transforms/v0.6.4/index.mjs')],
 ]);
 
 // Re-export from the shared utility so registry callers and other consumers