@astryxdesign/cli 0.6.3-canary.7210f0d → 0.6.3-canary.7ada42e

package/api/upgrade/upgrade.doc.mjs

@@ -121,7 +121,7 @@ export const doc = {
     {
       type: 'upgrade.run',
       description:
-        'The terminal run receipt: from/to versions, the codemod count, integrations processed, the agent-docs summary, an optional copied-composition registry summary, and (apply mode) filesChanged, transformsApplied, and any per-codemod errors.',
+        'The terminal run receipt: from/to versions, codemod count, integrations processed, agent-docs and registry summaries, modifiedFiles, protectedFiles, declinedCandidates, and completion state. A protected required change returns complete: false with ERR_CODEMOD_PROTECTED; the CLI exits nonzero while preserving the structured receipt.',
     },
   ],
   throws: [
@@ -147,6 +147,10 @@ export const doc = {
       code: 'ERR_CODEMOD_FAILED',
       when: 'one or more codemods failed, or a post-codemod hook failed',
     },
+    {
+      code: 'ERR_CODEMOD_PROTECTION_SOURCE',
+      when: 'a working-tree protection declaration cannot be read or parsed before writes begin',
+    },
   ],
   examples: [
     {

package/api/upgrade/upgrade.type.d.mts

@@ -131,6 +131,31 @@ export type UpgradeRegistryResponse = {
     type: "upgrade.registry";
     data: RegistryCompositionSummary;
 };
+/**
+ * A required codemod change blocked by effective working-tree protection.
+ */
+export type ProtectedCodemodFile = {
+    /**
+     * Project-relative path.
+     */
+    file: string;
+    /**
+     * Codemods that still require a change.
+     */
+    codemods: string[];
+    /**
+     * Protection categories (generated, vendored, ignored, and hard boundaries).
+     */
+    reasons: string[];
+    /**
+     * Effective declarations that protect the file.
+     */
+    declarations: string[];
+    /**
+     * Exact regeneration commands found in generated headers, when present.
+     */
+    commands: string[];
+};
 /**
  * astryx --json upgrade [--apply]
  */
@@ -144,7 +169,16 @@ export type UpgradeRunResponse = {
         agentDocsRefreshed: boolean;
         agentDocs: AgentDocsSummary;
         registryCompositions?: RegistryCompositionSummary | undefined;
+        complete?: boolean | undefined;
+        errorCode?: "ERR_CODEMOD_PROTECTED" | undefined;
         filesChanged?: number | undefined;
+        modifiedFiles?: string[] | undefined;
+        protectedFiles?: ProtectedCodemodFile[] | undefined;
+        declinedCandidates?: {
+            file: string;
+            location?: string;
+            reason: string;
+        }[] | undefined;
         transformsApplied?: number | undefined;
         errors?: {
             file: string;

package/api/upgrade/upgrade.type.mjs

@@ -95,6 +95,16 @@
  * @property {RegistryCompositionSummary} data
  */
 
+/**
+ * A required codemod change blocked by effective working-tree protection.
+ * @typedef {object} ProtectedCodemodFile
+ * @property {string} file Project-relative path.
+ * @property {string[]} codemods Codemods that still require a change.
+ * @property {string[]} reasons Protection categories (generated, vendored, ignored, and hard boundaries).
+ * @property {string[]} declarations Effective declarations that protect the file.
+ * @property {string[]} commands Exact regeneration commands found in generated headers, when present.
+ */
+
 /**
  * astryx --json upgrade [--apply]
  * @typedef {object} UpgradeRunResponse
@@ -107,7 +117,12 @@
  * @property {boolean} data.agentDocsRefreshed
  * @property {AgentDocsSummary} data.agentDocs
  * @property {RegistryCompositionSummary} [data.registryCompositions]
+ * @property {boolean} [data.complete] False when protected required changes remain.
+ * @property {'ERR_CODEMOD_PROTECTED'} [data.errorCode] Stable incomplete-result code when complete is false.
  * @property {number} [data.filesChanged] Total files changed across core + integration codemods (apply mode).
+ * @property {string[]} [data.modifiedFiles] Project-relative files changed or previewed.
+ * @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.
  * @property {number} [data.transformsApplied] Total transforms that reported a change.
  * @property {Array<{file: string, codemod: string, error: string}>} [data.errors] Per-codemod errors, when any codemod failed.
  */

package/assets/codemods/__tests__/runner.test.mjs

@@ -21,6 +21,40 @@ afterEach(() => {
   fs.rmSync(tmpDir, {recursive: true, force: true});
 });
 
+describe('runCodemods — ordered dry-run state', () => {
+  it('feeds each previewed code transform into the next transform', async () => {
+    const srcDir = path.join(tmpDir, 'src');
+    fs.mkdirSync(srcDir);
+    fs.writeFileSync(path.join(srcDir, 'a.ts'), 'const value = "a";\n');
+    const transforms = [
+      {
+        name: 'a-to-b',
+        meta: {title: 'a to b'},
+        transform: file => file.source.replace('"a"', '"b"'),
+      },
+      {
+        name: 'b-to-c',
+        meta: {title: 'b to c'},
+        transform: file => file.source.replace('"b"', '"c"'),
+      },
+    ];
+
+    const preview = await runCodemods([{version: '1.0.0', transforms}], {
+      apply: false,
+      path: srcDir,
+      root: tmpDir,
+      silent: true,
+    });
+
+    expect(preview.totalFilesChanged).toBe(2);
+    expect(preview.changedFiles).toEqual([
+      path.join(srcDir, 'a.ts'),
+      path.join(srcDir, 'a.ts'),
+    ]);
+    expect(fs.readFileSync(path.join(srcDir, 'a.ts'), 'utf8')).toContain('"a"');
+  });
+});
+
 describe('runCodemods — unified config codemod path', () => {
   it('routes a core config codemod through the (file, api) runner to edit astryx.config.*', async () => {
     fs.writeFileSync(
@@ -195,17 +229,219 @@ describe('runCodemods — unified config codemod path', () => {
   });
 });
 
-describe('findSourceFiles — scan boundaries (symlink + build dirs)', () => {
+describe('runCodemods — project plans honor existing-file protection', () => {
+  it('applies new and owned writes while blocking protected replacements and deletes', async () => {
+    fs.writeFileSync(
+      path.join(tmpDir, '.gitattributes'),
+      'generated/** linguist-generated=true\n',
+    );
+    fs.mkdirSync(path.join(tmpDir, 'generated'), {recursive: true});
+    fs.writeFileSync(path.join(tmpDir, 'generated', 'replace.ts'), 'old\n');
+    fs.writeFileSync(path.join(tmpDir, 'generated', 'remove.ts'), 'old\n');
+    fs.writeFileSync(path.join(tmpDir, 'owned.ts'), 'old\n');
+
+    const manifests = [
+      {
+        version: '1.0.0',
+        transforms: [
+          {
+            name: 'project-plan',
+            meta: {title: 'project plan', codemodType: 'project'},
+            transform: async root => ({
+              writes: [
+                {
+                  path: path.join(root, 'generated', 'replace.ts'),
+                  contents: 'new\n',
+                },
+                {path: path.join(root, 'owned.ts'), contents: 'new\n'},
+                {path: path.join(root, 'created.ts'), contents: 'new\n'},
+              ],
+              deletes: [path.join(root, 'generated', 'remove.ts')],
+              problems: [],
+            }),
+          },
+        ],
+      },
+    ];
+
+    const result = await runCodemods(manifests, {
+      apply: true,
+      path: './missing',
+      root: tmpDir,
+      silent: true,
+    });
+
+    expect(
+      fs.readFileSync(path.join(tmpDir, 'generated', 'replace.ts'), 'utf8'),
+    ).toBe('old\n');
+    expect(fs.existsSync(path.join(tmpDir, 'generated', 'remove.ts'))).toBe(
+      true,
+    );
+    expect(fs.readFileSync(path.join(tmpDir, 'owned.ts'), 'utf8')).toBe(
+      'new\n',
+    );
+    expect(fs.readFileSync(path.join(tmpDir, 'created.ts'), 'utf8')).toBe(
+      'new\n',
+    );
+    expect(result.totalFilesChanged).toBe(2);
+    expect(result.protectedFiles.map(item => item.file).sort()).toEqual([
+      'generated/remove.ts',
+      'generated/replace.ts',
+    ]);
+  });
+
+  it('blocks an existing file protected by a declaration in the same plan', async () => {
+    fs.mkdirSync(path.join(tmpDir, 'src'), {recursive: true});
+    fs.writeFileSync(path.join(tmpDir, 'src', 'out.ts'), 'old\n');
+    const manifests = [
+      {
+        version: '1.0.0',
+        transforms: [
+          {
+            name: 'declare-and-replace',
+            meta: {title: 'declare and replace', codemodType: 'project'},
+            transform: async root => ({
+              writes: [
+                {
+                  path: path.join(root, '.gitattributes'),
+                  contents: 'src/out.ts linguist-generated\n',
+                },
+                {path: path.join(root, 'src', 'out.ts'), contents: 'new\n'},
+              ],
+              deletes: [],
+              problems: [],
+            }),
+          },
+        ],
+      },
+    ];
+
+    const result = await runCodemods(manifests, {
+      apply: true,
+      path: './missing',
+      root: tmpDir,
+      silent: true,
+    });
+
+    expect(fs.readFileSync(path.join(tmpDir, 'src', 'out.ts'), 'utf8')).toBe(
+      'old\n',
+    );
+    expect(fs.readFileSync(path.join(tmpDir, '.gitattributes'), 'utf8')).toBe(
+      'src/out.ts linguist-generated\n',
+    );
+    expect(result.protectedFiles).toEqual([
+      expect.objectContaining({
+        file: 'src/out.ts',
+        declaration: 'linguist-generated in .gitattributes:1',
+      }),
+    ]);
+  });
+
+  it('does not apply rules from a blocked staged declaration', async () => {
+    fs.writeFileSync(
+      path.join(tmpDir, '.gitattributes'),
+      '.gitattributes linguist-generated\n',
+    );
+    fs.mkdirSync(path.join(tmpDir, 'src'), {recursive: true});
+    fs.writeFileSync(path.join(tmpDir, 'src', 'out.ts'), 'old\n');
+    const result = await runCodemods(
+      [
+        {
+          version: '1.0.0',
+          transforms: [
+            {
+              name: 'blocked-declaration',
+              meta: {title: 'blocked declaration', codemodType: 'project'},
+              transform: async root => ({
+                writes: [
+                  {
+                    path: path.join(root, '.gitattributes'),
+                    contents: 'src/out.ts linguist-generated\n',
+                  },
+                  {path: path.join(root, 'src', 'out.ts'), contents: 'new\n'},
+                ],
+                deletes: [],
+                problems: [],
+              }),
+            },
+          ],
+        },
+      ],
+      {apply: true, path: './missing', root: tmpDir, silent: true},
+    );
+
+    expect(fs.readFileSync(path.join(tmpDir, 'src', 'out.ts'), 'utf8')).toBe(
+      'new\n',
+    );
+    expect(result.protectedFiles).toEqual([
+      expect.objectContaining({file: '.gitattributes'}),
+    ]);
+  });
+
+  it('refreshes declarations written by an earlier project codemod before later writes', async () => {
+    fs.mkdirSync(path.join(tmpDir, 'src'), {recursive: true});
+    fs.writeFileSync(path.join(tmpDir, 'src', 'out.ts'), 'const foo = 1;\n');
+    const manifests = [
+      {
+        version: '1.0.0',
+        transforms: [
+          {
+            name: 'declare-generated',
+            meta: {title: 'declare generated', codemodType: 'project'},
+            transform: async root => ({
+              writes: [
+                {
+                  path: path.join(root, '.gitattributes'),
+                  contents: 'src/out.ts linguist-generated=true\n',
+                },
+              ],
+              deletes: [],
+              problems: [],
+            }),
+          },
+          {
+            name: 'rename-after-declaration',
+            meta: {title: 'rename after declaration'},
+            transform: file => file.source.replace('foo', 'bar'),
+          },
+        ],
+      },
+    ];
+
+    const result = await runCodemods(manifests, {
+      apply: true,
+      path: path.join(tmpDir, 'src'),
+      root: tmpDir,
+      silent: true,
+    });
+
+    expect(
+      fs.readFileSync(path.join(tmpDir, 'src', 'out.ts'), 'utf8'),
+    ).toContain('foo');
+    expect(result.protectedFiles).toEqual([
+      expect.objectContaining({
+        file: 'src/out.ts',
+        declaration: 'linguist-generated in .gitattributes:1',
+      }),
+    ]);
+  });
+});
+
+describe('findSourceFiles — scan boundaries (symlink + declared protection)', () => {
   const manifests = [
     {
       version: '0.1.3',
       transforms: [
-        {name: 'p', meta: {title: 'p'}, transform: f => f.source.replace(/foo/g, 'bar')},
+        {
+          name: 'p',
+          meta: {title: 'p'},
+          transform: f => f.source.replace(/foo/g, 'bar'),
+        },
       ],
     },
   ];
 
-  it('does not follow a symlinked file out of the scan tree', async () => {
+  it('reports a symlinked file without writing through it', async () => {
     const outside = path.join(tmpDir, 'outside');
     fs.mkdirSync(path.join(tmpDir, 'src'), {recursive: true});
     fs.mkdirSync(outside, {recursive: true});
@@ -214,13 +450,45 @@ describe('findSourceFiles — scan boundaries (symlink + build dirs)', () => {
     fs.writeFileSync(path.join(tmpDir, 'src', 'real.ts'), 'const foo = 2;\n');
     fs.symlinkSync(secret, path.join(tmpDir, 'src', 'link.ts'));
 
-    const r = await runCodemods(manifests, {apply: true, path: './src', silent: true});
+    const r = await runCodemods(manifests, {
+      apply: true,
+      path: './src',
+      silent: true,
+    });
     // the symlink target (outside the tree) must be untouched
     expect(fs.readFileSync(secret, 'utf-8')).toBe('const foo = 1;\n');
     expect(r.writtenFiles.map(f => path.basename(f))).toEqual(['real.ts']);
+    expect(r.protectedFiles).toEqual([
+      expect.objectContaining({file: 'src/link.ts', reason: 'symlink'}),
+    ]);
   });
 
-  it('does not scan generated-output dirs (dist/build/out)', async () => {
+  it('reports matching descendants of a symlinked directory without writing through it', async () => {
+    const targetDir = path.join(tmpDir, 'target');
+    const srcDir = path.join(tmpDir, 'src');
+    fs.mkdirSync(targetDir, {recursive: true});
+    fs.mkdirSync(srcDir, {recursive: true});
+    const target = path.join(targetDir, 'nested.ts');
+    fs.writeFileSync(target, 'const foo = 1;\n');
+    fs.symlinkSync(targetDir, path.join(srcDir, 'linked'));
+
+    const result = await runCodemods(manifests, {
+      apply: true,
+      path: srcDir,
+      root: tmpDir,
+      silent: true,
+    });
+
+    expect(fs.readFileSync(target, 'utf8')).toContain('foo');
+    expect(result.protectedFiles).toEqual([
+      expect.objectContaining({
+        file: 'src/linked/nested.ts',
+        reason: 'symlink',
+      }),
+    ]);
+  });
+
+  it('does not infer protection from generated-looking directory names', async () => {
     fs.mkdirSync(path.join(tmpDir, 'src'), {recursive: true});
     fs.mkdirSync(path.join(tmpDir, 'dist'), {recursive: true});
     fs.mkdirSync(path.join(tmpDir, 'build'), {recursive: true});
@@ -228,8 +496,62 @@ describe('findSourceFiles — scan boundaries (symlink + build dirs)', () => {
     fs.writeFileSync(path.join(tmpDir, 'dist', 'b.js'), 'const foo = 2;\n');
     fs.writeFileSync(path.join(tmpDir, 'build', 'c.js'), 'const foo = 3;\n');
 
-    const r = await runCodemods(manifests, {apply: true, path: '.', silent: true});
-    expect(r.writtenFiles.map(f => path.basename(f))).toEqual(['a.ts']);
-    expect(fs.readFileSync(path.join(tmpDir, 'dist', 'b.js'), 'utf-8')).toContain('foo');
+    const r = await runCodemods(manifests, {
+      apply: true,
+      path: '.',
+      silent: true,
+    });
+    expect(r.writtenFiles.map(f => path.basename(f)).sort()).toEqual([
+      'a.ts',
+      'b.js',
+      'c.js',
+    ]);
+  });
+
+  it('changes owned files but reports generated files without writing them', async () => {
+    fs.mkdirSync(path.join(tmpDir, 'src'), {recursive: true});
+    fs.mkdirSync(path.join(tmpDir, 'dist'), {recursive: true});
+    fs.writeFileSync(
+      path.join(tmpDir, '.gitattributes'),
+      'dist/** linguist-generated=true\n',
+    );
+    fs.writeFileSync(path.join(tmpDir, 'src', 'owned.ts'), 'const foo = 1;\n');
+    fs.writeFileSync(
+      path.join(tmpDir, 'dist', 'output.js'),
+      'const foo = 2;\n',
+    );
+
+    const r = await runCodemods(manifests, {
+      apply: true,
+      path: '.',
+      silent: true,
+    });
+
+    expect(
+      fs.readFileSync(path.join(tmpDir, 'src', 'owned.ts'), 'utf-8'),
+    ).toContain('bar');
+    expect(
+      fs.readFileSync(path.join(tmpDir, 'dist', 'output.js'), 'utf-8'),
+    ).toContain('foo');
+    expect(r.protectedFiles).toEqual([
+      expect.objectContaining({
+        file: 'dist/output.js',
+        reason: 'generated',
+        declaration: 'linguist-generated in .gitattributes:1',
+      }),
+    ]);
+  });
+
+  it('fails closed before an owned write when a declaration is malformed', async () => {
+    fs.mkdirSync(path.join(tmpDir, 'src'), {recursive: true});
+    fs.writeFileSync(path.join(tmpDir, 'src', 'owned.ts'), 'const foo = 1;\n');
+    fs.writeFileSync(path.join(tmpDir, '.hgignore'), 'syntax: regexp\n[bad\n');
+
+    await expect(
+      runCodemods(manifests, {apply: true, path: '.', silent: true}),
+    ).rejects.toThrow(/file-protection source \.hgignore/);
+    expect(
+      fs.readFileSync(path.join(tmpDir, 'src', 'owned.ts'), 'utf-8'),
+    ).toContain('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,40 @@ 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 +102,24 @@ 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});
+    const r = runConfigCodemod(entry, {
+      apply,
+      log,
+      jscodeshift,
+      root,
+      protection,
+      contents: virtualContents,
+    });
     totalFilesChanged += r.filesChanged;
     totalTransformsApplied += r.filesChanged;
+    changedFiles.push(...r.changedFiles);
     writtenFiles.push(...r.writtenFiles);
+    protectedFiles.push(...r.protectedFiles);
     errors.push(...r.errors);
   }
 
@@ -94,13 +130,26 @@ 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});
+      const r = runCodeCodemod(entry, files, {
+        apply,
+        log,
+        jscodeshift,
+        root,
+        protection,
+        contents: virtualContents,
+      });
       totalFilesChanged += r.filesChanged;
       totalTransformsApplied += r.filesChanged;
+      changedFiles.push(...r.changedFiles);
       writtenFiles.push(...r.writtenFiles);
+      protectedFiles.push(...r.protectedFiles);
       errors.push(...r.errors);
     }
   }
@@ -108,7 +157,10 @@ export function runIntegrationCodemods(
   return {
     totalFilesChanged,
     totalTransformsApplied,
+    changedFiles,
     writtenFiles,
+    stagedContents: virtualContents,
+    protectedFiles,
     errors,
     skippedOptional,
   };