@astryxdesign/cli 0.6.4 → 0.6.5-canary.031021b

package/api/theme/themePaletteGenerate.doc.mjs

@@ -27,30 +27,34 @@ export const doc = {
     {
       name: 'configPath',
       type: 'string',
-      description: 'JSON generation request, resolved within cwd.',
+      description:
+        'Path to a JSON file holding a TonalPaletteGenerationInput (the object generateTonalPalette() takes), resolved within cwd.',
       required: true,
     },
     {
       name: 'options.out',
       type: 'string',
       description:
-        'Optional candidate JSON destination. A sibling .receipt.json path is derived from it.',
+        'Where to write the candidate: a path ending in .ts (a TypeScript module) or .json. A sibling <name>.receipt.json is written next to it.',
     },
     {
       name: 'options.preview',
       type: 'string',
-      description: 'Optional path for a self-contained HTML review artifact.',
+      description:
+        'Optional path, ending in .html, for a self-contained HTML review page.',
     },
     {
       name: 'options.overwrite',
       type: 'boolean',
-      description: 'Replace existing candidate and receipt files.',
+      description:
+        "Replace existing candidate, receipt and preview files. Without it, if any target exists, nothing is written and the result has written: false, reason: 'exists'.",
       default: 'false',
     },
     {
       name: 'ctx.cwd',
       type: 'string',
       description: 'Directory used to resolve the input and output paths.',
+      default: 'process.cwd()',
     },
   ],
   returns: [
@@ -64,17 +68,20 @@ export const doc = {
     {code: 'ERR_FILE_NOT_FOUND', when: 'the config file does not exist'},
     {
       code: 'ERR_PALETTE_GENERATION',
-      when: 'the request, seed, stop layout, mode, or anchor constraint is invalid',
+      when: 'the config is not valid JSON; the request, seed, stop layout, mode or anchor is invalid; out does not end in .ts or .json; or preview does not end in .html',
     },
     {
       code: 'ERR_PATH_TRAVERSAL',
       when: 'an input or output path escapes cwd, or output would replace input',
     },
-    {code: 'ERR_WRITE_FAILED', when: 'the candidate pair cannot be written'},
+    {
+      code: 'ERR_WRITE_FAILED',
+      when: 'the candidate, receipt or preview file cannot be written',
+    },
   ],
   examples: [
     {
-      label: 'Preview a candidate',
+      label: 'Generate a candidate without writing files',
       code: "themePaletteGenerate('palette.config.json');",
     },
     {
@@ -83,5 +90,5 @@ export const doc = {
     },
   ],
   command: 'theme palette generate',
-  related: ['themeBuild', 'themeTemplate'],
+  related: ['generateTonalPalette', 'themeBuild', 'themeTemplate'],
 };

package/api/theme/themeTargets.doc.mjs

@@ -22,7 +22,7 @@ export const doc = {
     'Same source as the Theming table `astryx component <Name>` prints ' +
     '(the component docs), so the list cannot drift from the components, and `theme build` ' +
     'validates overrides against this exact set. A filter naming a component gives that ' +
-    "component's set; anything else is a substring search over the keys.",
+    "component's set; anything else is a case-insensitive substring search over each target's key, class and component.",
   importPath: '@astryxdesign/cli/api',
   signature:
     'themeTargets(filter?: string, ctx?: {cwd?: string}): Promise<ThemeTargetsResponse>',
@@ -41,13 +41,14 @@ export const doc = {
       name: 'filter',
       type: 'string',
       description:
-        'A component name (exact, case-insensitive) or a substring of a target key. Omit for the whole surface.',
+        'A component name (exact, case-insensitive), or a substring of a target key, class or component. Omit for the whole surface.',
     },
     {
       name: 'ctx.cwd',
       type: 'string',
       description:
         "Directory the project's @astryxdesign/core is resolved from.",
+      default: 'process.cwd()',
     },
   ],
   returns: [

package/api/theme/themeTemplate.doc.mjs

@@ -43,6 +43,7 @@ export const doc = {
       name: 'options.cwd',
       type: 'string',
       description: 'Directory the target path resolves against.',
+      default: 'process.cwd()',
     },
   ],
   returns: [
@@ -64,5 +65,5 @@ export const doc = {
     },
   ],
   command: 'theme template',
-  related: ['themeAdd', 'themeBuild', 'themeList'],
+  related: ['themeAdd', 'themeBuild', 'themeListAvailable', 'themeTargets'],
 };

