@aws/nx-plugin 1.0.0-rc.7 → 1.0.0-rc.71

package/src/migrations/latest/translate-script-whole-file-writes/files/get-files-to-translate.ts.fixture

@@ -0,0 +1,96 @@
+async function getFilesToTranslate(): Promise<FileToTranslate[]> {
+  const sourceLangRoot = `${DOCS_DIR}/${config.sourceLanguage}`;
+  const includePatterns = config.include.map((p) => `${sourceLangRoot}/${p}`);
+  const ignorePatterns = config.exclude.map((p) => `${sourceLangRoot}/${p}`);
+
+  if (options.all) {
+    log.info('Translating all source documentation files');
+    const files = await glob(includePatterns, { ignore: ignorePatterns });
+    return files.map((file) => ({
+      relativePath: path.relative(sourceLangRoot, file),
+      sourceAbsPath: file,
+    }));
+  }
+
+  const git = simpleGit();
+  // git reports paths relative to the repo root, which is not necessarily the
+  // directory this script runs from.
+  const repoRoot = (await git.revparse(['--show-toplevel'])).trim();
+
+  let currentBranch: string;
+  let mainBranch: string;
+  if (process.env.GITHUB_HEAD_REF) {
+    currentBranch = `origin/${process.env.GITHUB_HEAD_REF}`;
+    mainBranch = 'origin/main';
+  } else {
+    currentBranch = (await git.branch()).current;
+    mainBranch = 'main';
+  }
+
+  try {
+    await git.raw(['rev-parse', '--verify', mainBranch]);
+  } catch {
+    log.warn(`Could not find "${mainBranch}"; falling back to --all behaviour`);
+    options.all = true;
+    return getFilesToTranslate();
+  }
+
+  const mergeBase = (
+    await git.raw(['merge-base', mainBranch, currentBranch])
+  ).trim();
+
+  const translationCommits = (
+    await git.log({ from: mergeBase, to: 'HEAD' })
+  ).all.filter((c) => c.message.includes(TRANSLATION_COMMIT_MESSAGE));
+
+  const baseCommit =
+    translationCommits.length > 0 ? translationCommits[0].hash : mergeBase;
+
+  log.info(
+    translationCommits.length > 0
+      ? `Detecting changed files since last translation commit ${baseCommit.substring(0, 7)}`
+      : `Detecting changed files since branch creation ${baseCommit.substring(0, 7)}`,
+  );
+
+  const diffNames = (
+    await git.diff([`${baseCommit}..HEAD`, '--name-only', '--diff-filter=d'])
+  )
+    .split('\n')
+    .filter(Boolean);
+
+  const { files: uncommitted } = await git.status();
+  const uncommittedNames = uncommitted.map((f) => f.path);
+
+  const allCandidates = [...new Set([...diffNames, ...uncommittedNames])].map(
+    (p) => path.resolve(repoRoot, p),
+  );
+
+  // Filter to files inside the source language dir that match include/exclude
+  const includedGlob = await glob(includePatterns, {
+    ignore: ignorePatterns,
+  });
+  const includedSet = new Set(includedGlob.map((p) => path.resolve(p)));
+
+  const changed = allCandidates.filter((abs) => includedSet.has(abs));
+
+  if (changed.length === 0) {
+    log.warn('No changed source documentation files detected');
+    return [];
+  }
+
+  return Promise.all(
+    changed.map(async (file) => {
+      const relativePath = path.relative(sourceLangRoot, file);
+      const diff = await git.diff([
+        `${baseCommit}..HEAD`,
+        '--',
+        path.relative(repoRoot, file),
+      ]);
+      return {
+        relativePath,
+        sourceAbsPath: file,
+        diffPath: diff ? await writeDiff(relativePath, diff) : undefined,
+      };
+    }),
+  );
+}

package/src/migrations/latest/translate-script-whole-file-writes/files/header.ts.fixture

@@ -0,0 +1,15 @@
+/**
+ * Translate documentation files using a Strands agent powered by Claude on
+ * Amazon Bedrock.
+ *
+ * Configuration lives in ./translate.config.json (sibling to this file).
+ * Run from the project root:
+ *
+ *   <%= pkgMgrCmd %> nx translate <%= fullyQualifiedName %> -- --all
+ *   <%= pkgMgrCmd %> nx translate <%= fullyQualifiedName %>            # only files changed since last translate commit
+ *
+ * The driver works out which source docs to translate and spawns one Strands
+ * agent per (file × target language). Each agent gets the `fileEditor` tool and
+ * the paths it needs — the source file, the target file, and a diff of what
+ * changed — then reads, translates and writes the file itself.
+ */

package/src/migrations/latest/translate-script-whole-file-writes/files/log.ts.fixture

