An open source design system that's fully customizable and agent ready
TypeScript
Protect upgrade codemods from consumer-managed files (#6692)
EJ Hammonde59d786e24c4
diff --git a/.changeset/protect-consumer-codemod-files.md b/.changeset/protect-consumer-codemod-files.mdnew file mode 100644index 0000000000..2ac48a2163--- /dev/null+++ b/.changeset/protect-consumer-codemod-files.md@@ -0,0 +1,7 @@+---+'@astryxdesign/cli': patch+---++[fix] Protect generated, vendored, ignored, linked, dependency, and out-of-root files from upgrade codemods using working-tree declarations. Upgrades now run declared regeneration hooks, recheck protected outputs, and report incomplete changes in human and JSON results.++@ejhammonddiff --git a/packages/cli/README.md b/packages/cli/README.mdindex 2bf71ca7b2..d9f2f9439e 100644--- a/packages/cli/README.md+++ b/packages/cli/README.md@@ -189,6 +189,8 @@ if (isError(result)) {| `ERR_UNKNOWN_FEATURE` | An unrecognized `--features` value was passed to init. || `ERR_UNKNOWN_CODEMOD` | A `--codemod` value did not match any registered codemod (upgrade). || `ERR_CODEMOD_FAILED` | One or more codemods failed during an upgrade run. |+| `ERR_CODEMOD_PROTECTED` | A required codemod change remains blocked by a protected consumer file. |+| `ERR_CODEMOD_PROTECTION_SOURCE` | A working-tree protection declaration could not be read or parsed. || `ERR_NOT_FOUND` | A generic discover/lookup query matched nothing in any package. || `ERR_NO_DOC` | A component exists but has no typed `.doc.mjs` file. || `ERR_NO_SHOWCASE` | No showcase exists for the requested component. |diff --git a/packages/cli/api/upgrade/_adapter.mjs b/packages/cli/api/upgrade/_adapter.mjsindex a063493c5e..abd92ebafe 100644--- a/packages/cli/api/upgrade/_adapter.mjs+++ b/packages/cli/api/upgrade/_adapter.mjs@@ -329,19 +329,20 @@ export async function ensureCodemodDeps({installDeps} = {}) {* Run the CORE registry codemods. Runs BEFORE the config is loaded so a core* CONFIG codemod can repair a config the strict loader would otherwise reject.* @param {CoreVersionManifest[]} versionManifests- * @param {{apply: boolean, path: string, codemod?: string, skipCodemods: Set<string>, root?: string}} options+ * @param {{apply: boolean, path: string, codemod?: string, skipCodemods: Set<string>, root?: string, protection?: {root: string, classify: (file: string) => import('../../foundation/fs/file-protection.mjs').FileProtection[]}, silent?: boolean}} options*/export async function runCoreCodemods(versionManifests,- {apply, path: srcPath, codemod, skipCodemods, root},+ {apply, path: srcPath, codemod, skipCodemods, root, protection, silent},) {return runCodemods(versionManifests, {apply,path: srcPath,codemod,skipCodemods,- silent: logger.silent,+ silent: silent ?? logger.silent,root,+ protection,});}@@ -479,11 +480,20 @@ export async function selectIntegrationCodemodsFor(integrations, from, to) {/*** Run the file-based INTEGRATION codemods (config codemods first, then code).* @param {Array<{version: string, codemods: import('../../authoring/codemod/type').CodemodEntry[]}>} versionGroups- * @param {{apply: boolean, path: string, codemod?: string, skipCodemods: Set<string>}} options+ * @param {{apply: boolean, path: string, codemod?: string, skipCodemods: Set<string>, root?: string, protection?: {root: string, classify: (file: string) => import('../../foundation/fs/file-protection.mjs').FileProtection[]}, contents?: Map<string, string>, silent?: boolean}} options*/export async function runIntegrationCodemodsStep(versionGroups,- {apply, path: srcPath, codemod, skipCodemods},+ {+ apply,+ path: srcPath,+ codemod,+ skipCodemods,+ root,+ protection,+ contents,+ silent,+ },) {const jscodeshift = (await import('jscodeshift')).default;return runIntegrationCodemods(versionGroups, {@@ -492,6 +502,9 @@ export async function runIntegrationCodemodsStep(codemod,skipCodemods,jscodeshift,- silent: logger.silent,+ silent: silent ?? logger.silent,+ root,+ protection,+ contents,});}diff --git a/packages/cli/api/upgrade/run/run.mjs b/packages/cli/api/upgrade/run/run.mjsindex 42dfb60398..4e87d632df 100644--- a/packages/cli/api/upgrade/run/run.mjs+++ b/packages/cli/api/upgrade/run/run.mjs@@ -17,6 +17,7 @@* integration; execution errors abort before the agent-doc write.*/+import * as fs from 'node:fs';import * as path from 'node:path';import {detectInstalledTargetVersion,@@ -47,7 +48,58 @@ import {getCliInvocation} from '../../../foundation/env/package-manager.mjs';import {ERROR_CODES} from '../../../foundation/response/error-codes.mjs';import {AstryxError} from '../../error.mjs';import {logger} from '../../logger.mjs';-import {assertWithin, PathSafetyError} from '../../../foundation/fs/path-safety.mjs';+import {+ assertWithin,+ PathSafetyError,+} from '../../../foundation/fs/path-safety.mjs';+import {createFileProtectionResolver} from '../../../foundation/fs/file-protection.mjs';++/**+ * Collapse per-codemod protection hits into one stable row per file.+ * @param {Array<{file: string, codemod: string, reason: string, declaration: string, generated: boolean, command?: string}>} rows+ */+function summarizeProtectedFiles(rows) {+ const byFile = new Map();+ for (const row of rows) {+ const current = byFile.get(row.file) ?? {+ file: row.file,+ codemods: new Set(),+ reasons: new Set(),+ declarations: new Set(),+ commands: new Set(),+ };+ current.codemods.add(row.codemod);+ current.reasons.add(row.reason);+ current.declarations.add(row.declaration);+ if (row.command) current.commands.add(row.command);+ byFile.set(row.file, current);+ }+ return [...byFile.values()]+ .map(item => ({+ file: item.file,+ codemods: [...item.codemods].sort(),+ reasons: [...item.reasons].sort(),+ declarations: [...item.declarations].sort(),+ commands: [...item.commands].sort(),+ }))+ .sort((a, b) => a.file.localeCompare(b.file));+}++/** @param {string} cwd */+function loadFileProtection(cwd) {+ try {+ return createFileProtectionResolver(cwd);+ } catch (err) {+ const message = err instanceof Error ? err.message : String(err);+ logger.error(message);+ logger.log('Upgrade failed\n');+ throw new AstryxError(+ message,+ undefined,+ ERROR_CODES.ERR_CODEMOD_PROTECTION_SOURCE,+ );+ }+}/*** Run the upgrade pipeline for a validated, non-list invocation. Returns the@@ -75,7 +127,11 @@ export async function run(options = {}, {cwd = process.cwd()} = {}) {if (err instanceof PathSafetyError) {logger.error(err.message);logger.log('Aborted\n');- throw new AstryxError(err.message, undefined, ERROR_CODES.ERR_PATH_TRAVERSAL);+ throw new AstryxError(+ err.message,+ undefined,+ ERROR_CODES.ERR_PATH_TRAVERSAL,+ );}throw err;}@@ -133,7 +189,10 @@ export async function run(options = {}, {cwd = process.cwd()} = {}) {});}- const versionManifests = await getCoreVersionManifests(currentVersion, targetVersion);+ const versionManifests = await getCoreVersionManifests(+ currentVersion,+ targetVersion,+ );const coreConfigCodemodNames = [];for (const {transforms} of versionManifests) {@@ -157,6 +216,11 @@ export async function run(options = {}, {cwd = process.cwd()} = {}) {}}+ // Read and parse all working-tree protection declarations before any+ // dependency installation or codemod write. Core and integration runners+ // share this exact snapshot.+ let protection = loadFileProtection(cwd);+const ready = await ensureCodemodDeps({installDeps: options.installDeps});if (!ready) {const msg = 'jscodeshift is required but could not be installed.';@@ -172,34 +236,81 @@ export async function run(options = {}, {cwd = process.cwd()} = {}) {codemod: options.codemod,skipCodemods,root: cwd,+ protection,});- const coreResult = codemodResult && 'totalFilesChanged' in codemodResult ? codemodResult : null;+ const coreResult =+ codemodResult && 'totalFilesChanged' in codemodResult+ ? codemodResult+ : null;/** @type {Array<import('../../../foundation/integrations/integrations.mjs').LoadedIntegration>} */let integrations;/** @type {import('../../../authoring/config/type').PostCodemodHook[]} */let postCodemodHooks;try {- const projectContext = await loadProjectContext(cwd, options.integration ?? []);+ const projectContext = await loadProjectContext(+ cwd,+ options.integration ?? [],+ );postCodemodHooks = projectContext.postCodemodHooks;integrations = projectContext.integrations;} catch (err) {const configErr = /** @type {Error} */ (err);+ const allProtected = coreResult?.protectedFiles ?? [];+ if (allProtected.length > 0) {+ const protectedFiles = summarizeProtectedFiles(allProtected);+ logger.error(+ `${ERROR_CODES.ERR_CODEMOD_PROTECTED}: protected codemod changes remain while loading the Astryx config.`,+ );+ for (const item of protectedFiles) {+ logger.error(` ${item.file} — ${item.declarations.join('; ')}`);+ }+ logger.log('Upgrade incomplete: protected changes remain\n');+ return {+ type: 'upgrade.run',+ data: {+ from: currentVersion,+ to: targetVersion,+ codemods: totalTransforms,+ integrations: [],+ agentDocsRefreshed: false,+ agentDocs: {+ status: 'current',+ installedVersion: targetVersion,+ fromVersions: [],+ files: [],+ refreshed: false,+ action: 'none',+ },+ filesChanged: coreResult?.totalFilesChanged ?? 0,+ transformsApplied: coreResult?.totalTransformsApplied ?? 0,+ modifiedFiles: uniqueFiles(coreResult?.changedFiles).map(file =>+ path.relative(cwd, file).split(path.sep).join('/'),+ ),+ protectedFiles,+ declinedCandidates: [],+ complete: false,+ errorCode: 'ERR_CODEMOD_PROTECTED',+ errors: coreResult?.errors ?? [],+ },+ };+ }// Graceful dry-run catch: a config that fails strict validation is expected// & fixable ONLY when dry-run AND a pending core config codemod previewed a// change (the codemod that would repair it).- const codemodWouldFixConfig = hasCoreConfigCodemod && (coreResult?.totalFilesChanged ?? 0) > 0;+ const codemodWouldFixConfig =+ hasCoreConfigCodemod && (coreResult?.totalFilesChanged ?? 0) > 0;if (!apply && codemodWouldFixConfig) {// Lightweight inspection — no config/Project load (config is still broken// in dry-run; the codemod previewed a fix but did not write it).const inspection = inspectAgentDocs(cwd, targetVersion);- return statusConfigFixable(- {- from: currentVersion,- to: targetVersion,- configError: configErr.message,- configCodemods: coreConfigCodemodNames,- agentDocs: /** @type {import('../upgrade.type.mjs').AgentDocsSummary} */ ({+ return statusConfigFixable({+ from: currentVersion,+ to: targetVersion,+ configError: configErr.message,+ configCodemods: coreConfigCodemodNames,+ agentDocs:+ /** @type {import('../upgrade.type.mjs').AgentDocsSummary} */ ({status: inspection.status,installedVersion: targetVersion,fromVersions: inspection.blockVersions,@@ -207,17 +318,22 @@ export async function run(options = {}, {cwd = process.cwd()} = {}) {refreshed: false,action: inspection.status === 'missing' ? 'nudge-init' : 'none',}),- },- );+ });}// Genuine config error: abort.logger.error(configErr.message);logger.log('Aborted\n');- throw new AstryxError(configErr.message, undefined, ERROR_CODES.ERR_INVALID_ARGUMENT);+ throw new AstryxError(+ configErr.message,+ undefined,+ ERROR_CODES.ERR_INVALID_ARGUMENT,+ );}if (integrations.length > 0) {- logger.log(`Integrations: ${integrations.map(i => i.name ?? i.__spec).join(', ')}`);+ logger.log(+ `Integrations: ${integrations.map(i => i.name ?? i.__spec).join(', ')}`,+ );}// Non-blocking nudge for integration validation issues (suppressed for@@ -229,7 +345,9 @@ export async function run(options = {}, {cwd = process.cwd()} = {}) {currentVersion,targetVersion,);- const hasIntegrationCodemods = integrationVersionGroups.some(g => g.codemods.length > 0);+ const hasIntegrationCodemods = integrationVersionGroups.some(+ g => g.codemods.length > 0,+ );for (const {codemods} of integrationVersionGroups) {for (const c of codemods) {@@ -267,14 +385,14 @@ export async function run(options = {}, {cwd = process.cwd()} = {}) {}if (totalTransforms > 0) {- logger.log(`${totalTransforms} codemod${totalTransforms === 1 ? '' : 's'} to run${apply ? '' : ' (dry run)'}`);+ logger.log(+ `${totalTransforms} codemod${totalTransforms === 1 ? '' : 's'} to run${apply ? '' : ' (dry run)'}`,+ );} else {logger.log('No automatic codemods to run for this version range.');}- /**- * @type {{from: string, to: string, codemods: number, integrations: string[], agentDocsRefreshed: boolean, agentDocs: import('../upgrade.type.mjs').AgentDocsSummary, registryCompositions?: import('../upgrade.type.mjs').RegistryCompositionSummary, filesChanged?: number, transformsApplied?: number, errors?: Array<{file: string, codemod: string, error: string}>}}- */+ /** @type {import('../upgrade.type.mjs').UpgradeRunResponse['data']} */const receipt = {from: currentVersion,to: targetVersion,@@ -282,79 +400,257 @@ export async function run(options = {}, {cwd = process.cwd()} = {}) {integrations: integrations.map(i => i.name ?? i.__spec),agentDocsRefreshed: false,agentDocs: /** @type {import('../upgrade.type.mjs').AgentDocsSummary} */ ({- status: 'current', installedVersion: targetVersion,- fromVersions: [], files: [], refreshed: false, action: 'none',+ status: 'current',+ installedVersion: targetVersion,+ fromVersions: [],+ files: [],+ refreshed: false,+ action: 'none',}),};let integrationResult = null;if (hasIntegrationCodemods) {+ const coreStagedContents = coreResult?.stagedContents;+ if (+ (coreResult?.writtenFiles.length ?? 0) > 0 ||+ (coreStagedContents?.size ?? 0) > 0+ ) {+ protection = createFileProtectionResolver(cwd, {+ overrides: coreStagedContents,+ });+ }logger.log('Applying integration codemods...');- integrationResult = await runIntegrationCodemodsStep(integrationVersionGroups, {- apply,- path: path_,- codemod: options.codemod,- skipCodemods,- });+ integrationResult = await runIntegrationCodemodsStep(+ integrationVersionGroups,+ {+ apply,+ path: path_,+ codemod: options.codemod,+ skipCodemods,+ root: cwd,+ protection,+ contents: coreStagedContents,+ },+ );}const registryResult = await reconcileCompositions();- const mergedFilesChanged = (coreResult?.totalFilesChanged ?? 0) + (integrationResult?.totalFilesChanged ?? 0);- const mergedTransformsApplied = (coreResult?.totalTransformsApplied ?? 0) + (integrationResult?.totalTransformsApplied ?? 0);- const mergedWrittenFiles = [- ...(coreResult?.writtenFiles ?? []),- ...(integrationResult?.writtenFiles ?? []),+ const mergedFilesChanged =+ (coreResult?.totalFilesChanged ?? 0) ++ (integrationResult?.totalFilesChanged ?? 0);+ const mergedTransformsApplied =+ (coreResult?.totalTransformsApplied ?? 0) ++ (integrationResult?.totalTransformsApplied ?? 0);+ const mergedChangedFiles = [+ ...(coreResult?.changedFiles ?? []),+ ...(integrationResult?.changedFiles ?? []),...(registryResult?.writtenFiles ?? []),];- const mergedErrors = [...(coreResult?.errors ?? []), ...(integrationResult?.errors ?? [])];+ const mergedErrors = [+ ...(coreResult?.errors ?? []),+ ...(integrationResult?.errors ?? []),+ ];+ let finalErrors = mergedErrors;+ /** @type {string|undefined} */+ let hookFailure;+ const initialProtected = [+ ...(coreResult?.protectedFiles ?? []),+ ...(integrationResult?.protectedFiles ?? []),+ ];const registryFilesChanged = registryResult?.writtenFiles.length ?? 0;+ const generatedChangeBlocked = initialProtected.some(item => item.generated);+ const shouldRunHooks =+ postCodemodHooks.length > 0 &&+ (mergedFilesChanged > 0 ||+ registryFilesChanged > 0 ||+ generatedChangeBlocked);+ /** @type {Map<string, Buffer>} */+ const protectedBeforeHooks = new Map();+ if (apply && shouldRunHooks) {+ for (const item of initialProtected) {+ const absolute = path.resolve(cwd, item.file);+ const relative = path.relative(cwd, absolute);+ if (+ relative.startsWith(`..${path.sep}`) ||+ relative === '..' ||+ path.isAbsolute(relative)+ )+ continue;+ try {+ if (fs.lstatSync(absolute).isFile()) {+ protectedBeforeHooks.set(absolute, fs.readFileSync(absolute));+ }+ } catch {+ // A candidate can disappear between planning and regeneration.+ }+ }+ }+ /** @type {string[]} */+ const hookModifiedFiles = [];- if (postCodemodHooks.length > 0 && (mergedFilesChanged > 0 || registryFilesChanged > 0)) {- const files = uniqueFiles(mergedWrittenFiles).map(file => path.relative(cwd, file));+ if (shouldRunHooks) {+ const files = uniqueFiles(mergedChangedFiles).map(file =>+ path.relative(cwd, file),+ );try {- await runPostCodemodHooks(postCodemodHooks, {packageDir: cwd, files, apply: apply || false});+ await runPostCodemodHooks(postCodemodHooks, {+ packageDir: cwd,+ files,+ apply: apply || false,+ });} catch (err) {const hookErr = /** @type {Error} */ (err);const msg = `Post-codemod hook failed: ${hookErr.message}`;logger.error(msg);- logger.log('Upgrade failed\n');- throw new AstryxError(msg, undefined, ERROR_CODES.ERR_CODEMOD_FAILED);+ if (initialProtected.length === 0) {+ logger.log('Upgrade failed\n');+ throw new AstryxError(msg, undefined, ERROR_CODES.ERR_CODEMOD_FAILED);+ }+ hookFailure = msg;+ finalErrors = [+ ...mergedErrors,+ {file: '.', codemod: 'post-codemod-hook', error: msg},+ ];+ logger.log('Regeneration failed; protected changes remain\n');+ }+ if (apply) {+ for (const [file, before] of protectedBeforeHooks) {+ try {+ if (!before.equals(fs.readFileSync(file)))+ hookModifiedFiles.push(file);+ } catch {+ hookModifiedFiles.push(file);+ }+ }}}+ // A successful apply hook may have regenerated protected outputs. Rerun the+ // selected codemods in preview mode against fresh bytes and fresh declarations+ // to distinguish resolved outputs from changes that remain blocked.+ let remainingProtected = initialProtected;+ if (apply && shouldRunHooks && !hookFailure) {+ const refreshedProtection = loadFileProtection(cwd);+ const coreCheck = await runCoreCodemods(versionManifests, {+ apply: false,+ path: path_,+ codemod: options.codemod,+ skipCodemods,+ root: cwd,+ protection: refreshedProtection,+ silent: true,+ });+ const checkedCore =+ coreCheck && 'totalFilesChanged' in coreCheck ? coreCheck : null;+ const recheckProtection =+ (checkedCore?.stagedContents.size ?? 0) > 0+ ? createFileProtectionResolver(cwd, {+ overrides: checkedCore?.stagedContents,+ })+ : refreshedProtection;+ const integrationCheck = hasIntegrationCodemods+ ? await runIntegrationCodemodsStep(integrationVersionGroups, {+ apply: false,+ path: path_,+ codemod: options.codemod,+ skipCodemods,+ root: cwd,+ protection: recheckProtection,+ contents: checkedCore?.stagedContents,+ silent: true,+ })+ : null;+ const recheckedProtected = [+ ...(checkedCore?.protectedFiles ?? []),+ ...(integrationCheck?.protectedFiles ?? []),+ ];+ const recheckedChangedFiles = [+ ...(checkedCore?.changedFiles ?? []),+ ...(integrationCheck?.changedFiles ?? []),+ ].map(file => path.relative(cwd, file).split(path.sep).join('/'));+ const initialByFile = new Map();+ for (const item of initialProtected) {+ const rows = initialByFile.get(item.file) ?? [];+ rows.push(item);+ initialByFile.set(item.file, rows);+ }+ // A hook that removes a protection marker without regenerating the bytes+ // does not make the required change disappear. Retain the original+ // declaration for that still-pending file.+ for (const file of recheckedChangedFiles) {+ recheckedProtected.push(...(initialByFile.get(file) ?? []));+ }+ remainingProtected = recheckedProtected;+ finalErrors = [+ ...mergedErrors,+ ...(checkedCore?.errors ?? []),+ ...(integrationCheck?.errors ?? []),+ ];+ }++ const protectedFiles = summarizeProtectedFiles(remainingProtected);receipt.filesChanged = mergedFilesChanged;receipt.transformsApplied = mergedTransformsApplied;- receipt.errors = mergedErrors;+ receipt.modifiedFiles = uniqueFiles([+ ...mergedChangedFiles,+ ...hookModifiedFiles,+ ]).map(file => path.relative(cwd, file).split(path.sep).join('/'));+ receipt.protectedFiles = protectedFiles;+ receipt.declinedCandidates = [];+ receipt.complete = protectedFiles.length === 0;+ if (!receipt.complete) {+ receipt.errorCode = 'ERR_CODEMOD_PROTECTED';+ }+ receipt.errors = finalErrors;if (registryResult) receipt.registryCompositions = registryResult.summary;- if (receipt.errors?.length > 0) {+ if (protectedFiles.length > 0) {+ logger.error(+ `${ERROR_CODES.ERR_CODEMOD_PROTECTED}: ${protectedFiles.length} protected file${protectedFiles.length === 1 ? '' : 's'} still require${protectedFiles.length === 1 ? 's' : ''} a codemod change:`,+ );+ for (const item of protectedFiles) {+ logger.error(` ${item.file} — ${item.declarations.join('; ')}`);+ for (const command of item.commands) {+ logger.log(` Regenerate with: ${command}`);+ }+ }+ }++ if (receipt.errors?.length > 0 && protectedFiles.length === 0) {const msg = `Upgrade completed with ${receipt.errors.length} codemod error${receipt.errors.length === 1 ? '' : 's'}.`;logger.log('Upgrade failed\n');throw new AstryxError(msg, undefined, ERROR_CODES.ERR_CODEMOD_FAILED);}- // All codemods + hooks succeeded — render from final post-upgrade state.- const agentDocsPlan = await prepareAgentDocsRefresh({- cwd,- installedVersion: targetVersion,- apply,- fresh: true,- });- const completedAgentDocs = apply- ? applyAgentDocsRefresh(agentDocsPlan)- : agentDocsPlan.summary;- receipt.agentDocs = completedAgentDocs;- receipt.agentDocsRefreshed = completedAgentDocs.refreshed;+ // Only refresh managed docs after all required codemod changes are complete.+ if (protectedFiles.length === 0) {+ const agentDocsPlan = await prepareAgentDocsRefresh({+ cwd,+ installedVersion: targetVersion,+ apply,+ fresh: true,+ });+ const completedAgentDocs = apply+ ? applyAgentDocsRefresh(agentDocsPlan)+ : agentDocsPlan.summary;+ receipt.agentDocs = completedAgentDocs;+ receipt.agentDocsRefreshed = completedAgentDocs.refreshed;+ }const registryOk = receipt.registryCompositions?.ok ?? true;logger.log(- registryOk- ? (apply ? 'Upgrade complete' : 'Dry run complete') + '\n'- : 'Upgrade finished with unresolved registry items\n',+ protectedFiles.length > 0+ ? 'Upgrade incomplete: protected changes remain\n'+ : registryOk+ ? (apply ? 'Upgrade complete' : 'Dry run complete') + '\n'+ : 'Upgrade finished with unresolved registry items\n',);return {type: 'upgrade.run',- data: /** @type {import('../upgrade.type.mjs').UpgradeRunResponse['data']} */ (/** @type {unknown} */ (receipt)),+ data: /** @type {import('../upgrade.type.mjs').UpgradeRunResponse['data']} */ (+ /** @type {unknown} */ (receipt)+ ),};}diff --git a/packages/cli/api/upgrade/upgrade.doc.mjs b/packages/cli/api/upgrade/upgrade.doc.mjsindex e38cc96023..16e0bef762 100644--- a/packages/cli/api/upgrade/upgrade.doc.mjs+++ b/packages/cli/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: [{diff --git a/packages/cli/api/upgrade/upgrade.type.mjs b/packages/cli/api/upgrade/upgrade.type.mjsindex b7df3df6e5..23bbe2c5ef 100644--- a/packages/cli/api/upgrade/upgrade.type.mjs+++ b/packages/cli/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.*/diff --git a/packages/cli/assets/codemods/__tests__/runner.test.mjs b/packages/cli/assets/codemods/__tests__/runner.test.mjsindex b9da59698c..72e2a28c1f 100644--- a/packages/cli/assets/codemods/__tests__/runner.test.mjs+++ b/packages/cli/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 untouchedexpect(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');});});diff --git a/packages/cli/assets/codemods/integration-runner.mjs b/packages/cli/assets/codemods/integration-runner.mjsindex 21ec09f744..ae4313345e 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 {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,};diff --git a/packages/cli/assets/codemods/integration-runner.protection.test.mjs b/packages/cli/assets/codemods/integration-runner.protection.test.mjsnew file mode 100644index 0000000000..ffaba2c743--- /dev/null+++ b/packages/cli/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',+ }),+ ]);+ });+});diff --git a/packages/cli/assets/codemods/run-codemod.mjs b/packages/cli/assets/codemods/run-codemod.mjsindex 4bd65eeb36..71c4b209bb 100644--- a/packages/cli/assets/codemods/run-codemod.mjs+++ b/packages/cli/assets/codemods/run-codemod.mjs@@ -31,7 +31,12 @@ import * as fs from 'node:fs';import * as path from 'node:path';import * as p from './term-log.mjs';import {findConfigPath} from '../../foundation/config/project.mjs';-import {fixDirectiveCorruption, validateOutput, IGNORED_DIRS} from './runner.mjs';+import {+ fixDirectiveCorruption,+ validateOutput,+ isIgnoredDirectory,+} from './runner.mjs';+import {createFileProtectionResolver} from '../../foundation/fs/file-protection.mjs';export const DEFAULT_CODE_EXTENSIONS = ['.tsx',@@ -43,6 +48,41 @@ export const DEFAULT_CODE_EXTENSIONS = [];const PARSEABLE_EXTENSIONS = ['.tsx', '.ts', '.jsx', '.js', '.mjs', '.cjs'];+/**+ * @typedef {{file: string, codemod: string, reason: string, declaration: string, generated: boolean, command?: string}} ProtectedFile+ */++/**+ * Convert every effective protection declaration into the stable codemod result+ * shape. A file can carry more than one additive declaration.+ * @param {string} filePath+ * @param {string} name+ * @param {{root: string, classify: (file: string) => import('../../foundation/fs/file-protection.mjs').FileProtection[]}} protection+ * @returns {ProtectedFile[]}+ */+function protectedResult(filePath, name, protection) {+ return protection.classify(filePath).map(item => ({+ file: item.file,+ codemod: name,+ reason: item.reason,+ declaration: item.declaration,+ generated: item.reason === 'generated',+ ...(item.command ? {command: item.command} : {}),+ }));+}++/**+ * Print one blocked candidate without implying that the protected bytes changed.+ * @param {import('../../authoring/codemod/type').CliLog} log+ * @param {ProtectedFile[]} protections+ */+function logProtected(log, protections) {+ const [first] = protections;+ log.warn(+ ` ! ${first.file} — protected by ${protections.map(item => item.declaration).join('; ')}`,+ );+}+/*** Recursively find candidate source files in a directory.* @param {string} dir@@ -51,8 +91,17 @@ const PARSEABLE_EXTENSIONS = ['.tsx', '.ts', '.jsx', '.js', '.mjs', '.cjs'];export function findSourceFiles(dir) {/** @type {string[]} */const results = [];- /** @param {string} currentDir */- function walk(currentDir) {+ /** @param {string} currentDir @param {Set<string>} [ancestors] */+ function walk(currentDir, ancestors = new Set()) {+ let realDirectory;+ try {+ realDirectory = fs.realpathSync(currentDir);+ } catch {+ return;+ }+ if (ancestors.has(realDirectory)) return;+ const nextAncestors = new Set(ancestors);+ nextAncestors.add(realDirectory);let entries;try {entries = fs.readdirSync(currentDir, {withFileTypes: true});@@ -61,12 +110,21 @@ export function findSourceFiles(dir) {}for (const entry of entries) {const fullPath = path.join(currentDir, entry.name);- // Never follow symlinks — writing through one would rewrite its target- // outside the scan tree (e.g. into node_modules or anywhere on disk).- if (entry.isSymbolicLink()) continue;+ // Symlinked files and descendants remain read-only candidates so a+ // required change can be reported. Real-path ancestors prevent cycles.+ if (entry.isSymbolicLink()) {+ try {+ const target = fs.statSync(fullPath);+ if (target.isFile()) results.push(fullPath);+ else if (target.isDirectory()) walk(fullPath, nextAncestors);+ } catch {+ // Broken links have no source bytes to evaluate.+ }+ continue;+ }if (entry.isDirectory()) {- if (IGNORED_DIRS.has(entry.name)) continue;- walk(fullPath);+ if (isIgnoredDirectory(dir, fullPath, entry.name)) continue;+ walk(fullPath, nextAncestors);} else {results.push(fullPath);}@@ -91,37 +149,45 @@ export function makeLog(silent) {* Apply a config codemod to the consumer's astryx.config.* file.** @param {import('../../authoring/codemod/type').CodemodEntry} entry normalized codemod entry {id, codemod, package}- * @param {{apply: boolean, log: import('../../authoring/codemod/type').CliLog, jscodeshift: import('../../authoring/codemod/type').JscodeshiftFactory}} ctx+ * @param {{apply: boolean, log: import('../../authoring/codemod/type').CliLog, jscodeshift: import('../../authoring/codemod/type').JscodeshiftFactory, root?: string, protection: {root: string, classify: (file: string) => import('../../foundation/fs/file-protection.mjs').FileProtection[]}, contents?: Map<string, string>}} ctx* @returns {import('../../authoring/codemod/type').CodemodRunResult}*/-export function runConfigCodemod(entry, {apply, log, jscodeshift}) {+export function runConfigCodemod(+ entry,+ {apply, log, jscodeshift, root = process.cwd(), protection, contents},+) {const {codemod, id, package: pkg} = entry;const name = `${pkg}:${id}`;- // findConfigPath throws when multiple astryx.config.* files coexist. Config- // codemods run FIRST (before the strict project loader), so an uncaught throw- // here aborts the entire `astryx upgrade` with an un-coded error — breaking- // the per-codemod isolation every other failure path honors. Degrade it to a- // structured error so the run continues and reports it.+ const resolver = protection ?? createFileProtectionResolver(root);let configPath;try {- configPath = findConfigPath(process.cwd());+ configPath = findConfigPath(root);} catch (err) {const message = /** @type {any} */ (err).message;log.error(` ✗ astryx.config.* — ${message}`);return {filesChanged: 0,+ changedFiles: [],writtenFiles: [],+ protectedFiles: [],errors: [{file: 'astryx.config.*', codemod: name, error: message}],};}if (!configPath) {log.info(` ${codemod.title} — no astryx.config.* found; skipping.`);- return {filesChanged: 0, writtenFiles: [], errors: []};+ return {+ filesChanged: 0,+ changedFiles: [],+ writtenFiles: [],+ protectedFiles: [],+ errors: [],+ };}- const relativePath = path.relative(process.cwd(), configPath);+ const relativePath = path.relative(root, configPath);try {- const source = fs.readFileSync(configPath, 'utf-8');+ const source =+ contents?.get(configPath) ?? fs.readFileSync(configPath, 'utf-8');const ext = path.extname(configPath);const parser = ext === '.tsx' || ext === '.ts' ? 'tsx' : 'babel';const j = jscodeshift.withParser(parser);@@ -129,7 +195,13 @@ export function runConfigCodemod(entry, {apply, log, jscodeshift}) {let result = codemod.transform({source, path: configPath}, api);if (result == null || result === source) {- return {filesChanged: 0, writtenFiles: [], errors: []};+ return {+ filesChanged: 0,+ changedFiles: [],+ writtenFiles: [],+ protectedFiles: [],+ errors: [],+ };}result = fixDirectiveCorruption(result);@@ -140,11 +212,26 @@ export function runConfigCodemod(entry, {apply, log, jscodeshift}) {log.error(` ✗ ${relativePath} — ${validation.reason}`);return {filesChanged: 0,+ changedFiles: [],writtenFiles: [],+ protectedFiles: [],errors: [{file: relativePath, codemod: name, error: validation.reason}],};}+ const protectedFiles = protectedResult(configPath, name, resolver);+ if (protectedFiles.length > 0) {+ logProtected(log, protectedFiles);+ return {+ filesChanged: 0,+ changedFiles: [],+ writtenFiles: [],+ protectedFiles,+ errors: [],+ };+ }++ contents?.set(configPath, result);if (apply) {fs.writeFileSync(configPath, result, 'utf-8');log.success(` ✓ ${relativePath}`);@@ -153,7 +240,9 @@ export function runConfigCodemod(entry, {apply, log, jscodeshift}) {}return {filesChanged: 1,+ changedFiles: [configPath],writtenFiles: apply ? [configPath] : [],+ protectedFiles: [],errors: [],};} catch (err) {@@ -161,7 +250,9 @@ export function runConfigCodemod(entry, {apply, log, jscodeshift}) {log.error(` ✗ ${relativePath} — ${message}`);return {filesChanged: 0,+ changedFiles: [],writtenFiles: [],+ protectedFiles: [],errors: [{file: relativePath, codemod: name, error: message}],};}@@ -172,27 +263,41 @@ export function runConfigCodemod(entry, {apply, log, jscodeshift}) {** @param {import('../../authoring/codemod/type').CodemodEntry} entry normalized codemod entry {id, codemod, package}* @param {string[]} files- * @param {{apply: boolean, log: import('../../authoring/codemod/type').CliLog, jscodeshift: import('../../authoring/codemod/type').JscodeshiftFactory}} ctx+ * @param {{apply: boolean, log: import('../../authoring/codemod/type').CliLog, jscodeshift: import('../../authoring/codemod/type').JscodeshiftFactory, root?: string, protection: {root: string, classify: (file: string) => import('../../foundation/fs/file-protection.mjs').FileProtection[]}, contents?: Map<string, string>}} ctx* @returns {import('../../authoring/codemod/type').CodemodRunResult}*/-export function runCodeCodemod(entry, files, {apply, log, jscodeshift}) {+export function runCodeCodemod(+ entry,+ files,+ {apply, log, jscodeshift, root = process.cwd(), protection, contents},+) {const {codemod, id, package: pkg} = entry;const name = `${pkg}:${id}`;+ const resolver = protection ?? createFileProtectionResolver(root);const extensions = new Set(codemod.fileExtensions ?? DEFAULT_CODE_EXTENSIONS);let filesChanged = 0;/** @type {string[]} */+ const changedFiles = [];+ /** @type {string[]} */const writtenFiles = [];+ /** @type {ProtectedFile[]} */+ const protectedFiles = [];/** @type {Array<{file: string, codemod: string, error: string}>} */const errors = [];+ /** @type {Array<{filePath: string, relativePath: string, result: string}>} */+ const candidates = [];+ // Transform and validate every candidate before any write. This lets a+ // protection source changed by this entry govern every other staged output.for (const filePath of files) {const ext = path.extname(filePath);if (!extensions.has(ext)) continue;- const relativePath = path.relative(process.cwd(), filePath);+ const relativePath = path.relative(root, filePath);try {- const source = fs.readFileSync(filePath, 'utf-8');+ const source =+ 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: () => {}};@@ -213,15 +318,7 @@ export function runCodeCodemod(entry, files, {apply, log, jscodeshift}) {});continue;}-- filesChanged++;- if (apply) {- fs.writeFileSync(filePath, result, 'utf-8');- writtenFiles.push(filePath);- log.success(` ✓ ${relativePath}`);- } else {- log.warn(` ~ ${relativePath} (would change)`);- }+ candidates.push({filePath, relativePath, result});} catch (err) {const message = /** @type {any} */ (err).message;log.error(` ✗ ${relativePath} — ${message}`);@@ -229,5 +326,51 @@ export function runCodeCodemod(entry, files, {apply, log, jscodeshift}) {}}- return {filesChanged, writtenFiles, errors};+ /** @type {Map<string, ProtectedFile[]>} */+ const currentProtections = new Map();+ /** @type {Map<string, string|null>} */+ const stagedContents = new Map(contents ?? []);+ for (const candidate of candidates) {+ const blocked = protectedResult(candidate.filePath, name, resolver);+ currentProtections.set(candidate.filePath, blocked);+ if (blocked.length === 0) {+ stagedContents.set(candidate.filePath, candidate.result);+ }+ }+ const stagedResolver = createFileProtectionResolver(root, {+ overrides: stagedContents,+ });++ for (const candidate of candidates) {+ const blocked = [+ ...(currentProtections.get(candidate.filePath) ?? []),+ ...protectedResult(candidate.filePath, name, stagedResolver),+ ].filter(+ (item, index, all) =>+ all.findIndex(+ candidateItem =>+ candidateItem.file === item.file &&+ candidateItem.reason === item.reason &&+ candidateItem.declaration === item.declaration,+ ) === index,+ );+ if (blocked.length > 0) {+ protectedFiles.push(...blocked);+ logProtected(log, blocked);+ continue;+ }++ filesChanged++;+ changedFiles.push(candidate.filePath);+ contents?.set(candidate.filePath, candidate.result);+ if (apply) {+ fs.writeFileSync(candidate.filePath, candidate.result, 'utf-8');+ writtenFiles.push(candidate.filePath);+ log.success(` ✓ ${candidate.relativePath}`);+ } else {+ log.warn(` ~ ${candidate.relativePath} (would change)`);+ }+ }++ return {filesChanged, changedFiles, writtenFiles, protectedFiles, errors};}diff --git a/packages/cli/assets/codemods/runner.mjs b/packages/cli/assets/codemods/runner.mjsindex 0e27d78c20..7a827c8e41 100644--- a/packages/cli/assets/codemods/runner.mjs+++ b/packages/cli/assets/codemods/runner.mjs@@ -12,7 +12,8 @@ import * as fs from 'node:fs';import * as path from 'node:path';import * as p from './term-log.mjs';import {humanLog} from '../../foundation/response/json.mjs';-import {runConfigCodemod} from './run-codemod.mjs';+import {runCodeCodemod, runConfigCodemod} from './run-codemod.mjs';+import {createFileProtectionResolver} from '../../foundation/fs/file-protection.mjs';// Known corruption patterns that indicate a broken transform.// Each entry: [regex, human-readable description]@@ -46,20 +47,30 @@ export function fixDirectiveCorruption(code) {}/**- * Directories a source scan must never descend into: dependencies, VCS, and- * generated build output (codemods rewrite source, not artifacts).+ * Directories a source scan must never descend into. Generated-looking names+ * are intentionally absent: protection comes from checkout declarations, not a+ * directory-name heuristic.*/const IGNORED_DIRS = new Set(['node_modules',+ 'bower_components',+ 'jspm_packages','.git',- 'dist',- 'build',- 'out',- '.next',- 'coverage',+ '.hg',+ '.sl',]);export {IGNORED_DIRS};+/** @param {string} root @param {string} fullPath @param {string} name */+export function isIgnoredDirectory(root, fullPath, name) {+ if (IGNORED_DIRS.has(name)) return true;+ const parts = path.relative(root, fullPath).split(path.sep);+ return (+ parts[0] === '.yarn' &&+ ['__virtual__', 'cache', 'sdks', 'unplugged'].includes(parts[1])+ );+}+/*** Recursively find all source files in a directory.* @param {string} dir@@ -81,8 +92,17 @@ function findSourceFiles(dir) {'.less',]);- /** @param {string} currentDir */- function walk(currentDir) {+ /** @param {string} currentDir @param {Set<string>} [ancestors] */+ function walk(currentDir, ancestors = new Set()) {+ let realDirectory;+ try {+ realDirectory = fs.realpathSync(currentDir);+ } catch {+ return;+ }+ if (ancestors.has(realDirectory)) return;+ const nextAncestors = new Set(ancestors);+ nextAncestors.add(realDirectory);let entries;try {entries = fs.readdirSync(currentDir, {withFileTypes: true});@@ -91,16 +111,27 @@ function findSourceFiles(dir) {}for (const entry of entries) {const fullPath = path.join(currentDir, entry.name);- // Never follow symlinks: readFileSync/writeFileSync would traverse a- // symlinked file and rewrite its target OUTSIDE the scan tree (e.g. into- // node_modules or anywhere on disk). A codemod must only edit real files- // it reaches directly under the scanned path.- if (entry.isSymbolicLink()) continue;+ // Symlinked files and descendants remain read-only candidates so a+ // required change can be reported. Real-path ancestors prevent cycles.+ if (entry.isSymbolicLink()) {+ try {+ const target = fs.statSync(fullPath);+ if (target.isFile() && extensions.has(path.extname(entry.name))) {+ results.push(fullPath);+ } else if (target.isDirectory()) {+ walk(fullPath, nextAncestors);+ }+ } catch {+ // Broken links have no source bytes to evaluate.+ }+ continue;+ }if (entry.isDirectory()) {- // Skip dependency, VCS, and generated-output dirs — codemods rewrite- // source, not build artifacts.- if (IGNORED_DIRS.has(entry.name)) continue;- walk(fullPath);+ // Only hard boundaries are skipped by name. Generated and vendored+ // content is discovered, transformed in memory, and classified by the+ // shared protection resolver so required changes can be reported.+ if (isIgnoredDirectory(dir, fullPath, entry.name)) continue;+ walk(fullPath, nextAncestors);} else if (extensions.has(path.extname(entry.name))) {results.push(fullPath);}@@ -213,10 +244,13 @@ function toUnifiedEntry(transformEntry, version) {* the file contract.** @param {{name: string, transform: unknown}} transformEntry- * @param {{apply: boolean, root: string, log: {success: (m: string) => void, warn: (m: string) => void, error: (m: string) => void}}} options- * @returns {Promise<{filesChanged: number, writtenFiles: string[], errors: Array<{file: string, codemod: string, error: string}>}>}+ * @param {{apply: boolean, root: string, protection: {root: string, classify: (file: string) => import('../../foundation/fs/file-protection.mjs').FileProtection[]}, log: {success: (m: string) => void, warn: (m: string) => void, error: (m: string) => void}}} options+ * @returns {Promise<import('../../authoring/codemod/type').CodemodRunResult & {stagedOverrides?: Map<string, string|null>}>}*/-async function runProjectCodemod({name, transform}, {apply, root, log}) {+async function runProjectCodemod(+ {name, transform},+ {apply, root, protection, log},+) {/** @param {string} file */const rel = file => path.relative(root, file).split(path.sep).join('/');/** @type {ProjectCodemodPlan} */@@ -230,7 +264,9 @@ async function runProjectCodemod({name, transform}, {apply, root, log}) {log.error(` ✗ ${message}`);return {filesChanged: 0,+ changedFiles: [],writtenFiles: [],+ protectedFiles: [],errors: [{file: '.', codemod: name, error: message}],};}@@ -240,7 +276,9 @@ async function runProjectCodemod({name, transform}, {apply, root, log}) {}return {filesChanged: 0,+ changedFiles: [],writtenFiles: [],+ protectedFiles: [],errors: plan.problems.map(({file, message}) => ({file,codemod: name,@@ -248,9 +286,93 @@ async function runProjectCodemod({name, transform}, {apply, root, log}) {})),};}++ const candidates = [+ ...plan.writes.map(write => ({+ file: write.path,+ existing: fs.existsSync(write.path),+ })),+ ...plan.deletes.map(file => ({file, existing: true})),+ ];+ /** @param {{file: string, existing: boolean}} candidate */+ const currentDeclarations = candidate =>+ protection+ .classify(candidate.file)+ .filter(+ item =>+ candidate.existing ||+ ['outside-root', 'dependency', 'vcs', 'symlink'].includes(+ item.reason,+ ),+ );+ const currentlyBlocked = new Set(+ candidates+ .filter(candidate => currentDeclarations(candidate).length > 0)+ .map(candidate => candidate.file),+ );+ /** @type {Map<string, string|null>} */+ const stagedOverrides = new Map();+ for (const write of plan.writes) {+ if (!currentlyBlocked.has(write.path)) {+ stagedOverrides.set(write.path, write.contents);+ }+ }+ for (const file of plan.deletes) {+ if (!currentlyBlocked.has(file)) stagedOverrides.set(file, null);+ }+ // A plan cannot introduce a protection declaration and then overwrite the+ // file it protects in the same transaction. Only declarations whose own+ // writes are allowed participate in the staged view.+ const stagedProtection = createFileProtectionResolver(root, {+ overrides: stagedOverrides,+ });+ /** @type {import('../../authoring/codemod/type').CodemodRunResult['protectedFiles']} */+ const protectedFiles = [];+ const blocked = new Set();+ for (const candidate of candidates) {+ const file = candidate.file;+ const declarations = [+ ...currentDeclarations(candidate),+ ...stagedProtection.classify(file),+ ]+ .filter(+ item =>+ candidate.existing ||+ ['outside-root', 'dependency', 'vcs', 'symlink'].includes(+ item.reason,+ ),+ )+ .filter(+ (item, index, all) =>+ all.findIndex(+ candidate =>+ candidate.file === item.file &&+ candidate.reason === item.reason &&+ candidate.declaration === item.declaration,+ ) === index,+ );+ if (declarations.length === 0) continue;+ blocked.add(file);+ const rows = declarations.map(item => ({+ file: item.file,+ codemod: name,+ reason: item.reason,+ declaration: item.declaration,+ generated: item.reason === 'generated',+ ...(item.command ? {command: item.command} : {}),+ }));+ protectedFiles.push(...rows);+ log.warn(+ ` ! ${rel(file)} — protected by ${rows.map(item => item.declaration).join('; ')}`,+ );+ }++ const writes = plan.writes.filter(write => !blocked.has(write.path));+ const deletes = plan.deletes.filter(file => !blocked.has(file));+ const changedFiles = [...writes.map(write => write.path), ...deletes];/** @type {string[]} */const writtenFiles = [];- for (const write of plan.writes) {+ for (const write of writes) {if (apply) {fs.mkdirSync(path.dirname(write.path), {recursive: true});fs.writeFileSync(write.path, write.contents, 'utf-8');@@ -261,7 +383,7 @@ async function runProjectCodemod({name, transform}, {apply, root, log}) {}}// Deletions go last, so a failed write leaves a state a rerun completes.- for (const file of plan.deletes) {+ for (const file of deletes) {if (apply) {fs.rmSync(file);writtenFiles.push(file);@@ -270,9 +392,16 @@ async function runProjectCodemod({name, transform}, {apply, root, log}) {log.warn(` ~ ${rel(file)} (would remove)`);}}+ /** @type {Map<string, string|null>} */+ const appliedOverrides = new Map();+ for (const write of writes) appliedOverrides.set(write.path, write.contents);+ for (const file of deletes) appliedOverrides.set(file, null);return {- filesChanged: plan.writes.length + plan.deletes.length,+ filesChanged: changedFiles.length,+ changedFiles,writtenFiles,+ protectedFiles,+ stagedOverrides: appliedOverrides,errors: [],};}@@ -288,7 +417,8 @@ async function runProjectCodemod({name, transform}, {apply, root, log}) {* @param {Set<string>} [options.skipCodemods] - Transform names to exclude* @param {boolean} [options.silent] - Suppress all human-facing output (for --json)* @param {string} [options.root] - Project root a project codemod reads (default: the process cwd)- * @returns {Promise<{totalFilesChanged: number, totalTransformsApplied: number, totalValidationBlocked: number, writtenFiles: string[], 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}>}+ * @param {{root: string, classify: (file: string) => import('../../foundation/fs/file-protection.mjs').FileProtection[]}} [options.protection] - Preloaded protection resolver+ * @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}>}*/export async function runCodemods(versionManifests,@@ -299,6 +429,7 @@ export async function runCodemods(skipCodemods,silent = false,root = process.cwd(),+ protection: providedProtection,},) {// No-op stub object so silent mode skips log output entirely without@@ -311,6 +442,13 @@ export async function runCodemods(};const resolvedPath = path.resolve(srcPath);+ // Eager construction is the fail-closed barrier: every working-tree+ // declaration is read and parsed before the first codemod can write.+ let protection =+ providedProtection ?? createFileProtectionResolver(path.resolve(root));+ /** @type {Map<string, string|null>} */+ const protectionOverrides = new Map();+ let protectionWriteCount = 0;// Config and project codemods never read the files under --path, so a// missing --path should not block them. Only hard-fail on a missing source@@ -353,8 +491,14 @@ export async function runCodemods(let totalValidationBlocked = 0;/** @type {Array<{file: string, codemod: string, error: string}>} */const errors = [];+ /** In-memory pipeline state keeps ordered dry-runs equivalent to apply. */+ const virtualContents = new Map();+ /** @type {string[]} */+ const changedFiles = [];/** @type {string[]} */const writtenFiles = [];+ /** @type {import('../../authoring/codemod/type').CodemodRunResult['protectedFiles']} */+ const protectedFiles = [];/** @type {Array<{name: string, meta: {title: string, description?: string, fileExtensions?: string[], codemodType?: string}, version: string}>} */const skippedOptional = [];for (const {version, transforms} of versionManifests) {@@ -366,10 +510,7 @@ export async function runCodemods(// Exclude explicitly skipped codemods (by transform name).if (skipCodemods?.has(transformEntry.name)) continue;- const {name, transform, meta, optional} = transformEntry;- const transformExtensions = new Set(- meta.fileExtensions ?? ['.tsx', '.ts', '.jsx', '.js', '.mjs', '.cjs'],- );+ const {name, meta, optional} = transformEntry;// Skip optional codemods unless explicitly requested via --codemodif (optional && !codemod) {@@ -377,6 +518,13 @@ export async function runCodemods(continue;}+ if (apply && writtenFiles.length !== protectionWriteCount) {+ protection = createFileProtectionResolver(path.resolve(root), {+ overrides: protectionOverrides,+ });+ protectionWriteCount = writtenFiles.length;+ }+log.info(` ${meta.title}`);// Config codemods are routed through the SAME shared runner that@@ -388,102 +536,74 @@ export async function runCodemods(const result = await runProjectCodemod(transformEntry, {apply,root,+ protection,log,});- if (result.errors.length > 0) {- errors.push(...result.errors);- } else if (result.filesChanged > 0) {+ errors.push(...result.errors);+ protectedFiles.push(...result.protectedFiles);+ changedFiles.push(...result.changedFiles);+ writtenFiles.push(...result.writtenFiles);+ if (result.stagedOverrides) {+ for (const [file, contents] of result.stagedOverrides) {+ protectionOverrides.set(file, contents);+ if (contents !== null) virtualContents.set(file, contents);+ }+ protection = createFileProtectionResolver(path.resolve(root), {+ overrides: protectionOverrides,+ });+ protectionWriteCount = writtenFiles.length;+ }+ if (result.filesChanged > 0) {totalFilesChanged += result.filesChanged;totalTransformsApplied += 1;- writtenFiles.push(...result.writtenFiles);}continue;}if (meta?.codemodType === 'config') {- const result = runConfigCodemod(toUnifiedEntry(transformEntry, version), {- apply,- log,- jscodeshift,- });- if (result.errors.length > 0) {- errors.push(...result.errors);- } else if (result.filesChanged > 0) {+ const result = runConfigCodemod(+ toUnifiedEntry(transformEntry, version),+ {+ apply,+ log,+ jscodeshift,+ root,+ protection,+ contents: virtualContents,+ },+ );+ errors.push(...result.errors);+ protectedFiles.push(...result.protectedFiles);+ changedFiles.push(...result.changedFiles);+ writtenFiles.push(...result.writtenFiles);+ if (result.filesChanged > 0) {totalFilesChanged += result.filesChanged;totalTransformsApplied += result.filesChanged;- writtenFiles.push(...result.writtenFiles);}continue;}- let filesChanged = 0;-- for (const filePath of files) {- const relativePath = path.relative(process.cwd(), filePath);-- try {- const ext = path.extname(filePath);- if (!transformExtensions.has(ext)) {- continue;- }-- const source = fs.readFileSync(filePath, 'utf-8');- // Configure parser based on file extension- const parser = ext === '.tsx' || ext === '.ts' ? 'tsx' : 'babel';- const j = jscodeshift.withParser(parser);- const api = {- jscodeshift: j,- stats: () => {},- report: () => {},- };- const file = {source, path: filePath};-- let result = transform(file, api);-- if (result != null && result !== source) {- // Fix known jscodeshift output corruption before validation- result = fixDirectiveCorruption(result);-- // Validate output before writing- const validation = validateOutput(result, source, j, {- parse: ['.tsx', '.ts', '.jsx', '.js', '.mjs', '.cjs'].includes(- ext,- ),- });- if (!validation.valid) {- totalValidationBlocked++;- log.error(` ✗ ${relativePath} — ${validation.reason}`);- errors.push({- file: relativePath,- codemod: name,- error: validation.reason,- });- continue;- }-- filesChanged++;- totalFilesChanged++;- totalTransformsApplied++;-- if (apply) {- fs.writeFileSync(filePath, result, 'utf-8');- writtenFiles.push(filePath);- log.success(` ✓ ${relativePath}`);- } else {- log.warn(` ~ ${relativePath} (would change)`);- }- }- } catch (err) {- const message = /** @type {any} */ (err).message;- log.error(` ✗ ${relativePath} — ${message}`);- errors.push({file: relativePath, codemod: name, error: message});- }- }-- if (filesChanged > 0) {+ const result = runCodeCodemod(+ toUnifiedEntry(transformEntry, version),+ files,+ {apply, log, jscodeshift, root, protection, contents: virtualContents},+ );+ errors.push(...result.errors);+ protectedFiles.push(...result.protectedFiles);+ changedFiles.push(...result.changedFiles);+ writtenFiles.push(...result.writtenFiles);+ totalFilesChanged += result.filesChanged;+ totalTransformsApplied += result.filesChanged;+ totalValidationBlocked += result.errors.filter(+ error =>+ error.error.startsWith('transform produced unparseable output') ||+ error.error.startsWith('detected corruption:'),+ ).length;++ if (result.filesChanged > 0) {const verb = apply ? 'Updated' : 'Would update';log.info(- ` ${verb} ${filesChanged} file${filesChanged === 1 ? '' : 's'}`,+ ` ${verb} ${result.filesChanged} file${result.filesChanged === 1 ? '' : 's'}`,);}}@@ -510,8 +630,23 @@ export async function runCodemods();}- if (totalFilesChanged === 0 && errors.length === 0) {+ if (protectedFiles.length > 0) {+ const files = [...new Set(protectedFiles.map(item => item.file))];+ log.warn(+ `${files.length} protected file${files.length === 1 ? '' : 's'} require${files.length === 1 ? 's' : ''} regeneration or manual review.`,+ );+ }++ if (+ totalFilesChanged === 0 &&+ errors.length === 0 &&+ protectedFiles.length === 0+ ) {log.success('No changes needed — your code is already up to date!');+ } else if (apply && protectedFiles.length > 0) {+ log.warn(+ `Applied ${totalTransformsApplied} owned change${totalTransformsApplied === 1 ? '' : 's'} across ${totalFilesChanged} file${totalFilesChanged === 1 ? '' : 's'}; protected changes remain.`,+ );} else if (apply) {log.success(`Done! Applied ${totalTransformsApplied} change${totalTransformsApplied === 1 ? '' : 's'} across ${totalFilesChanged} file${totalFilesChanged === 1 ? '' : 's'}.`,@@ -548,7 +683,10 @@ export async function runCodemods(totalFilesChanged,totalTransformsApplied,totalValidationBlocked,+ changedFiles,writtenFiles,+ protectedFiles,+ stagedContents: virtualContents,errors,skippedOptional,};diff --git a/packages/cli/assets/docs/cli-integrations.doc.mjs b/packages/cli/assets/docs/cli-integrations.doc.mjsindex 6d319489b1..76d1c52e17 100644--- a/packages/cli/assets/docs/cli-integrations.doc.mjs+++ b/packages/cli/assets/docs/cli-integrations.doc.mjs@@ -330,6 +330,19 @@ export const docs = {lang: 'bash',code: '# Preview what would change (dry-run, the default)\nastryx upgrade --from 0.1.0\n\n# Apply the migration\nastryx upgrade --from 0.1.0 --apply',},+ {+ type: 'prose',+ text: 'Core and integration upgrade codemods do not edit existing consumer files that the working tree protects. Protection is VCS-neutral: Astryx reads nested `.gitattributes` rules for `linguist-generated` and `linguist-vendored`, leading `@generated` and `@partially-generated` comments, standard `Code generated … DO NOT EDIT.` comments, `.gitignore`, and `.hgignore` directly from disk. Later attribute rules, explicit false or unset values, and ignore negation keep their normal semantics. Installed dependencies, VCS metadata, paths outside the project, and symbolic links are also protected. Directory or file names such as `dist` and `generated` are not evidence by themselves.',+ },+ {+ type: 'prose',+ text: 'A protected file is transformed only in memory. If it would change, the upgrade applies eligible owned-source edits, runs `hooks.postCodemod` regeneration, and checks the protected file again. A remaining change makes the run incomplete and exits nonzero with `ERR_CODEMOD_PROTECTED`; JSON output lists `modifiedFiles` and `protectedFiles` with every effective declaration. Generated headers may include `Command: <exact command>` so the result can tell a consumer how to regenerate when no hook resolves the output. Dry-run uses the same classification without writing.',+ },+ {+ type: 'code',+ lang: 'text',+ code: '# .gitattributes\ngenerated/** linguist-generated=true\nvendor/** linguist-vendored=true\n\n# A later rule can explicitly return an authored file to normal handling\ngenerated/hand-authored.ts linguist-generated=false',+ },{type: 'prose',text: 'All authoring types are exported from `@astryxdesign/cli/authoring`: `ComponentDoc`, `HookDoc`, and `ReferenceDoc` for docs, `TemplateDoc` for templates, and `AstryxConfig`, `AstryxIntegration`, and `AstryxCodemod` for the project files. Consumers can also run their own post-codemod hooks, such as a reinstall or rebuild, via `hooks.postCodemod` in their `astryx.config`.',diff --git a/packages/cli/authoring/codemod/type.ts b/packages/cli/authoring/codemod/type.tsindex 9da04dde55..a947a817f6 100644--- a/packages/cli/authoring/codemod/type.ts+++ b/packages/cli/authoring/codemod/type.ts@@ -128,7 +128,19 @@ export interface CodemodEntry {/** The result of running a single codemod over one or more files. */export interface CodemodRunResult {filesChanged: number;+ /** Existing owned files changed or previewed by this codemod. */+ changedFiles: string[];+ /** Files actually written; empty during a dry run. */writtenFiles: string[];+ /** Existing files that require the change but are protected. */+ protectedFiles: Array<{+ file: string;+ codemod: string;+ reason: string;+ declaration: string;+ generated: boolean;+ command?: 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 1c42c9b623..94b695fb89 100644--- a/packages/cli/clients/cli/commands/upgrade.doc.mjs+++ b/packages/cli/clients/cli/commands/upgrade.doc.mjs@@ -101,13 +101,14 @@ export const doc = {{label: 'Apply a migration', cli: 'astryx upgrade --from 0.1.0 --apply'},],exitCodes: [- {code: 0, when: 'success (including dry-run previews)'},+ {code: 0, when: 'success, including complete dry-run previews'},{code: 1,when:'missing or invalid --from, --registry with --list or a migration flag, a --path escape, ' +'no installed @astryxdesign/core (or legacy @xds/core), jscodeshift missing and not installed by --install-deps, ' +'an astryx.config that fails validation and that no pending config codemod repairs, ' ++ 'an unreadable or invalid protection declaration, a protected file that still requires a codemod change, ' +'an unknown codemod, a codemod or post-codemod hook failure, or unresolved registry items',},],diff --git a/packages/cli/clients/cli/commands/upgrade.file-protection.test.mjs b/packages/cli/clients/cli/commands/upgrade.file-protection.test.mjsnew file mode 100644index 0000000000..401bc298c5--- /dev/null+++ b/packages/cli/clients/cli/commands/upgrade.file-protection.test.mjs@@ -0,0 +1,228 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file End-to-end protection and regeneration behavior for `astryx upgrade`.+ */++import {afterEach, beforeEach, describe, expect, it} from 'vitest';+import {spawnSync} from 'node:child_process';+import * as fs from 'node:fs';+import * as os from 'node:os';+import * as path from 'node:path';+import {fileURLToPath} from 'node:url';++const CLI = path.resolve(+ path.dirname(fileURLToPath(import.meta.url)),+ '..',+ 'bin',+ 'astryx.mjs',+);+let root;++function write(relative, contents) {+ const file = path.join(root, relative);+ fs.mkdirSync(path.dirname(file), {recursive: true});+ fs.writeFileSync(file, contents);+ return file;+}++function run(args) {+ const result = spawnSync(+ process.execPath,+ [CLI, '--json', 'upgrade', ...args],+ {+ cwd: root,+ encoding: 'utf8',+ timeout: 60_000,+ env: {...process.env, FORCE_COLOR: '0', CI: ''},+ },+ );+ return {...result, envelope: JSON.parse(result.stdout)};+}++function seed({hook = false} = {}) {+ write('package.json', JSON.stringify({name: 'consumer', private: true}));+ write(+ 'node_modules/@astryxdesign/core/package.json',+ JSON.stringify({name: '@astryxdesign/core', version: '0.6.0'}),+ );+ write('.gitattributes', 'generated/** linguist-generated=true\n');+ const source =+ "import {useResizable} from '@astryxdesign/core';\n" ++ 'export const usePanel = () => useResizable({minSizePx: 200});\n';+ write('src/owned.tsx', source);+ write('generated/panel.tsx', `// @generated\n${source}`);+ write(+ 'astryx.config.mjs',+ hook+ ? `export default {hooks: {postCodemod: [{name: 'regenerate', buildCommand: () => ({command: process.execPath, args: ['-e', ${JSON.stringify("const fs=require('node:fs');const p='generated/panel.tsx';const s=fs.readFileSync(p,'utf8');fs.writeFileSync(p,s.replaceAll('minSizePx','minSize')); ")} ]})}]}};\n`+ : 'export default {};\n',+ );+}++beforeEach(() => {+ root = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-protected-upgrade-'));+});++afterEach(() => {+ fs.rmSync(root, {recursive: true, force: true});+});++const ARGS = [+ '--from',+ '0.5.0',+ '--codemod',+ 'rename-resizable-pixel-bounds',+ '--path',+ '.',+];++describe('upgrade protected-file contract', () => {+ it('reports the same protected candidate in dry-run and apply while retaining owned edits', () => {+ seed();++ const dry = run(ARGS);+ expect(dry.status).toBe(1);+ expect(dry.envelope).toMatchObject({+ type: 'upgrade.run',+ data: {+ complete: false,+ errorCode: 'ERR_CODEMOD_PROTECTED',+ modifiedFiles: ['src/owned.tsx'],+ protectedFiles: [+ {+ file: 'generated/panel.tsx',+ reasons: ['generated'],+ declarations: expect.arrayContaining([+ 'linguist-generated in .gitattributes:1',+ '@generated in the leading comment block',+ ]),+ },+ ],+ },+ });+ expect(fs.readFileSync(path.join(root, 'src/owned.tsx'), 'utf8')).toContain(+ 'minSizePx',+ );++ const applied = run([...ARGS, '--apply']);+ expect(applied.status).toBe(1);+ expect(applied.envelope.data.protectedFiles).toEqual(+ dry.envelope.data.protectedFiles,+ );+ expect(fs.readFileSync(path.join(root, 'src/owned.tsx'), 'utf8')).toContain(+ 'minSize: 200',+ );+ expect(+ fs.readFileSync(path.join(root, 'generated/panel.tsx'), 'utf8'),+ ).toContain('minSizePx');+ });++ it('preserves a protected config migration when strict config loading fails', () => {+ write('package.json', JSON.stringify({name: 'consumer', private: true}));+ write(+ 'node_modules/@astryxdesign/core/package.json',+ JSON.stringify({name: '@astryxdesign/core', version: '0.1.3'}),+ );+ write(+ 'astryx.config.mjs',+ `// @generated\nexport default {layout: {components: {KpiCard: '@/KpiCard'}}};\n`,+ );+ write('src/index.ts', 'export {};\n');++ const result = run([+ '--from',+ '0.1.2',+ '--codemod',+ 'migrate-layout-components-to-experimental',+ '--path',+ 'src',+ '--apply',+ ]);++ expect(result.status).toBe(1);+ expect(result.envelope).toMatchObject({+ type: 'upgrade.run',+ data: {+ complete: false,+ errorCode: 'ERR_CODEMOD_PROTECTED',+ protectedFiles: [expect.objectContaining({file: 'astryx.config.mjs'})],+ },+ });+ expect(+ fs.readFileSync(path.join(root, 'astryx.config.mjs'), 'utf8'),+ ).toContain('layout');+ });++ it('fails before writes when a protection declaration cannot be parsed', () => {+ seed();+ write('.hgignore', 'syntax: regexp\n[bad\n');++ const result = run([...ARGS, '--apply']);++ expect(result.status).toBe(1);+ expect(result.envelope).toMatchObject({+ code: 'ERR_CODEMOD_PROTECTION_SOURCE',+ });+ expect(result.envelope.error).toContain('.hgignore');+ expect(fs.readFileSync(path.join(root, 'src/owned.tsx'), 'utf8')).toContain(+ 'minSizePx',+ );+ });++ it('preserves protected-file facts when regeneration fails', () => {+ seed();+ write(+ 'astryx.config.mjs',+ `export default {hooks: {postCodemod: [{name: 'regenerate', buildCommand: () => ({command: process.execPath, args: ['-e', 'process.exit(7)']})}]}};\n`,+ );++ const applied = run([...ARGS, '--apply']);++ expect(applied.status).toBe(1);+ expect(applied.envelope).toMatchObject({+ type: 'upgrade.run',+ data: {+ complete: false,+ errorCode: 'ERR_CODEMOD_PROTECTED',+ protectedFiles: [+ expect.objectContaining({file: 'generated/panel.tsx'}),+ ],+ errors: [+ expect.objectContaining({+ codemod: 'post-codemod-hook',+ error: expect.stringContaining('Post-codemod hook failed'),+ }),+ ],+ },+ });+ });++ it('runs declared regeneration and clears a generated-file block after reevaluation', () => {+ seed({hook: true});++ 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', 'generated/panel.tsx'],+ protectedFiles: [],+ declinedCandidates: [],+ },+ });+ expect(fs.readFileSync(path.join(root, 'src/owned.tsx'), 'utf8')).toContain(+ 'minSize: 200',+ );+ expect(+ fs.readFileSync(path.join(root, 'generated/panel.tsx'), 'utf8'),+ ).toContain('minSize: 200');++ const second = run([...ARGS, '--apply']);+ expect(second.status, second.stderr).toBe(0);+ expect(second.envelope.data.complete).toBe(true);+ expect(second.envelope.data.filesChanged).toBe(0);+ });+});diff --git a/packages/cli/clients/cli/commands/upgrade.mjs b/packages/cli/clients/cli/commands/upgrade.mjsindex accdcd0cdb..1eb53376a7 100644--- a/packages/cli/clients/cli/commands/upgrade.mjs+++ b/packages/cli/clients/cli/commands/upgrade.mjs@@ -65,6 +65,9 @@ export function registerUpgrade(program) {? result.data.registryCompositions: undefined;if (registrySummary && !registrySummary.ok) process.exitCode = 1;+ if (result.type === 'upgrade.run' && result.data.complete === false) {+ process.exitCode = 1;+ }// `--list` is the one lookup here: which migrations exist for the// range. Everything else migrates the project — an effect, reported bydiff --git a/packages/cli/foundation/fs/file-protection.mjs b/packages/cli/foundation/fs/file-protection.mjsnew file mode 100644index 0000000000..739e79d331--- /dev/null+++ b/packages/cli/foundation/fs/file-protection.mjs@@ -0,0 +1,825 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file VCS-neutral protection for existing consumer files.+ *+ * Reads declarations from the working tree only. No Git, Sapling, or Mercurial+ * process is invoked, so the same checkout bytes produce the same answer in+ * every supported environment.+ */++import * as fs from 'node:fs';+import * as path from 'node:path';+import ignore from 'ignore';++const DEPENDENCY_DIRS = new Set([+ 'node_modules',+ 'bower_components',+ 'jspm_packages',+]);+const YARN_DEPENDENCY_DIRS = new Set([+ '__virtual__',+ 'cache',+ 'sdks',+ 'unplugged',+]);+const YARN_DEPENDENCY_FILES = new Set(['install-state.gz']);+const VCS_DIRS = new Set(['.git', '.hg', '.sl']);+const PROTECTION_FILES = new Set(['.gitattributes', '.gitignore', '.hgignore']);++/** A stable failure raised before any consumer write. */+export class ProtectionSourceError extends Error {+ /** @param {string} source @param {string} reason */+ constructor(source, reason) {+ super(`Could not read file-protection source ${source}: ${reason}`);+ this.name = 'ProtectionSourceError';+ this.code = 'ERR_CODEMOD_PROTECTION_SOURCE';+ this.source = source;+ }+}++/** @param {string} value */+function slash(value) {+ return value.split(path.sep).join('/');+}++/** @param {string} candidate @param {string} root */+function relativeWithin(candidate, root) {+ const relative = path.relative(root, candidate);+ if (+ relative === '' ||+ (!relative.startsWith(`..${path.sep}`) &&+ relative !== '..' &&+ !path.isAbsolute(relative))+ ) {+ return slash(relative);+ }+ return null;+}++/**+ * Translate the path globs used by attributes and Mercurial into a RegExp.+ * `*` and `?` never cross a path separator; `**` does.+ * @param {string} pattern+ * @param {{basename?: boolean}} [options]+ */+function globRegex(pattern, {basename = false} = {}) {+ let out = basename ? '(?:^|/)' : '^';+ let i = 0;+ while (i < pattern.length) {+ const c = pattern[i];+ if (c === '*') {+ if (pattern[i + 1] === '*') {+ while (pattern[i + 1] === '*') i++;+ if (pattern[i + 1] === '/') {+ i++;+ out += '(?:.*/)?';+ } else {+ out += '.*';+ }+ } else {+ out += '[^/]*';+ }+ } else if (c === '?') {+ out += '[^/]';+ } else if (c === '[') {+ const end = pattern.indexOf(']', i + 1);+ if (end === -1) throw new Error('unterminated character class');+ let cls = pattern.slice(i + 1, end);+ if (cls.startsWith('!')) cls = `^${cls.slice(1)}`;+ out += `[${cls.replace(/\\/g, '\\\\')}]`;+ i = end;+ } else if (c === '\\' && i + 1 < pattern.length) {+ i++;+ out += pattern[i].replace(/[.*+?^${}()|[\]\\]/g, '\\$&');+ } else {+ out += c.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');+ }+ i++;+ }+ out += '$';+ return new RegExp(out);+}++/** @param {string} line */+function splitAttributeLine(line) {+ /** @type {string[]} */+ const tokens = [];+ let token = '';+ let escaped = false;+ let quoted = false;+ const text = line.trim();+ for (let index = 0; index < text.length; index++) {+ const c = text[index];+ if (escaped) {+ const octal = quoted ? /^[0-7]{1,3}/.exec(text.slice(index)) : null;+ if (octal) {+ token += String.fromCodePoint(Number.parseInt(octal[0], 8));+ index += octal[0].length - 1;+ } else if (quoted) {+ token += c === 'n' ? '\n' : c === 't' ? '\t' : c === 'r' ? '\r' : c;+ } else {+ // Keep pattern escapes so globRegex can distinguish a literal wildcard+ // from a wildcard. Escaped whitespace is only tokenization syntax.+ token += /\s/.test(c) ? c : `\\${c}`;+ }+ escaped = false;+ } else if (c === '\\') {+ escaped = true;+ } else if (c === '"') {+ quoted = !quoted;+ } else if (/\s/.test(c) && !quoted) {+ if (token) {+ tokens.push(token);+ token = '';+ }+ } else {+ token += c;+ }+ }+ if (escaped) token += '\\';+ if (quoted) throw new Error('unterminated quoted pattern');+ if (token) tokens.push(token);+ return tokens;+}++/**+ * @param {string[]} tokens+ * @param {Map<string, Map<string, boolean|null>>} macros+ */+function parseAttributeAssignments(tokens, macros) {+ /** @type {Map<string, boolean|null>} */+ const attributes = new Map();+ for (const token of tokens) {+ const macro = macros.get(token);+ if (macro) {+ for (const [name, value] of macro) attributes.set(name, value);+ continue;+ }+ const decorated = token.startsWith('-') || token.startsWith('!');+ const decoratedName = decorated ? token.slice(1) : token;+ if (token.startsWith('-')) attributes.set(decoratedName, false);+ else if (token.startsWith('!')) attributes.set(decoratedName, null);+ else {+ const equals = token.indexOf('=');+ const name = equals === -1 ? token : token.slice(0, equals);+ const value = equals === -1 ? 'true' : token.slice(equals + 1);+ attributes.set(name, value.toLowerCase() !== 'false');+ }+ }+ return attributes;+}++/**+ * @param {string} source+ * @param {string} contents+ * @param {Map<string, Map<string, boolean|null>>} macros+ * @param {boolean} topLevel+ * @returns {Array<{pattern: RegExp, attributes: Map<string, boolean|null>, line: number}>}+ */+function parseAttributes(source, contents, macros, topLevel) {+ const rules = [];+ const lines = contents.split(/\r?\n/);+ if (topLevel) {+ /** @type {Map<string, {tokens: string[], line: number}>} */+ const definitions = new Map();+ for (let index = 0; index < lines.length; index++) {+ const raw = lines[index].trim();+ if (!raw || raw.startsWith('#')) continue;+ let tokens;+ try {+ tokens = splitAttributeLine(raw);+ } catch (error) {+ throw new ProtectionSourceError(+ source,+ `invalid rule on line ${index + 1}: ${error instanceof Error ? error.message : String(error)}`,+ );+ }+ const pattern = tokens.shift();+ if (!pattern?.startsWith('[attr]')) continue;+ const name = pattern.slice('[attr]'.length);+ if (!name || tokens.length === 0) {+ throw new ProtectionSourceError(+ source,+ `invalid attribute macro on line ${index + 1}`,+ );+ }+ definitions.set(name, {tokens, line: index + 1});+ }+ const resolving = new Set();+ /** @param {string} name */+ const resolveMacro = name => {+ if (macros.has(name)) return macros.get(name);+ const definition = definitions.get(name);+ if (!definition) return undefined;+ if (resolving.has(name)) {+ throw new ProtectionSourceError(+ source,+ `cyclic attribute macro on line ${definition.line}`,+ );+ }+ resolving.add(name);+ for (const token of definition.tokens) {+ if (definitions.has(token)) resolveMacro(token);+ }+ const attributes = parseAttributeAssignments(definition.tokens, macros);+ macros.set(name, attributes);+ resolving.delete(name);+ return attributes;+ };+ for (const name of definitions.keys()) resolveMacro(name);+ }+ for (let index = 0; index < lines.length; index++) {+ const raw = lines[index].trim();+ if (!raw || raw.startsWith('#')) continue;+ let tokens;+ try {+ tokens = splitAttributeLine(raw);+ } catch (error) {+ throw new ProtectionSourceError(+ source,+ `invalid rule on line ${index + 1}: ${error instanceof Error ? error.message : String(error)}`,+ );+ }+ if (tokens.length < 2) {+ throw new ProtectionSourceError(+ source,+ `invalid rule on line ${index + 1}`,+ );+ }+ let pattern = tokens.shift();+ if (!pattern || pattern.startsWith('!')) {+ throw new ProtectionSourceError(+ source,+ `invalid pattern on line ${index + 1}`,+ );+ }+ if (pattern.startsWith('[attr]')) {+ const name = pattern.slice('[attr]'.length);+ if (!topLevel || !name) {+ throw new ProtectionSourceError(+ source,+ `invalid attribute macro on line ${index + 1}`,+ );+ }+ continue;+ }+ pattern = pattern.replace(/^\//, '');+ const basename = !pattern.includes('/');+ let matcher;+ try {+ matcher = globRegex(pattern, {basename});+ } catch (error) {+ throw new ProtectionSourceError(+ source,+ `invalid pattern on line ${index + 1}: ${error instanceof Error ? error.message : String(error)}`,+ );+ }+ const attributes = parseAttributeAssignments(tokens, macros);+ rules.push({pattern: matcher, attributes, line: index + 1});+ }+ return rules;+}++/** @param {string} contents @param {string} filePath */+function generatedMarker(contents, filePath) {+ const text = contents.slice(0, 65_536);+ const extension = path.extname(filePath).toLowerCase();+ const hashComments =+ text.startsWith('#!') ||+ new Set([+ '.py',+ '.pyi',+ '.rb',+ '.sh',+ '.bash',+ '.zsh',+ '.yaml',+ '.yml',+ '.toml',+ ]).has(extension);+ const dashComments = new Set(['.sql', '.lua']).has(extension);+ let cursor = 0;+ if (text.startsWith('#!')) {+ const end = text.indexOf('\n');+ cursor = end === -1 ? text.length : end + 1;+ }+ /** @type {string[]} */+ const comments = [];+ while (cursor < text.length) {+ const ws = /^\s+/.exec(text.slice(cursor));+ if (ws) cursor += ws[0].length;+ if (+ text.startsWith('//', cursor) ||+ (hashComments && text.startsWith('#', cursor)) ||+ (dashComments && text.startsWith('--', cursor))+ ) {+ const end = text.indexOf('\n', cursor);+ comments.push(text.slice(cursor, end === -1 ? text.length : end));+ cursor = end === -1 ? text.length : end + 1;+ continue;+ }+ const block = text.startsWith('/*', cursor)+ ? ['/*', '*/']+ : text.startsWith('<!--', cursor)+ ? ['<!--', '-->']+ : null;+ if (block) {+ const end = text.indexOf(block[1], cursor + block[0].length);+ if (end === -1) break;+ comments.push(text.slice(cursor, end + block[1].length));+ cursor = end + block[1].length;+ continue;+ }+ break;+ }+ const leading = comments.join('\n');+ if (/(?:^|[^\w-])@partially-generated(?:[^\w-]|$)/i.test(leading))+ return '@partially-generated in the leading comment block';+ if (/(?:^|[^\w-])@generated(?:[^\w-]|$)/i.test(leading))+ return '@generated in the leading comment block';+ if (/Code generated\b[^\r\n]*\bDO NOT EDIT\./.test(leading))+ return 'Code generated ... DO NOT EDIT. in the leading comment block';+ return null;+}++/** @param {string} contents */+function generatedCommand(contents) {+ const match = contents+ .slice(0, 65_536)+ .match(/^\s*(?:\/\/|\*|#|<!--)?\s*Command:\s*(.+?)\s*(?:\*\/|-->)?\s*$/m);+ return match?.[1]?.trim() || undefined;+}++/**+ * @typedef {{file: string, reason: 'generated'|'vendored'|'ignored'|'dependency'|'vcs'|'symlink'|'outside-root', declaration: string, source?: string, line?: number, command?: string}} FileProtection+ */++/**+ * Create an eager, fail-closed resolver. Every declaration under root is parsed+ * before the caller can begin writing consumer files.+ * @param {string} root+ * @param {{overrides?: Map<string, string|null>}} [options]+ */+export function createFileProtectionResolver(+ root,+ {overrides = new Map()} = {},+) {+ const resolvedRoot = path.resolve(root);+ const normalizedOverrides = new Map(+ [...overrides].map(([file, contents]) => [path.resolve(file), contents]),+ );+ /** @type {string} */+ let realRoot;+ try {+ realRoot = fs.realpathSync(resolvedRoot);+ } catch (error) {+ throw new ProtectionSourceError(+ '.',+ error instanceof Error ? error.message : String(error),+ );+ }+ /** @type {Array<{file: string, dir: string, contents: string}>} */+ const rawAttributeSources = [];+ /** @type {Array<{file: string, dir: string, rules: ReturnType<typeof parseAttributes>}>} */+ const attributeSources = [];+ /** @type {Map<string, Map<string, boolean|null>>} */+ const attributeMacros = new Map();+ /** @type {Array<{file: string, dir: string, matcher: ReturnType<typeof ignore>}>} */+ const gitIgnoreSources = [];+ /** @type {Array<{file: string, dir: string, matcher: RegExp, line: number}>} */+ const hgIgnoreRules = [];+ const parsedHgFiles = new Set();+ const seenProtectionFiles = new Set();++ /** @param {string} file */+ function readProtectionFile(file) {+ const relative = slash(path.relative(resolvedRoot, file)) || '.';+ try {+ const override = normalizedOverrides.get(path.resolve(file));+ if (override === null) throw new Error('is deleted by the staged plan');+ const contents =+ override === undefined ? fs.readFileSync(file, 'utf-8') : override;+ if (contents.includes('\0')) throw new Error('contains a NUL byte');+ return {contents, relative};+ } catch (error) {+ if (error instanceof ProtectionSourceError) throw error;+ throw new ProtectionSourceError(+ relative,+ error instanceof Error ? error.message : String(error),+ );+ }+ }++ /** @param {string} file @param {string} baseDir */+ function parseHgIgnore(file, baseDir) {+ const absolute = path.resolve(file);+ if (parsedHgFiles.has(absolute)) return;+ const within = relativeWithin(absolute, resolvedRoot);+ if (within == null) {+ throw new ProtectionSourceError(+ slash(path.relative(resolvedRoot, absolute)),+ 'included source is outside the operation root',+ );+ }+ const virtualSource =+ normalizedOverrides.has(absolute) &&+ normalizedOverrides.get(absolute) !== null;+ if (!virtualSource) {+ let realSource;+ try {+ realSource = fs.realpathSync(absolute);+ } catch (error) {+ throw new ProtectionSourceError(+ within,+ error instanceof Error ? error.message : String(error),+ );+ }+ if (realSource !== path.resolve(realRoot, within)) {+ throw new ProtectionSourceError(+ within,+ 'included source is reached through a symbolic link',+ );+ }+ } else {+ let ancestor = path.dirname(absolute);+ while (!fs.existsSync(ancestor) && ancestor !== resolvedRoot) {+ ancestor = path.dirname(ancestor);+ }+ const ancestorWithin = relativeWithin(ancestor, resolvedRoot);+ if (+ ancestorWithin == null ||+ fs.realpathSync(ancestor) !== path.resolve(realRoot, ancestorWithin)+ ) {+ throw new ProtectionSourceError(+ within,+ 'staged source is beneath a symbolic link',+ );+ }+ }+ parsedHgFiles.add(absolute);+ const {contents, relative} = readProtectionFile(absolute);+ let syntax = 'regexp';+ const lines = contents.split(/\r?\n/);+ for (let index = 0; index < lines.length; index++) {+ const raw = lines[index].trim();+ if (!raw || raw.startsWith('#')) continue;+ if (raw.startsWith('syntax:')) {+ syntax = raw.slice('syntax:'.length).trim();+ if (syntax !== 'glob' && syntax !== 'regexp') {+ throw new ProtectionSourceError(+ relative,+ `unknown syntax on line ${index + 1}`,+ );+ }+ continue;+ }+ if (raw.startsWith('include:') || raw.startsWith('subinclude:')) {+ const sub = raw.startsWith('subinclude:');+ const includePath = raw.slice(raw.indexOf(':') + 1).trim();+ if (!includePath)+ throw new ProtectionSourceError(+ relative,+ `empty include on line ${index + 1}`,+ );+ const included = path.resolve(path.dirname(absolute), includePath);+ parseHgIgnore(included, sub ? path.dirname(included) : baseDir);+ continue;+ }+ let kind = syntax;+ let pattern = raw;+ if (raw.startsWith('glob:')) {+ kind = 'glob';+ pattern = raw.slice(5);+ } else if (raw.startsWith('re:')) {+ kind = 'regexp';+ pattern = raw.slice(3);+ }+ try {+ const matcher =+ kind === 'glob'+ ? globRegex(pattern.replace(/^\//, ''), {+ basename: !pattern.includes('/'),+ })+ : new RegExp(pattern);+ hgIgnoreRules.push({+ file: relative,+ dir: baseDir,+ matcher,+ line: index + 1,+ });+ } catch (error) {+ throw new ProtectionSourceError(+ relative,+ `invalid ${kind} pattern on line ${index + 1}: ${error instanceof Error ? error.message : String(error)}`,+ );+ }+ }+ }++ /** @param {string} dir */+ function scan(dir) {+ let entries;+ try {+ entries = fs.readdirSync(dir, {withFileTypes: true});+ } catch (error) {+ throw new ProtectionSourceError(+ slash(path.relative(resolvedRoot, dir)) || '.',+ error instanceof Error ? error.message : String(error),+ );+ }+ // Parent declarations (and attribute macros) must be parsed before child+ // directories regardless of filesystem enumeration order.+ entries.sort((a, b) => Number(a.isDirectory()) - Number(b.isDirectory()));+ for (const entry of entries) {+ const full = path.join(dir, entry.name);+ if (entry.isSymbolicLink()) continue;+ if (entry.isDirectory()) {+ const relativeParts = slash(path.relative(resolvedRoot, full)).split(+ '/',+ );+ if (+ DEPENDENCY_DIRS.has(entry.name) ||+ VCS_DIRS.has(entry.name) ||+ (relativeParts[0] === '.yarn' &&+ YARN_DEPENDENCY_DIRS.has(relativeParts[1]))+ )+ continue;+ scan(full);+ continue;+ }+ if (!PROTECTION_FILES.has(entry.name)) continue;+ if (entry.name === '.hgignore' && dir !== resolvedRoot) continue;+ seenProtectionFiles.add(path.resolve(full));+ if (normalizedOverrides.get(path.resolve(full)) === null) continue;+ const {contents, relative} = readProtectionFile(full);+ if (entry.name === '.gitattributes') {+ rawAttributeSources.push({file: relative, dir, contents});+ } else if (entry.name === '.gitignore') {+ try {+ gitIgnoreSources.push({+ file: relative,+ dir,+ matcher: ignore({ignorecase: false}).add(contents),+ });+ } catch (error) {+ throw new ProtectionSourceError(+ relative,+ error instanceof Error ? error.message : String(error),+ );+ }+ } else if (dir === resolvedRoot) {+ // Mercurial reads only the repository-root .hgignore directly. Nested+ // rule files participate through include:/subinclude: directives.+ parseHgIgnore(full, dir);+ }+ }+ }++ scan(resolvedRoot);+ for (const [absolute, contents] of normalizedOverrides) {+ if (contents === null || seenProtectionFiles.has(absolute)) continue;+ const name = path.basename(absolute);+ if (!PROTECTION_FILES.has(name)) continue;+ const relative = relativeWithin(absolute, resolvedRoot);+ if (relative == null) continue;+ const dir = path.dirname(absolute);+ if (name === '.hgignore' && dir !== resolvedRoot) continue;+ if (contents.includes('\0')) {+ throw new ProtectionSourceError(relative, 'contains a NUL byte');+ }+ if (name === '.gitattributes') {+ rawAttributeSources.push({file: relative, dir, contents});+ } else if (name === '.gitignore') {+ try {+ gitIgnoreSources.push({+ file: relative,+ dir,+ matcher: ignore({ignorecase: false}).add(contents),+ });+ } catch (error) {+ throw new ProtectionSourceError(+ relative,+ error instanceof Error ? error.message : String(error),+ );+ }+ } else {+ parseHgIgnore(absolute, dir);+ }+ }+ rawAttributeSources.sort(+ (a, b) => a.dir.length - b.dir.length || a.file.localeCompare(b.file),+ );+ for (const source of rawAttributeSources) {+ attributeSources.push({+ file: source.file,+ dir: source.dir,+ rules: parseAttributes(+ source.file,+ source.contents,+ attributeMacros,+ source.dir === resolvedRoot,+ ),+ });+ }+ attributeSources.sort(+ (a, b) => a.dir.length - b.dir.length || a.file.localeCompare(b.file),+ );+ gitIgnoreSources.sort(+ (a, b) => a.dir.length - b.dir.length || a.file.localeCompare(b.file),+ );++ /** @param {string} target @param {number} end @param {boolean} directory */+ function gitIgnoredBy(+ target,+ end = gitIgnoreSources.length,+ directory = false,+ ) {+ let state = null;+ for (let index = 0; index < end; index++) {+ const source = gitIgnoreSources[index];+ let relative = relativeWithin(target, source.dir);+ if (relative == null || relative === '') continue;+ if (directory) relative += '/';+ // Git never reads a nested ignore file whose parent was excluded by an+ // earlier source. This preserves the "cannot re-include beneath an+ // excluded parent" rule while still allowing lower-file precedence.+ const sourceIndex = gitIgnoreSources.indexOf(source);+ if (+ source.dir !== resolvedRoot &&+ gitIgnoredBy(source.dir, sourceIndex, true)?.ignored+ ) {+ continue;+ }+ const tested = source.matcher.test(relative);+ if (tested.ignored) state = {ignored: true, source, relative};+ else if (tested.unignored) state = {ignored: false, source, relative};+ }+ return state;+ }++ /** @param {string} filePath @returns {FileProtection[]} */+ function classify(filePath) {+ const absolute = path.resolve(filePath);+ const relative = relativeWithin(absolute, resolvedRoot);+ if (relative == null) {+ return [+ {+ file: slash(path.relative(resolvedRoot, absolute)),+ reason: 'outside-root',+ declaration: 'outside the operation root',+ },+ ];+ }+ const parts = relative.split('/').filter(Boolean);+ if (+ (parts.length === 1 &&+ /^\.pnp\.(?:cjs|loader\.mjs|data\.json)$/.test(parts[0])) ||+ (parts[0] === '.yarn' &&+ (YARN_DEPENDENCY_DIRS.has(parts[1]) ||+ (parts.length === 2 && YARN_DEPENDENCY_FILES.has(parts[1]))))+ ) {+ return [+ {+ file: relative,+ reason: 'dependency',+ declaration: `installed dependency metadata ${parts.slice(0, 2).join('/')}`,+ },+ ];+ }+ for (const part of parts) {+ if (DEPENDENCY_DIRS.has(part))+ return [+ {+ file: relative,+ reason: 'dependency',+ declaration: `installed dependency directory ${part}`,+ },+ ];+ if (VCS_DIRS.has(part))+ return [+ {+ file: relative,+ reason: 'vcs',+ declaration: `version-control metadata directory ${part}`,+ },+ ];+ }+ let current = resolvedRoot;+ for (const part of parts) {+ current = path.join(current, part);+ try {+ if (fs.lstatSync(current).isSymbolicLink()) {+ return [+ {+ file: relative,+ reason: 'symlink',+ declaration: `symbolic link at ${slash(path.relative(resolvedRoot, current))}`,+ },+ ];+ }+ } catch (error) {+ if (+ current === absolute &&+ /** @type {any} */ (error).code === 'ENOENT'+ )+ break;+ throw new ProtectionSourceError(+ relative,+ error instanceof Error ? error.message : String(error),+ );+ }+ }++ /** @type {FileProtection[]} */+ const protections = [];+ const ignored = gitIgnoredBy(absolute);+ if (ignored?.ignored) {+ protections.push({+ file: relative,+ reason: 'ignored',+ declaration: `excluded by ${ignored.source.file}`,+ source: ignored.source.file,+ });+ }+ for (const rule of hgIgnoreRules) {+ const candidate = relativeWithin(absolute, rule.dir);+ if (candidate != null && rule.matcher.test(candidate)) {+ protections.push({+ file: relative,+ reason: 'ignored',+ declaration: `excluded by ${rule.file}:${rule.line}`,+ source: rule.file,+ line: rule.line,+ });+ }+ }++ /** @type {Map<string, {value: boolean|null, source: string, line: number}>} */+ const attributes = new Map();+ for (const source of attributeSources) {+ const candidate = relativeWithin(absolute, source.dir);+ if (candidate == null || candidate === '') continue;+ for (const rule of source.rules) {+ if (!rule.pattern.test(candidate)) continue;+ for (const [name, value] of rule.attributes) {+ attributes.set(name, {value, source: source.file, line: rule.line});+ }+ }+ }+ for (const [name, reason] of [+ ['linguist-generated', 'generated'],+ ['linguist-vendored', 'vendored'],+ ]) {+ const attribute = attributes.get(name);+ if (attribute?.value === true) {+ protections.push({+ file: relative,+ reason: /** @type {'generated'|'vendored'} */ (reason),+ declaration: `${name} in ${attribute.source}:${attribute.line}`,+ source: attribute.source,+ line: attribute.line,+ });+ }+ }++ const hasContentOverride = normalizedOverrides.has(absolute);+ const contentOverride = normalizedOverrides.get(absolute);+ if (+ contentOverride !== null &&+ (hasContentOverride ||+ (fs.existsSync(absolute) && fs.statSync(absolute).isFile()))+ ) {+ let contents;+ try {+ contents = hasContentOverride+ ? /** @type {string} */ (contentOverride)+ : fs.readFileSync(absolute, 'utf-8');+ } catch (error) {+ throw new ProtectionSourceError(+ relative,+ error instanceof Error ? error.message : String(error),+ );+ }+ const marker = generatedMarker(contents, absolute);+ const command = generatedCommand(contents);+ if (marker) {+ protections.push({+ file: relative,+ reason: 'generated',+ declaration: marker,+ command,+ });+ }+ if (command) {+ for (const item of protections) {+ if (item.reason === 'generated' && !item.command)+ item.command = command;+ }+ }+ }+ return protections;+ }++ return Object.freeze({root: resolvedRoot, classify});+}diff --git a/packages/cli/foundation/fs/file-protection.test.mjs b/packages/cli/foundation/fs/file-protection.test.mjsnew file mode 100644index 0000000000..0c49ec9c65--- /dev/null+++ b/packages/cli/foundation/fs/file-protection.test.mjs@@ -0,0 +1,250 @@+// 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 {+ createFileProtectionResolver,+ ProtectionSourceError,+} from './file-protection.mjs';++let root;++beforeEach(() => {+ root = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-protection-'));+});++afterEach(() => {+ 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;+}++function declarations(relative) {+ return createFileProtectionResolver(root)+ .classify(path.join(root, relative))+ .map(item => item.declaration);+}++describe('working-tree .gitattributes', () => {+ it('honors nested later rules and explicit false or unset values', () => {+ write(+ '.gitattributes',+ [+ '*.css linguist-generated=true',+ 'vendor/** linguist-vendored',+ 'authored.css -linguist-generated',+ 'unset.css !linguist-generated',+ '',+ ].join('\n'),+ );+ write('generated.css', 'body {}');+ write('authored.css', 'body {}');+ write('unset.css', 'body {}');+ write('nested/keep.css', 'body {}');+ write('nested/.gitattributes', 'keep.css linguist-generated=false\n');+ write('vendor/pkg/index.js', 'export {};');++ expect(declarations('generated.css')).toContain(+ 'linguist-generated in .gitattributes:1',+ );+ expect(declarations('authored.css')).toEqual([]);+ expect(declarations('unset.css')).toEqual([]);+ expect(declarations('nested/keep.css')).toEqual([]);+ expect(declarations('vendor/pkg/index.js')).toContain(+ 'linguist-vendored in .gitattributes:2',+ );+ });++ it('expands top-level attribute macros, including forward definitions', () => {+ write(+ '.gitattributes',+ 'via-macro/** outer\n[attr]outer generated\n[attr]generated linguist-generated\n',+ );+ write('via-macro/output.js', 'export {};');+ expect(declarations('via-macro/output.js')).toContain(+ 'linguist-generated in .gitattributes:1',+ );+ });++ it('preserves escaped wildcards as literal path characters', () => {+ write('.gitattributes', 'literal\\*.js linguist-generated\n');+ write('literal*.js', 'export {};');+ write('literalX.js', 'export {};');+ expect(declarations('literal*.js')).toHaveLength(1);+ expect(declarations('literalX.js')).toEqual([]);+ });++ it('supports quoted attribute patterns with spaces', () => {+ write('.gitattributes', '"generated output/*.js" linguist-generated\n');+ write('generated output/theme.js', 'export {};');+ expect(declarations('generated output/theme.js')).toHaveLength(1);+ });++ it('matches basename patterns below the declaring directory', () => {+ write('.gitattributes', '*.gen.ts linguist-generated\n');+ write('src/deep/theme.gen.ts', 'export {};');+ expect(declarations('src/deep/theme.gen.ts')).toHaveLength(1);+ });+});++describe('working-tree ignore rules', () => {+ it('honors gitignore negation and nested precedence', () => {+ write('.gitignore', ['src/**/*.js', '!src/keep.js', ''].join('\n'));+ write('src/drop.js', 'drop');+ write('src/keep.js', 'keep');+ write('src/deep/drop.js', 'drop');+ write('src/.gitignore', '!deep/keep.js\n');+ write('src/deep/keep.js', 'keep');++ expect(declarations('src/drop.js')[0]).toBe('excluded by .gitignore');+ expect(declarations('src/deep/drop.js')[0]).toBe('excluded by .gitignore');+ expect(declarations('src/keep.js')).toEqual([]);+ expect(declarations('src/deep/keep.js')).toEqual([]);+ });++ it('uses case-sensitive Git matching on case-sensitive platforms', () => {+ write('.gitignore', 'FOO\n');+ write('FOO', 'x');+ write('foo', 'x');++ expect(declarations('FOO')[0]).toBe('excluded by .gitignore');+ expect(declarations('foo')).toEqual([]);+ });++ it('does not let a nested ignore file re-include beneath an excluded parent', () => {+ write('.gitignore', 'ignored/\n');+ write('ignored/.gitignore', '!keep.js\n');+ write('ignored/keep.js', 'keep');++ expect(declarations('ignored/keep.js')[0]).toBe('excluded by .gitignore');+ });++ it('ignores nested .hgignore files unless the root file includes them', () => {+ write('sub/.hgignore', 'syntax: glob\n*.tmp\n');+ write('sub/file.tmp', 'x');+ expect(declarations('sub/file.tmp')).toEqual([]);+ });++ it('reads Mercurial glob and regexp syntax without a repository process', () => {+ write(+ '.hgignore',+ ['syntax: glob', '**/*.generated.css', 're:^legacy/.+\\.js$', ''].join(+ '\n',+ ),+ );+ write('src/theme.generated.css', 'x');+ write('legacy/file.js', 'x');+ write('src/file.js', 'x');++ expect(declarations('src/theme.generated.css')[0]).toMatch(/\.hgignore:2/);+ expect(declarations('legacy/file.js')[0]).toMatch(/\.hgignore:3/);+ expect(declarations('src/file.js')).toEqual([]);+ });+});++describe('leading generated comments', () => {+ it.each([+ ['// @generated\nexport const x = 1;\n', '@generated'],+ [+ '/* @partially-generated */\nexport const x = 1;\n',+ '@partially-generated',+ ],+ [+ '// Code generated by Acme. DO NOT EDIT.\nconst x = 1;\n',+ 'Code generated',+ ],+ ['#!/usr/bin/env node\n// @generated\nconsole.log(1);\n', '@generated'],+ ])('protects a recognized leading marker', (source, expected) => {+ write('file.js', source);+ expect(declarations('file.js')[0]).toContain(expected);+ });++ it('recognizes hash comments after a shebang in an extensionless file', () => {+ write('script', '#!/bin/sh\n# @generated\necho hi\n');+ expect(declarations('script')[0]).toContain('@generated');+ });++ it('does not treat a marker after authored code as protection', () => {+ write('file.js', 'export const authored = true;\n// @generated\n');+ expect(declarations('file.js')).toEqual([]);+ });++ it('does not accept longer generated-like annotations', () => {+ write('file.js', '// @generated-code\nexport const authored = true;\n');+ expect(declarations('file.js')).toEqual([]);+ });++ it('does not mistake a leading CSS id selector for a comment', () => {+ write('file.css', '#root { color: red; }\n/* @generated */\n');+ expect(declarations('file.css')).toEqual([]);+ });++ it('extracts an exact regeneration command from a generated header', () => {+ const file = write(+ 'theme.css',+ '/*\n * @generated\n * Command: pnpm astryx theme build src/theme.ts\n */\n',+ );+ const protection = createFileProtectionResolver(root).classify(file)[0];+ expect(protection.command).toBe('pnpm astryx theme build src/theme.ts');+ });+});++describe('hard boundaries and fail-closed parsing', () => {+ it('protects dependency metadata, VCS metadata leaves, symlinks, and paths outside root', () => {+ const dependency = write('node_modules/pkg/index.js', 'x');+ const yarnDependency = write('.yarn/unplugged/pkg/index.js', 'x');+ const yarnVirtual = write('.yarn/__virtual__/pkg/index.js', 'x');+ const yarnInstallState = write('.yarn/install-state.gz', 'x');+ const yarnPatch = write('.yarn/patches/pkg.patch', 'x');+ const pnp = write('.pnp.cjs', 'x');+ const pnpData = write('.pnp.data.json', '{}');+ const metadata = write('.git', 'gitdir: elsewhere\n');+ const target = write('target.js', 'x');+ const link = path.join(root, 'link.js');+ fs.symlinkSync(target, link);+ const resolver = createFileProtectionResolver(root);++ expect(resolver.classify(dependency)[0].reason).toBe('dependency');+ expect(resolver.classify(yarnDependency)[0].reason).toBe('dependency');+ expect(resolver.classify(yarnVirtual)[0].reason).toBe('dependency');+ expect(resolver.classify(yarnInstallState)[0].reason).toBe('dependency');+ expect(resolver.classify(yarnPatch)).toEqual([]);+ expect(resolver.classify(pnp)[0].reason).toBe('dependency');+ expect(resolver.classify(pnpData)[0].reason).toBe('dependency');+ expect(resolver.classify(metadata)[0].reason).toBe('vcs');+ expect(resolver.classify(link)[0].reason).toBe('symlink');+ expect(+ resolver.classify(path.join(root, '..', 'outside.js'))[0].reason,+ ).toBe('outside-root');+ });++ it('rejects an .hgignore include reached through a symlink', () => {+ const outside = path.join(+ os.tmpdir(),+ `astryx-ignore-${process.pid}-${Date.now()}`,+ );+ fs.writeFileSync(outside, 'syntax: glob\n*.generated\n');+ try {+ fs.symlinkSync(outside, path.join(root, 'rules'));+ write('.hgignore', 'include:rules\n');+ expect(() => createFileProtectionResolver(root)).toThrow(/symbolic link/);+ } finally {+ fs.rmSync(outside, {force: true});+ }+ });++ it('fails before use when a protection source cannot be parsed', () => {+ write('.hgignore', 'syntax: regexp\n[unterminated\n');+ expect(() => createFileProtectionResolver(root)).toThrow(+ ProtectionSourceError,+ );+ expect(() => createFileProtectionResolver(root)).toThrow(/\.hgignore/);+ });+});diff --git a/packages/cli/foundation/response/error-codes.d.ts b/packages/cli/foundation/response/error-codes.d.tsindex 4186e1d027..a209a42f5f 100644--- a/packages/cli/foundation/response/error-codes.d.ts+++ b/packages/cli/foundation/response/error-codes.d.ts@@ -34,6 +34,8 @@ export type ErrorCode =| 'ERR_UNKNOWN_FEATURE'| 'ERR_UNKNOWN_CODEMOD'| 'ERR_CODEMOD_FAILED'+ | 'ERR_CODEMOD_PROTECTED'+ | 'ERR_CODEMOD_PROTECTION_SOURCE'| 'ERR_NOT_FOUND'| 'ERR_NO_DOC'| 'ERR_NO_SHOWCASE'diff --git a/packages/cli/foundation/response/error-codes.doc.mjs b/packages/cli/foundation/response/error-codes.doc.mjsindex 3d0570c130..052b1a70bc 100644--- a/packages/cli/foundation/response/error-codes.doc.mjs+++ b/packages/cli/foundation/response/error-codes.doc.mjs@@ -154,6 +154,16 @@ export const doc = {value: 'ERR_CODEMOD_FAILED',description: 'One or more codemods failed during an upgrade run.',},+ {+ value: 'ERR_CODEMOD_PROTECTED',+ description:+ 'A required codemod change remains blocked by a protected consumer file.',+ },+ {+ value: 'ERR_CODEMOD_PROTECTION_SOURCE',+ description:+ 'A working-tree protection declaration could not be read or parsed.',+ },{value: 'ERR_NOT_FOUND',description:diff --git a/packages/cli/foundation/response/error-codes.mjs b/packages/cli/foundation/response/error-codes.mjsindex bc6eb49670..7ed88e3850 100644--- a/packages/cli/foundation/response/error-codes.mjs+++ b/packages/cli/foundation/response/error-codes.mjs@@ -64,6 +64,8 @@* | 'ERR_UNKNOWN_FEATURE'* | 'ERR_UNKNOWN_CODEMOD'* | 'ERR_CODEMOD_FAILED'+ * | 'ERR_CODEMOD_PROTECTED'+ * | 'ERR_CODEMOD_PROTECTION_SOURCE'* | 'ERR_NOT_FOUND'* | 'ERR_NO_DOC'* | 'ERR_NO_SHOWCASE'@@ -161,6 +163,10 @@ export const ERROR_CODES = Object.freeze({ERR_UNKNOWN_CODEMOD: 'ERR_UNKNOWN_CODEMOD',/** One or more codemods failed during an upgrade run. */ERR_CODEMOD_FAILED: 'ERR_CODEMOD_FAILED',+ /** A required codemod change remains blocked by a protected consumer file. */+ ERR_CODEMOD_PROTECTED: 'ERR_CODEMOD_PROTECTED',+ /** A working-tree protection declaration could not be read or parsed. */+ ERR_CODEMOD_PROTECTION_SOURCE: 'ERR_CODEMOD_PROTECTION_SOURCE',/** A generic discover/lookup query matched nothing in any package. */ERR_NOT_FOUND: 'ERR_NOT_FOUND',diff --git a/packages/cli/foundation/response/error-codes.test.mjs b/packages/cli/foundation/response/error-codes.test.mjsindex 5c3dc01a6f..58ab5b0313 100644--- a/packages/cli/foundation/response/error-codes.test.mjs+++ b/packages/cli/foundation/response/error-codes.test.mjs@@ -86,6 +86,8 @@ describe('error codes: shipped set', () => {'ERR_AMBIGUOUS_TEMPLATE','ERR_AMBIGUOUS_THEME','ERR_CODEMOD_FAILED',+ 'ERR_CODEMOD_PROTECTED',+ 'ERR_CODEMOD_PROTECTION_SOURCE','ERR_CORE_INCOMPATIBLE','ERR_CORE_NOT_FOUND','ERR_DEP_MISSING',@@ -135,25 +137,67 @@ describe('error codes: shipped set', () => {];it('still carries every shipped code, spelled the same', () => {- const missing = SHIPPED.filter(code => !isErrorCode(code) || ERROR_CODES[code] !== code);+ const missing = SHIPPED.filter(+ code => !isErrorCode(code) || ERROR_CODES[code] !== code,+ );expect(missing, 'shipped codes removed or respelled').toEqual([]);});});describe('error codes: end-to-end JSON envelopes', () => {const cases = [- {name: 'unknown component', args: ['component', 'Bogus', '--json'], code: 'ERR_UNKNOWN_COMPONENT'},- {name: 'unknown hook', args: ['hook', 'bogusHook', '--json'], code: 'ERR_UNKNOWN_HOOK'},- {name: 'unknown topic', args: ['docs', 'bogusTopic', '--json'], code: 'ERR_UNKNOWN_TOPIC'},- {name: 'unknown template', args: ['template', 'bogusTemplate', '--json'], code: 'ERR_UNKNOWN_TEMPLATE'},- {name: 'unknown command', args: ['bogus-cmd', '--json'], code: 'ERR_UNKNOWN_COMMAND'},- {name: 'invalid --lang', args: ['docs', 'color', '--lang', 'fr', '--json'], code: 'ERR_INVALID_LANG'},- {name: 'invalid --detail', args: ['docs', 'color', '--detail', 'bogus', '--json'], code: 'ERR_INVALID_DETAIL'},- {name: 'unknown option', args: ['component', 'Button', '--bogus-flag', '--json'], code: 'ERR_INVALID_OPTION'},- {name: 'missing argument', args: ['theme', 'build', '--json'], code: 'ERR_MISSING_ARGUMENT'},+ {+ name: 'unknown component',+ args: ['component', 'Bogus', '--json'],+ code: 'ERR_UNKNOWN_COMPONENT',+ },+ {+ name: 'unknown hook',+ args: ['hook', 'bogusHook', '--json'],+ code: 'ERR_UNKNOWN_HOOK',+ },+ {+ name: 'unknown topic',+ args: ['docs', 'bogusTopic', '--json'],+ code: 'ERR_UNKNOWN_TOPIC',+ },+ {+ name: 'unknown template',+ args: ['template', 'bogusTemplate', '--json'],+ code: 'ERR_UNKNOWN_TEMPLATE',+ },+ {+ name: 'unknown command',+ args: ['bogus-cmd', '--json'],+ code: 'ERR_UNKNOWN_COMMAND',+ },+ {+ name: 'invalid --lang',+ args: ['docs', 'color', '--lang', 'fr', '--json'],+ code: 'ERR_INVALID_LANG',+ },+ {+ name: 'invalid --detail',+ args: ['docs', 'color', '--detail', 'bogus', '--json'],+ code: 'ERR_INVALID_DETAIL',+ },+ {+ name: 'unknown option',+ args: ['component', 'Button', '--bogus-flag', '--json'],+ code: 'ERR_INVALID_OPTION',+ },+ {+ name: 'missing argument',+ args: ['theme', 'build', '--json'],+ code: 'ERR_MISSING_ARGUMENT',+ },// `theme` is not on the --json allowlist, so --json on any theme subcommand// is rejected at the preAction gate with a stable invalid-option code.- {name: 'json not supported', args: ['theme', 'bogus-sub', '--json'], code: 'ERR_INVALID_OPTION'},+ {+ name: 'json not supported',+ args: ['theme', 'bogus-sub', '--json'],+ code: 'ERR_INVALID_OPTION',+ },];for (const {name, args, code} of cases) {diff --git a/packages/cli/package.json b/packages/cli/package.jsonindex 942711a52d..d42910e2cc 100644--- a/packages/cli/package.json+++ b/packages/cli/package.json@@ -105,6 +105,7 @@"@babel/types": "7.29.8","ast-types": "0.16.3","commander": "^12.1.0",+ "ignore": "^7.0.5","jiti": "^2.7.0","jscodeshift": "^17.3.0","node-diff3": "3.2.1",diff --git a/pnpm-lock.yaml b/pnpm-lock.yamlindex b5c0a7a532..a62210fce7 100644--- a/pnpm-lock.yaml+++ b/pnpm-lock.yaml@@ -778,6 +778,9 @@ importers:commander:specifier: ^12.1.0version: 12.1.0+ ignore:+ specifier: ^7.0.5+ version: 7.0.5jiti:specifier: ^2.7.0version: 2.7.0