Sync eng/common directory with azure-sdk-tools for PR 16330 (#48049)

azure-sdk-automation[bot] · helen229 · web-flow · commit 08d53c364edc · 2026-07-14T14:15:36.000-07:00
* Convert eval CI glue scripts from .js to .ts (Node type stripping) Rename the 7 source + 4 test modules under eng/common/scripts/eval to .ts and rewrite relative import specifiers to .ts (Node native type erasure, no build step). Pipeline node invocations and the npm test script gain --experimental-strip-types --disable-warning=ExperimentalWarning so they run on Node 22.6-22.17 (local) and unflagged on 22.18+ (CI). engines bumped to >=22.6. Addresses Mike Harder feedback to prefer .ts with type erasure over .js. * Reuse azure-rest-api-specs exec primitives in eval git sync Vendor .github/shared/src/exec.js from azure-rest-api-specs (@ef7dd74) as lib/exec.ts (TS port, erasable syntax) under eng/common so it syncs into the language repos. Rewire sync-eval-git-repo invokeGit onto the async execFile helper (no-shell child_process.execFile, git stderr surfaced only on failure); syncRepo and init-eval-git-fixtures main become async accordingly. README documents the vendored file and provenance. Addresses Mike Harder feedback to reuse the shared exec primitives; see #16296. * Polish: keep vendored exec.ts faithful to upstream; note shard spawnSync rationale * Drop --disable-warning=ExperimentalWarning; keep only --experimental-strip-types --------- Co-authored-by: helen229 <gaoh@microsoft.com>
diff --git a/eng/common/pipelines/templates/jobs/eval-shard.yml b/eng/common/pipelines/templates/jobs/eval-shard.yml
@@ -101,7 +101,7 @@ jobs:
             patterns+=(--pattern "$tok")
           done
           set +f
-          node "$(Build.SourcesDirectory)/eng/common/scripts/eval/init-eval-git-fixtures.js" \
+          node --experimental-strip-types "$(Build.SourcesDirectory)/eng/common/scripts/eval/init-eval-git-fixtures.ts" \
             --eval-root "$(Build.SourcesDirectory)/${{ parameters.vallyRoot }}" \
             "${patterns[@]}"
         displayName: 'Prime eval git fixtures'
diff --git a/eng/common/pipelines/templates/jobs/eval-summarize.yml b/eng/common/pipelines/templates/jobs/eval-summarize.yml
@@ -29,7 +29,7 @@ jobs:
 
       # Renders the rollup to the run's Summary tab (##vso[task.uploadsummary]).
       - script: |
-          node "$(Build.SourcesDirectory)/eng/common/scripts/eval/build-eval-summary.js" \
+          node --experimental-strip-types "$(Build.SourcesDirectory)/eng/common/scripts/eval/build-eval-summary.ts" \
             --results-root "$(Pipeline.Workspace)/eval-results" \
             --output-path "$(Build.ArtifactStagingDirectory)/eval-summary.md"
         displayName: 'Render Markdown rollup'
diff --git a/eng/common/pipelines/templates/jobs/generate-eval-matrix.yml b/eng/common/pipelines/templates/jobs/generate-eval-matrix.yml
@@ -37,7 +37,7 @@ jobs:
             set +f
           fi
           base="$(Build.SourcesDirectory)/${{ parameters.vallyRoot }}"
-          node "$(Build.SourcesDirectory)/eng/common/scripts/eval/collect-stimuli.js" \
+          node --experimental-strip-types "$(Build.SourcesDirectory)/eng/common/scripts/eval/collect-stimuli.ts" \
             --eval-root "$base" \
             --path-base "$base" \
             "${patterns[@]}" \
diff --git a/eng/common/pipelines/templates/steps/eval-invoke.yml b/eng/common/pipelines/templates/steps/eval-invoke.yml
@@ -27,7 +27,7 @@ steps:
         scriptLocation: inlineScript
         workingDirectory: ${{ parameters.vallyRoot }}
         inlineScript: |
-          node "$(Build.SourcesDirectory)/eng/common/scripts/eval/invoke-eval-shard.js" \
+          node --experimental-strip-types "$(Build.SourcesDirectory)/eng/common/scripts/eval/invoke-eval-shard.ts" \
             --eval-args "$(evalArgs)" \
             --shard-name "$(shardName)" \
             --output-dir "$(Build.SourcesDirectory)/artifacts/vally-results/$(shardName)" \
@@ -37,7 +37,7 @@ steps:
 
   - ${{ else }}:
     - script: |
-        node "$(Build.SourcesDirectory)/eng/common/scripts/eval/invoke-eval-shard.js" \
+        node --experimental-strip-types "$(Build.SourcesDirectory)/eng/common/scripts/eval/invoke-eval-shard.ts" \
           --eval-args "$(evalArgs)" \
           --shard-name "$(shardName)" \
           --output-dir "$(Build.SourcesDirectory)/artifacts/vally-results/$(shardName)" \
diff --git a/eng/common/scripts/eval/.gitignore b/eng/common/scripts/eval/.gitignore
@@ -1,4 +1,4 @@
-# The Vally eval harness ships hand-written ES modules under lib/ (glob.js, verdict.js).
+# The Vally eval harness ships hand-written ES modules under lib/ (glob.ts, verdict.ts).
 # Most repos ignore a top-level `lib/` (Python build output); re-include ours here so the
 # harness stays tracked wherever eng/common is synced (else node fails ERR_MODULE_NOT_FOUND).
 # Living in eng/common means this fix travels with the sync to every language SDK repo, so no
diff --git a/eng/common/scripts/eval/README.md b/eng/common/scripts/eval/README.md
@@ -1,6 +1,6 @@
 # eval-scripts (CI glue + pinned Vally CLI)
 
-This folder holds the JavaScript glue the Vally eval CI runs (matrix sharding, the shard
+This folder holds the TypeScript glue the Vally eval CI runs (matrix sharding, the shard
 runner, the JUnit summary) **and** pins the [`@microsoft/vally-cli`](https://www.npmjs.com/package/@microsoft/vally-cli)
 version those shards install. The CLI and its full transitive dependency tree are locked by
 the committed `package-lock.json` instead of resolved fresh from semver ranges on every run.
@@ -10,6 +10,23 @@ templates.
 - The only dependency should be `@microsoft/vally-cli`, pinned to the version CI should evaluate with.
 - `package-lock.json` must be committed so `npm ci` is deterministic.
 
+## TypeScript (no build step)
+
+The `*.ts` sources run directly through Node's native type stripping (erasable syntax only —
+no `enum`/`namespace`/parameter properties, no emit). CI pins Node `22.x`, which strips types
+unflagged on `>=22.18`; the pipeline `node` invocations and the `npm test` script pass
+`--experimental-strip-types` so the same sources also run on older local Node (`>=22.6`), which
+prints a harmless `ExperimentalWarning`. Relative imports use explicit `.ts` specifiers, as Node requires.
+
+## Vendored files
+
+- `lib/exec.ts` was **copied from azure-rest-api-specs** (`.github/shared/src/exec.js`
+  @ `ef7dd74c13aa9ca12b67b33b9dc4b5d1419a46f0`) and ported to TypeScript. It lives here under
+  `eng/common` (rather than the specs repo's `.github/shared` path) so it travels with the
+  eng/common sync into the language repos. Re-vendor from upstream rather than editing locally;
+  see [azure-sdk-tools#16296](https://github.com/Azure/azure-sdk-tools/issues/16296) for the plan
+  to share these primitives instead of copying.
+
 ## Updating the Vally CLI version
 
 1. Bump `@microsoft/vally-cli` in `package.json`.
diff --git a/eng/common/scripts/eval/build-eval-summary.ts b/eng/common/scripts/eval/build-eval-summary.ts
@@ -5,7 +5,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
-import { globFiles } from "./lib/glob.js";
+import { globFiles } from "./lib/glob.ts";
 
 // Maps a JUnit file path back to its shard and job attempt. Result artifacts download into
 // folders named `eval-result-<shardName>-<attempt>` (the attempt suffix keeps "Rerun failed
diff --git a/eng/common/scripts/eval/collect-stimuli.ts b/eng/common/scripts/eval/collect-stimuli.ts
@@ -6,7 +6,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
-import { globFiles } from "./lib/glob.js";
+import { globFiles } from "./lib/glob.ts";
 
 // Fallback patterns when run with no --pattern. Mirrors archetype-eval.yml's evalGlobs default.
 const DEFAULT_PATTERNS = [
diff --git a/eng/common/scripts/eval/init-eval-git-fixtures.ts b/eng/common/scripts/eval/init-eval-git-fixtures.ts
@@ -5,8 +5,8 @@
 import fs from "node:fs";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
-import { globFiles } from "./lib/glob.js";
-import { syncRepo } from "./sync-eval-git-repo.js";
+import { globFiles } from "./lib/glob.ts";
+import { syncRepo } from "./sync-eval-git-repo.ts";
 
 export const DEFAULT_PATTERNS = [
   "evals/tools/*.eval.yaml",
@@ -113,7 +113,7 @@ function parseArgs(argv) {
   return options;
 }
 
-function main(argv) {
+async function main(argv) {
   const options = parseArgs(argv);
   const root = path.resolve(options.evalRoot);
 
@@ -139,7 +139,7 @@ function main(argv) {
     const sparseCheckoutPaths = known ? known.sparse : [];
     const cacheRoot = path.dirname(fixture.cachePath);
     console.log(`[prime-fixtures] Priming ${fixture.repoName} @ ${fixture.ref} from ${repoUrl}`);
-    syncRepo({
+    await syncRepo({
       cacheRoot,
       repoUrl,
       repoName: fixture.repoName,
@@ -154,10 +154,8 @@ function main(argv) {
 }
 
 if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
-  try {
-    main(process.argv.slice(2));
-  } catch (error) {
-    console.error(error.message);
+  main(process.argv.slice(2)).catch((error) => {
+    console.error(error instanceof Error ? error.message : error);
     process.exit(1);
-  }
+  });
 }
diff --git a/eng/common/scripts/eval/invoke-eval-shard.ts b/eng/common/scripts/eval/invoke-eval-shard.ts
@@ -4,7 +4,7 @@
 import { spawnSync } from "node:child_process";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
-import { getVallyShardVerdict } from "./lib/verdict.js";
+import { getVallyShardVerdict } from "./lib/verdict.ts";
 
 // The pinned Vally CLI is installed next to this script (package.json + node_modules live here),
 // so the npm --prefix is just this file's own directory.
@@ -30,6 +30,9 @@ export function runShard({ evalArgs, shardName, outputDir, threshold = 0.8 }) {
   );
 
   // Do NOT abort on a non-zero exit — the verdict below is authoritative.
+  // Uses spawnSync (not the vendored execFile helper) on purpose: the shard needs vally's output
+  // streamed live to the log (stdio: "inherit") and must keep going on a non-zero exit, whereas
+  // the exec helper captures output and rejects on failure.
   const proc = spawnSync(
     "npm",
     [
diff --git a/eng/common/scripts/eval/lib/exec.ts b/eng/common/scripts/eval/lib/exec.ts
@@ -0,0 +1,139 @@
+// Secure process/exec primitives (execFile wrapper with logging + a larger default maxBuffer).
+//
+// PROVENANCE: Copied from azure-rest-api-specs .github/shared/src/exec.js
+//   @ ef7dd74c13aa9ca12b67b33b9dc4b5d1419a46f0 and ported to TypeScript (erasable syntax only,
+//   run via Node native type stripping). See azure-sdk-tools#16296 for the plan to share these
+//   primitives properly instead of copying. Kept under eng/common/scripts/eval/lib so it travels
+//   with the eng/common sync into the language repos (unlike .github/shared, which does not sync);
+//   this is why the folder path differs from the specs repo.
+
+import child_process from "node:child_process";
+import { dirname, join } from "node:path";
+import { promisify } from "node:util";
+
+const execFileImpl = promisify(child_process.execFile);
+
+// Minimal logger contract used by the exec helpers (subset of the specs repo ILogger).
+export interface ILogger {
+  info(message: string): void;
+  debug(message: string): void;
+}
+
+export interface ExecOptions {
+  /** Current working directory. Default: process.cwd(). */
+  cwd?: string;
+  logger?: ILogger;
+  /** Max bytes allowed on stdout or stderr. Default: 16 * 1024 * 1024. */
+  maxBuffer?: number;
+}
+
+export interface NpmPrefixOptions {
+  /** Prefix to pass to npm via "--prefix". */
+  prefix?: string;
+}
+
+export type ExecNpmOptions = ExecOptions & NpmPrefixOptions;
+
+export interface ExecResult {
+  stdout: string;
+  stderr: string;
+}
+
+export type ExecError = Error & { stdout?: string; stderr?: string; code?: number };
+
+/**
+ * Checks whether an unknown error object is an ExecError.
+ */
+export function isExecError(error: unknown): error is ExecError {
+  if (!(error instanceof Error)) return false;
+
+  const e = error as ExecError;
+  return typeof e.stdout === "string" || typeof e.stderr === "string";
+}
+
+/**
+ * Wraps `child_process.execFile()`, adding logging and a larger default maxBuffer.
+ *
+ * @throws {ExecError}
+ */
+export async function execFile(
+  file: string,
+  args?: string[],
+  options: ExecOptions = {},
+): Promise<ExecResult> {
+  const {
+    cwd,
+    logger,
+    // Node default is 1024 * 1024, which is too small for some git commands returning many
+    // entities or large file content. To support "git show", should be larger than the largest
+    // swagger file in the repo (2.5 MB as of 2/28/2025).
+    maxBuffer = 16 * 1024 * 1024,
+  } = options;
+
+  logger?.info(`execFile("${file}", ${JSON.stringify(args)})`);
+
+  try {
+    // execFile(file, args) is more secure than exec(cmd), since the latter is vulnerable to
+    // shell injection.
+    const result = await execFileImpl(file, args, {
+      cwd,
+      maxBuffer,
+    });
+
+    logger?.debug(`stdout: '${result.stdout}'`);
+    logger?.debug(`stderr: '${result.stderr}'`);
+
+    return result;
+  } catch (error) {
+    /* v8 ignore next */
+    logger?.debug(`error: '${JSON.stringify(error)}'`);
+
+    throw error;
+  }
+}
+
+/**
+ * Calls `execFile()` with appropriate arguments to run `npm` on all platforms.
+ *
+ * @throws {ExecError}
+ */
+export async function execNpm(args: string[], options: ExecNpmOptions = {}): Promise<ExecResult> {
+  const { prefix } = options;
+
+  // Exclude platform-specific code from coverage
+  /* v8 ignore start */
+  const { file, defaultArgs } =
+    process.platform === "win32"
+      ? {
+          // Only way I could find to run "npm" on Windows, without using the shell (e.g.
+          // "cmd /c npm ...")
+          //
+          // "node.exe", ["--", "npm-cli.js", ...args]
+          //
+          // The "--" MUST come BEFORE "npm-cli.js", to ensure args are sent to the script
+          // unchanged. If the "--" comes after "npm-cli.js", the args sent to the script will be
+          // ["--", ...args], which is NOT equivalent, and can break if args itself contains
+          // another "--".
+
+          // example: "C:\Program Files\nodejs\node.exe"
+          file: process.execPath,
+
+          // example: "C:\Program Files\nodejs\node_modules\npm\bin\npm-cli.js"
+          defaultArgs: ["--", join(dirname(process.execPath), "node_modules", "npm", "bin", "npm-cli.js")],
+        }
+      : { file: "npm", defaultArgs: [] as string[] };
+  /* v8 ignore stop */
+
+  const prefixArgs = prefix ? ["--prefix", prefix] : [];
+
+  return await execFile(file, [...defaultArgs, ...prefixArgs, ...args], options);
+}
+
+/**
+ * Calls `execNpm()` with arguments ["exec", "--no", "--"] prepended.
+ *
+ * @throws {ExecError}
+ */
+export async function execNpmExec(args: string[], options: ExecNpmOptions = {}): Promise<ExecResult> {
+  return await execNpm(["exec", "--no", "--", ...args], options);
+}
diff --git a/eng/common/scripts/eval/lib/glob.ts b/eng/common/scripts/eval/lib/glob.ts
diff --git a/eng/common/scripts/eval/lib/verdict.ts b/eng/common/scripts/eval/lib/verdict.ts
@@ -5,7 +5,7 @@
 
 import fs from "node:fs";
 import path from "node:path";
-import { globFiles } from "./glob.js";
+import { globFiles } from "./glob.ts";
 
 // Formats a 0..1 ratio as a fixed-1-decimal percentage string (e.g. 97.1).
 function pct(ratio) {
diff --git a/eng/common/scripts/eval/package.json b/eng/common/scripts/eval/package.json
@@ -5,10 +5,10 @@
   "description": "Vally eval CI glue scripts (matrix sharding, shard runner, JUnit summary) plus the pinned @microsoft/vally-cli the shards install from the committed lockfile. Synced via eng/common; not published.",
   "type": "module",
   "engines": {
-    "node": ">=18"
+    "node": ">=22.6"
   },
   "scripts": {
-    "test": "node --test"
+    "test": "node --experimental-strip-types --test"
   },
   "devDependencies": {
     "@microsoft/vally-cli": "0.6.0"
diff --git a/eng/common/scripts/eval/sync-eval-git-repo.ts b/eng/common/scripts/eval/sync-eval-git-repo.ts
diff --git a/eng/common/scripts/eval/test/build-eval-summary.test.ts b/eng/common/scripts/eval/test/build-eval-summary.test.ts
diff --git a/eng/common/scripts/eval/test/collect-stimuli.test.ts b/eng/common/scripts/eval/test/collect-stimuli.test.ts
diff --git a/eng/common/scripts/eval/test/init-eval-git-fixtures.test.ts b/eng/common/scripts/eval/test/init-eval-git-fixtures.test.ts
diff --git a/eng/common/scripts/eval/test/verdict.test.ts b/eng/common/scripts/eval/test/verdict.test.ts

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# The Vally eval harness ships hand-written ES modules under lib/ (glob.js, verdict.js).`
	`1`	`+# The Vally eval harness ships hand-written ES modules under lib/ (glob.ts, verdict.ts).`
`2`	`2`	# Most repos ignore a top-level `lib/` (Python build output); re-include ours here so the
`3`	`3`	`# harness stays tracked wherever eng/common is synced (else node fails ERR_MODULE_NOT_FOUND).`
`4`	`4`	`# Living in eng/common means this fix travels with the sync to every language SDK repo, so no`