@@ -0,0 +1,18 @@
+const log = {
+  info: (m: string) => console.log(`[translate] ${m}`),
+  warn: (m: string) => console.warn(`[translate] ${m}`),
+  error: (m: string) => console.error(`[translate] ERROR ${m}`),
+  verbose: (m: string) => options.verbose && console.log(`[translate] ${m}`),
+};
+
+/**
+ * Diffs live under the docs directory so the agent's file access — which is
+ * scoped to that directory — can read them. Removed when the run finishes.
+ */
+const DIFF_DIR = path.join(DOCS_DIR, '.translate-diffs');
+
+async function writeDiff(relativePath: string, diff: string): Promise<string> {
+  const diffPath = path.join(DIFF_DIR, `${relativePath}.diff`);
+  await fs.outputFile(diffPath, diff, 'utf-8');
+  return diffPath;
+}

package/src/migrations/latest/translate-script-whole-file-writes/files/main-call.ts.fixture

@@ -0,0 +1,6 @@
+main()
+  .finally(() => fs.remove(DIFF_DIR))
+  .catch((err) => {
+    log.error(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+  });

package/src/migrations/latest/translate-script-whole-file-writes/files/main.ts.fixture

@@ -0,0 +1,79 @@
+async function main() {
+  const requestedLanguages: string[] = options.languages
+    ? options.languages
+        .split(',')
+        .map((l: string) => l.trim())
+        .filter(Boolean)
+    : config.targetLanguages;
+
+  const targetLanguages = requestedLanguages.filter(
+    (l) => l !== config.sourceLanguage,
+  );
+
+  if (targetLanguages.length === 0) {
+    log.error('No target languages configured');
+    process.exit(1);
+  }
+
+  log.info(`Source: ${config.sourceLanguage}`);
+  log.info(`Targets: ${targetLanguages.join(', ')}`);
+
+  await pruneOrphanedTranslations(targetLanguages);
+
+  const files = await getFilesToTranslate();
+
+  if (files.length === 0) {
+    log.info('No documentation files to translate.');
+    return;
+  }
+
+  log.info(`Files to translate: ${files.length}`);
+  for (const f of files) {
+    log.verbose(
+      `  - ${f.relativePath}${f.diffPath ? ' (changed)' : ' (full)'}`,
+    );
+  }
+
+  if (options.dryRun) {
+    for (const lang of targetLanguages) {
+      for (const f of files) {
+        log.info(`[dry-run] would translate ${f.relativePath} → ${lang}`);
+      }
+    }
+    log.info('Done (dry-run).');
+    return;
+  }
+
+  // Build one task per (file × target language) — each is a fresh agent invocation,
+  // so context windows stay small no matter how big the docs site is. A single
+  // failing translation records its error rather than aborting the whole run, so
+  // every other (file × language) still completes and gets written to disk.
+  const failures: string[] = [];
+  const tasks = targetLanguages.flatMap((lang) =>
+    files.map((file) => async () => {
+      log.info(`  ${file.relativePath} → ${lang}`);
+      try {
+        await translateFileForLanguage(file, lang);
+      } catch (err) {
+        log.error(
+          `${file.relativePath} → ${lang}: ${err instanceof Error ? err.message : String(err)}`,
+        );
+        failures.push(`${file.relativePath} → ${lang}`);
+      }
+    }),
+  );
+
+  const concurrency = Math.max(1, config.concurrency ?? 5);
+  log.info(
+    `Running ${tasks.length} translation(s) with concurrency=${concurrency}`,
+  );
+  await runWithConcurrency(tasks, concurrency);
+
+  if (failures.length > 0) {
+    throw new Error(
+      `${failures.length} translation(s) failed after retries:\n  ${failures.join('\n  ')}`,
+    );
+  }
+
+  log.info('Done.');
+}

package/src/migrations/latest/translate-script-whole-file-writes/files/project-root.ts.fixture

@@ -0,0 +1 @@
+const PROJECT_ROOT = path.resolve(SCRIPTS_DIR, '..');

package/src/migrations/latest/translate-script-whole-file-writes/files/run-with-concurrency.ts.fixture

@@ -0,0 +1,57 @@
+async function runWithConcurrency<T>(
+  tasks: Array<() => Promise<T>>,
+  limit: number,
+): Promise<T[]> {
+  const results: T[] = new Array(tasks.length);
+  let next = 0;
+  async function worker() {
+    while (true) {
+      const i = next++;
+      if (i >= tasks.length) return;
+      results[i] = await tasks[i]();
+    }
+  }
+  const workers = Array.from({ length: Math.min(limit, tasks.length) }, worker);
+  await Promise.all(workers);
+  return results;
+}
+
+/**
+ * Delete translated files whose source document no longer exists. Without this
+ * a source file that is renamed or removed leaves its translations behind in
+ * every locale, where they still resolve as snippets and pages.
+ */
+async function pruneOrphanedTranslations(
+  targetLanguages: string[],
+): Promise<void> {
+  const sourceLangRoot = `${DOCS_DIR}/${config.sourceLanguage}`;
+  const sourceFiles = new Set(
+    (
+      await glob(
+        config.include.map((p) => `${sourceLangRoot}/${p}`),
+        { ignore: config.exclude.map((p) => `${sourceLangRoot}/${p}`) },
+      )
+    ).map((p) => path.relative(sourceLangRoot, p)),
+  );
+
+  for (const lang of targetLanguages) {
+    const langRoot = path.join(DOCS_DIR, lang);
+    if (!fs.existsSync(langRoot)) continue;
+    const translated = await glob(
+      config.include.map((p) => `${langRoot}/${p}`),
+      { ignore: config.exclude.map((p) => `${langRoot}/${p}`) },
+    );
+    for (const abs of translated) {
+      const rel = path.relative(langRoot, abs);
+      if (sourceFiles.has(rel)) continue;
+      if (options.dryRun) {
+        log.info(`[dry-run] would delete orphaned ${lang}/${rel}`);
+      } else {
+        log.info(
+          `Deleting orphaned ${lang}/${rel} (no ${config.sourceLanguage} source)`,
+        );
+        await fs.remove(abs);
+      }
+    }
+  }
+}

package/src/migrations/latest/translate-script-whole-file-writes/files/scripts-dir.ts.fixture

@@ -0,0 +1 @@
+const SCRIPTS_DIR = <% if (esm) { %>import.meta.dirname<% } else { %>__dirname<% } %>;

package/src/migrations/latest/translate-script-whole-file-writes/files/translate-file-for-language.ts.fixture

@@ -0,0 +1,61 @@
+async function translateFileForLanguage(
+  file: FileToTranslate,
+  targetLang: string,
+): Promise<void> {
+  const targetAbsPath = path.join(DOCS_DIR, targetLang, file.relativePath);
+
+  let lastError: unknown;
+  for (let attempt = 1; attempt <= TRANSLATE_MAX_ATTEMPTS; attempt++) {
+    const agent = new Agent({
+      model: new BedrockModel({
+        modelId: config.modelId,
+        region: process.env.AWS_REGION ?? config.awsRegion,
+        maxTokens: 64_000,
+        temperature: 0.2,
+        // Translating a long file can stream for several minutes, well past the
+        // AWS SDK's two-minute default socket timeout.
+        clientConfig: { requestHandler: { requestTimeout: 15 * 60_000 } },
+      }),
+      systemPrompt: buildSystemPrompt(targetLang),
+      tools: [fileEditor],
+      printer: !!options.verbose,
+    });
+    agent.addHook(BeforeToolCallEvent, rejectOutsideDocsDir);
+
+    try {
+      const result = await agent.invoke(buildUserPrompt(file, targetLang));
+      if (result.stopReason !== 'endTurn') {
+        log.warn(
+          `agent stopped with reason=${result.stopReason} while translating ${file.relativePath} → ${targetLang} — inspect output above`,
+        );
+      }
+      lastError = undefined;
+    } catch (err) {
+      lastError = err;
+    }
+
+    // Judge the file on disk rather than on whether the agent wrote it: the
+    // stream often drops after a successful write, and an agent handed an
+    // already-correct translation may rightly decide there is nothing to do.
+    if (fs.existsSync(targetAbsPath)) {
+      try {
+        assertFrontmatterIsParseable(await fs.readFile(targetAbsPath, 'utf-8'));
+        await restoreCodeBlocks(file.sourceAbsPath, targetAbsPath);
+        return;
+      } catch (err) {
+        lastError = err;
+      }
+    }
+    lastError ??= new Error('no translation exists at the target path');
+
+    if (attempt < TRANSLATE_MAX_ATTEMPTS) {
+      const delayMs = 2000 * attempt;
+      log.warn(
+        `translation attempt ${attempt}/${TRANSLATE_MAX_ATTEMPTS} for ${file.relativePath} → ${targetLang} failed (${lastError instanceof Error ? lastError.message : String(lastError)}); retrying in ${delayMs}ms`,
+      );
+      await sleep(delayMs);
+    }
+  }
+
+  throw lastError;
+}

package/src/migrations/latest/translate-script-whole-file-writes/grit/already-migrated.grit

@@ -0,0 +1 @@
+function_declaration($name) where { $name <: `restoreCodeBlocks` }

package/src/migrations/latest/translate-script-whole-file-writes/grit/build-system-prompt.grit

@@ -0,0 +1,6 @@
+function_declaration($name, $body) as $decl where {
+  $name <: `buildSystemPrompt`,
+  $body <: includes "Efficiency rule",
+  $body <: includes "Never wrap the file output in triple backticks",
+  $decl => `__GRIT_INSERT_PLACEHOLDER__`
+}

package/src/migrations/latest/translate-script-whole-file-writes/grit/build-user-prompt.grit

@@ -0,0 +1,6 @@
+function_declaration($name, $body) as $decl where {
+  $name <: `buildUserPrompt`,
+  $body <: contains `const targetLangRoot = path.join(DOCS_DIR, targetLang)`,
+  $body <: contains `const existingTranslationExists = fs.existsSync(targetAbsPath)`,
+  $decl => `__GRIT_INSERT_PLACEHOLDER__`
+}

package/src/migrations/latest/translate-script-whole-file-writes/grit/config-path.grit

@@ -0,0 +1 @@
+`const CONFIG_PATH = path.resolve($dir, 'translate.config.json');` => `__GRIT_INSERT_PLACEHOLDER__`

package/src/migrations/latest/translate-script-whole-file-writes/grit/file-to-translate.grit

@@ -0,0 +1,11 @@
+interface_declaration($name, $body) as $decl where {
+  $name <: `FileToTranslate`,
+  $body <: contains `relativePath: string`,
+  $body <: contains `sourceAbsPath: string`,
+  $body <: contains `sourceContent: string`,
+  $body <: contains `diff: string`,
+  $body <: not contains property_signature(name = $field) where {
+    $field <: not or { `relativePath`, `sourceAbsPath`, `sourceContent`, `diff` }
+  },
+  $decl => `__GRIT_INSERT_PLACEHOLDER__`
+}

package/src/migrations/latest/translate-script-whole-file-writes/grit/get-files-to-translate.grit

@@ -0,0 +1,7 @@
+function_declaration($name, $body) as $decl where {
+  $name <: `getFilesToTranslate`,
+  $body <: contains `const { files: uncommitted } = await git.status()`,
+  $body <: contains `const includedSet = new Set(includedGlob.map((p) => path.resolve(p)))`,
+  $body <: contains `const changed = allCandidates.filter((abs) => includedSet.has(abs))`,
+  $decl => `__GRIT_INSERT_PLACEHOLDER__`
+}

package/src/migrations/latest/translate-script-whole-file-writes/grit/log.grit

@@ -0,0 +1,3 @@
+`const log = $props;` => `__GRIT_INSERT_PLACEHOLDER__` where {
+  $props <: contains `verbose: (m: string) => options.verbose && console.log($_)`
+}

package/src/migrations/latest/translate-script-whole-file-writes/grit/main-call.grit

@@ -0,0 +1 @@
+`main().catch($handler);` => `__GRIT_INSERT_PLACEHOLDER__`

package/src/migrations/latest/translate-script-whole-file-writes/grit/main.grit

@@ -0,0 +1,8 @@
+function_declaration($name, $body) as $decl where {
+  $name <: `main`,
+  $body <: contains `log.error('No target languages configured')`,
+  $body <: contains `log.info('Nothing to translate.')`,
+  $body <: contains `log.info('Done.')`,
+  $body <: contains `await runWithConcurrency(tasks, concurrency)`,
+  $decl => `__GRIT_INSERT_PLACEHOLDER__`
+}

package/src/migrations/latest/translate-script-whole-file-writes/grit/project-root.grit

@@ -0,0 +1 @@
+`const PROJECT_ROOT = path.resolve($dir, '..');` => `__GRIT_INSERT_PLACEHOLDER__`

package/src/migrations/latest/translate-script-whole-file-writes/grit/run-with-concurrency.grit

@@ -0,0 +1,6 @@
+function_declaration($name, $body) as $decl where {
+  $name <: `runWithConcurrency`,
+  $body <: contains `const results: T[] = new Array(tasks.length)`,
+  $body <: contains `await Promise.all(workers)`,
+  $decl => `__GRIT_INSERT_PLACEHOLDER__`
+}

package/src/migrations/latest/translate-script-whole-file-writes/grit/translate-file-for-language.grit

@@ -0,0 +1,6 @@
+function_declaration($name, $body) as $decl where {
+  $name <: `translateFileForLanguage`,
+  $body <: contains `agent.addHook(BeforeToolCallEvent, rejectOutsideDocsDir)`,
+  $body <: contains `const result = await agent.invoke(buildUserPrompt(file, targetLang))`,
+  $decl => `__GRIT_INSERT_PLACEHOLDER__`
+}

package/src/migrations/latest/translate-script-whole-file-writes/metadata.json

@@ -0,0 +1,3 @@
+{
+  "description": "Update the docs translate script to write whole translated files rather than editing them in place"
+}

package/src/migrations/latest/translate-script-whole-file-writes/migration.d.ts

@@ -0,0 +1,2 @@
+import { type MigrationReturnObject, type Tree } from '@nx/devkit';
+export default function migration(tree: Tree): Promise<MigrationReturnObject>;

package/src/migrations/latest/translate-script-whole-file-writes/migration.js

@@ -0,0 +1,103 @@
+/**
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */ import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { getProjects, joinPathFragments } from "@nx/devkit";
+import { TS_ASTRO_DOCS_GENERATOR_INFO } from "../../../ts/astro-docs/generator.js";
+import { insertViaGritQL, matchGritQL } from "../../../utils/ast.js";
+import { formatFilesInSubtree } from "../../../utils/format.js";
+import { isEsmWorkspace } from "../../../utils/module-format.js";
+import { getPackageManagerDisplayCommands } from "../../../utils/pkg-manager.js";
+/**
+ * Rewrite the docs translate script so it writes whole translated files.
+ *
+ * The script used to tell the agent to update an existing translation with
+ * `str_replace` edits. A replacement that did not match cleanly duplicated or
+ * spliced sections, and nothing checked the result, so the damage was committed.
+ * The rewrite also fixes incremental runs, which never matched a changed file in
+ * a generated workspace, and raises the Bedrock socket timeout that made every
+ * large file fail.
+ *
+ * Most of the script changed, so it is rewritten a declaration at a time. Each
+ * pattern in `grit/` matches one declaration as a previous release wrote it and
+ * rewrites it to a placeholder, which `insertViaGritQL` swaps for today's version
+ * from `files/`. Routing the replacement through a placeholder keeps it out of the
+ * pattern: the script is full of template literals, and a GritQL snippet
+ * containing a backtick cannot be parsed.
+ *
+ * Each pattern recognises its declaration by name *and* by statements the released
+ * body contained, so a declaration the user has edited no longer matches. The
+ * rewrite is all or nothing — every pattern must match before anything is written
+ * — so an edited script keeps its whole file and is reported through `nextSteps`
+ * rather than being half-rewritten from two different versions.
+ */ /**
+ * The declarations that changed, in the order they appear in the script. Each name
+ * pairs a `grit/<name>.grit` pattern matching its previous form with a
+ * `files/<name>.ts.fixture` holding its replacement, which carries any new
+ * declarations that follow it.
+ *
+ * `grit/already-migrated.grit` stands apart: it recognises today's script rather
+ * than rewriting anything.
+ */ const REWRITES = [
+    'project-root',
+    'config-path',
+    'file-to-translate',
+    'log',
+    'get-files-to-translate',
+    'build-system-prompt',
+    'build-user-prompt',
+    'translate-file-for-language',
+    'run-with-concurrency',
+    'main',
+    'main-call'
+];
+/** A leading block comment, which GritQL does not match. */ const HEADER_COMMENT = /^\/\*\*[\s\S]*?\*\/\n/;
+const readGritPattern = (name)=>`language js\n${readFileSync(join(import.meta.dirname, 'grit', `${name}.grit`), 'utf-8').trim()}`;
+const readReplacement = (name)=>readFileSync(join(import.meta.dirname, 'files', `${name}.ts.fixture`), 'utf-8');
+/** Fills in the values the generator interpolates when it vends the script. */ const render = (tree, source, fullyQualifiedName)=>source.replace(/<% if \(esm\) \{ %>(.*?)<% \} else \{ %>(.*?)<% \} %>/g, isEsmWorkspace(tree) ? '$1' : '$2').replace(/<%= pkgMgrCmd %>/g, getPackageManagerDisplayCommands().exec).replace(/<%= fullyQualifiedName %>/g, fullyQualifiedName);
+const editedNextStep = (projectName)=>`${projectName}: its scripts/translate.ts has been customised, so it was left as it is. The script now writes each translation as a whole file rather than editing it in place — see https://awslabs.github.io/nx-plugin-for-aws/guides/astro-docs/ for the version it expects.`;
+export default async function migration(tree) {
+    const nextSteps = [];
+    for (const [name, project] of getProjects(tree)){
+        const metadata = project.metadata;
+        if (metadata?.generator !== TS_ASTRO_DOCS_GENERATOR_INFO.id) {
+            continue;
+        }
+        // Absent when the docs site was generated with --noTranslation.
+        const scriptPath = joinPathFragments(project.root, 'scripts', 'translate.ts');
+        if (!tree.exists(scriptPath)) {
+            continue;
+        }
+        // Already migrated: matched by a declaration only today's script has, so a
+        // second run is a no-op rather than a rewrite.
+        if (await matchGritQL(tree, scriptPath, readGritPattern('already-migrated'))) {
+            continue;
+        }
+        // All or nothing: every declaration must still be the one a release vended,
+        // so a partly edited script is never left half-rewritten.
+        const matches = await Promise.all(REWRITES.map((rewrite)=>matchGritQL(tree, scriptPath, readGritPattern(rewrite))));
+        if (!matches.every(Boolean)) {
+            nextSteps.push(editedNextStep(name));
+            continue;
+        }
+        // The header is a leading comment, which GritQL does not reach. Anchored to
+        // the start of the file so the replacement cannot match anything else.
+        tree.write(scriptPath, (tree.read(scriptPath, 'utf-8') ?? '').replace(HEADER_COMMENT, render(tree, readReplacement('header'), name)));
+        // The first release resolved paths from `__dirname` directly, with no
+        // `SCRIPTS_DIR` for the rewrites below to build on.
+        const script = tree.read(scriptPath, 'utf-8') ?? '';
+        if (!/^const SCRIPTS_DIR /m.test(script)) {
+            tree.write(scriptPath, script.replace(/^const PROJECT_ROOT /m, `${render(tree, readReplacement('scripts-dir'), name).trimEnd()}\nconst PROJECT_ROOT `));
+        }
+        for (const rewrite of REWRITES){
+            await insertViaGritQL(tree, scriptPath, readGritPattern(rewrite), render(tree, readReplacement(rewrite), name).trimEnd());
+        }
+    }
+    await formatFilesInSubtree(tree);
+    return {
+        nextSteps
+    };
+}
+
+//# sourceMappingURL=migration.js.map

package/src/migrations/latest/translate-script-whole-file-writes/migration.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../packages/nx-plugin/src/migrations/latest/translate-script-whole-file-writes/migration.ts"],"sourcesContent":["/**\n * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.\n * SPDX-License-Identifier: Apache-2.0\n */\nimport { readFileSync } from 'node:fs';\nimport { join } from 'node:path';\nimport {\n  getProjects,\n  joinPathFragments,\n  type MigrationReturnObject,\n  type Tree,\n} from '@nx/devkit';\nimport { TS_ASTRO_DOCS_GENERATOR_INFO } from '../../../ts/astro-docs/generator';\nimport { insertViaGritQL, matchGritQL } from '../../../utils/ast';\nimport { formatFilesInSubtree } from '../../../utils/format';\nimport { isEsmWorkspace } from '../../../utils/module-format';\nimport { getPackageManagerDisplayCommands } from '../../../utils/pkg-manager';\n\n/**\n * Rewrite the docs translate script so it writes whole translated files.\n *\n * The script used to tell the agent to update an existing translation with\n * `str_replace` edits. A replacement that did not match cleanly duplicated or\n * spliced sections, and nothing checked the result, so the damage was committed.\n * The rewrite also fixes incremental runs, which never matched a changed file in\n * a generated workspace, and raises the Bedrock socket timeout that made every\n * large file fail.\n *\n * Most of the script changed, so it is rewritten a declaration at a time. Each\n * pattern in `grit/` matches one declaration as a previous release wrote it and\n * rewrites it to a placeholder, which `insertViaGritQL` swaps for today's version\n * from `files/`. Routing the replacement through a placeholder keeps it out of the\n * pattern: the script is full of template literals, and a GritQL snippet\n * containing a backtick cannot be parsed.\n *\n * Each pattern recognises its declaration by name *and* by statements the released\n * body contained, so a declaration the user has edited no longer matches. The\n * rewrite is all or nothing — every pattern must match before anything is written\n * — so an edited script keeps its whole file and is reported through `nextSteps`\n * rather than being half-rewritten from two different versions.\n */\n\n/**\n * The declarations that changed, in the order they appear in the script. Each name\n * pairs a `grit/<name>.grit` pattern matching its previous form with a\n * `files/<name>.ts.fixture` holding its replacement, which carries any new\n * declarations that follow it.\n *\n * `grit/already-migrated.grit` stands apart: it recognises today's script rather\n * than rewriting anything.\n */\nconst REWRITES = [\n  'project-root',\n  'config-path',\n  'file-to-translate',\n  'log',\n  'get-files-to-translate',\n  'build-system-prompt',\n  'build-user-prompt',\n  'translate-file-for-language',\n  'run-with-concurrency',\n  'main',\n  'main-call',\n] as const;\n\n/** A leading block comment, which GritQL does not match. */\nconst HEADER_COMMENT = /^\\/\\*\\*[\\s\\S]*?\\*\\/\\n/;\n\nconst readGritPattern = (name: string): string =>\n  `language js\\n${readFileSync(join(import.meta.dirname, 'grit', `${name}.grit`), 'utf-8').trim()}`;\n\nconst readReplacement = (name: string): string =>\n  readFileSync(\n    join(import.meta.dirname, 'files', `${name}.ts.fixture`),\n    'utf-8',\n  );\n\n/** Fills in the values the generator interpolates when it vends the script. */\nconst render = (\n  tree: Tree,\n  source: string,\n  fullyQualifiedName: string,\n): string =>\n  source\n    .replace(\n      /<% if \\(esm\\) \\{ %>(.*?)<% \\} else \\{ %>(.*?)<% \\} %>/g,\n      isEsmWorkspace(tree) ? '$1' : '$2',\n    )\n    .replace(/<%= pkgMgrCmd %>/g, getPackageManagerDisplayCommands().exec)\n    .replace(/<%= fullyQualifiedName %>/g, fullyQualifiedName);\n\nconst editedNextStep = (projectName: string): string =>\n  `${projectName}: its scripts/translate.ts has been customised, so it was left as it is. The script now writes each translation as a whole file rather than editing it in place — see https://awslabs.github.io/nx-plugin-for-aws/guides/astro-docs/ for the version it expects.`;\n\nexport default async function migration(\n  tree: Tree,\n): Promise<MigrationReturnObject> {\n  const nextSteps: string[] = [];\n\n  for (const [name, project] of getProjects(tree)) {\n    const metadata = project.metadata as { generator?: string } | undefined;\n    if (metadata?.generator !== TS_ASTRO_DOCS_GENERATOR_INFO.id) {\n      continue;\n    }\n\n    // Absent when the docs site was generated with --noTranslation.\n    const scriptPath = joinPathFragments(\n      project.root,\n      'scripts',\n      'translate.ts',\n    );\n    if (!tree.exists(scriptPath)) {\n      continue;\n    }\n\n    // Already migrated: matched by a declaration only today's script has, so a\n    // second run is a no-op rather than a rewrite.\n    if (\n      await matchGritQL(tree, scriptPath, readGritPattern('already-migrated'))\n    ) {\n      continue;\n    }\n\n    // All or nothing: every declaration must still be the one a release vended,\n    // so a partly edited script is never left half-rewritten.\n    const matches = await Promise.all(\n      REWRITES.map((rewrite) =>\n        matchGritQL(tree, scriptPath, readGritPattern(rewrite)),\n      ),\n    );\n    if (!matches.every(Boolean)) {\n      nextSteps.push(editedNextStep(name));\n      continue;\n    }\n\n    // The header is a leading comment, which GritQL does not reach. Anchored to\n    // the start of the file so the replacement cannot match anything else.\n    tree.write(\n      scriptPath,\n      (tree.read(scriptPath, 'utf-8') ?? '').replace(\n        HEADER_COMMENT,\n        render(tree, readReplacement('header'), name),\n      ),\n    );\n\n    // The first release resolved paths from `__dirname` directly, with no\n    // `SCRIPTS_DIR` for the rewrites below to build on.\n    const script = tree.read(scriptPath, 'utf-8') ?? '';\n    if (!/^const SCRIPTS_DIR /m.test(script)) {\n      tree.write(\n        scriptPath,\n        script.replace(\n          /^const PROJECT_ROOT /m,\n          `${render(tree, readReplacement('scripts-dir'), name).trimEnd()}\\nconst PROJECT_ROOT `,\n        ),\n      );\n    }\n\n    for (const rewrite of REWRITES) {\n      await insertViaGritQL(\n        tree,\n        scriptPath,\n        readGritPattern(rewrite),\n        render(tree, readReplacement(rewrite), name).trimEnd(),\n      );\n    }\n  }\n\n  await formatFilesInSubtree(tree);\n\n  return { nextSteps };\n}\n"],"names":["readFileSync","join","getProjects","joinPathFragments","TS_ASTRO_DOCS_GENERATOR_INFO","insertViaGritQL","matchGritQL","formatFilesInSubtree","isEsmWorkspace","getPackageManagerDisplayCommands","REWRITES","HEADER_COMMENT","readGritPattern","name","dirname","trim","readReplacement","render","tree","source","fullyQualifiedName","replace","exec","editedNextStep","projectName","migration","nextSteps","project","metadata","generator","id","scriptPath","root","exists","matches","Promise","all","map","rewrite","every","Boolean","push","write","read","script","test","trimEnd"],"mappings":"AAAA;;;CAGC,GACD,SAASA,YAAY,QAAQ,UAAU;AACvC,SAASC,IAAI,QAAQ,YAAY;AACjC,SACEC,WAAW,EACXC,iBAAiB,QAGZ,aAAa;AACpB,SAASC,4BAA4B,QAAQ,sCAAmC;AAChF,SAASC,eAAe,EAAEC,WAAW,QAAQ,wBAAqB;AAClE,SAASC,oBAAoB,QAAQ,2BAAwB;AAC7D,SAASC,cAAc,QAAQ,kCAA+B;AAC9D,SAASC,gCAAgC,QAAQ,gCAA6B;AAE9E;;;;;;;;;;;;;;;;;;;;;;CAsBC,GAED;;;;;;;;CAQC,GACD,MAAMC,WAAW;IACf;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;CACD;AAED,0DAA0D,GAC1D,MAAMC,iBAAiB;AAEvB,MAAMC,kBAAkB,CAACC,OACvB,CAAC,aAAa,EAAEb,aAAaC,KAAK,YAAYa,OAAO,EAAE,QAAQ,GAAGD,KAAK,KAAK,CAAC,GAAG,SAASE,IAAI,IAAI;AAEnG,MAAMC,kBAAkB,CAACH,OACvBb,aACEC,KAAK,YAAYa,OAAO,EAAE,SAAS,GAAGD,KAAK,WAAW,CAAC,GACvD;AAGJ,6EAA6E,GAC7E,MAAMI,SAAS,CACbC,MACAC,QACAC,qBAEAD,OACGE,OAAO,CACN,0DACAb,eAAeU,QAAQ,OAAO,MAE/BG,OAAO,CAAC,qBAAqBZ,mCAAmCa,IAAI,EACpED,OAAO,CAAC,8BAA8BD;AAE3C,MAAMG,iBAAiB,CAACC,cACtB,GAAGA,YAAY,gQAAgQ,CAAC;AAElR,eAAe,eAAeC,UAC5BP,IAAU;IAEV,MAAMQ,YAAsB,EAAE;IAE9B,KAAK,MAAM,CAACb,MAAMc,QAAQ,IAAIzB,YAAYgB,MAAO;QAC/C,MAAMU,WAAWD,QAAQC,QAAQ;QACjC,IAAIA,UAAUC,cAAczB,6BAA6B0B,EAAE,EAAE;YAC3D;QACF;QAEA,gEAAgE;QAChE,MAAMC,aAAa5B,kBACjBwB,QAAQK,IAAI,EACZ,WACA;QAEF,IAAI,CAACd,KAAKe,MAAM,CAACF,aAAa;YAC5B;QACF;QAEA,2EAA2E;QAC3E,+CAA+C;QAC/C,IACE,MAAMzB,YAAYY,MAAMa,YAAYnB,gBAAgB,sBACpD;YACA;QACF;QAEA,4EAA4E;QAC5E,0DAA0D;QAC1D,MAAMsB,UAAU,MAAMC,QAAQC,GAAG,CAC/B1B,SAAS2B,GAAG,CAAC,CAACC,UACZhC,YAAYY,MAAMa,YAAYnB,gBAAgB0B;QAGlD,IAAI,CAACJ,QAAQK,KAAK,CAACC,UAAU;YAC3Bd,UAAUe,IAAI,CAAClB,eAAeV;YAC9B;QACF;QAEA,4EAA4E;QAC5E,uEAAuE;QACvEK,KAAKwB,KAAK,CACRX,YACA,AAACb,CAAAA,KAAKyB,IAAI,CAACZ,YAAY,YAAY,EAAC,EAAGV,OAAO,CAC5CV,gBACAM,OAAOC,MAAMF,gBAAgB,WAAWH;QAI5C,sEAAsE;QACtE,oDAAoD;QACpD,MAAM+B,SAAS1B,KAAKyB,IAAI,CAACZ,YAAY,YAAY;QACjD,IAAI,CAAC,uBAAuBc,IAAI,CAACD,SAAS;YACxC1B,KAAKwB,KAAK,CACRX,YACAa,OAAOvB,OAAO,CACZ,yBACA,GAAGJ,OAAOC,MAAMF,gBAAgB,gBAAgBH,MAAMiC,OAAO,GAAG,qBAAqB,CAAC;QAG5F;QAEA,KAAK,MAAMR,WAAW5B,SAAU;YAC9B,MAAML,gBACJa,MACAa,YACAnB,gBAAgB0B,UAChBrB,OAAOC,MAAMF,gBAAgBsB,UAAUzB,MAAMiC,OAAO;QAExD;IACF;IAEA,MAAMvC,qBAAqBW;IAE3B,OAAO;QAAEQ;IAAU;AACrB"}