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

package/src/migrations/latest/translate-script-whole-file-writes/test-fixtures/released-script.ts.fixture

@@ -0,0 +1,431 @@
+/**
+ * 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 gathers the set of changed source docs + their git diffs and hands
+ * them to an agent that has read/write access (scoped to the docs directory)
+ * via a wrapped version of the built-in `fileEditor` tool. The agent decides
+ * how to translate each file and writes the output itself.
+ */
+import { Command } from 'commander';
+import fs from 'fs-extra';
+import path from 'path';
+import { simpleGit } from 'simple-git';
+import glob from 'fast-glob';
+import { Agent, BeforeToolCallEvent } from '@strands-agents/sdk';
+import { BedrockModel } from '@strands-agents/sdk/models/bedrock';
+import { fileEditor } from '@strands-agents/sdk/vended-tools/file-editor';
+
+interface TranslateConfig {
+  sourceLanguage: string;
+  targetLanguages: string[];
+  docsDir: string;
+  include: string[];
+  exclude: string[];
+  modelId: string;
+  awsRegion: string;
+  /**
+   * Maximum number of (file x language) translations running in parallel. Each one
+   * is a fresh agent invocation, so this caps concurrent Bedrock requests.
+   * Defaults to 5 when omitted.
+   */
+  concurrency?: number;
+  /**
+   * Commit message marker used to identify previous translation commits, so
+   * incremental runs only re-translate changes since the last translation.
+   * Defaults to "docs: update translations".
+   */
+  translationCommitMessage?: string;
+}
+
+const SCRIPTS_DIR = <% if (esm) { %>import.meta.dirname<% } else { %>__dirname<% } %>;
+const PROJECT_ROOT = path.resolve(SCRIPTS_DIR, '..');
+const CONFIG_PATH = path.resolve(SCRIPTS_DIR, 'translate.config.json');
+const config: TranslateConfig = JSON.parse(
+  fs.readFileSync(CONFIG_PATH, 'utf-8'),
+);
+const DOCS_DIR = path.resolve(PROJECT_ROOT, config.docsDir);
+const TRANSLATION_COMMIT_MESSAGE =
+  config.translationCommitMessage ?? 'docs: update translations';
+
+/**
+ * Reject any `fileEditor` call whose `path` resolves outside the configured
+ * docs directory. Runs as a `BeforeToolCallEvent` hook so we reuse the
+ * built-in tool's schema/description verbatim — nothing else uses fileEditor in
+ * this script, so the check is unconditional.
+ */
+function rejectOutsideDocsDir(event: BeforeToolCallEvent): void {
+  if (event.toolUse.name !== 'fileEditor') return;
+  const input = event.toolUse.input as { path?: unknown };
+  if (typeof input.path !== 'string') return;
+  const resolved = path.resolve(input.path);
+  const docsDirWithSep = DOCS_DIR.endsWith(path.sep)
+    ? DOCS_DIR
+    : DOCS_DIR + path.sep;
+  if (resolved !== DOCS_DIR && !resolved.startsWith(docsDirWithSep)) {
+    event.cancel = `Path ${resolved} is outside the docs directory (${DOCS_DIR}); refusing access.`;
+  }
+}
+
+interface FileToTranslate {
+  relativePath: string;
+  sourceAbsPath: string;
+  sourceContent: string;
+  /** Empty when this is a newly-added file. */
+  diff: string;
+}
+
+const program = new Command();
+program
+  .name('translate')
+  .description('Translate documentation files using a Strands agent')
+  .option('-a, --all', 'Translate all source documentation files')
+  .option(
+    '-l, --languages <languages>',
+    'Comma-separated list of target languages (overrides translate.config.json)',
+  )
+  .option(
+    '-d, --dry-run',
+    'Show what would be translated without invoking the agent',
+  )
+  .option('-v, --verbose', 'Show verbose output')
+  .parse(process.argv);
+const options = program.opts();
+
+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}`),
+};
+
+/**
+ * Gather the set of source-language files to translate, with their diffs.
+ */
+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 Promise.all(
+      files.map(async (file) => ({
+        relativePath: path.relative(sourceLangRoot, file),
+        sourceAbsPath: file,
+        sourceContent: await fs.readFile(file, 'utf-8'),
+        diff: '',
+      })),
+    );
+  }
+
+  const git = simpleGit();
+
+  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(process.cwd(), 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 sourceContent = await fs.readFile(file, 'utf-8');
+      let diff = '';
+      try {
+        diff = await git.diff([
+          `${baseCommit}..HEAD`,
+          '--',
+          path.relative(process.cwd(), file),
+        ]);
+      } catch {
+        // treat as new file
+      }
+      return {
+        relativePath: path.relative(sourceLangRoot, file),
+        sourceAbsPath: file,
+        sourceContent,
+        diff,
+      };
+    }),
+  );
+}
+
+function buildSystemPrompt(targetLang: string): string {
+  return `You are an expert technical-documentation translator. Your job is to translate a single MDX documentation file from the source locale \`${config.sourceLanguage}\` into the target locale \`${targetLang}\`.
+
+Both values are locale codes (e.g. ISO 639-1 / BCP-47 style, or common short forms like \`jp\`, \`zh\`, \`pt\`). Interpret them yourself and translate naturally into the language they identify. If a code is ambiguous, prefer the most widely used written form.
+
+You have one tool available: \`fileEditor\`. Use it to:
+- Read the source file (\`command: "view"\`). For large files you can read a portion at a time using \`view_range\`, then request the next range.
+- Read the existing translation if one is provided (\`command: "view"\`).
+- Write the translated file (\`command: "create"\` — it overwrites).
+
+Translation rules:
+1. Translate natural-language prose into the target language. Keep technical accuracy.
+2. DO NOT translate:
+   - Code blocks and inline code (text inside backticks)
+   - URLs, link paths, and HTML/JSX/MDX tag names and attributes
+   - \`import\` statements, component names, and frontmatter keys
+   - Proper names of people, products, or AWS services
+3. Preserve every aspect of the MDX structure exactly: frontmatter delimiters, headings, lists, code blocks, MDX components, JSX, whitespace, blank lines.
+4. For frontmatter:
+   - Translate only string values for the \`title\` and \`description\` keys.
+   - Leave \`date\`, \`authors\`, \`template\`, \`slug\`, and all other keys untouched.
+5. If any localised link paths embed the source locale (e.g. \`/${config.sourceLanguage}/foo\`), rewrite them to the target locale (\`/${targetLang}/foo\`).
+6. Efficiency rule: if an existing translation is provided AND a diff is provided, reuse the existing translation verbatim for any section of the document that is NOT touched by the diff. Only retranslate sections that actually changed. Still emit the complete final file.
+7. If no existing translation exists, translate the whole file.
+8. Never wrap the file output in triple backticks.
+9. Always use absolute paths with \`fileEditor\`.
+
+When the translated file has been written, reply with a one-line summary and stop.`;
+}
+
+function buildUserPrompt(
+  file: FileToTranslate,
+  targetLang: string,
+): string {
+  const targetLangRoot = path.join(DOCS_DIR, targetLang);
+  const targetAbsPath = path.join(targetLangRoot, file.relativePath);
+  const existingTranslationExists = fs.existsSync(targetAbsPath);
+
+  const diffBlock = file.diff
+    ? `Git diff showing what changed in the source since the last translation:\n\`\`\`diff\n${file.diff.slice(0, 40_000)}\n\`\`\``
+    : 'There is no prior diff for this file — treat it as new content and translate in full.';
+
+  const existingBlock = existingTranslationExists
+    ? `An existing translation for locale \`${targetLang}\` already lives at:\n  \`${targetAbsPath}\`\nRead it with \`fileEditor\` (\`command: "view"\`) before writing so you can reuse any sections that have not changed.`
+    : `No existing translation exists yet — you will create it fresh.`;
+
+  return `Translate one file from source locale \`${config.sourceLanguage}\` into target locale \`${targetLang}\`.
+
+- Source file (read from here): \`${file.sourceAbsPath}\`
+- Target file (write the translation here, absolute path): \`${targetAbsPath}\`
+
+${existingBlock}
+
+${diffBlock}
+
+Steps:
+1. Read the source file. If it is long, read it in slices using \`view_range\`.
+2. If an existing translation is present, read it first so you can reuse unchanged sections.
+3. Write the full translated file to the target path using \`command: "create"\`.
+4. Reply with a single short confirmation line.`;
+}
+
+async function translateFileForLanguage(
+  file: FileToTranslate,
+  targetLang: string,
+): Promise<void> {
+  const targetAbsPath = path.join(
+    DOCS_DIR,
+    targetLang,
+    file.relativePath,
+  );
+  const beforeMtimeMs = fs.existsSync(targetAbsPath)
+    ? (await fs.stat(targetAbsPath)).mtimeMs
+    : 0;
+
+  const agent = new Agent({
+    model: new BedrockModel({
+      modelId: config.modelId,
+      region: process.env.AWS_REGION ?? config.awsRegion,
+      maxTokens: 64_000,
+      temperature: 0.2,
+    }),
+    systemPrompt: buildSystemPrompt(targetLang),
+    tools: [fileEditor],
+    printer: !!options.verbose,
+  });
+  agent.addHook(BeforeToolCallEvent, rejectOutsideDocsDir);
+
+  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`,
+    );
+  }
+
+  // Sanity check: the target file should now exist and have been written during this run.
+  if (!fs.existsSync(targetAbsPath)) {
+    throw new Error(
+      `agent did not write target file ${targetAbsPath} for ${file.relativePath} → ${targetLang}`,
+    );
+  }
+  const afterMtimeMs = (await fs.stat(targetAbsPath)).mtimeMs;
+  if (afterMtimeMs <= beforeMtimeMs) {
+    log.warn(
+      `target ${file.relativePath} → ${targetLang} was not updated (mtime unchanged) — the agent may have decided no change was needed`,
+    );
+  }
+}
+
+/**
+ * Simple concurrency-limited runner.
+ */
+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;
+}
+
+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(', ')}`);
+
+  const files = await getFilesToTranslate();
+
+  if (files.length === 0) {
+    log.info('Nothing to translate.');
+    return;
+  }
+
+  log.info(`Files to translate: ${files.length}`);
+  for (const f of files) {
+    log.verbose(
+      `  - ${f.relativePath}${f.diff ? ' (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.
+  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)}`,
+        );
+        throw err;
+      }
+    }),
+  );
+
+  const concurrency = Math.max(1, config.concurrency ?? 5);
+  log.info(
+    `Running ${tasks.length} translation(s) with concurrency=${concurrency}`,
+  );
+  await runWithConcurrency(tasks, concurrency);
+
+  log.info('Done.');
+}
+
+main().catch((err) => {
+  log.error(err instanceof Error ? err.message : String(err));
+  process.exit(1);
+});