@aws/nx-plugin 1.0.0-rc.66 → 1.0.0-rc.68

package/migrations.json

@@ -2,6 +2,16 @@
   "$schema": "http://json-schema.org/schema",
   "name": "@aws/nx-plugin",
   "generators": {
+    "latest-smithy-server-package-rename": {
+      "version": "1.0.0-rc.67",
+      "description": "Move Smithy APIs onto the renamed @smithy/server-* packages",
+      "implementation": "./src/migrations/latest/smithy-server-package-rename/migration"
+    },
+    "latest-translate-script-whole-file-writes": {
+      "version": "1.0.0-rc.68",
+      "description": "Update the docs translate script to write whole translated files rather than editing them in place",
+      "implementation": "./src/migrations/latest/translate-script-whole-file-writes/migration"
+    },
     "v1.0.0-rc.50-0001-modernize-function-props-cast": {
       "version": "1.0.0-rc.50",
       "description": "Replace the legacy angle-bracket FunctionProps type assertion with the modern as syntax in generated API constructs",
@@ -98,7 +108,7 @@
       "implementation": "./src/migrations/v1.0.0-rc.65/0002-rolldown-code-splitting/migration"
     },
     "sync-vended-versions": {
-      "version": "1.0.0-rc.66",
+      "version": "1.0.0-rc.68",
       "description": "Sync vended dependency versions and the tracked plugin version to those vended by this release",
       "implementation": "./src/utils/version-upgrade-migration/migration"
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aws/nx-plugin",
-  "version": "1.0.0-rc.66",
+  "version": "1.0.0-rc.68",
   "repository": {
     "type": "git",
     "url": "https://github.com/awslabs/nx-plugin-for-aws.git",

package/src/migrations/latest/smithy-server-package-rename/metadata.json

@@ -0,0 +1,3 @@
+{
+  "description": "Move Smithy APIs onto the renamed @smithy/server-* packages"
+}

package/src/migrations/latest/smithy-server-package-rename/migration.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { type MigrationReturnObject, type Tree } from '@nx/devkit';
+export default function migration(tree: Tree): Promise<MigrationReturnObject>;

package/src/migrations/latest/smithy-server-package-rename/migration.js

@@ -0,0 +1,123 @@
+/**
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */ import { getProjects, joinPathFragments, readJson, updateJson } from "@nx/devkit";
+import { applyGritQL, matchGritQL } from "../../../utils/ast.js";
+import { formatFilesInSubtree } from "../../../utils/format.js";
+/**
+ * Move a Smithy API onto the renamed `@smithy/server-*` packages.
+ *
+ * The Smithy server runtime was published as `@aws-smithy/server-*`, stopped at
+ * `1.0.0-alpha.10`, and was renamed to `@smithy/server-*`. The Server SDK codegen
+ * this release vends generates against the renamed packages, importing
+ * `AuthScheme` and `ServerInterceptor` — types the deprecated packages never
+ * exported — so a workspace left on them fails to bundle its SSDK.
+ *
+ * Both the imports and the declarations move: the renamed packages are no longer
+ * the same names, so the version sync cannot recognise the old ones and would
+ * leave them installed alongside the new.
+ *
+ * Guardrails:
+ * - Scoped to a Smithy API project this plugin generated, found through the
+ *   metadata the generator records. A file of the user's own that happens to
+ *   import these packages is left alone.
+ * - Imports are rewritten by module specifier, preserving whatever the file
+ *   imports from it, so a project that imports more than the generated shape
+ *   keeps its own bindings. Only the two packages the generators vend are
+ *   matched: `@aws-smithy/server-common` is a transitive dependency of those and
+ *   is never declared or imported directly.
+ * - A manifest is only rewritten where it declares the old package, and the new
+ *   name takes the field the old one occupied. A workspace that already moved
+ *   itself is left alone.
+ * - Idempotent: nothing matches the old names once they are gone.
+ *
+ * Every value here is hardcoded rather than read from the generators: this runs
+ * once, for the release that renamed the packages, so it has to keep applying
+ * that exact change however far the vended versions and generators move
+ * afterwards.
+ */ /** The id the `ts#smithy-api` generator records on the projects it creates. */ const SMITHY_API_GENERATOR_ID = 'ts#smithy-api';
+/** The renamed packages, old name to new, with the version this release vends. */ const RENAMES = [
+    {
+        old: '@aws-smithy/server-apigateway',
+        renamed: '@smithy/server-apigateway',
+        version: '0.2.0'
+    },
+    {
+        old: '@aws-smithy/server-node',
+        renamed: '@smithy/server-node',
+        version: '0.2.0'
+    }
+];
+/** The source files the generators give these imports. */ const SOURCE_FILES = [
+    'src/handler.ts',
+    'src/local-server.ts'
+];
+/**
+ * Rewrite an import's module specifier, keeping its bindings — `$bindings` holds
+ * whatever the file imports, so a binding the project added survives the move.
+ */ const importPattern = (from, to)=>`\`import { $bindings } from '${from}'\` => \`import { $bindings } from '${to}'\``;
+/** Whether the file still imports the old package under any other form. */ const hasRemainingImport = (from)=>`\`import $_ from '${from}'\``;
+/** Rename the packages a manifest declares, reporting whether anything changed. */ const renameInManifest = (tree, path)=>{
+    if (!tree.exists(path)) {
+        return false;
+    }
+    const json = readJson(tree, path);
+    const fields = [
+        'dependencies',
+        'devDependencies'
+    ].filter((field)=>RENAMES.some(({ old })=>json[field]?.[old]));
+    if (fields.length === 0) {
+        return false;
+    }
+    updateJson(tree, path, (manifest)=>{
+        for (const field of fields){
+            const declared = manifest[field];
+            for (const { old, renamed, version } of RENAMES){
+                if (!declared[old]) {
+                    continue;
+                }
+                delete declared[old];
+                // The vended pin rather than the old specifier: the renamed line
+                // restarted at 0.x, so carrying `1.0.0-alpha.10` across resolves nothing.
+                declared[renamed] = version;
+            }
+        }
+        return manifest;
+    });
+    return true;
+};
+const divergedNextStep = (path)=>`${path}: still imports a deprecated '@aws-smithy/server-*' package in a form this migration does not rewrite - update the import to the matching '@smithy/server-*' package by hand.`;
+export default async function migration(tree) {
+    const nextSteps = [];
+    // Only a Smithy API project this plugin generated carries these packages.
+    const projects = [
+        ...getProjects(tree).values()
+    ].filter((project)=>project.metadata?.generator === SMITHY_API_GENERATOR_ID);
+    for (const project of projects){
+        for (const sourceFile of SOURCE_FILES){
+            const sourcePath = joinPathFragments(project.root, sourceFile);
+            if (!tree.exists(sourcePath)) {
+                continue;
+            }
+            for (const { old, renamed } of RENAMES){
+                await applyGritQL(tree, sourcePath, importPattern(old, renamed));
+                // A namespace or default import of the same package is left as it is —
+                // reported rather than rewritten, so a diverged file is never clobbered.
+                if (await matchGritQL(tree, sourcePath, hasRemainingImport(old))) {
+                    nextSteps.push(divergedNextStep(sourcePath));
+                }
+            }
+        }
+        renameInManifest(tree, joinPathFragments(project.root, 'package.json'));
+    }
+    // A workspace may hoist these to the root manifest, which is not an nx project.
+    if (projects.length > 0) {
+        renameInManifest(tree, 'package.json');
+    }
+    await formatFilesInSubtree(tree);
+    return {
+        nextSteps
+    };
+}
+
+//# sourceMappingURL=migration.js.map

package/src/migrations/latest/smithy-server-package-rename/migration.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../packages/nx-plugin/src/migrations/latest/smithy-server-package-rename/migration.ts"],"sourcesContent":["/**\n * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.\n * SPDX-License-Identifier: Apache-2.0\n */\nimport {\n  getProjects,\n  joinPathFragments,\n  type MigrationReturnObject,\n  readJson,\n  type Tree,\n  updateJson,\n} from '@nx/devkit';\nimport { applyGritQL, matchGritQL } from '../../../utils/ast';\nimport { formatFilesInSubtree } from '../../../utils/format';\n\n/**\n * Move a Smithy API onto the renamed `@smithy/server-*` packages.\n *\n * The Smithy server runtime was published as `@aws-smithy/server-*`, stopped at\n * `1.0.0-alpha.10`, and was renamed to `@smithy/server-*`. The Server SDK codegen\n * this release vends generates against the renamed packages, importing\n * `AuthScheme` and `ServerInterceptor` — types the deprecated packages never\n * exported — so a workspace left on them fails to bundle its SSDK.\n *\n * Both the imports and the declarations move: the renamed packages are no longer\n * the same names, so the version sync cannot recognise the old ones and would\n * leave them installed alongside the new.\n *\n * Guardrails:\n * - Scoped to a Smithy API project this plugin generated, found through the\n *   metadata the generator records. A file of the user's own that happens to\n *   import these packages is left alone.\n * - Imports are rewritten by module specifier, preserving whatever the file\n *   imports from it, so a project that imports more than the generated shape\n *   keeps its own bindings. Only the two packages the generators vend are\n *   matched: `@aws-smithy/server-common` is a transitive dependency of those and\n *   is never declared or imported directly.\n * - A manifest is only rewritten where it declares the old package, and the new\n *   name takes the field the old one occupied. A workspace that already moved\n *   itself is left alone.\n * - Idempotent: nothing matches the old names once they are gone.\n *\n * Every value here is hardcoded rather than read from the generators: this runs\n * once, for the release that renamed the packages, so it has to keep applying\n * that exact change however far the vended versions and generators move\n * afterwards.\n */\n\n/** The id the `ts#smithy-api` generator records on the projects it creates. */\nconst SMITHY_API_GENERATOR_ID = 'ts#smithy-api';\n\n/** The renamed packages, old name to new, with the version this release vends. */\nconst RENAMES = [\n  {\n    old: '@aws-smithy/server-apigateway',\n    renamed: '@smithy/server-apigateway',\n    version: '0.2.0',\n  },\n  {\n    old: '@aws-smithy/server-node',\n    renamed: '@smithy/server-node',\n    version: '0.2.0',\n  },\n] as const;\n\n/** The source files the generators give these imports. */\nconst SOURCE_FILES = ['src/handler.ts', 'src/local-server.ts'];\n\n/**\n * Rewrite an import's module specifier, keeping its bindings — `$bindings` holds\n * whatever the file imports, so a binding the project added survives the move.\n */\nconst importPattern = (from: string, to: string): string =>\n  `\\`import { $bindings } from '${from}'\\` => \\`import { $bindings } from '${to}'\\``;\n\n/** Whether the file still imports the old package under any other form. */\nconst hasRemainingImport = (from: string): string =>\n  `\\`import $_ from '${from}'\\``;\n\n/** Rename the packages a manifest declares, reporting whether anything changed. */\nconst renameInManifest = (tree: Tree, path: string): boolean => {\n  if (!tree.exists(path)) {\n    return false;\n  }\n  const json = readJson(tree, path);\n  const fields = (['dependencies', 'devDependencies'] as const).filter(\n    (field) => RENAMES.some(({ old }) => json[field]?.[old]),\n  );\n  if (fields.length === 0) {\n    return false;\n  }\n  updateJson(tree, path, (manifest) => {\n    for (const field of fields) {\n      const declared = manifest[field] as Record<string, string>;\n      for (const { old, renamed, version } of RENAMES) {\n        if (!declared[old]) {\n          continue;\n        }\n        delete declared[old];\n        // The vended pin rather than the old specifier: the renamed line\n        // restarted at 0.x, so carrying `1.0.0-alpha.10` across resolves nothing.\n        declared[renamed] = version;\n      }\n    }\n    return manifest;\n  });\n  return true;\n};\n\nconst divergedNextStep = (path: string): string =>\n  `${path}: still imports a deprecated '@aws-smithy/server-*' package in a form this migration does not rewrite - update the import to the matching '@smithy/server-*' package by hand.`;\n\nexport default async function migration(\n  tree: Tree,\n): Promise<MigrationReturnObject> {\n  const nextSteps: string[] = [];\n\n  // Only a Smithy API project this plugin generated carries these packages.\n  const projects = [...getProjects(tree).values()].filter(\n    (project) =>\n      (project.metadata as { generator?: string } | undefined)?.generator ===\n      SMITHY_API_GENERATOR_ID,\n  );\n\n  for (const project of projects) {\n    for (const sourceFile of SOURCE_FILES) {\n      const sourcePath = joinPathFragments(project.root, sourceFile);\n      if (!tree.exists(sourcePath)) {\n        continue;\n      }\n      for (const { old, renamed } of RENAMES) {\n        await applyGritQL(tree, sourcePath, importPattern(old, renamed));\n        // A namespace or default import of the same package is left as it is —\n        // reported rather than rewritten, so a diverged file is never clobbered.\n        if (await matchGritQL(tree, sourcePath, hasRemainingImport(old))) {\n          nextSteps.push(divergedNextStep(sourcePath));\n        }\n      }\n    }\n\n    renameInManifest(tree, joinPathFragments(project.root, 'package.json'));\n  }\n\n  // A workspace may hoist these to the root manifest, which is not an nx project.\n  if (projects.length > 0) {\n    renameInManifest(tree, 'package.json');\n  }\n\n  await formatFilesInSubtree(tree);\n\n  return { nextSteps };\n}\n"],"names":["getProjects","joinPathFragments","readJson","updateJson","applyGritQL","matchGritQL","formatFilesInSubtree","SMITHY_API_GENERATOR_ID","RENAMES","old","renamed","version","SOURCE_FILES","importPattern","from","to","hasRemainingImport","renameInManifest","tree","path","exists","json","fields","filter","field","some","length","manifest","declared","divergedNextStep","migration","nextSteps","projects","values","project","metadata","generator","sourceFile","sourcePath","root","push"],"mappings":"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"}

package/src/migrations/latest/translate-script-whole-file-writes/files/build-system-prompt.ts.fixture

@@ -0,0 +1,23 @@
+function buildSystemPrompt(targetLang: string): string {
+  return `You are an expert technical-documentation translator. You translate MDX documentation files from the source locale \`${config.sourceLanguage}\` into the target locale \`${targetLang}\`.
+
+Both are locale codes (ISO 639-1 / BCP-47 style, or short forms like \`jp\`, \`zh\`, \`pt\`). Translate naturally into the language the target code identifies.
+
+Use the \`fileEditor\` tool to read the files you are given and to write your translation. Read a long file in slices with \`view_range\`. Use the absolute paths exactly as given — write to the target path verbatim, never to a variation of it.
+
+Translate the prose. Everything else is copied from the source exactly as it is:
+
+- Code blocks. Reproduce each one character for character: the language and \`title\` on the opening fence, and every line of the body. Comments inside code are code — a \`# Creates a new subsegment\` stays in English. Never translate anything between the fences.
+- Inline code, URLs, link paths, \`import\` statements, component names, JSX attributes, and \`<Snippet name="..." />\` values.
+- Product, service, and people's names, and package names such as \`@aws/nx-plugin\` — translate no part of them, even where they appear in prose or in a \`title\`.
+- The MDX structure itself: frontmatter delimiters, heading levels, lists, and the blank lines between blocks. Add none and remove none.
+
+Two things do change:
+
+- In frontmatter, translate only \`title\` and \`description\`. Leave every other key and value alone. Frontmatter is YAML, so wrap a value in double quotes whenever it would otherwise begin with a character YAML reserves — for example a title starting with \`@aws/nx-plugin\` must be written as \`"@aws/nx-plugin ..."\`.
+- Rewrite link paths that embed the source locale (\`/${config.sourceLanguage}/foo\` becomes \`/${targetLang}/foo\`), and make a \`parentHeading\` match the translated heading it sits under.
+
+Write the finished file in one \`create\` call, and never with \`str_replace\` — a partial replacement silently duplicates or splices sections. Do not wrap the file in triple backticks.
+
+When the file is written, reply with a one-line summary and stop.`;
+}

package/src/migrations/latest/translate-script-whole-file-writes/files/build-user-prompt.ts.fixture

@@ -0,0 +1,96 @@
+function buildUserPrompt(file: FileToTranslate, targetLang: string): string {
+  const targetAbsPath = path.join(DOCS_DIR, targetLang, file.relativePath);
+
+  if (!file.diffPath) {
+    return `Translate \`${file.sourceAbsPath}\` into locale \`${targetLang}\` and write it to \`${targetAbsPath}\`.
+
+Read the source, then write the whole translated file with \`create\`. Always write it, even if a translation is already there — it may be out of date.`;
+  }
+
+  return `Update the \`${targetLang}\` translation of \`${file.sourceAbsPath}\`.
+
+- Source: \`${file.sourceAbsPath}\`
+- Existing translation to update: \`${targetAbsPath}\`
+- Diff of what changed in the source: \`${file.diffPath}\`
+
+Read all three. Retranslate only what the diff touched, keep the existing translated wording everywhere else, then write the whole file back with \`create\`.`;
+}
+
+const FENCE_RE = /^\s*(?:`{3,}|~{3,})/;
+
+/**
+ * Split a document into alternating prose and fenced-code segments.
+ */
+function splitOnFences(text: string): { prose: string[]; code: string[] } {
+  const prose: string[] = [];
+  const code: string[] = [];
+  let current: string[] = [];
+  let inFence = false;
+  for (const line of text.split('\n')) {
+    if (FENCE_RE.test(line)) {
+      (inFence ? code : prose).push(current.concat(line).join('\n'));
+      current = [];
+      inFence = !inFence;
+      continue;
+    }
+    current.push(line);
+  }
+  (inFence ? code : prose).push(current.join('\n'));
+  return { prose, code };
+}
+
+/**
+ * YAML frontmatter must still parse after translation. A value that begins with
+ * a character YAML reserves — most often a title starting with \`@aws/...\` —
+ * breaks the docs build, so reject it here and let the retry quote it.
+ */
+function assertFrontmatterIsParseable(text: string): void {
+  const lines = text.split('\n');
+  if (lines[0]?.trim() !== '---') return;
+  for (let i = 1; i < lines.length && lines[i].trim() !== '---'; i++) {
+    const value = lines[i].match(/^[A-Za-z0-9_-]+:\s+(\S)/)?.[1];
+    if (value && '@*&%!|>'.includes(value)) {
+      throw new Error(
+        `frontmatter line ${i + 1} starts with the reserved YAML character "${value}" and must be quoted: ${lines[i].trim()}`,
+      );
+    }
+  }
+}
+
+/**
+ * Copy the source's code blocks over the translated file's. The prompt tells the
+ * agent to reproduce them verbatim, but it occasionally translates a comment
+ * anyway, which would ship stale or broken code.
+ *
+ * A differing block count means the translation lost the document's shape —
+ * usually a section duplicated or dropped — so this throws rather than stitching
+ * mismatched blocks together, letting the caller retry.
+ */
+async function restoreCodeBlocks(
+  sourceAbsPath: string,
+  targetAbsPath: string,
+): Promise<void> {
+  const source = splitOnFences(await fs.readFile(sourceAbsPath, 'utf-8'));
+  const target = splitOnFences(await fs.readFile(targetAbsPath, 'utf-8'));
+
+  if (source.code.length !== target.code.length) {
+    throw new Error(
+      `translation has ${target.code.length} code block(s) but the source has ${source.code.length}`,
+    );
+  }
+  if (source.code.length === 0) return;
+
+  const merged = target.prose.flatMap((chunk, i) =>
+    i < source.code.length ? [chunk, source.code[i]] : [chunk],
+  );
+  await fs.writeFile(targetAbsPath, merged.join('\n'), 'utf-8');
+}
+
+/**
+ * Number of times to retry a single (file x language) translation. Large files
+ * occasionally hit transient Bedrock streaming errors; a fresh agent invocation
+ * re-reads the files from disk, so retries are idempotent.
+ */
+const TRANSLATE_MAX_ATTEMPTS = 4;
+
+const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));

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

@@ -0,0 +1 @@
+const CONFIG_PATH = path.resolve(SCRIPTS_DIR, 'translate.config.json');

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

@@ -0,0 +1,10 @@
+interface FileToTranslate {
+  relativePath: string;
+  sourceAbsPath: string;
+  /**
+   * Path to a file holding the source diff, or undefined when there is no prior
+   * translation to update. Passed to the agent as a path rather than inlined
+   * into the prompt, so it reads only as much of it as it needs.
+   */
+  diffPath?: string;
+}

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<% } %>;