package/api/upgrade/run/files-changed.test.mjs

@@ -0,0 +1,111 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file The upgrade receipt counts a file once when a core codemod AND an
+ * integration codemod both change it: `filesChanged` is the union of the two
+ * runners' files, while `transformsApplied` adds their changes.
+ *
+ * Uses a real consumer under a repo-local temp dir (Vite blocks dynamic import
+ * of config and integration modules from /tmp), the real core registry, and an
+ * installed integration whose code codemod stamps the same file.
+ */
+
+import {describe, it, expect, afterEach} from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {upgrade} from '../upgrade.mjs';
+import {
+  latestVersion,
+  versions,
+  getTransformsBetween,
+} from '../../../assets/codemods/registry.mjs';
+
+const SLOW = 60_000;
+
+/** The registry version whose manifest ships the authoring migration. */
+async function authoringTier() {
+  const all = await getTransformsBetween('0.0.0', latestVersion);
+  const tier = all.find(({transforms}) =>
+    transforms.some(t => t.name === 'migrate-authoring-imports'),
+  );
+  if (!tier) throw new Error('no registry version ships the authoring migration');
+  return tier.version;
+}
+
+/**
+ * A consumer with installed core at the registry's latest version and one
+ * old-surface file that the core authoring codemods rewrite.
+ * @param {string} dir
+ * @param {{integrationCodemod: boolean}} options
+ */
+function seed(dir, {integrationCodemod}) {
+  fs.writeFileSync(
+    path.join(dir, 'package.json'),
+    JSON.stringify({name: 'consumer', version: '1.0.0'}),
+  );
+  const core = path.join(dir, 'node_modules', '@astryxdesign', 'core');
+  fs.mkdirSync(core, {recursive: true});
+  fs.writeFileSync(
+    path.join(core, 'package.json'),
+    JSON.stringify({name: '@astryxdesign/core', version: latestVersion}),
+  );
+  fs.mkdirSync(path.join(dir, 'src'), {recursive: true});
+  fs.writeFileSync(
+    path.join(dir, 'src', 'Button.doc.mjs'),
+    [
+      "import {createComponentDoc} from '@astryxdesign/core/authoring';",
+      "export default createComponentDoc({name: 'Button', props: []});",
+      '',
+    ].join('\n'),
+  );
+  if (!integrationCodemod) return;
+  fs.writeFileSync(
+    path.join(dir, 'astryx.config.mjs'),
+    "export default {integrations: ['@acme/widgets']};\n",
+  );
+  const pkg = path.join(dir, 'node_modules', '@acme', 'widgets');
+  fs.mkdirSync(path.join(pkg, 'codemods', latestVersion), {recursive: true});
+  fs.writeFileSync(
+    path.join(pkg, 'package.json'),
+    JSON.stringify({name: '@acme/widgets', version: '1.0.0'}),
+  );
+  fs.writeFileSync(
+    path.join(pkg, 'astryx.integration.mjs'),
+    "export default {codemods: './codemods'};\n",
+  );
+  fs.writeFileSync(
+    path.join(pkg, 'codemods', latestVersion, 'acme-stamp.mjs'),
+    "export default {type: 'code', title: 'Stamp', transform: file => (file.source.includes('// acme') ? null : `${file.source}// acme\\n`)};\n",
+  );
+}
+
+describe('upgrade receipt — filesChanged across core and integration codemods', () => {
+  /** @type {string[]} */
+  const dirs = [];
+  afterEach(() => {
+    for (const dir of dirs.splice(0)) fs.rmSync(dir, {recursive: true, force: true});
+  });
+
+  /** @param {{integrationCodemod: boolean}} options */
+  async function run(options) {
+    const dir = fs.mkdtempSync(path.join(process.cwd(), '.astryx-files-changed-'));
+    dirs.push(dir);
+    seed(dir, options);
+    const tier = await authoringTier();
+    const from = versions[versions.indexOf(tier) - 1];
+    const res = await upgrade({from, path: 'src'}, {cwd: dir});
+    expect(res.type).toBe('upgrade.run');
+    return res.data;
+  }
+
+  it('counts a file changed by both a core and an integration codemod once', async () => {
+    const coreOnly = await run({integrationCodemod: false});
+    expect(coreOnly.filesChanged).toBe(1);
+    expect(coreOnly.transformsApplied).toBeGreaterThan(0);
+
+    const both = await run({integrationCodemod: true});
+    expect(both.integrations).toEqual(['@acme/widgets']);
+    expect(both.filesChanged).toBe(1);
+    expect(both.transformsApplied).toBe(coreOnly.transformsApplied + 1);
+  }, SLOW);
+});

package/api/upgrade/run/run.mjs

@@ -437,9 +437,11 @@ export async function run(options = {}, {cwd = process.cwd()} = {}) {
 
   const registryResult = await reconcileCompositions();
 
-  const mergedFilesChanged =
-    (coreResult?.totalFilesChanged ?? 0) +
-    (integrationResult?.totalFilesChanged ?? 0);
+  // A file a core codemod AND an integration codemod both changed is one file.
+  const mergedFilesChanged = new Set([
+    ...(coreResult?.changedFiles ?? []),
+    ...(integrationResult?.changedFiles ?? []),
+  ]).size;
   const mergedTransformsApplied =
     (coreResult?.totalTransformsApplied ?? 0) +
     (integrationResult?.totalTransformsApplied ?? 0);

package/api/upgrade/upgrade.doc.mjs

@@ -13,19 +13,16 @@ export const doc = {
   name: 'upgrade',
   namespace: 'cli/api',
   displayName: 'upgrade()',
-  summary: 'Run version migrations and reconcile copied compositions.',
+  summary:
+    'After bumping @astryxdesign/core, migrate project source with codemods and update copied compositions.',
   description:
-    'Migrates project source from a previous Astryx version to the currently ' +
-    'installed one by running the registered codemods, and compares the fully ' +
-    'rendered managed agent-docs block on every migration path, including ' +
-    'same-Core integration guidance changes; list and registry-only modes do not ' +
-    'run migration reconciliation. Dry-run previews without writing; `apply` ' +
-    'writes the prepared block only after selected codemods and hooks succeed. ' +
-    'Core codemods run before ' +
-    'the config is loaded so a config codemod can repair an otherwise-invalid ' +
-    'astryx.config. Copied compositions carry adjacent receipts with exact canonical and format-specific install bases; upgrade ' +
-    'compares those installed bases with the matching registry release, updates pristine ' +
-    'files, merges non-overlapping edits, and leaves conflicting originals untouched.',
+    'Runs the codemods between `from` and the installed Core version, then refreshes the ' +
+    'managed agent-docs block. Dry-run by default; `apply` writes changes only after the ' +
+    'selected codemods and hooks succeed. Config codemods run before astryx.config is ' +
+    'loaded, so they can repair an invalid config. Also updates copied compositions from ' +
+    'their install receipts: unchanged files are updated, non-overlapping edits are merged, ' +
+    'and conflicts are left untouched. `list` only lists codemods; `registry` only updates ' +
+    'copied compositions.',
   importPath: '@astryxdesign/cli/api',
   signature:
     'upgrade(options?: UpgradeOptions, ctx?: {cwd?: string}): Promise<UpgradeListResponse | UpgradeRegistryResponse | UpgradeStatusResponse | UpgradeRunResponse>',
@@ -42,7 +39,7 @@ export const doc = {
       name: 'options.from',
       type: 'string',
       description:
-        'Version before the dependency bump. Required unless `list` or `registry` is set.',
+        'Version before the dependency bump; the target is the installed @astryxdesign/core (or legacy @xds/core). Required unless `list` or `registry` is set.',
     },
     {
       name: 'options.apply',
@@ -55,11 +52,13 @@ export const doc = {
       type: 'boolean',
       description:
         'Run codemods even when `from` is at/after the installed version.',
+      default: 'false',
     },
     {
       name: 'options.codemod',
       type: 'string',
-      description: 'Run a single named transform instead of the full set.',
+      description:
+        'Run only this codemod. Optional codemods run only when named here. Setting it also skips copied-composition reconciliation.',
     },
     {
       name: 'options.skipCodemod',
@@ -83,23 +82,26 @@ export const doc = {
       type: 'boolean',
       description:
         'Install jscodeshift when it is missing; otherwise a missing jscodeshift throws ERR_DEP_MISSING.',
+      default: 'false',
     },
     {
       name: 'options.registry',
       type: 'boolean',
       description:
-        'Reconcile copied compositions from their install receipts without requiring `from`.',
+        'Only reconcile copied compositions from their install receipts; `from` is not required. Cannot be combined with `list`, `from`, `force`, `codemod`, `skipCodemod`, `integration` or `installDeps`.',
       default: 'false',
     },
     {
       name: 'options.list',
       type: 'boolean',
       description: 'Return the available codemods instead of running any.',
+      default: 'false',
     },
     {
       name: 'ctx.cwd',
       type: 'string',
       description: 'Directory to run the upgrade in.',
+      default: 'process.cwd()',
     },
   ],
   returns: [
@@ -116,36 +118,36 @@ export const doc = {
     {
       type: 'upgrade.status',
       description:
-        'A short-circuit outcome (no codemods executed): `up_to_date` (`from` is at/after the installed target and no `force`), `no_codemods` (none apply to the range), or `config_fixable` (dry-run preview that a pending config codemod would repair an invalid astryx.config). Each carries the agent-docs summary and, when found, the copied-composition registry summary.',
+        'A short-circuit outcome (no codemods executed): `up_to_date` (`from` is at/after the installed target and no `force`), `no_codemods` (none apply to the range), or `config_fixable` (dry-run preview that a pending config codemod would repair an invalid astryx.config). up_to_date and no_codemods carry the agent-docs summary and, when receipts are found, the copied-composition summary; config_fixable carries configError, configCodemods, suggestedCommand, message, note, and the agent-docs summary.',
     },
     {
       type: 'upgrade.run',
       description:
-        '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.',
+        'The terminal run receipt: from, to, codemods (count), integrations, agentDocs, agentDocsRefreshed, registryCompositions (when receipts are found), filesChanged, transformsApplied, modifiedFiles, protectedFiles, declinedCandidates, errors, and complete. When a protected file still requires a change, complete is false and errorCode is ERR_CODEMOD_PROTECTED; the CLI exits nonzero while preserving the structured receipt.',
     },
   ],
   throws: [
     {
       code: 'ERR_INVALID_ARGUMENT',
-      when: '`from` is missing (and neither `list` nor `registry` is set), or the project config fails strict validation and no pending config codemod can repair it',
+      when: '`from` is missing (and neither `list` nor `registry` is set); `list` and `registry` are both set; `registry` is combined with `from`, `force`, `codemod`, `skipCodemod`, `integration` or `installDeps`; an `integration` specifier is invalid or not installed; or astryx.config fails to load or validate and no pending config codemod repairs it',
     },
     {code: 'ERR_INVALID_VERSION', when: '`from` is not a valid semver string'},
     {code: 'ERR_PATH_TRAVERSAL', when: '`path` resolves outside cwd'},
     {
       code: 'ERR_VERSION_DETECT',
-      when: 'the installed @astryxdesign/core version cannot be detected',
+      when: 'neither @astryxdesign/core nor legacy @xds/core is installed in cwd; with `registry`, only when copied-composition receipts exist and @astryxdesign/core is not installed',
     },
     {
       code: 'ERR_DEP_MISSING',
-      when: 'jscodeshift is required but could not be installed',
+      when: 'jscodeshift is missing and `installDeps` is not set, or installing it failed',
     },
     {
       code: 'ERR_UNKNOWN_CODEMOD',
-      when: 'a `codemod` name matches no registered codemod',
+      when: 'the version range has codemods but none remain selected: `codemod` names no codemod in the range, or `skipCodemod` excludes all of them',
     },
     {
       code: 'ERR_CODEMOD_FAILED',
-      when: 'one or more codemods failed, or a post-codemod hook failed',
+      when: 'one or more codemods failed, or a post-codemod hook failed, and no protected file still needs a change (otherwise an upgrade.run receipt with complete: false is returned)',
     },
     {
       code: 'ERR_CODEMOD_PROTECTION_SOURCE',

package/api/upgrade/upgrade.type.mjs

@@ -119,11 +119,11 @@
  * @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 {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] 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 {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.
  */
 

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

@@ -46,7 +46,9 @@ describe('runCodemods — ordered dry-run state', () => {
       silent: true,
     });
 
-    expect(preview.totalFilesChanged).toBe(2);
+    // One file that two transforms changed is one file and two changes.
+    expect(preview.totalFilesChanged).toBe(1);
+    expect(preview.totalTransformsApplied).toBe(2);
     expect(preview.changedFiles).toEqual([
       path.join(srcDir, 'a.ts'),
       path.join(srcDir, 'a.ts'),

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-runner.mjs

@@ -67,7 +67,6 @@ export function runIntegrationCodemods(
   /** 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 = [];
@@ -115,7 +114,6 @@ export function runIntegrationCodemods(
       protection,
       contents: virtualContents,
     });
-    totalFilesChanged += r.filesChanged;
     totalTransformsApplied += r.filesChanged;
     changedFiles.push(...r.changedFiles);
     writtenFiles.push(...r.writtenFiles);
@@ -145,7 +143,6 @@ export function runIntegrationCodemods(
         protection,
         contents: virtualContents,
       });
-      totalFilesChanged += r.filesChanged;
       totalTransformsApplied += r.filesChanged;
       changedFiles.push(...r.changedFiles);
       writtenFiles.push(...r.writtenFiles);
@@ -154,6 +151,9 @@ export function runIntegrationCodemods(
     }
   }
 
+  // A file several codemods changed is one file; transforms count each change.
+  const totalFilesChanged = new Set(changedFiles).size;
+
   return {
     totalFilesChanged,
     totalTransformsApplied,

package/assets/codemods/runner.mjs

@@ -486,7 +486,6 @@ export async function runCodemods(
       (await import('jscodeshift')).default
     );
 
-  let totalFilesChanged = 0;
   let totalTransformsApplied = 0;
   let totalValidationBlocked = 0;
   /** @type {Array<{file: string, codemod: string, error: string}>} */
@@ -554,7 +553,6 @@ export async function runCodemods(
           protectionWriteCount = writtenFiles.length;
         }
         if (result.filesChanged > 0) {
-          totalFilesChanged += result.filesChanged;
           totalTransformsApplied += 1;
         }
         continue;
@@ -577,7 +575,6 @@ export async function runCodemods(
         changedFiles.push(...result.changedFiles);
         writtenFiles.push(...result.writtenFiles);
         if (result.filesChanged > 0) {
-          totalFilesChanged += result.filesChanged;
           totalTransformsApplied += result.filesChanged;
         }
         continue;
@@ -592,7 +589,6 @@ export async function runCodemods(
       protectedFiles.push(...result.protectedFiles);
       changedFiles.push(...result.changedFiles);
       writtenFiles.push(...result.writtenFiles);
-      totalFilesChanged += result.filesChanged;
       totalTransformsApplied += result.filesChanged;
       totalValidationBlocked += result.errors.filter(
         error =>
@@ -630,6 +626,11 @@ export async function runCodemods(
     );
   }
 
+  // A file several codemods changed is one file. `totalTransformsApplied` is
+  // unchanged: a code or config codemod counts each file it changed, and a
+  // project codemod counts once. The two answer different questions.
+  const totalFilesChanged = new Set(changedFiles).size;
+
   if (protectedFiles.length > 0) {
     const files = [...new Set(protectedFiles.map(item => item.file))];
     log.warn(

package/assets/docs/README.md

@@ -21,13 +21,15 @@ Someone building a product with Astryx. Their questions:
 ## Tells that you are writing for us instead
 
 - second person aimed at the wrong reader — "reviewers should…", "before promoting a component…", "attach evidence for…"
-- **rubric, readiness, gate, audit, checklist, sign-off, promotion, evidence** as things the reader must produce
+- an internal rubric, readiness gate, audit checklist, or sign-off that the reader must satisfy for Astryx maintainers
 - a table of things to verify rather than things to use
 - anything about lab → core, which is our lifecycle, not theirs
 - Storybook, Playwright, CI or the Simulator named as tools the reader runs
 
 One subtlety: a statement about the **system's behavior** is caller-facing even when it sounds like process. "A component's theme targets are stable once published" tells a caller what they can rely on; "reviewers must check that theme targets are stable" is ours. Same fact, different reader — **rewrite it rather than move it**.
 
+A public authoring-quality rubric is also caller-facing when it helps someone evaluate an artifact they create through Astryx. It must be complete and actionable from public inputs. It must not include Astryx's internal approval, promotion, evidence-publication, or CI process. A current system spec must assign the shipped guide as the rubric's owner.
+
 ## Where the rest goes
 
 The material is usually good; the finding is placement, not quality. It goes in the [wiki](https://github.com/facebook/astryx/wiki) — **as a section on the page that already covers it, not a new page.** The wiki is at nearly 60 pages, several of them overlapping, because every stray section got its own.
@@ -55,5 +57,5 @@ Worked example: a responsive-and-interaction readiness rubric is grading criteri
 one section by its key. A section's key is its `id`, or a key derived from its
 title when it has none. Give a section an `id` when its title may change, since
 readers and extensions link to the key. Two sections in one topic cannot share
-a key. Keep each section small enough to read on its own: `astryx doctor` fails
+a key. Keep each section small enough to read on its own: `astryx doctor` warns on
 any section over 32 KB.