From b741d3b87a848885c616856f537317f2a60bb355 Mon Sep 17 00:00:00 2001 From: Libba Lawrence Date: Tue, 30 Jun 2026 13:22:15 -0700 Subject: [PATCH 01/52] Add language-agnostic emitter-diff tool + python adapter Ports the eng/emitter-diff tool: diffs generated code between two emitter versions (npm version, local folder, or github ref) and optionally runs the emitter's generated-code test suites. Ships the python adapter for @typespec/http-client-python, driving its native two-phase regenerate pipeline with a venv per emitter version. - eng/emitter-diff: @typespec/emitter-diff package (CLI, ref resolver, diff engine with HTML/VS Code/terminal output, adapter registry). - regenerate.ts: add --httpSpecsDir, --azureSpecsDir, --no-baseline flags. - pnpm-workspace.yaml: add eng/emitter-diff member + diff2html catalog entry. - ci-emitter-diff-python.yml: PR workflow that diffs head vs the PR base commit, uploads the rendered HTML artifact, and posts a sticky PR comment. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- ...r-diff-regenerate-flags-2026-6-30-0-0-0.md | 7 + .github/workflows/ci-emitter-diff-python.yml | 168 ++++++++++++ eng/emitter-diff/README.md | 173 ++++++++++++ eng/emitter-diff/package.json | 27 ++ eng/emitter-diff/src/adapters/python.ts | 212 +++++++++++++++ eng/emitter-diff/src/cli.ts | 247 ++++++++++++++++++ eng/emitter-diff/src/diff.ts | 229 ++++++++++++++++ eng/emitter-diff/src/registry.ts | 20 ++ eng/emitter-diff/src/resolver.ts | 170 ++++++++++++ eng/emitter-diff/src/types.ts | 116 ++++++++ eng/emitter-diff/src/util.ts | 104 ++++++++ eng/emitter-diff/tsconfig.json | 16 ++ .../eng/scripts/ci/regenerate.ts | 26 +- pnpm-lock.yaml | 45 ++++ pnpm-workspace.yaml | 2 + 15 files changed, 1559 insertions(+), 3 deletions(-) create mode 100644 .chronus/changes/emitter-diff-regenerate-flags-2026-6-30-0-0-0.md create mode 100644 .github/workflows/ci-emitter-diff-python.yml create mode 100644 eng/emitter-diff/README.md create mode 100644 eng/emitter-diff/package.json create mode 100644 eng/emitter-diff/src/adapters/python.ts create mode 100644 eng/emitter-diff/src/cli.ts create mode 100644 eng/emitter-diff/src/diff.ts create mode 100644 eng/emitter-diff/src/registry.ts create mode 100644 eng/emitter-diff/src/resolver.ts create mode 100644 eng/emitter-diff/src/types.ts create mode 100644 eng/emitter-diff/src/util.ts create mode 100644 eng/emitter-diff/tsconfig.json diff --git a/.chronus/changes/emitter-diff-regenerate-flags-2026-6-30-0-0-0.md b/.chronus/changes/emitter-diff-regenerate-flags-2026-6-30-0-0-0.md new file mode 100644 index 00000000000..bd9efd2c41f --- /dev/null +++ b/.chronus/changes/emitter-diff-regenerate-flags-2026-6-30-0-0-0.md @@ -0,0 +1,7 @@ +--- +changeKind: internal +packages: + - "@typespec/http-client-python" +--- + +Add `--httpSpecsDir`, `--azureSpecsDir`, and `--no-baseline` flags to `regenerate.ts` so the language-agnostic `eng/emitter-diff` tool can drive code generation against pinned specs without cloning the published baseline. diff --git a/.github/workflows/ci-emitter-diff-python.yml b/.github/workflows/ci-emitter-diff-python.yml new file mode 100644 index 00000000000..a3741500268 --- /dev/null +++ b/.github/workflows/ci-emitter-diff-python.yml @@ -0,0 +1,168 @@ +name: "python / emitter diff" + +# Generates code with the current checkout's emitter and with the PR's base +# commit, then diffs the two. The rendered HTML diff is uploaded as a per-PR +# artifact, and a sticky PR comment summarizes the changed files (+/-) with a +# link to download it, so reviewers can see exactly how an emitter change +# affects generated SDKs. Powered by the language-agnostic eng/emitter-diff tool. +# +# Python's generator uses a native two-phase pipeline (TypeSpec emits YAML, then +# a batched Python subprocess writes the .py files) with a venv co-located with +# each emitter version. So this workflow builds + sets up a venv for both the +# head checkout and a worktree of the baseline commit before diffing. + +on: + pull_request: + branches: + - main + - release/* + paths: + - "packages/http-client-python/**" + - "eng/emitter-diff/**" + - ".github/workflows/ci-emitter-diff-python.yml" + workflow_dispatch: + inputs: + baseline: + description: "Baseline emitter ref (npm version, local path, or github ref). Defaults to the PR base commit." + required: false + default: "" + +permissions: + contents: read + pull-requests: write + +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + +jobs: + emitter-diff: + name: "Generate & Diff" + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v6 + with: + fetch-depth: 0 + + - uses: ./.github/actions/setup + + - uses: actions/setup-python@v5 + with: + python-version: "3.12" + + - name: Install repo dependencies (emitter-diff tool) + run: pnpm install + + - name: Build + venv for head emitter + working-directory: packages/http-client-python + run: | + npm ci + npm run build + npm run install + + - name: Determine baseline + id: baseline + run: | + input="${{ github.event.inputs.baseline }}" + if [ -z "$input" ]; then + base_sha="${{ github.event.pull_request.base.sha }}" + git worktree add "${{ runner.temp }}/baseline" "$base_sha" + (cd "${{ runner.temp }}/baseline/packages/http-client-python" && npm ci && npm run build && npm run install) + input="local:${{ runner.temp }}/baseline/packages/http-client-python" + fi + echo "ref=$input" >> "$GITHUB_OUTPUT" + echo "Baseline: $input" + + - name: Run emitter diff + id: diff + run: | + set +e + pnpm --filter @typespec/emitter-diff exec tsx src/cli.ts \ + --emitter python \ + --baseline "${{ steps.baseline.outputs.ref }}" \ + --work-dir "${{ runner.temp }}/emitter-diff" \ + --html "${{ runner.temp }}/emitter-diff.html" \ + --patch "${{ runner.temp }}/emitter-diff.patch" \ + | tee "${{ runner.temp }}/emitter-diff.log" + echo "status=$?" >> "$GITHUB_OUTPUT" + + - name: Write job summary + if: always() + run: | + { + echo "## Emitter diff" + echo "" + echo "Baseline: \`${{ steps.baseline.outputs.ref }}\` vs current checkout." + echo "" + echo '```' + grep -E "Diff summary:" "${{ runner.temp }}/emitter-diff.log" || echo "No summary captured." + echo '```' + echo "" + echo "Download the **emitter-diff-html** artifact for the full rendered diff." + } >> "$GITHUB_STEP_SUMMARY" + + - name: Upload HTML diff + if: always() + uses: actions/upload-artifact@v7 + with: + name: emitter-diff-html + path: ${{ runner.temp }}/emitter-diff.html + if-no-files-found: ignore + retention-days: 7 + + - name: Comment on PR + if: always() && github.event_name == 'pull_request' + continue-on-error: true + uses: actions/github-script@v7 + env: + BASELINE: ${{ steps.baseline.outputs.ref }} + PATCH_FILE: ${{ runner.temp }}/emitter-diff.patch + HTML_FILE: ${{ runner.temp }}/emitter-diff.html + with: + script: | + const fs = require("fs"); + const marker = ""; + const runUrl = `${context.serverUrl}/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId}`; + + // Parse the unified patch directly so the numbers match the tool exactly. + let patch = ""; + try { patch = fs.readFileSync(process.env.PATCH_FILE, "utf8"); } catch {} + const lines = patch.split("\n"); + const files = []; + let insertions = 0, deletions = 0; + for (const line of lines) { + const m = line.match(/^diff --git a\/(.+?) b\/(.+)$/); + if (m) files.push(m[2]); + else if (line.startsWith("+") && !line.startsWith("+++")) insertions++; + else if (line.startsWith("-") && !line.startsWith("---")) deletions++; + } + const hasChanges = patch.trim().length > 0; + const htmlExists = fs.existsSync(process.env.HTML_FILE); + + let body = `${marker}\n## 🐍 Python emitter diff\n\n` + + `Baseline \`${process.env.BASELINE}\` vs this PR's checkout.\n\n`; + if (!hasChanges) { + body += `βœ… **No changes** to generated output.\n`; + } else { + body += `**${files.length} file(s) changed** Β· +${insertions} / -${deletions}\n\n`; + const shown = files.slice(0, 50); + body += `
Changed files\n\n` + + shown.map((f) => `- \`${f}\``).join("\n") + + (files.length > shown.length ? `\n- …and ${files.length - shown.length} more` : "") + + `\n
\n\n`; + if (htmlExists) { + body += `πŸ“„ Download the **emitter-diff-html** artifact from the ` + + `[workflow run](${runUrl}) for the full side-by-side rendered diff.\n`; + } + } + body += `\n_Generated by \`eng/emitter-diff\`._`; + + const { owner, repo } = context.repo; + const issue_number = context.issue.number; + const { data: comments } = await github.rest.issues.listComments({ owner, repo, issue_number }); + const existing = comments.find((c) => c.body && c.body.includes(marker)); + if (existing) { + await github.rest.issues.updateComment({ owner, repo, comment_id: existing.id, body }); + } else { + await github.rest.issues.createComment({ owner, repo, issue_number, body }); + } diff --git a/eng/emitter-diff/README.md b/eng/emitter-diff/README.md new file mode 100644 index 00000000000..6774898d13f --- /dev/null +++ b/eng/emitter-diff/README.md @@ -0,0 +1,173 @@ +# @typespec/emitter-diff + +A language-agnostic tool for **diffing the generated code produced by two versions of a +TypeSpec emitter** β€” and optionally running that emitter's generated-code test suites. + +It generates code from the test specs twice (a **baseline** emitter and a **head** emitter), +then shows the diff between the two outputs. Use it locally during development and in CI on PRs. + +Each language emitter (python, and later java/rust/go/ts) plugs in via a small **adapter** that +wraps that emitter's own generation/test commands. The core (ref resolution, diffing, orchestration) +contains no language-specific logic. + +## How it works + +``` + baseline emitter ─┐ + β”œβ”€ generate (adapter) ─► /baseline ─┐ + specs ────────────────────── β”œβ”€β–Ί git diff ─► terminal / VS Code / HTML + β”œβ”€ generate (adapter) ─► /head β”€β”€β”€β”€β”€β”˜ + head emitter β”€β”€β”€β”€β”€β”˜ └─► (optional) run test suites +``` + +- The **adapter** wraps the emitter's existing commands. For python that is + `packages/http-client-python/eng/scripts/ci/regenerate.ts` (generation) and + `eng/scripts/ci/run-tests.ts` (suites). +- The regenerate _driver_ always comes from the current checkout; only the emitter build it points + at (`--pluginDir`) changes between baseline and head, isolating the diff to emitter behavior. + +## Usage + +```bash +# From the repo root, via pnpm: +pnpm --filter @typespec/emitter-diff exec tsx src/cli.ts --emitter python --baseline 0.34.0 + +# Or directly with Node 22+ (native TS): +npx tsx eng/emitter-diff/src/cli.ts --emitter python --baseline 0.34.0 +``` + +### Refs (`--baseline`, `--head`, `--specs`) + +| Syntax | Meaning | +| --------------------------------- | -------------------------------------- | +| `npm:1.2.3` or `1.2.3` | a published package version (prebuilt) | +| `local:/path` or `./path` | a local source folder | +| `github:owner/repo@` | a GitHub source at a ref | +| `gh:` | the current repo at a ref | + +`--head` defaults to the **current checkout**. `--specs` defaults to **all** repo specs. + +### Common options + +By default the tool writes a **clickable HTML report** (`emitter-diff.html`) into the work dir and +prints a `file://` link to it. Use `--vscode` for a live VS Code diff, `--terminal` for the full +patch in your shell, or `--patch`/`--html` to write to a specific file. + +| Option | Description | +| ----------------------- | ------------------------------------------------------------------------------------- | +| `--name ` | Filter which specs/packages are generated | +| `--html ` | Write the rendered HTML report to this path (default: `/emitter-diff.html`) | +| `--vscode` | Open the diff in VS Code instead of writing HTML | +| `--terminal` | Print the full colored patch to the terminal instead | +| `--patch ` | Write the raw unified diff to a file | +| `--fail-on-diff` | Exit non-zero when output differs (CI gating) | +| `--run-tests` | Run the adapter's test suites on the output | +| `--test-env ` | Suites to run, e.g. `test,lint,mypy,pyright` | +| `--test-target ` | `head` (default) \| `baseline` \| `both` | +| `--opt key=value` | Repeatable adapter-specific option (e.g. `--opt flavor=azure`) | +| `-- ` | Everything after `--` is forwarded to the adapter | + +> `--open` is kept as an alias for `--vscode`. + +### Examples + +```bash +# Default: writes a clickable emitter-diff.html and prints a file:// link. +npx tsx eng/emitter-diff/src/cli.ts --emitter python --baseline 0.34.0 \ + --opt flavor=azure --name authentication-api-key + +# Open the diff live in VS Code instead: +npx tsx eng/emitter-diff/src/cli.ts --emitter python --baseline 0.34.0 \ + --opt flavor=azure --name authentication-api-key --vscode + +# Compare two source folders and write an HTML report to a specific path: +npx tsx eng/emitter-diff/src/cli.ts --emitter python \ + --baseline local:/path/to/old/http-client-python \ + --head local:/path/to/new/http-client-python \ + --html diff.html + +# Diff against a GitHub sha and run pytest + type checks on the head output: +npx tsx eng/emitter-diff/src/cli.ts --emitter python \ + --baseline github:microsoft/typespec@ \ + test,mypy,pyright --opt flavor=azure --run-tests < sha > --test-env +``` + +## Viewing the diff in VS Code + +`--vscode` gives you a native, side-by-side source diff of the two generated trees. VS Code has +no CLI to diff two _folders_ (`code --diff` only compares two files), so the tool stages the +comparison as a throwaway git working tree under `/vscode-diff`: the **baseline** tree +is committed, the **head** tree is overlaid on top and left staged. Opening that folder shows +every changed generated file in the **Source Control** panel with red/green diffs β€” click any +file for the side-by-side view. + +```bash +# Keep the scratch dir so it survives the run, and open the diff in VS Code: +npx tsx eng/emitter-diff/src/cli.ts --emitter python \ + --baseline npm:0.60.0 --opt flavor=azure --name encode/duration \ + --work-dir ./emitter-diff-out --vscode +``` + +If you generated the trees without `--vscode` (or want to reopen later), build the same view by +hand from the `baseline/` and `head/` folders under your `--work-dir` and open it in VS Code: + +```bash +cd ./emitter-diff-out +git init -q vscode-diff +cp -r baseline/. vscode-diff/ +git -C vscode-diff add -A && git -C vscode-diff commit -qm baseline +# overlay head on top, keeping .git +find vscode-diff -mindepth 1 -maxdepth 1 ! -name .git -exec rm -rf {} + +cp -r head/. vscode-diff/ +git -C vscode-diff add -A +code vscode-diff # browse changes in the Source Control panel +``` + +```powershell +# PowerShell equivalent of the overlay step: +cd .\emitter-diff-out +git init -q vscode-diff +Copy-Item -Recurse -Force .\baseline\* .\vscode-diff +git -C vscode-diff add -A; git -C vscode-diff commit -qm baseline +Get-ChildItem .\vscode-diff -Force | Where-Object Name -ne ".git" | Remove-Item -Recurse -Force +Copy-Item -Recurse -Force .\head\* .\vscode-diff +git -C vscode-diff add -A +code vscode-diff +``` + +## CI integration + +`.github/workflows/ci-emitter-diff-python.yml` runs on PRs that touch the python emitter or this +tool. It builds the python emitter (and a venv) for both the PR's checkout and a worktree of the +PR's base commit, diffs the two, and then: + +- uploads the rendered **`emitter-diff-html`** artifact (full side-by-side diff; downloadable from + the workflow run β€” GitHub artifacts are zip downloads, so they can't be rendered inline in a + comment), +- writes a job-summary with the diff totals, and +- posts a **sticky PR comment** (updated in place on each push) listing the changed files and + `+`/`-` counts with a link to download the artifact. + +The comment step needs `pull-requests: write`. PRs **from forks** get a read-only token, so the +comment is best-effort there (`continue-on-error`) β€” the artifact and job-summary still work. + +## Adding a new language adapter + +1. Implement `EmitterAdapter` (`src/types.ts`) β€” `prepareEmitter`, `generate`, optional `runTests` β€” + wrapping that emitter's own commands (e.g. rust's `npm run tspcompile`, ts's `gen-spector`). +2. Register it in `src/registry.ts`. + +The core needs no changes. + +## Notes & limitations + +- External `--specs` folders must mirror the `http-specs` / `azure-http-specs` layout. +- `--html` uses the optional `diff2html` dependency (declared in this package's `package.json`). +- **Python's native two-phase pipeline needs a venv per emitter version.** `regenerate.ts` + compiles TypeSpec to YAML in-process and then runs a batched Python subprocess + (`eng/scripts/setup/run_batch.py`) that writes the `.py` files using a venv co-located with the + emitter at `/venv`. The adapter therefore builds **and** creates a venv (`npm run +install`) for each side before generating. Because each version's venv is built from that + version's generator, a baseline must be a buildable **source** ref (`local`/`github`) or an npm + version whose package can run `npm run install`; the CI workflow uses a worktree of the PR base + commit as the baseline. diff --git a/eng/emitter-diff/package.json b/eng/emitter-diff/package.json new file mode 100644 index 00000000000..958490123c1 --- /dev/null +++ b/eng/emitter-diff/package.json @@ -0,0 +1,27 @@ +{ + "name": "@typespec/emitter-diff", + "version": "0.1.0", + "private": true, + "description": "Diff generated code across TypeSpec emitter versions and run generated-code tests, for all language emitters in this repo.", + "type": "module", + "main": "src/cli.ts", + "bin": { + "emitter-diff": "./src/cli.ts" + }, + "engines": { + "node": ">=22.0.0" + }, + "scripts": { + "emitter-diff": "tsx src/cli.ts", + "build": "tsc -p .", + "typecheck": "tsc -p ." + }, + "dependencies": { + "diff2html": "catalog:" + }, + "devDependencies": { + "@types/node": "catalog:", + "tsx": "catalog:", + "typescript": "catalog:" + } +} diff --git a/eng/emitter-diff/src/adapters/python.ts b/eng/emitter-diff/src/adapters/python.ts new file mode 100644 index 00000000000..7b8264a1d20 --- /dev/null +++ b/eng/emitter-diff/src/adapters/python.ts @@ -0,0 +1,212 @@ +/** + * typespec-python adapter. + * + * This is the only python-aware code in the tool. It satisfies the generic + * {@link EmitterAdapter} contract by wrapping the python package's own scripts: + * - generation β†’ `eng/scripts/ci/regenerate.ts` (driven with `--pluginDir` + * (emitter build) + `--generatedFolder` (output root) overrides so any + * emitter build can target any output dir). + * - test suites β†’ `eng/scripts/ci/run-tests.ts` (pytest/lint/mypy/pyright...). + * + * The regenerate *driver* always comes from the current checkout; only the + * `--pluginDir` it points at changes between baseline and head. Specs are also + * pinned to the current checkout so the diff isolates emitter behavior rather + * than driver/spec differences. + */ +import { cpSync, existsSync, rmSync } from "node:fs"; +import { join } from "node:path"; + +import { describeRef } from "../resolver.js"; +import type { + AdapterContext, + ClassifiedRef, + EmitterAdapter, + GenerateRequest, + ResolvedEmitter, + RunTestsRequest, +} from "../types.js"; +import { run, runChecked } from "../util.js"; + +const PACKAGE_NAME = "@typespec/http-client-python"; +const PKG_REL = "packages/http-client-python"; + +function pkgDir(ctx: AdapterContext): string { + return join(ctx.repoRoot, PKG_REL); +} + +/** Resolve `tsx` from the python package and run a script in its directory. */ +async function runScript( + ctx: AdapterContext, + scriptRelPath: string, + args: string[], + inherit = true, +): Promise { + const cwd = pkgDir(ctx); + await runChecked("npx", ["tsx", join(cwd, scriptRelPath), ...args], { cwd, inherit }); +} + +async function isBuilt(dir: string): Promise { + return existsSync(join(dir, "dist", "emitter", "index.js")); +} + +async function ensureBuilt(dir: string, ctx: AdapterContext): Promise { + if (await isBuilt(dir)) return; + ctx.log.warn(`Emitter at ${dir} is not built; attempting build...`); + // Best-effort build. http-client-python is npm-managed (its own + // package-lock.json); building an arbitrary source checkout may require a + // prior `npm ci`, so surface a clear error if it fails. + const res = await run("npm", ["run", "build"], { cwd: dir, inherit: true }); + if (res.code !== 0 || !(await isBuilt(dir))) { + throw new Error( + `Could not build emitter at ${dir}. Build it manually (npm ci && npm run build) and retry.`, + ); + } +} + +/** + * Core's regenerate pipeline is two-phase: the TypeSpec compile emits YAML, then + * a batched Python subprocess (`run_batch.py`) writes the `.py` files using a + * venv co-located with the emitter at `/venv`. Each emitter version needs + * its own venv (built from that version's generator), so ensure one exists. + */ +async function ensureVenv(dir: string, ctx: AdapterContext): Promise { + if (existsSync(join(dir, "venv"))) return; + ctx.log.warn(`No Python venv at ${dir}; creating one (npm run install)...`); + const res = await run("npm", ["run", "install"], { cwd: dir, inherit: true }); + if (res.code !== 0 || !existsSync(join(dir, "venv"))) { + throw new Error( + `Could not create a Python venv at ${dir}. Run \`npm run install\` there manually and retry. ` + + `(The native two-phase pipeline needs a venv per emitter version.)`, + ); + } +} + +export const pythonAdapter: EmitterAdapter = { + name: "python", + packageName: PACKAGE_NAME, + + async prepareEmitter( + ref: ClassifiedRef | "current", + ctx: AdapterContext, + ): Promise { + if (ref === "current") { + const dir = pkgDir(ctx); + await ensureBuilt(dir, ctx); + await ensureVenv(dir, ctx); + return { dir, label: "current checkout" }; + } + + if (ref.kind === "npm") { + // npm versions ship a prebuilt dist + python generator. The native + // pipeline still needs a venv built from that generator, so create one. + const dir = await ctx.installNpmPackage(PACKAGE_NAME, ref.version ?? "latest"); + await ensureVenv(dir, ctx); + return { dir, label: describeRef(ref, PACKAGE_NAME) }; + } + + // local / github: resolve to a source dir, then ensure it is built + has a venv. + const sourceRoot = await ctx.resolveSource(ref, PACKAGE_NAME); + // For a full-repo source (github clone or repo root), the emitter lives in + // packages/http-client-python; otherwise the resolved dir is the package itself. + const candidate = existsSync(join(sourceRoot, PKG_REL)) + ? join(sourceRoot, PKG_REL) + : sourceRoot; + await ensureBuilt(candidate, ctx); + await ensureVenv(candidate, ctx); + return { dir: candidate, label: describeRef(ref, PACKAGE_NAME) }; + }, + + async generate(request: GenerateRequest, ctx: AdapterContext): Promise { + // The new in-process regenerate driver anchors generated output at + // `/../tests/generated/...`. Point generatedFolder at a + // `generator` subdir of the requested output dir so files land directly + // under request.outputDir/tests/generated, which the diff engine compares. + const args = [ + "--pluginDir", + request.emitter.dir, + "--generatedFolder", + join(request.outputDir, "generator"), + // Emit only fresh codegen β€” skip the azure-sdk-for-python baseline clone. + "--no-baseline", + ]; + + const flavor = request.options.flavor; + if (flavor) args.push("--flavor", flavor); + if (request.nameFilter) args.push("--name", request.nameFilter); + + // Specs are pinned to the current checkout so only the emitter differs + // between baseline and head. External specs (--specs) override that. + const httpSpecs = resolveHttpSpecs(request, ctx); + const azureSpecs = resolveAzureSpecs(request, ctx); + if (httpSpecs) args.push("--httpSpecsDir", httpSpecs); + if (azureSpecs) args.push("--azureSpecsDir", azureSpecs); + + args.push(...request.passthrough); + + ctx.log.step(`Generating with ${request.emitter.label} β†’ ${request.outputDir}`); + await runScript(ctx, "eng/scripts/ci/regenerate.ts", args); + }, + + async runTests(request: RunTestsRequest, ctx: AdapterContext): Promise { + // The python test harness is wired to /tests/generated. The diff + // tool's output dir holds the generated tree under `tests/generated` + // (see generate()), so sync that subtree there, then run the runner. + const generatedRoot = join(pkgDir(ctx), "tests", "generated"); + const source = firstExisting([ + join(request.outputDir, "tests", "generated"), + request.outputDir, + ])!; + ctx.log.step(`Syncing ${source} into ${generatedRoot} for test run`); + rmSync(generatedRoot, { recursive: true, force: true }); + cpSync(source, generatedRoot, { recursive: true }); + + // `--generator` runs the suites against the generated packages (as opposed + // to the emitter's own unit tests). + const args: string[] = ["--generator"]; + if (request.envs && request.envs.length > 0) { + args.push("--env", request.envs.join(",")); + } + const flavor = request.options.flavor; + if (flavor) args.push("--flavor", flavor); + if (request.nameFilter) args.push("--name", request.nameFilter); + args.push(...request.passthrough); + + ctx.log.step("Running python test suites"); + await runScript(ctx, "eng/scripts/ci/run-tests.ts", args); + }, +}; + +function firstExisting(paths: string[]): string | undefined { + return paths.find((p) => existsSync(p)); +} + +/** Default http-specs dir inside the current checkout's python package. */ +function defaultHttpSpecs(ctx: AdapterContext): string { + return join(pkgDir(ctx), "node_modules", "@typespec", "http-specs", "specs"); +} + +/** Default azure-http-specs dir inside the current checkout's python package. */ +function defaultAzureSpecs(ctx: AdapterContext): string { + return join(pkgDir(ctx), "node_modules", "@azure-tools", "azure-http-specs", "specs"); +} + +function resolveHttpSpecs(request: GenerateRequest, ctx: AdapterContext): string | undefined { + if (request.specsDir) { + return firstExisting([ + join(request.specsDir, "http-specs", "specs"), + join(request.specsDir, "specs"), + request.specsDir, + ]); + } + return firstExisting([defaultHttpSpecs(ctx)]); +} + +function resolveAzureSpecs(request: GenerateRequest, ctx: AdapterContext): string | undefined { + if (request.specsDir) { + return firstExisting([ + join(request.specsDir, "azure-http-specs", "specs"), + join(request.specsDir, "azure", "specs"), + ]); + } + return firstExisting([defaultAzureSpecs(ctx)]); +} diff --git a/eng/emitter-diff/src/cli.ts b/eng/emitter-diff/src/cli.ts new file mode 100644 index 00000000000..43822f64641 --- /dev/null +++ b/eng/emitter-diff/src/cli.ts @@ -0,0 +1,247 @@ +#!/usr/bin/env -S npx tsx +/** + * emitter-diff β€” language-agnostic CLI. + * + * Generates code from the test specs with two emitter versions (baseline + head) + * and diffs the output. All language specifics live behind the selected adapter; + * this file contains zero language logic. + */ +import { join } from "node:path"; +import { parseArgs } from "node:util"; + +import { diffDirs, openInVsCode, printDiff, printSummary, writeHtml, writePatch } from "./diff.js"; +import { getAdapter, listAdapters } from "./registry.js"; +import { + classifyRef, + defaultWorkDir, + installNpmPackage as installNpm, + resolveSource as resolveSrc, +} from "./resolver.js"; +import type { AdapterContext, ClassifiedRef } from "./types.js"; +import { color, createLogger, ensureDir, runChecked } from "./util.js"; + +const HELP = `${color.bold("emitter-diff")} β€” diff generated code across emitter versions + +${color.bold("Usage:")} + emitter-diff --emitter --baseline [options] + +${color.bold("Required:")} + --emitter Adapter to use. Available: ${listAdapters().join(", ")} + --baseline Old emitter to compare against. + +${color.bold("Refs")} (for --baseline / --head / --specs): + npm:1.2.3 | 1.2.3 a published package version + local:/path | ./path a local folder + github:owner/repo@ a GitHub source at a ref + gh: the current repo at a ref + +${color.bold("Options:")} + --head New emitter. Default: current checkout. + --specs Spec inputs: all (default) | local | github. + --name Filter which specs/packages are generated. + --work-dir Scratch dir (default: a temp dir). + --html Write the rendered HTML diff to this path. + Default output: a clickable HTML report in the work dir. + --vscode Open the diff in VS Code instead of writing HTML. + --terminal Print the full colored patch to the terminal instead. + --patch Write the raw unified diff to a file. + --fail-on-diff Exit non-zero when output differs (CI gating). + --run-tests Run the adapter's test suites on the output. + --test-env Suites to run (adapter-defined), e.g. test,lint,mypy. + --test-target head | baseline | both (default: head). + --opt key=value Repeatable adapter-specific option (e.g. --opt flavor=azure). + -- Everything after -- is forwarded to the adapter. + -h, --help Show this help. +`; + +async function main(): Promise { + const rawArgs = process.argv.slice(2); + + // Split off adapter passthrough after a standalone `--`. + const sepIndex = rawArgs.indexOf("--"); + const ownArgs = sepIndex === -1 ? rawArgs : rawArgs.slice(0, sepIndex); + const passthrough = sepIndex === -1 ? [] : rawArgs.slice(sepIndex + 1); + + const { values } = parseArgs({ + args: ownArgs, + options: { + emitter: { type: "string" }, + baseline: { type: "string" }, + head: { type: "string" }, + specs: { type: "string" }, + name: { type: "string" }, + "work-dir": { type: "string" }, + open: { type: "boolean" }, + vscode: { type: "boolean" }, + terminal: { type: "boolean" }, + patch: { type: "string" }, + html: { type: "string" }, + "fail-on-diff": { type: "boolean" }, + "run-tests": { type: "boolean" }, + "test-env": { type: "string" }, + "test-target": { type: "string", default: "head" }, + opt: { type: "string", multiple: true }, + help: { type: "boolean", short: "h" }, + }, + allowPositionals: false, + }); + + const log = createLogger(); + + if (values.help || ownArgs.length === 0) { + process.stdout.write(HELP); + return 0; + } + if (!values.emitter) { + log.error("--emitter is required (no default). " + `Available: ${listAdapters().join(", ")}`); + return 2; + } + if (!values.baseline) { + log.error("--baseline is required."); + return 2; + } + + if (!listAdapters().includes(values.emitter)) { + log.error(`Unknown emitter '${values.emitter}'. Available: ${listAdapters().join(", ")}`); + return 2; + } + const adapter = getAdapter(values.emitter); + + // Repo root = current git working tree. + const repoRoot = (await runChecked("git", ["rev-parse", "--show-toplevel"])).stdout.trim(); + + const workDir = ensureDir(values["work-dir"] ? join(values["work-dir"]) : defaultWorkDir()); + log.info(`${color.dim("work dir:")} ${workDir}`); + + const ctx: AdapterContext = { + repoRoot, + workDir, + log, + resolveSource: (ref, _packageName) => resolveSrc(ref, workDir, log), + installNpmPackage: (packageName, version) => installNpm(packageName, version, workDir, log), + }; + + // Parse adapter options (--opt key=value). + const options: Record = {}; + for (const entry of values.opt ?? []) { + const eq = entry.indexOf("="); + if (eq === -1) { + log.error(`Invalid --opt '${entry}'. Expected key=value.`); + return 2; + } + options[entry.slice(0, eq)] = entry.slice(eq + 1); + } + + // Resolve emitters. + const baselineRef = classifyRef(values.baseline, repoRoot); + const headRef: ClassifiedRef | "current" = values.head + ? classifyRef(values.head, repoRoot) + : "current"; + + log.step("Preparing baseline emitter"); + const baselineEmitter = await adapter.prepareEmitter(baselineRef, ctx); + log.step("Preparing head emitter"); + const headEmitter = await adapter.prepareEmitter(headRef, ctx); + + // Resolve specs source (local/github). `all`/omitted => adapter default (repo). + let specsDir: string | undefined; + if (values.specs && values.specs.toLowerCase() !== "all") { + const specsRef = classifyRef(values.specs, repoRoot); + if (specsRef.kind === "npm") { + log.error("--specs as an npm version is not supported; use a local folder or github ref."); + return 2; + } + specsDir = await resolveSrc(specsRef, workDir, log); + } + + // Generate both sides. + const baselineOut = ensureDir(join(workDir, "baseline")); + const headOut = ensureDir(join(workDir, "head")); + + await adapter.generate( + { + emitter: baselineEmitter, + specsDir, + outputDir: baselineOut, + nameFilter: values.name, + options, + passthrough, + }, + ctx, + ); + await adapter.generate( + { + emitter: headEmitter, + specsDir, + outputDir: headOut, + nameFilter: values.name, + options, + passthrough, + }, + ctx, + ); + + // Diff. + const diff = await diffDirs(baselineOut, headOut, log); + + // Decide how to present the diff. Explicit flags win; otherwise the default + // is a clickable HTML report written to the work dir. + const wantsVsCode = Boolean(values.vscode || values.open); + const wantsTerminal = Boolean(values.terminal); + const wantsPatch = Boolean(values.patch); + const htmlTarget = + values.html ?? + (!wantsVsCode && !wantsTerminal && !wantsPatch + ? join(workDir, "emitter-diff.html") + : undefined); + + if (!diff.hasChanges) { + log.success("No differences between baseline and head output."); + } else if (wantsTerminal) { + printDiff(diff, log); + } else { + printSummary(diff, log); + } + + if (wantsPatch) writePatch(diff, values.patch as string, log); + if (htmlTarget && diff.hasChanges) await writeHtml(diff, htmlTarget, log); + if (wantsVsCode) await openInVsCode(baselineOut, headOut, workDir, log); + + // Optionally run test suites. + if (values["run-tests"]) { + if (!adapter.runTests) { + log.warn(`Adapter '${adapter.name}' does not support --run-tests yet.`); + } else { + const envs = values["test-env"] + ?.split(",") + .map((s) => s.trim()) + .filter(Boolean); + const target = values["test-target"] ?? "head"; + const targets: Array<{ label: string; dir: string }> = []; + if (target === "head" || target === "both") targets.push({ label: "head", dir: headOut }); + if (target === "baseline" || target === "both") + targets.push({ label: "baseline", dir: baselineOut }); + + for (const t of targets) { + log.step(`Running test suites on ${t.label} output`); + await adapter.runTests( + { outputDir: t.dir, envs, nameFilter: values.name, options, passthrough }, + ctx, + ); + } + } + } + + if (values["fail-on-diff"] && diff.hasChanges) { + log.error("Differences detected and --fail-on-diff is set."); + return 1; + } + return 0; +} + +main() + .then((code) => process.exit(code)) + .catch((err) => { + createLogger().error(err?.stack ?? String(err)); + process.exit(1); + }); diff --git a/eng/emitter-diff/src/diff.ts b/eng/emitter-diff/src/diff.ts new file mode 100644 index 00000000000..e15ed65b3f7 --- /dev/null +++ b/eng/emitter-diff/src/diff.ts @@ -0,0 +1,229 @@ +/** + * Diff engine. One canonical unified patch (`git diff --no-index`) is the + * source of truth; it is then rendered for whichever environment is in use: + * - terminal: colored patch + summary + * - local `--open`: VS Code folder diff + * - CI `--html`: rendered via diff2html (optional dependency, lazily loaded) + */ +import { cpSync, mkdirSync, readdirSync, rmSync, writeFileSync } from "node:fs"; +import { basename, dirname, join, resolve } from "node:path"; +import { pathToFileURL } from "node:url"; + +import type { Logger } from "./types.js"; +import { color, run, runChecked } from "./util.js"; + +export interface DiffResult { + /** The unified patch text (empty when there are no differences). */ + patch: string; + /** True when the two trees differ. */ + hasChanges: boolean; + filesChanged: number; + insertions: number; + deletions: number; +} + +/** + * Produce a unified patch between two directories using git's directory diff, + * which works outside a repo and ignores index state. + */ +export async function diffDirs( + baselineDir: string, + headDir: string, + log: Logger, +): Promise { + log.step("Diffing generated output"); + + // When both dirs share a parent, diff with relative names from that parent so + // the patch carries clean, comparable paths instead of absolute Windows ones. + const parent = dirname(baselineDir); + const sharesParent = dirname(headDir) === parent; + const baseName = basename(baselineDir); + const headName = basename(headDir); + const args = sharesParent + ? ["diff", "--no-index", "--no-color", "--", baseName, headName] + : ["diff", "--no-index", "--no-color", "--", baselineDir, headDir]; + + // `git diff --no-index` exits 1 when there are differences β€” that is not an error. + const result = await run("git", args, { cwd: sharesParent ? parent : undefined }); + if (result.code > 1) { + throw new Error(`git diff failed (${result.code}): ${result.stderr}`); + } + + // Strip the baseline/head root segments so each file shows as a single + // modification (a/pkg/x vs b/pkg/x) rather than a rename across roots. + const patch = sharesParent + ? result.stdout.replace( + new RegExp(`([ab])/(?:${escapeRe(baseName)}|${escapeRe(headName)})/`, "g"), + "$1/", + ) + : result.stdout; + + const stats = summarize(patch); + return { patch, hasChanges: patch.trim().length > 0, ...stats }; +} + +function escapeRe(s: string): string { + return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"); +} + +function summarize(patch: string): { + filesChanged: number; + insertions: number; + deletions: number; +} { + let filesChanged = 0; + let insertions = 0; + let deletions = 0; + for (const line of patch.split("\n")) { + if (line.startsWith("diff --git") || line.startsWith("diff --no-index")) filesChanged++; + else if (line.startsWith("+") && !line.startsWith("+++")) insertions++; + else if (line.startsWith("-") && !line.startsWith("---")) deletions++; + } + return { filesChanged, insertions, deletions }; +} + +/** Print a colorized patch and a one-line summary to the terminal. */ +export function printDiff(diff: DiffResult, log: Logger): void { + if (!diff.hasChanges) { + log.success("No differences between baseline and head output."); + return; + } + for (const line of diff.patch.split("\n")) { + if (line.startsWith("+") && !line.startsWith("+++")) + process.stdout.write(color.green(line) + "\n"); + else if (line.startsWith("-") && !line.startsWith("---")) + process.stdout.write(color.red(line) + "\n"); + else if (line.startsWith("@@")) process.stdout.write(color.cyan(line) + "\n"); + else if (line.startsWith("diff ") || line.startsWith("index ")) + process.stdout.write(color.bold(line) + "\n"); + else process.stdout.write(line + "\n"); + } + printSummary(diff, log); +} + +export function printSummary(diff: DiffResult, log: Logger): void { + log.info( + `${color.bold("Diff summary:")} ${diff.filesChanged} file(s), ` + + `${color.green("+" + diff.insertions)} / ${color.red("-" + diff.deletions)}`, + ); +} + +/** Write the raw unified patch to a file instead of dumping it to the terminal. */ +export function writePatch(diff: DiffResult, outFile: string, log: Logger): void { + writeFileSync(outFile, diff.patch, "utf8"); + if (!diff.hasChanges) { + log.success( + `No differences between baseline and head output (wrote empty patch to ${outFile}).`, + ); + return; + } + log.success(`Wrote unified diff to ${outFile}`); +} + +/** + * Render the patch to a self-contained HTML file via diff2html. diff2html is an + * optional dependency loaded lazily so the core runs without it installed. + */ +export async function writeHtml(diff: DiffResult, outFile: string, log: Logger): Promise { + let html: (typeof import("diff2html"))["html"]; + try { + ({ html } = await import("diff2html")); + } catch { + throw new Error( + "Rendering --html requires the 'diff2html' package. Install it in eng/emitter-diff " + + "(it is declared as a dependency) or run with `pnpm` so it is available.", + ); + } + const body = html(diff.patch, { + drawFileList: true, + matching: "lines", + outputFormat: "side-by-side", + }); + const doc = ` + + + +Emitter diff + + + + +
Emitter diff β€” ${diff.filesChanged} file(s), +${diff.insertions} / -${diff.deletions}
+${body} + +`; + writeFileSync(outFile, doc, "utf8"); + const abs = resolve(outFile); + log.success(`Wrote HTML diff to ${abs}`); + log.info(`${color.bold("Open it:")} ${pathToFileURL(abs).href}`); +} + +/** + * Open a native side-by-side diff of the two generated trees in VS Code. + * + * VS Code has no CLI to diff two folders (`code --diff` only compares two + * files), so we materialize the comparison as a throwaway git working-tree + * change: commit the baseline tree, then overlay the head tree on top and leave + * it unstaged. Opening that folder surfaces every changed generated file in the + * Source Control view with red/green side-by-side diffs. + */ +export async function openInVsCode( + baselineDir: string, + headDir: string, + workDir: string, + log: Logger, +): Promise { + log.step("Preparing VS Code diff"); + const repo = join(workDir, "vscode-diff"); + rmSync(repo, { recursive: true, force: true }); + mkdirSync(repo, { recursive: true }); + + const git = (args: string[]) => + runChecked("git", [ + "-C", + repo, + "-c", + "user.email=emitter-diff@local", + "-c", + "user.name=emitter-diff", + "-c", + "commit.gpgsign=false", + "-c", + "core.autocrlf=false", + ...args, + ]); + + await git(["init", "-q"]); + // Commit the baseline tree as the starting point. + cpSync(baselineDir, repo, { recursive: true }); + await git(["add", "-A"]); + await git(["commit", "-q", "-m", "baseline", "--allow-empty"]); + + // Overlay the head tree (keeping .git), then stage so VS Code shows the diff. + for (const entry of readdirSync(repo)) { + if (entry === ".git") continue; + rmSync(join(repo, entry), { recursive: true, force: true }); + } + cpSync(headDir, repo, { recursive: true }); + // Drop all index entries first, then re-add. A plain `git add -A` decides a + // file is unchanged from (size, mtime) and skips re-hashing it; because the + // baseline commit and the head overlay are written within the same second, + // a same-size content edit would be treated as clean and never staged (so it + // would silently not appear in VS Code). Clearing the index forces git to + // re-hash every file's content, surfacing every real modification. + await git(["rm", "-r", "--cached", "-q", "--", "."]); + await git(["add", "-A"]); + + const result = await run("code", [repo]); + if (result.code !== 0) { + log.warn( + "Could not launch VS Code (`code` not on PATH?). Open the folder manually " + + `and use the Source Control view to browse the diff: ${repo}`, + ); + return; + } + log.success( + `Opened ${repo} in VS Code β€” use the Source Control panel to browse the diff ` + + "(baseline = last commit, head = working tree).", + ); +} diff --git a/eng/emitter-diff/src/registry.ts b/eng/emitter-diff/src/registry.ts new file mode 100644 index 00000000000..6b7bd59db55 --- /dev/null +++ b/eng/emitter-diff/src/registry.ts @@ -0,0 +1,20 @@ +/** Adapter registry. New languages register here; the core is otherwise agnostic. */ +import { pythonAdapter } from "./adapters/python.js"; +import type { EmitterAdapter } from "./types.js"; + +const adapters: Record = { + [pythonAdapter.name]: pythonAdapter, + // Future: ts, rust, java, go ... each wraps its own generate/test command. +}; + +export function getAdapter(name: string): EmitterAdapter { + const adapter = adapters[name]; + if (!adapter) { + throw new Error(`Unknown emitter '${name}'. Available: ${Object.keys(adapters).join(", ")}`); + } + return adapter; +} + +export function listAdapters(): string[] { + return Object.keys(adapters); +} diff --git a/eng/emitter-diff/src/resolver.ts b/eng/emitter-diff/src/resolver.ts new file mode 100644 index 00000000000..6f77a4fba07 --- /dev/null +++ b/eng/emitter-diff/src/resolver.ts @@ -0,0 +1,170 @@ +/** + * Language-agnostic ref resolver. + * + * Classifies a user-provided ref string into npm / local / github and + * materializes it into a local directory the adapter can consume. Building a + * source checkout into a usable emitter is intentionally NOT done here β€” that + * is language-specific and belongs to the adapter's `prepareEmitter`. + */ +import { existsSync, mkdtempSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { isAbsolute, join, resolve } from "node:path"; + +import type { ClassifiedRef, Logger } from "./types.js"; +import { ensureDir, runChecked } from "./util.js"; + +/** + * Classify a ref string. Explicit prefixes (`npm:`, `local:`, `github:`, + * `gh:`) are honored first, then a few heuristics: + * - an `https://github.com/...` url β†’ github + * - an existing filesystem path β†’ local + * - a bare `pkg@version` or semver-ish string β†’ npm + */ +export function classifyRef(raw: string, repoRoot: string): ClassifiedRef { + const trimmed = raw.trim(); + + if (trimmed.startsWith("npm:")) { + return { kind: "npm", raw, version: trimmed.slice(4) }; + } + if (trimmed.startsWith("local:")) { + const p = trimmed.slice(6); + return { kind: "local", raw, path: isAbsolute(p) ? p : resolve(repoRoot, p) }; + } + if (trimmed.startsWith("github:")) { + return parseGithub(trimmed.slice(7), raw); + } + if (trimmed.startsWith("gh:")) { + // gh: => current repo at + return { kind: "github", raw, gitRef: trimmed.slice(3) }; + } + if (/^https?:\/\/github\.com\//i.test(trimmed)) { + return parseGithubUrl(trimmed, raw); + } + + // Heuristic: existing path -> local. + const asPath = isAbsolute(trimmed) ? trimmed : resolve(repoRoot, trimmed); + if (existsSync(asPath)) { + return { kind: "local", raw, path: asPath }; + } + + // Fallback: treat as an npm version/tag (or `@scope/pkg@version`). + return { kind: "npm", raw, version: extractNpmVersion(trimmed) }; +} + +function extractNpmVersion(spec: string): string { + // `@scope/pkg@1.2.3` -> `1.2.3`; `pkg@1.2.3` -> `1.2.3`; `1.2.3` -> `1.2.3`. + const at = spec.lastIndexOf("@"); + if (at > 0) return spec.slice(at + 1); + return spec; +} + +function parseGithub(rest: string, raw: string): ClassifiedRef { + // owner/repo@ref OR owner/repo + const at = rest.lastIndexOf("@"); + if (at > 0) { + return { kind: "github", raw, repo: rest.slice(0, at), gitRef: rest.slice(at + 1) }; + } + return { kind: "github", raw, repo: rest }; +} + +function parseGithubUrl(url: string, raw: string): ClassifiedRef { + // https://github.com/owner/repo/tree/[/...] or .../commit/ + const m = url.match(/github\.com\/([^/]+)\/([^/]+)(?:\/(?:tree|commit|blob)\/([^/]+))?/i); + if (!m) return { kind: "github", raw }; + const repo = `${m[1]}/${m[2].replace(/\.git$/, "")}`; + return { kind: "github", raw, repo, gitRef: m[3] }; +} + +export function describeRef(ref: ClassifiedRef, packageName: string): string { + switch (ref.kind) { + case "npm": + return `npm ${packageName}@${ref.version}`; + case "local": + return `local ${ref.path}`; + case "github": + return `github ${ref.repo ?? ""}@${ref.gitRef ?? ""}`; + } +} + +const DEFAULT_REPO = "microsoft/typespec"; + +/** + * Materialize a local-or-github ref into a source directory. npm refs are + * handled by {@link installNpmPackage} (the package name is adapter-specific). + */ +export async function resolveSource( + ref: ClassifiedRef, + workDir: string, + log: Logger, +): Promise { + if (ref.kind === "local") { + if (!ref.path || !existsSync(ref.path)) { + throw new Error(`Local ref path does not exist: ${ref.path}`); + } + return ref.path; + } + if (ref.kind === "github") { + return cloneGithub(ref, workDir, log); + } + throw new Error(`resolveSource cannot handle npm refs directly (ref: ${ref.raw})`); +} + +async function cloneGithub(ref: ClassifiedRef, workDir: string, log: Logger): Promise { + const repo = ref.repo ?? DEFAULT_REPO; + const gitRef = ref.gitRef ?? "main"; + const dest = ensureDir(join(workDir, `github-${repo.replace(/[/]/g, "_")}-${sanitize(gitRef)}`)); + const cloneUrl = `https://github.com/${repo}.git`; + + log.step(`Fetching ${repo}@${gitRef}`); + // Shallow-clone then fetch the exact ref so both branches and SHAs work. + await runChecked("git", ["init", "-q"], { cwd: dest }); + await runChecked("git", ["remote", "add", "origin", cloneUrl], { cwd: dest }).catch(() => {}); + const fetched = await runChecked("git", ["fetch", "--depth", "1", "origin", gitRef], { + cwd: dest, + }).catch(() => undefined); + if (!fetched) { + // SHA not directly fetchable on some servers; fall back to a full fetch. + await runChecked("git", ["fetch", "origin"], { cwd: dest }); + } + await runChecked("git", ["checkout", "-q", "FETCH_HEAD"], { cwd: dest }).catch(async () => { + await runChecked("git", ["checkout", "-q", gitRef], { cwd: dest }); + }); + return dest; +} + +/** + * Install a published npm package version into an isolated dir and return the + * path to the installed package (which ships a prebuilt `dist`). + */ +export async function installNpmPackage( + packageName: string, + version: string, + workDir: string, + log: Logger, +): Promise { + const dir = ensureDir( + join(workDir, `npm-${packageName.replace(/[@/]/g, "_")}-${sanitize(version)}`), + ); + log.step(`Installing ${packageName}@${version}`); + // Create a throwaway package root and install just the one package there. + await runChecked("npm", ["init", "-y"], { cwd: dir }); + await runChecked( + "npm", + ["install", `${packageName}@${version}`, "--no-audit", "--no-fund", "--no-save"], + { cwd: dir }, + ); + const pkgDir = join(dir, "node_modules", packageName); + if (!existsSync(pkgDir)) { + throw new Error(`Installed ${packageName}@${version} but ${pkgDir} not found`); + } + return pkgDir; +} + +function sanitize(s: string): string { + return s.replace(/[^a-z0-9._-]/gi, "-").slice(0, 40); +} + +/** Create a fresh scratch dir under the OS temp dir when `--work-dir` is omitted. */ +export function defaultWorkDir(): string { + return mkdtempSync(join(tmpdir(), "emitter-diff-")); +} diff --git a/eng/emitter-diff/src/types.ts b/eng/emitter-diff/src/types.ts new file mode 100644 index 00000000000..cfd70e0f778 --- /dev/null +++ b/eng/emitter-diff/src/types.ts @@ -0,0 +1,116 @@ +/** + * Core, language-agnostic types for the emitter-diff tool. + * + * The orchestrator, ref resolver and diff engine depend only on the generic + * {@link EmitterAdapter} contract defined here. Nothing in this file (or in the + * core) knows anything about a specific language's tooling β€” all language + * details live behind an adapter. + */ + +/** The three kinds of source a ref can point at. */ +export type RefKind = "npm" | "local" | "github"; + +/** + * A classified reference to either an emitter version or a specs source. + * + * Accepted user syntaxes (see {@link classifyRef}): + * - npm: `npm:1.2.3`, `1.2.3`, `@scope/pkg@1.2.3` + * - local: `local:/abs/or/rel/path`, or any existing filesystem path + * - github: `github:owner/repo@`, `gh:` (this repo), or an `https://github.com/...` url + */ +export interface ClassifiedRef { + kind: RefKind; + /** The original, unparsed ref string. */ + raw: string; + /** npm: the version/tag (e.g. `1.2.3`, `latest`). */ + version?: string; + /** local: the absolute path on disk. */ + path?: string; + /** github: `owner/repo` (defaults to the current repo when omitted). */ + repo?: string; + /** github: branch, tag or sha. */ + gitRef?: string; +} + +/** A built/usable emitter, ready to be pointed at by the adapter's generate step. */ +export interface ResolvedEmitter { + /** Directory containing the usable emitter build. */ + dir: string; + /** Human-readable label for logs (e.g. `npm @typespec/http-client-python@0.34.0`). */ + label: string; +} + +/** Shared context handed to every adapter call. */ +export interface AdapterContext { + /** Repo root (the git working tree the tool was invoked from). */ + repoRoot: string; + /** Scratch directory the adapter may use for builds/installs. */ + workDir: string; + /** Structured logger. */ + log: Logger; + /** + * Core helper that materializes a {@link ClassifiedRef} into a local source + * directory (handles `local` passthrough and `github` fetch). For `npm`, the + * adapter typically resolves the package itself via {@link installNpmPackage}. + */ + resolveSource(ref: ClassifiedRef, packageName: string): Promise; + /** Core helper that installs an npm package version and returns its dir. */ + installNpmPackage(packageName: string, version: string): Promise; +} + +export interface GenerateRequest { + /** Resolved emitter build to generate with. */ + emitter: ResolvedEmitter; + /** Resolved specs directory, or undefined to use the adapter's repo default. */ + specsDir?: string; + /** Directory the generated code must be written to. */ + outputDir: string; + /** Optional name/pattern filter limiting which specs/packages are generated. */ + nameFilter?: string; + /** Adapter-specific options collected from repeatable `--opt key=value`. */ + options: Record; + /** Everything after a `--` on the command line, forwarded verbatim. */ + passthrough: string[]; +} + +export interface RunTestsRequest { + /** The generated output tree to run suites against. */ + outputDir: string; + /** Adapter-defined suite/environment names (e.g. `test`, `lint`, `mypy`). */ + envs?: string[]; + nameFilter?: string; + options: Record; + passthrough: string[]; +} + +/** + * Per-language plugin. A thin wrapper over an emitter's own generate and test + * commands. The core never reaches around this contract. + */ +export interface EmitterAdapter { + /** Stable id used by `--emitter` (e.g. `python`). */ + readonly name: string; + /** npm package name, used when a ref is an npm version. */ + readonly packageName: string; + + /** + * Turn a classified ref (or the special `current` checkout) into a usable, + * built emitter. `npm` versions ship prebuilt; `local`/`github`/`current` + * may need a build, which is the adapter's responsibility. + */ + prepareEmitter(ref: ClassifiedRef | "current", ctx: AdapterContext): Promise; + + /** Generate code into `request.outputDir` using `request.emitter`. */ + generate(request: GenerateRequest, ctx: AdapterContext): Promise; + + /** Optional: run the emitter's test suites against an output tree. */ + runTests?(request: RunTestsRequest, ctx: AdapterContext): Promise; +} + +export interface Logger { + info(msg: string): void; + warn(msg: string): void; + error(msg: string): void; + step(msg: string): void; + success(msg: string): void; +} diff --git a/eng/emitter-diff/src/util.ts b/eng/emitter-diff/src/util.ts new file mode 100644 index 00000000000..eb31a127214 --- /dev/null +++ b/eng/emitter-diff/src/util.ts @@ -0,0 +1,104 @@ +/** + * Small shared utilities with zero external dependencies so the tool can run + * via `node`/`tsx` without a workspace install. + */ +import { spawn, type SpawnOptions } from "node:child_process"; +import { mkdirSync } from "node:fs"; + +import type { Logger } from "./types.js"; + +// ---- Minimal ANSI colors (no picocolors dependency) ---- + +const useColor = process.stdout.isTTY && process.env.NO_COLOR === undefined; +function wrap(open: number, close: number): (s: string) => string { + return (s) => (useColor ? `\x1b[${open}m${s}\x1b[${close}m` : s); +} +export const color = { + bold: wrap(1, 22), + dim: wrap(2, 22), + red: wrap(31, 39), + green: wrap(32, 39), + yellow: wrap(33, 39), + blue: wrap(34, 39), + cyan: wrap(36, 39), + gray: wrap(90, 39), +}; + +export function createLogger(): Logger { + /* eslint-disable no-console */ + return { + info: (m) => console.log(m), + warn: (m) => console.warn(`${color.yellow("warn")} ${m}`), + error: (m) => console.error(`${color.red("error")} ${m}`), + step: (m) => console.log(`${color.cyan("β€Ί")} ${color.bold(m)}`), + success: (m) => console.log(`${color.green("βœ“")} ${m}`), + }; + /* eslint-enable no-console */ +} + +export function ensureDir(dir: string): string { + mkdirSync(dir, { recursive: true }); + return dir; +} + +export interface RunResult { + code: number; + stdout: string; + stderr: string; +} + +/** + * Spawn a command and resolve with its captured output. Never rejects on a + * non-zero exit; inspect {@link RunResult.code}. Set `inherit` to stream + * output straight to the terminal (used for long generation/test runs). + */ +export function run( + cmd: string, + args: string[], + opts: { cwd?: string; env?: NodeJS.ProcessEnv; inherit?: boolean } = {}, +): Promise { + return new Promise((resolve, reject) => { + // Only route through a shell for Windows .cmd shims (npm/pnpm/npx/code/yarn). + // Native binaries like git/node are spawned directly to avoid the shell + // argument-escaping deprecation and quoting pitfalls. + const needsShell = process.platform === "win32" && /^(npm|pnpm|npx|yarn|code)$/.test(cmd); + const spawnOpts: SpawnOptions = { + cwd: opts.cwd, + env: opts.env ?? process.env, + stdio: opts.inherit ? "inherit" : "pipe", + shell: needsShell, + }; + // With `shell: true`, passing an args array triggers a Node deprecation + // (DEP0190). Build a single quoted command line instead; spawn directly + // with the args array when no shell is involved. + const child = needsShell + ? spawn([cmd, ...args.map(quoteForShell)].join(" "), spawnOpts) + : spawn(cmd, args, spawnOpts); + let stdout = ""; + let stderr = ""; + child.stdout?.on("data", (d) => (stdout += d.toString())); + child.stderr?.on("data", (d) => (stderr += d.toString())); + child.on("error", reject); + child.on("close", (code) => resolve({ code: code ?? 0, stdout, stderr })); + }); +} + +/** Quote an argument for cmd.exe when running through a shell. */ +function quoteForShell(s: string): string { + if (s.length > 0 && /^[A-Za-z0-9_.:\\/=@^-]+$/.test(s)) return s; + return `"${s.replace(/"/g, '""')}"`; +} + +/** Run a command and throw if it exits non-zero. */ +export async function runChecked( + cmd: string, + args: string[], + opts: { cwd?: string; env?: NodeJS.ProcessEnv; inherit?: boolean } = {}, +): Promise { + const result = await run(cmd, args, opts); + if (result.code !== 0) { + const detail = opts.inherit ? "" : `\n${result.stderr || result.stdout}`; + throw new Error(`Command failed (${result.code}): ${cmd} ${args.join(" ")}${detail}`); + } + return result; +} diff --git a/eng/emitter-diff/tsconfig.json b/eng/emitter-diff/tsconfig.json new file mode 100644 index 00000000000..f51bfa6da96 --- /dev/null +++ b/eng/emitter-diff/tsconfig.json @@ -0,0 +1,16 @@ +{ + "compilerOptions": { + "module": "nodenext", + "moduleResolution": "nodenext", + "target": "es2022", + "lib": ["es2023"], + "strict": true, + "skipLibCheck": true, + "noEmit": true, + "verbatimModuleSyntax": true, + "esModuleInterop": true, + "forceConsistentCasingInFileNames": true, + "types": ["node"] + }, + "include": ["src/**/*.ts"] +} diff --git a/packages/http-client-python/eng/scripts/ci/regenerate.ts b/packages/http-client-python/eng/scripts/ci/regenerate.ts index e6c8cee1110..bc80dd93367 100644 --- a/packages/http-client-python/eng/scripts/ci/regenerate.ts +++ b/packages/http-client-python/eng/scripts/ci/regenerate.ts @@ -40,6 +40,9 @@ const argv = parseArgs({ pluginDir: { type: "string" }, emitterName: { type: "string" }, generatedFolder: { type: "string" }, + httpSpecsDir: { type: "string" }, + azureSpecsDir: { type: "string" }, + "no-baseline": { type: "boolean" }, jobs: { type: "string", short: "j" }, help: { type: "boolean", short: "h" }, }, @@ -70,6 +73,15 @@ ${pc.bold("Options:")} ${pc.cyan("-j, --jobs ")} Number of parallel compilation tasks (default: 30 on Linux/Mac, 10 on Windows). + ${pc.cyan("--httpSpecsDir ")} + Override the @typespec/http-specs specs directory (used by emitter-diff). + + ${pc.cyan("--azureSpecsDir ")} + Override the @azure-tools/azure-http-specs specs directory (used by emitter-diff). + + ${pc.cyan("--no-baseline")} + Skip cloning the published-package baseline tree (used by emitter-diff). + ${pc.cyan("-h, --help")} Show this help message. @@ -94,8 +106,12 @@ const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url)); const PLUGIN_DIR = argv.values.pluginDir ? resolve(argv.values.pluginDir) : resolve(SCRIPT_DIR, "../../../"); -const AZURE_HTTP_SPECS = resolve(PLUGIN_DIR, "node_modules/@azure-tools/azure-http-specs/specs"); -const HTTP_SPECS = resolve(PLUGIN_DIR, "node_modules/@typespec/http-specs/specs"); +const AZURE_HTTP_SPECS = argv.values.azureSpecsDir + ? resolve(argv.values.azureSpecsDir) + : resolve(PLUGIN_DIR, "node_modules/@azure-tools/azure-http-specs/specs"); +const HTTP_SPECS = argv.values.httpSpecsDir + ? resolve(argv.values.httpSpecsDir) + : resolve(PLUGIN_DIR, "node_modules/@typespec/http-specs/specs"); const GENERATED_FOLDER = argv.values.generatedFolder ? resolve(argv.values.generatedFolder) : resolve(PLUGIN_DIR, "generator"); @@ -256,7 +272,11 @@ async function main() { const startTime = performance.now(); let success: boolean; - await prepareBaselineOfGeneratedCode(GENERATED_FOLDER); + // `--no-baseline` skips cloning the published-package baseline tree; the + // emitter-diff tool generates each side fresh, so the baseline clone is noise. + if (!argv.values["no-baseline"]) { + await prepareBaselineOfGeneratedCode(GENERATED_FOLDER); + } if (flavor) { success = await regenerateFlavor(flavor, name, debug, jobs); diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 0209fdfc111..2c54eb05577 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -288,6 +288,9 @@ catalogs: decimal.js: specifier: ^10.6.0 version: 10.6.0 + diff2html: + specifier: ^3.4.48 + version: 3.4.56 ecmarkup: specifier: ~23.0.2 version: 23.0.2 @@ -626,6 +629,22 @@ importers: e2e: {} + eng/emitter-diff: + dependencies: + diff2html: + specifier: 'catalog:' + version: 3.4.56 + devDependencies: + '@types/node': + specifier: 'catalog:' + version: 26.0.0 + tsx: + specifier: 'catalog:' + version: 4.22.4 + typescript: + specifier: 'catalog:' + version: 6.0.3 + packages/asset-emitter: devDependencies: '@types/node': @@ -6356,6 +6375,10 @@ packages: '@polka/url@1.0.0-next.29': resolution: {integrity: sha512-wwQAWhWSuHaag8c4q/KN/vCoeOJYshAIvMQwD4GpSb3OiZklFfvAgmj0VCBBImRpuF/aFgIRzllXlVX93Jevww==} + '@profoundlogic/hogan@3.0.4': + resolution: {integrity: sha512-pmNVGuooS30Mm7YbZd5T7E5zYVO6D5Ct91sn4T39mUvMUc3sCGridcnhAufL1/Bz2QzAtzEn0agNrdk3+5yWzw==} + hasBin: true + '@reflink/reflink-darwin-arm64@0.1.19': resolution: {integrity: sha512-ruy44Lpepdk1FqDz38vExBY/PVUsjxZA+chd9wozjUH9JjuDT/HEaQYA6wYN9mf041l0yLVar6BCZuWABJvHSA==} engines: {node: '>= 10'} @@ -9095,6 +9118,10 @@ packages: devlop@1.1.0: resolution: {integrity: sha512-RWmIqhcFf1lRYBvNmr7qTNuyCt/7/ns2jbpp1+PalgE/rDQcBT0fioSMUpJ93irlUhC5hrg4cYqe6U+0ImW0rA==} + diff2html@3.4.56: + resolution: {integrity: sha512-u9gfn+BlbHcyO7vItCIC4z49LJDUt31tODzOfAuJ5R1E7IdlRL6KjugcB9zOpejD+XiR+dDZbsnHSQ3g6A/u8A==} + engines: {node: '>=12'} + diff@5.2.2: resolution: {integrity: sha512-vtcDfH3TOjP8UekytvnHH1o1P4FcUdt4eQ1Y+Abap1tk/OB2MWQvcwS2ClCd1zuIhc3JKOx6p3kod8Vfys3E+A==} engines: {node: '>=0.3.1'} @@ -9906,6 +9933,10 @@ packages: resolution: {integrity: sha512-EqYpWyTF2s8nMfttfBA2yLKPNoZCO33pLS4MnbXQ4hECf1TKujCt1Kq7QAdrio7roL4+CqsfjqwYj4tYgq0pJQ==} engines: {node: '>=12.0.0'} + highlight.js@11.11.1: + resolution: {integrity: sha512-Xwwo44whKBVCYoliBQwaPvtd/2tYFkRQtXDWj1nackaV2JPXx3L0+Jvd8/qCJ2p+ML0/XVkJ2q+Mr+UVdpJK5w==} + engines: {node: '>=12.0.0'} + hosted-git-info@4.1.0: resolution: {integrity: sha512-kyCuEOWjJqZuDbRHzL8V93NzQhwIB71oFWSyzVo+KPZI+pnQPPxucdkrOZvkLRnrf5URsQM+IJ09Dw29cRALIA==} engines: {node: '>=10'} @@ -18538,6 +18569,10 @@ snapshots: '@polka/url@1.0.0-next.29': {} + '@profoundlogic/hogan@3.0.4': + dependencies: + nopt: 1.0.10 + '@reflink/reflink-darwin-arm64@0.1.19': optional: true @@ -21757,6 +21792,13 @@ snapshots: dependencies: dequal: 2.0.3 + diff2html@3.4.56: + dependencies: + '@profoundlogic/hogan': 3.0.4 + diff: 8.0.4 + optionalDependencies: + highlight.js: 11.11.1 + diff@5.2.2: {} diff@8.0.4: {} @@ -22869,6 +22911,9 @@ snapshots: highlight.js@11.0.1: {} + highlight.js@11.11.1: + optional: true + hosted-git-info@4.1.0: dependencies: lru-cache: 6.0.0 diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml index 7aa0552c415..fbaa8589069 100644 --- a/pnpm-workspace.yaml +++ b/pnpm-workspace.yaml @@ -1,5 +1,6 @@ packages: - packages/* + - eng/emitter-diff - e2e - website - "!packages/http-client-csharp/**" @@ -101,6 +102,7 @@ catalog: cspell: ^10.0.0 debounce: ^3.0.0 decimal.js: ^10.6.0 + diff2html: ^3.4.48 ecmarkup: ~23.0.2 env-paths: ^4.0.0 es-module-shims: ^2.8.0 From dadc8413c297581c1bcd0b280b5633351369a604 Mon Sep 17 00:00:00 2001 From: Libba Lawrence Date: Tue, 30 Jun 2026 13:26:13 -0700 Subject: [PATCH 02/52] Add approved-baseline gate to emitter-diff CI CI now diffs the PR's emitter against the emitter at the commit recorded in eng/emitter-diff/baselines/python.sha and fails when generated output differs. To approve an intended change, update that SHA to a commit on the branch that contains the emitter changes and push; once the baseline matches head the diff is empty and the check passes. - cli.ts: --fail-on-diff now exits 2 for "diff present" (vs 1 for hard errors) so CI can distinguish an unapproved diff from a failure. - baselines/python.sha: the approved baseline commit. - ci-emitter-diff-python.yml: read the SHA file as baseline, run with --fail-on-diff, enforce the gate, and explain approval in the summary/comment. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- .github/workflows/ci-emitter-diff-python.yml | 55 ++++++++++++++++---- eng/emitter-diff/README.md | 11 +++- eng/emitter-diff/baselines/python.sha | 6 +++ eng/emitter-diff/src/cli.ts | 7 ++- 4 files changed, 66 insertions(+), 13 deletions(-) create mode 100644 eng/emitter-diff/baselines/python.sha diff --git a/.github/workflows/ci-emitter-diff-python.yml b/.github/workflows/ci-emitter-diff-python.yml index a3741500268..b2788cbe296 100644 --- a/.github/workflows/ci-emitter-diff-python.yml +++ b/.github/workflows/ci-emitter-diff-python.yml @@ -23,7 +23,7 @@ on: workflow_dispatch: inputs: baseline: - description: "Baseline emitter ref (npm version, local path, or github ref). Defaults to the PR base commit." + description: "Baseline emitter ref (npm version, local path, or github ref). Defaults to the approved baseline SHA file." required: false default: "" @@ -65,10 +65,17 @@ jobs: run: | input="${{ github.event.inputs.baseline }}" if [ -z "$input" ]; then - base_sha="${{ github.event.pull_request.base.sha }}" + sha_file="eng/emitter-diff/baselines/python.sha" + base_sha="$(grep -vE '^[[:space:]]*(#|$)' "$sha_file" | head -n1 | tr -d '[:space:]')" + if [ -z "$base_sha" ]; then + echo "::error::No approved baseline SHA found in $sha_file" + exit 1 + fi + echo "Approved baseline SHA: $base_sha (from $sha_file)" git worktree add "${{ runner.temp }}/baseline" "$base_sha" (cd "${{ runner.temp }}/baseline/packages/http-client-python" && npm ci && npm run build && npm run install) input="local:${{ runner.temp }}/baseline/packages/http-client-python" + echo "sha=$base_sha" >> "$GITHUB_OUTPUT" fi echo "ref=$input" >> "$GITHUB_OUTPUT" echo "Baseline: $input" @@ -83,8 +90,9 @@ jobs: --work-dir "${{ runner.temp }}/emitter-diff" \ --html "${{ runner.temp }}/emitter-diff.html" \ --patch "${{ runner.temp }}/emitter-diff.patch" \ + --fail-on-diff \ | tee "${{ runner.temp }}/emitter-diff.log" - echo "status=$?" >> "$GITHUB_OUTPUT" + echo "status=${PIPESTATUS[0]}" >> "$GITHUB_OUTPUT" - name: Write job summary if: always() @@ -92,7 +100,17 @@ jobs: { echo "## Emitter diff" echo "" - echo "Baseline: \`${{ steps.baseline.outputs.ref }}\` vs current checkout." + echo "Baseline (approved): \`${{ steps.baseline.outputs.sha }}\` vs current checkout." + echo "" + if [ "${{ steps.diff.outputs.status }}" = "2" ]; then + echo "❌ **Generated output changed vs the approved baseline.**" + echo "" + echo "If this change is intended, approve it by updating" + echo "\`eng/emitter-diff/baselines/python.sha\` to a commit on your branch that" + echo "contains your emitter changes, then push." + elif [ "${{ steps.diff.outputs.status }}" = "0" ]; then + echo "βœ… Generated output matches the approved baseline." + fi echo "" echo '```' grep -E "Diff summary:" "${{ runner.temp }}/emitter-diff.log" || echo "No summary captured." @@ -115,7 +133,7 @@ jobs: continue-on-error: true uses: actions/github-script@v7 env: - BASELINE: ${{ steps.baseline.outputs.ref }} + BASELINE: ${{ steps.baseline.outputs.sha }} PATCH_FILE: ${{ runner.temp }}/emitter-diff.patch HTML_FILE: ${{ runner.temp }}/emitter-diff.html with: @@ -140,11 +158,11 @@ jobs: const htmlExists = fs.existsSync(process.env.HTML_FILE); let body = `${marker}\n## 🐍 Python emitter diff\n\n` + - `Baseline \`${process.env.BASELINE}\` vs this PR's checkout.\n\n`; + `Approved baseline \`${process.env.BASELINE}\` vs this PR's checkout.\n\n`; if (!hasChanges) { - body += `βœ… **No changes** to generated output.\n`; + body += `βœ… **No changes** β€” generated output matches the approved baseline.\n`; } else { - body += `**${files.length} file(s) changed** Β· +${insertions} / -${deletions}\n\n`; + body += `❌ **${files.length} file(s) changed** Β· +${insertions} / -${deletions}\n\n`; const shown = files.slice(0, 50); body += `
Changed files\n\n` + shown.map((f) => `- \`${f}\``).join("\n") + @@ -152,8 +170,11 @@ jobs: `\n
\n\n`; if (htmlExists) { body += `πŸ“„ Download the **emitter-diff-html** artifact from the ` + - `[workflow run](${runUrl}) for the full side-by-side rendered diff.\n`; + `[workflow run](${runUrl}) for the full side-by-side rendered diff.\n\n`; } + body += `**This check fails until the change is approved.** If the new output is ` + + `intended, update \`eng/emitter-diff/baselines/python.sha\` to a commit on this ` + + `branch that contains your emitter changes, then push.\n`; } body += `\n_Generated by \`eng/emitter-diff\`._`; @@ -166,3 +187,19 @@ jobs: } else { await github.rest.issues.createComment({ owner, repo, issue_number, body }); } + + - name: Enforce baseline approval + if: always() + run: | + status="${{ steps.diff.outputs.status }}" + if [ "$status" = "2" ]; then + echo "::error::Generated output differs from the approved baseline (${{ steps.baseline.outputs.sha }})." + echo "Review the emitter-diff-html artifact. If the change is intended, approve it by" + echo "updating eng/emitter-diff/baselines/python.sha to a commit on your branch that" + echo "contains your emitter changes, then push." + exit 1 + elif [ "$status" != "0" ]; then + echo "::error::emitter-diff failed (exit $status). See the log and artifact." + exit 1 + fi + echo "Generated output matches the approved baseline." diff --git a/eng/emitter-diff/README.md b/eng/emitter-diff/README.md index 6774898d13f..61f4401588b 100644 --- a/eng/emitter-diff/README.md +++ b/eng/emitter-diff/README.md @@ -138,8 +138,9 @@ code vscode-diff ## CI integration `.github/workflows/ci-emitter-diff-python.yml` runs on PRs that touch the python emitter or this -tool. It builds the python emitter (and a venv) for both the PR's checkout and a worktree of the -PR's base commit, diffs the two, and then: +tool. The **approved baseline** is a commit SHA stored in +`eng/emitter-diff/baselines/python.sha`. CI builds the python emitter (and a venv) for both the +PR's checkout and a worktree of that approved commit, diffs the two, and then: - uploads the rendered **`emitter-diff-html`** artifact (full side-by-side diff; downloadable from the workflow run β€” GitHub artifacts are zip downloads, so they can't be rendered inline in a @@ -148,6 +149,12 @@ PR's base commit, diffs the two, and then: - posts a **sticky PR comment** (updated in place on each push) listing the changed files and `+`/`-` counts with a link to download the artifact. +**Approval gate:** if the generated output differs from the approved baseline, the +`--fail-on-diff` run exits with code `2` and the job **fails**. To approve an intended change, +update `eng/emitter-diff/baselines/python.sha` to a commit on your branch that contains your +emitter changes, then push. Once the baseline SHA points at a commit whose emitter matches the +PR's emitter, the diff is empty and the check passes. + The comment step needs `pull-requests: write`. PRs **from forks** get a read-only token, so the comment is best-effort there (`continue-on-error`) β€” the artifact and job-summary still work. diff --git a/eng/emitter-diff/baselines/python.sha b/eng/emitter-diff/baselines/python.sha new file mode 100644 index 00000000000..d75a167710b --- /dev/null +++ b/eng/emitter-diff/baselines/python.sha @@ -0,0 +1,6 @@ +# Approved baseline for the python emitter-diff gate. +# This is the commit whose generated output is currently blessed. CI generates +# code with the emitter at this commit and with the PR's emitter, and fails if +# they differ. To approve a new generated output, update the SHA below to a +# commit on your branch that contains your emitter changes, then push. +37199629393b92015668f107b3ac2502ca734f53 diff --git a/eng/emitter-diff/src/cli.ts b/eng/emitter-diff/src/cli.ts index 43822f64641..ce5790be0b9 100644 --- a/eng/emitter-diff/src/cli.ts +++ b/eng/emitter-diff/src/cli.ts @@ -45,7 +45,8 @@ ${color.bold("Options:")} --vscode Open the diff in VS Code instead of writing HTML. --terminal Print the full colored patch to the terminal instead. --patch Write the raw unified diff to a file. - --fail-on-diff Exit non-zero when output differs (CI gating). + --fail-on-diff Exit non-zero when output differs (CI gating). Exit + code 2 means "diff present"; 1 means a hard error. --run-tests Run the adapter's test suites on the output. --test-env Suites to run (adapter-defined), e.g. test,lint,mypy. --test-target head | baseline | both (default: head). @@ -234,7 +235,9 @@ async function main(): Promise { if (values["fail-on-diff"] && diff.hasChanges) { log.error("Differences detected and --fail-on-diff is set."); - return 1; + // Exit code 2 is reserved for "diff present" so CI can distinguish an + // expected-but-unapproved diff from a hard failure (exit 1). + return 2; } return 0; } From 244f1346e98067425b80c593ae76eeee6c57e7c6 Mon Sep 17 00:00:00 2001 From: Libba Lawrence Date: Tue, 30 Jun 2026 13:29:45 -0700 Subject: [PATCH 03/52] Add gpgsign to cspell word list Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- cspell.yaml | 1 + 1 file changed, 1 insertion(+) diff --git a/cspell.yaml b/cspell.yaml index 04bf892ca38..ad4a91cbffd 100644 --- a/cspell.yaml +++ b/cspell.yaml @@ -98,6 +98,7 @@ words: - getpgid - ghapp - giacamo + - gpgsign - graalvm - Gson - Hdvcmxk From b996a66de60f3e69c0a6b02414ae7cecb5a15c7d Mon Sep 17 00:00:00 2001 From: Libba Lawrence Date: Tue, 30 Jun 2026 13:44:16 -0700 Subject: [PATCH 04/52] Make diff2html import resilient to aggregate typecheck Use a non-literal import specifier + local type so a typecheck that doesn't install this package's deps (e.g. the parent repo's check:eng, which includes core/eng) doesn't fail with TS2307; availability is validated at runtime. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- eng/emitter-diff/src/diff.ts | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/eng/emitter-diff/src/diff.ts b/eng/emitter-diff/src/diff.ts index e15ed65b3f7..9505b013851 100644 --- a/eng/emitter-diff/src/diff.ts +++ b/eng/emitter-diff/src/diff.ts @@ -125,16 +125,22 @@ export function writePatch(diff: DiffResult, outFile: string, log: Logger): void * optional dependency loaded lazily so the core runs without it installed. */ export async function writeHtml(diff: DiffResult, outFile: string, log: Logger): Promise { - let html: (typeof import("diff2html"))["html"]; + // diff2html is an optional dependency, loaded lazily. Use a non-literal + // specifier and a local type so an aggregate typecheck that doesn't install + // this package's deps (e.g. the parent repo's `check:eng`, which includes + // `core/eng`) doesn't fail to resolve it β€” we validate availability at runtime. + type Diff2Html = { html(patch: string, options: Record): string }; + const specifier: string = "diff2html"; + let mod: Diff2Html; try { - ({ html } = await import("diff2html")); + mod = (await import(specifier)) as unknown as Diff2Html; } catch { throw new Error( "Rendering --html requires the 'diff2html' package. Install it in eng/emitter-diff " + "(it is declared as a dependency) or run with `pnpm` so it is available.", ); } - const body = html(diff.patch, { + const body = mod.html(diff.patch, { drawFileList: true, matching: "lines", outputFormat: "side-by-side", From c7d896fd14415012da5243ce6aeedef7f288c61d Mon Sep 17 00:00:00 2001 From: Libba Lawrence Date: Tue, 30 Jun 2026 13:54:21 -0700 Subject: [PATCH 05/52] Fix batch Python phase to honor --generatedFolder override run_batch.py was always passed PLUGIN_DIR as --generated-dir, so when the emitter-diff tool redirects output via --generatedFolder the batch phase looked in the wrong tree, found no .tsp-codegen config files, and wrote zero .py files (leaving the path-bearing config files behind as spurious diffs). Pass the parent of GENERATED_FOLDER instead; it equals PLUGIN_DIR in the default case so normal regeneration is unchanged. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- packages/http-client-python/eng/scripts/ci/regenerate.ts | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/packages/http-client-python/eng/scripts/ci/regenerate.ts b/packages/http-client-python/eng/scripts/ci/regenerate.ts index bc80dd93367..9fdc12b8b52 100644 --- a/packages/http-client-python/eng/scripts/ci/regenerate.ts +++ b/packages/http-client-python/eng/scripts/ci/regenerate.ts @@ -115,6 +115,10 @@ const HTTP_SPECS = argv.values.httpSpecsDir const GENERATED_FOLDER = argv.values.generatedFolder ? resolve(argv.values.generatedFolder) : resolve(PLUGIN_DIR, "generator"); +// Directory that contains `tests/generated//`. Defaults to PLUGIN_DIR (since the +// default GENERATED_FOLDER is PLUGIN_DIR/generator), but tracks a custom --generatedFolder so +// the batch Python phase reads the same output tree the TypeScript phase wrote to. +const GENERATED_PARENT = resolve(GENERATED_FOLDER, ".."); const EMITTER_NAME = argv.values.emitterName || "@typespec/http-client-python"; const ctx: RegenerateContext = { @@ -168,7 +172,7 @@ function runBatchPythonProcessing(flavor: string, configCount: number, jobs: num try { // Pass directory and flavor instead of individual config files to avoid command line length limits on Windows execSync( - `"${venvPath}" "${batchScript}" --generated-dir "${PLUGIN_DIR}" --flavor ${flavor} --jobs ${jobs}`, + `"${venvPath}" "${batchScript}" --generated-dir "${GENERATED_PARENT}" --flavor ${flavor} --jobs ${jobs}`, { stdio: "inherit", cwd: PLUGIN_DIR, From 1b64aa7decb8b7559e22bf21d75f9aed94d79f5d Mon Sep 17 00:00:00 2001 From: Libba Lawrence Date: Tue, 30 Jun 2026 14:12:57 -0700 Subject: [PATCH 06/52] Generate baseline and head in parallel by default The two sides write to isolated output dirs, use separate venvs, and emit uniquely-named temp YAML, so they can regenerate concurrently. Run them with Promise.all and tag each side's streamed output with a [baseline]/[head] prefix so the interleaved logs stay attributable. Add --sequential to opt back into one-at-a-time generation (quieter logs, lower peak CPU/memory). Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- eng/emitter-diff/src/adapters/python.ts | 11 +++- eng/emitter-diff/src/cli.ts | 58 +++++++++++-------- eng/emitter-diff/src/types.ts | 6 ++ eng/emitter-diff/src/util.ts | 75 +++++++++++++++++++++++-- 4 files changed, 118 insertions(+), 32 deletions(-) diff --git a/eng/emitter-diff/src/adapters/python.ts b/eng/emitter-diff/src/adapters/python.ts index 7b8264a1d20..ddd83fdb712 100644 --- a/eng/emitter-diff/src/adapters/python.ts +++ b/eng/emitter-diff/src/adapters/python.ts @@ -39,10 +39,15 @@ async function runScript( ctx: AdapterContext, scriptRelPath: string, args: string[], - inherit = true, + opts: { inherit?: boolean; prefix?: string } = {}, ): Promise { const cwd = pkgDir(ctx); - await runChecked("npx", ["tsx", join(cwd, scriptRelPath), ...args], { cwd, inherit }); + const inherit = opts.inherit ?? opts.prefix === undefined; + await runChecked("npx", ["tsx", join(cwd, scriptRelPath), ...args], { + cwd, + inherit, + prefix: opts.prefix, + }); } async function isBuilt(dir: string): Promise { @@ -144,7 +149,7 @@ export const pythonAdapter: EmitterAdapter = { args.push(...request.passthrough); ctx.log.step(`Generating with ${request.emitter.label} β†’ ${request.outputDir}`); - await runScript(ctx, "eng/scripts/ci/regenerate.ts", args); + await runScript(ctx, "eng/scripts/ci/regenerate.ts", args, { prefix: request.logPrefix }); }, async runTests(request: RunTestsRequest, ctx: AdapterContext): Promise { diff --git a/eng/emitter-diff/src/cli.ts b/eng/emitter-diff/src/cli.ts index ce5790be0b9..a526be5bd64 100644 --- a/eng/emitter-diff/src/cli.ts +++ b/eng/emitter-diff/src/cli.ts @@ -51,6 +51,8 @@ ${color.bold("Options:")} --test-env Suites to run (adapter-defined), e.g. test,lint,mypy. --test-target head | baseline | both (default: head). --opt key=value Repeatable adapter-specific option (e.g. --opt flavor=azure). + --sequential Generate baseline then head one at a time (default: + generate both in parallel with prefixed logs). -- Everything after -- is forwarded to the adapter. -h, --help Show this help. `; @@ -82,6 +84,7 @@ async function main(): Promise { "test-env": { type: "string" }, "test-target": { type: "string", default: "head" }, opt: { type: "string", multiple: true }, + sequential: { type: "boolean" }, help: { type: "boolean", short: "h" }, }, allowPositionals: false, @@ -155,32 +158,41 @@ async function main(): Promise { specsDir = await resolveSrc(specsRef, workDir, log); } - // Generate both sides. + // Generate both sides. By default baseline and head generate concurrently + // (their outputs, virtual envs, and temp YAML are isolated), roughly halving wall + // time at the cost of doubled peak CPU/memory and interleaved logs β€” so each + // side's output is tagged with a prefix. Use --sequential to generate one at + // a time (quieter logs, lower peak resource use). const baselineOut = ensureDir(join(workDir, "baseline")); const headOut = ensureDir(join(workDir, "head")); - await adapter.generate( - { - emitter: baselineEmitter, - specsDir, - outputDir: baselineOut, - nameFilter: values.name, - options, - passthrough, - }, - ctx, - ); - await adapter.generate( - { - emitter: headEmitter, - specsDir, - outputDir: headOut, - nameFilter: values.name, - options, - passthrough, - }, - ctx, - ); + const parallel = !values.sequential; + const baselineReq = { + emitter: baselineEmitter, + specsDir, + outputDir: baselineOut, + nameFilter: values.name, + options, + passthrough, + logPrefix: parallel ? color.dim("[baseline] ") : undefined, + }; + const headReq = { + emitter: headEmitter, + specsDir, + outputDir: headOut, + nameFilter: values.name, + options, + passthrough, + logPrefix: parallel ? color.cyan("[head] ") : undefined, + }; + + if (parallel) { + log.step("Generating baseline + head in parallel"); + await Promise.all([adapter.generate(baselineReq, ctx), adapter.generate(headReq, ctx)]); + } else { + await adapter.generate(baselineReq, ctx); + await adapter.generate(headReq, ctx); + } // Diff. const diff = await diffDirs(baselineOut, headOut, log); diff --git a/eng/emitter-diff/src/types.ts b/eng/emitter-diff/src/types.ts index cfd70e0f778..d89a00582cc 100644 --- a/eng/emitter-diff/src/types.ts +++ b/eng/emitter-diff/src/types.ts @@ -71,6 +71,12 @@ export interface GenerateRequest { options: Record; /** Everything after a `--` on the command line, forwarded verbatim. */ passthrough: string[]; + /** + * Optional prefix to tag each line of this generation's output with. Set when + * baseline and head generate concurrently so their interleaved logs stay + * attributable; when unset, output streams straight to the terminal. + */ + logPrefix?: string; } export interface RunTestsRequest { diff --git a/eng/emitter-diff/src/util.ts b/eng/emitter-diff/src/util.ts index eb31a127214..3ef50e4c7d2 100644 --- a/eng/emitter-diff/src/util.ts +++ b/eng/emitter-diff/src/util.ts @@ -50,12 +50,15 @@ export interface RunResult { /** * Spawn a command and resolve with its captured output. Never rejects on a * non-zero exit; inspect {@link RunResult.code}. Set `inherit` to stream - * output straight to the terminal (used for long generation/test runs). + * output straight to the terminal (used for long generation/test runs). Set + * `prefix` to stream each output line tagged with that prefix instead β€” useful + * when several children run concurrently and their logs would otherwise + * interleave unintelligibly. `prefix` is ignored when `inherit` is set. */ export function run( cmd: string, args: string[], - opts: { cwd?: string; env?: NodeJS.ProcessEnv; inherit?: boolean } = {}, + opts: { cwd?: string; env?: NodeJS.ProcessEnv; inherit?: boolean; prefix?: string } = {}, ): Promise { return new Promise((resolve, reject) => { // Only route through a shell for Windows .cmd shims (npm/pnpm/npx/code/yarn). @@ -76,13 +79,73 @@ export function run( : spawn(cmd, args, spawnOpts); let stdout = ""; let stderr = ""; - child.stdout?.on("data", (d) => (stdout += d.toString())); - child.stderr?.on("data", (d) => (stderr += d.toString())); + + // When a prefix is requested, tee complete lines to our own stdout/stderr + // tagged with the prefix while still capturing the raw output for the + // returned RunResult. A small line buffer holds partial trailing lines + // until the next chunk (or close) completes them. + const tee = !opts.inherit && opts.prefix !== undefined ? makeLineTee(opts.prefix) : undefined; + + child.stdout?.on("data", (d) => { + const s = d.toString(); + stdout += s; + tee?.stdout(s); + }); + child.stderr?.on("data", (d) => { + const s = d.toString(); + stderr += s; + tee?.stderr(s); + }); child.on("error", reject); - child.on("close", (code) => resolve({ code: code ?? 0, stdout, stderr })); + child.on("close", (code) => { + tee?.flush(); + resolve({ code: code ?? 0, stdout, stderr }); + }); }); } +/** + * Build a pair of line-buffering writers that emit `${prefix}${line}` to the + * parent process's stdout/stderr as complete lines arrive, plus a `flush` to + * drain any partial trailing line when the child closes. + */ +function makeLineTee(prefix: string): { + stdout: (s: string) => void; + stderr: (s: string) => void; + flush: () => void; +} { + function writer(out: NodeJS.WriteStream): { write: (s: string) => void; rest: () => string } { + let buf = ""; + return { + write(s: string) { + buf += s; + let nl: number; + while ((nl = buf.indexOf("\n")) >= 0) { + out.write(`${prefix}${buf.slice(0, nl)}\n`); + buf = buf.slice(nl + 1); + } + }, + rest() { + const r = buf; + buf = ""; + return r; + }, + }; + } + const o = writer(process.stdout); + const e = writer(process.stderr); + return { + stdout: o.write, + stderr: e.write, + flush() { + const ro = o.rest(); + if (ro) process.stdout.write(`${prefix}${ro}\n`); + const re = e.rest(); + if (re) process.stderr.write(`${prefix}${re}\n`); + }, + }; +} + /** Quote an argument for cmd.exe when running through a shell. */ function quoteForShell(s: string): string { if (s.length > 0 && /^[A-Za-z0-9_.:\\/=@^-]+$/.test(s)) return s; @@ -93,7 +156,7 @@ function quoteForShell(s: string): string { export async function runChecked( cmd: string, args: string[], - opts: { cwd?: string; env?: NodeJS.ProcessEnv; inherit?: boolean } = {}, + opts: { cwd?: string; env?: NodeJS.ProcessEnv; inherit?: boolean; prefix?: string } = {}, ): Promise { const result = await run(cmd, args, opts); if (result.code !== 0) { From ce0ab9583f9316471afdc8dbd6fe99cf778ed074 Mon Sep 17 00:00:00 2001 From: Libba Lawrence Date: Tue, 30 Jun 2026 14:32:37 -0700 Subject: [PATCH 07/52] TEMP: point emitter-diff baseline at older commit for demo Temporarily set the approved baseline to #10947 (timedelta duration encoding) so the diff PR comment and approval gate can be exercised end-to-end. Revert to the blessed HEAD SHA after the demo. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- eng/emitter-diff/baselines/python.sha | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/eng/emitter-diff/baselines/python.sha b/eng/emitter-diff/baselines/python.sha index d75a167710b..ddcae32bc9a 100644 --- a/eng/emitter-diff/baselines/python.sha +++ b/eng/emitter-diff/baselines/python.sha @@ -3,4 +3,8 @@ # code with the emitter at this commit and with the PR's emitter, and fails if # they differ. To approve a new generated output, update the SHA below to a # commit on your branch that contains your emitter changes, then push. -37199629393b92015668f107b3ac2502ca734f53 +# +# NOTE: temporarily set to an older commit (#10947, timedelta duration encoding) +# to exercise the diff PR comment + approval gate. Revert to the blessed HEAD +# SHA once the demo is done. +c8b8194a022599d4609b4f0d6fa9128515cc087d From 4fca715f42abb6058b7f75cc00f6ec5a1a1029c6 Mon Sep 17 00:00:00 2001 From: Libba Lawrence Date: Tue, 30 Jun 2026 14:53:31 -0700 Subject: [PATCH 08/52] Report emitter-diff hard errors distinctly in the PR comment A non-zero exit that is not the dedicated 'diff present' code (2) means the tool failed to run (build/venv/generate threw), not that output is unchanged. Drive the comment off the diff step's exit status so a hard error shows a clear failure notice instead of a misleading 'no changes'. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- .github/workflows/ci-emitter-diff-python.yml | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/.github/workflows/ci-emitter-diff-python.yml b/.github/workflows/ci-emitter-diff-python.yml index b2788cbe296..8a0e6c61189 100644 --- a/.github/workflows/ci-emitter-diff-python.yml +++ b/.github/workflows/ci-emitter-diff-python.yml @@ -134,6 +134,7 @@ jobs: uses: actions/github-script@v7 env: BASELINE: ${{ steps.baseline.outputs.sha }} + STATUS: ${{ steps.diff.outputs.status }} PATCH_FILE: ${{ runner.temp }}/emitter-diff.patch HTML_FILE: ${{ runner.temp }}/emitter-diff.html with: @@ -141,6 +142,7 @@ jobs: const fs = require("fs"); const marker = ""; const runUrl = `${context.serverUrl}/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId}`; + const status = process.env.STATUS; // Parse the unified patch directly so the numbers match the tool exactly. let patch = ""; @@ -154,12 +156,17 @@ jobs: else if (line.startsWith("+") && !line.startsWith("+++")) insertions++; else if (line.startsWith("-") && !line.startsWith("---")) deletions++; } - const hasChanges = patch.trim().length > 0; const htmlExists = fs.existsSync(process.env.HTML_FILE); let body = `${marker}\n## 🐍 Python emitter diff\n\n` + `Approved baseline \`${process.env.BASELINE}\` vs this PR's checkout.\n\n`; - if (!hasChanges) { + if (status !== "0" && status !== "2") { + // Hard error (build/venv/generate threw) β€” not a diff. Don't claim "no changes". + body += `⚠️ **emitter-diff failed to run** (exit \`${status}\`). This is a tool/build ` + + `error, not a generated-output diff. See the ` + + `[workflow run](${runUrl}) logs` + + (htmlExists ? ` and the **emitter-diff-html** artifact` : "") + `.\n`; + } else if (status === "0") { body += `βœ… **No changes** β€” generated output matches the approved baseline.\n`; } else { body += `❌ **${files.length} file(s) changed** Β· +${insertions} / -${deletions}\n\n`; From 943d24a5a1daf1cdea7af5e09f701c846a7b3d4e Mon Sep 17 00:00:00 2001 From: Libba Lawrence Date: Tue, 30 Jun 2026 14:53:31 -0700 Subject: [PATCH 09/52] DEMO: sample emitter output change to exercise the diff gate Revert the approved baseline to the blessed HEAD SHA and add a one-line comment to the generated package __init__.py so the PR's generated output differs from the baseline, exercising the emitter-diff PR comment + approval gate end to end. Both changes are temporary and must be reverted before merge. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- eng/emitter-diff/baselines/python.sha | 6 +----- .../generator/pygen/codegen/templates/init.py.jinja2 | 1 + 2 files changed, 2 insertions(+), 5 deletions(-) diff --git a/eng/emitter-diff/baselines/python.sha b/eng/emitter-diff/baselines/python.sha index ddcae32bc9a..d75a167710b 100644 --- a/eng/emitter-diff/baselines/python.sha +++ b/eng/emitter-diff/baselines/python.sha @@ -3,8 +3,4 @@ # code with the emitter at this commit and with the PR's emitter, and fails if # they differ. To approve a new generated output, update the SHA below to a # commit on your branch that contains your emitter changes, then push. -# -# NOTE: temporarily set to an older commit (#10947, timedelta duration encoding) -# to exercise the diff PR comment + approval gate. Revert to the blessed HEAD -# SHA once the demo is done. -c8b8194a022599d4609b4f0d6fa9128515cc087d +37199629393b92015668f107b3ac2502ca734f53 diff --git a/packages/http-client-python/generator/pygen/codegen/templates/init.py.jinja2 b/packages/http-client-python/generator/pygen/codegen/templates/init.py.jinja2 index 007009e4bc9..6cd44d9892a 100644 --- a/packages/http-client-python/generator/pygen/codegen/templates/init.py.jinja2 +++ b/packages/http-client-python/generator/pygen/codegen/templates/init.py.jinja2 @@ -1,5 +1,6 @@ {% import 'keywords.jinja2' as keywords %} # coding=utf-8 +# DEMO: emitter-diff sample change β€” revert before merge. {% if code_model.license_header %} {{ code_model.license_header }} {% endif %} From 2ab04283784f500273c08211073ba3c129cfd4a6 Mon Sep 17 00:00:00 2001 From: Libba Lawrence Date: Tue, 30 Jun 2026 15:10:57 -0700 Subject: [PATCH 10/52] Preserve the emitter-diff exit code in CI (avoid pnpm code masking) pnpm's recursive 'pnpm --filter exec' collapses any non-zero child exit into its own generic exit 1 (ERR_PNPM_RECURSIVE_EXEC_FIRST_FAIL), which masked the tool's dedicated 'diff present' code (2) as a hard error (1). Run the CLI from the package directory via plain (non-recursive) 'pnpm exec' so the real exit code propagates and the approval gate can distinguish a diff from a crash. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- .github/workflows/ci-emitter-diff-python.yml | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/.github/workflows/ci-emitter-diff-python.yml b/.github/workflows/ci-emitter-diff-python.yml index 8a0e6c61189..c01f1e20576 100644 --- a/.github/workflows/ci-emitter-diff-python.yml +++ b/.github/workflows/ci-emitter-diff-python.yml @@ -82,9 +82,14 @@ jobs: - name: Run emitter diff id: diff + working-directory: eng/emitter-diff run: | set +e - pnpm --filter @typespec/emitter-diff exec tsx src/cli.ts \ + # Run via plain (non-recursive) `pnpm exec` so the tool's real exit code + # propagates. `pnpm --filter exec` collapses any non-zero child exit + # into pnpm's own generic exit 1 (ERR_PNPM_RECURSIVE_EXEC_FIRST_FAIL), + # which would mask the "diff present" code (2) as a hard error (1). + pnpm exec tsx src/cli.ts \ --emitter python \ --baseline "${{ steps.baseline.outputs.ref }}" \ --work-dir "${{ runner.temp }}/emitter-diff" \ From 4d2044d2d29d056f66049d96cf38469c809506ca Mon Sep 17 00:00:00 2001 From: Libba Lawrence Date: Wed, 1 Jul 2026 08:20:52 -0700 Subject: [PATCH 11/52] Harden emitter-diff secondary paths (refs, specs, HTML, validation, docs) - resolver: on the full-fetch fallback, check out a github ref by name rather than FETCH_HEAD (which could be a branch head), so a SHA baseline/head never silently diffs the wrong commit. - resolver: gh: now resolves the origin repo from the local remote instead of hard-coding microsoft/typespec, so forks/renames work. - python adapter: recognize packages/http-specs and packages/azure-http-specs layouts for external --specs, and warn (instead of silently falling back to the current checkout) when an explicit --specs dir can't be resolved. - diff: --html always writes a file (a 'No differences' stub when unchanged) and inlines the diff2html stylesheet so the CI artifact renders offline. - cli: reject an invalid --test-target instead of silently running no suites. - docs: fix the broken github-sha example, note --specs doesn't accept npm refs, soften the 'no core changes' wording, and correct the stale workflow comment. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- .github/workflows/ci-emitter-diff-python.yml | 5 ++- eng/emitter-diff/README.md | 8 +++- eng/emitter-diff/src/adapters/python.ts | 20 ++++++++++ eng/emitter-diff/src/cli.ts | 16 ++++++-- eng/emitter-diff/src/diff.ts | 31 +++++++++++++++- eng/emitter-diff/src/resolver.ts | 39 +++++++++++++++----- 6 files changed, 100 insertions(+), 19 deletions(-) diff --git a/.github/workflows/ci-emitter-diff-python.yml b/.github/workflows/ci-emitter-diff-python.yml index c01f1e20576..1dac8e83039 100644 --- a/.github/workflows/ci-emitter-diff-python.yml +++ b/.github/workflows/ci-emitter-diff-python.yml @@ -1,7 +1,8 @@ name: "python / emitter diff" -# Generates code with the current checkout's emitter and with the PR's base -# commit, then diffs the two. The rendered HTML diff is uploaded as a per-PR +# Generates code with the current checkout's emitter and with the approved +# baseline emitter (the commit SHA in eng/emitter-diff/baselines/python.sha), +# then diffs the two. The rendered HTML diff is uploaded as a per-PR # artifact, and a sticky PR comment summarizes the changed files (+/-) with a # link to download it, so reviewers can see exactly how an emitter change # affects generated SDKs. Powered by the language-agnostic eng/emitter-diff tool. diff --git a/eng/emitter-diff/README.md b/eng/emitter-diff/README.md index 61f4401588b..84dbdbe7a98 100644 --- a/eng/emitter-diff/README.md +++ b/eng/emitter-diff/README.md @@ -47,6 +47,9 @@ npx tsx eng/emitter-diff/src/cli.ts --emitter python --baseline 0.34.0 `--head` defaults to the **current checkout**. `--specs` defaults to **all** repo specs. +> `--baseline`/`--head` accept all three ref kinds. `--specs` accepts **local** or **github** +> refs only (npm versions aren't a valid spec source) β€” an `npm:` spec ref is rejected. + ### Common options By default the tool writes a **clickable HTML report** (`emitter-diff.html`) into the work dir and @@ -89,7 +92,7 @@ npx tsx eng/emitter-diff/src/cli.ts --emitter python \ # Diff against a GitHub sha and run pytest + type checks on the head output: npx tsx eng/emitter-diff/src/cli.ts --emitter python \ --baseline github:microsoft/typespec@ \ - test,mypy,pyright --opt flavor=azure --run-tests < sha > --test-env + flavor=azure --run-tests --test-env test,mypy,pyright < sha > --opt ``` ## Viewing the diff in VS Code @@ -164,7 +167,8 @@ comment is best-effort there (`continue-on-error`) β€” the artifact and job-summ wrapping that emitter's own commands (e.g. rust's `npm run tspcompile`, ts's `gen-spector`). 2. Register it in `src/registry.ts`. -The core needs no changes. +That's the only wiring needed β€” the orchestrator, ref resolver, and diff engine are +language-agnostic and require no changes. ## Notes & limitations diff --git a/eng/emitter-diff/src/adapters/python.ts b/eng/emitter-diff/src/adapters/python.ts index ddd83fdb712..37f1bbaf403 100644 --- a/eng/emitter-diff/src/adapters/python.ts +++ b/eng/emitter-diff/src/adapters/python.ts @@ -146,6 +146,24 @@ export const pythonAdapter: EmitterAdapter = { if (httpSpecs) args.push("--httpSpecsDir", httpSpecs); if (azureSpecs) args.push("--azureSpecsDir", azureSpecs); + // When the user explicitly pinned specs, warn (rather than silently falling + // back to the current checkout's specs) if the expected layout wasn't found. + if (request.specsDir) { + if (!httpSpecs) { + ctx.log.warn( + `--specs was given (${request.specsDir}) but no http-specs dir was found under it ` + + `(looked for http-specs/specs, packages/http-specs/specs, specs/). Falling back to defaults.`, + ); + } + if ((flavor === undefined || flavor === "azure") && !azureSpecs) { + ctx.log.warn( + `--specs was given (${request.specsDir}) but no azure-http-specs dir was found under it ` + + `(looked for azure-http-specs/specs, packages/azure-http-specs/specs, azure/specs). ` + + `Azure specs will use the current checkout's dependency.`, + ); + } + } + args.push(...request.passthrough); ctx.log.step(`Generating with ${request.emitter.label} β†’ ${request.outputDir}`); @@ -199,6 +217,7 @@ function resolveHttpSpecs(request: GenerateRequest, ctx: AdapterContext): string if (request.specsDir) { return firstExisting([ join(request.specsDir, "http-specs", "specs"), + join(request.specsDir, "packages", "http-specs", "specs"), join(request.specsDir, "specs"), request.specsDir, ]); @@ -210,6 +229,7 @@ function resolveAzureSpecs(request: GenerateRequest, ctx: AdapterContext): strin if (request.specsDir) { return firstExisting([ join(request.specsDir, "azure-http-specs", "specs"), + join(request.specsDir, "packages", "azure-http-specs", "specs"), join(request.specsDir, "azure", "specs"), ]); } diff --git a/eng/emitter-diff/src/cli.ts b/eng/emitter-diff/src/cli.ts index a526be5bd64..4cec29160a0 100644 --- a/eng/emitter-diff/src/cli.ts +++ b/eng/emitter-diff/src/cli.ts @@ -121,7 +121,7 @@ async function main(): Promise { repoRoot, workDir, log, - resolveSource: (ref, _packageName) => resolveSrc(ref, workDir, log), + resolveSource: (ref, _packageName) => resolveSrc(ref, workDir, log, repoRoot), installNpmPackage: (packageName, version) => installNpm(packageName, version, workDir, log), }; @@ -136,6 +136,14 @@ async function main(): Promise { options[entry.slice(0, eq)] = entry.slice(eq + 1); } + // Validate --test-target early so a typo fails loudly rather than silently + // running no suites. + const testTarget = values["test-target"] ?? "head"; + if (!["head", "baseline", "both"].includes(testTarget)) { + log.error(`Invalid --test-target '${testTarget}'. Expected head | baseline | both.`); + return 2; + } + // Resolve emitters. const baselineRef = classifyRef(values.baseline, repoRoot); const headRef: ClassifiedRef | "current" = values.head @@ -155,7 +163,7 @@ async function main(): Promise { log.error("--specs as an npm version is not supported; use a local folder or github ref."); return 2; } - specsDir = await resolveSrc(specsRef, workDir, log); + specsDir = await resolveSrc(specsRef, workDir, log, repoRoot); } // Generate both sides. By default baseline and head generate concurrently @@ -217,7 +225,7 @@ async function main(): Promise { } if (wantsPatch) writePatch(diff, values.patch as string, log); - if (htmlTarget && diff.hasChanges) await writeHtml(diff, htmlTarget, log); + if (htmlTarget) await writeHtml(diff, htmlTarget, log); if (wantsVsCode) await openInVsCode(baselineOut, headOut, workDir, log); // Optionally run test suites. @@ -229,7 +237,7 @@ async function main(): Promise { ?.split(",") .map((s) => s.trim()) .filter(Boolean); - const target = values["test-target"] ?? "head"; + const target = testTarget; const targets: Array<{ label: string; dir: string }> = []; if (target === "head" || target === "both") targets.push({ label: "head", dir: headOut }); if (target === "baseline" || target === "both") diff --git a/eng/emitter-diff/src/diff.ts b/eng/emitter-diff/src/diff.ts index 9505b013851..731f4bdf04d 100644 --- a/eng/emitter-diff/src/diff.ts +++ b/eng/emitter-diff/src/diff.ts @@ -5,7 +5,8 @@ * - local `--open`: VS Code folder diff * - CI `--html`: rendered via diff2html (optional dependency, lazily loaded) */ -import { cpSync, mkdirSync, readdirSync, rmSync, writeFileSync } from "node:fs"; +import { cpSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs"; +import { createRequire } from "node:module"; import { basename, dirname, join, resolve } from "node:path"; import { pathToFileURL } from "node:url"; @@ -125,6 +126,21 @@ export function writePatch(diff: DiffResult, outFile: string, log: Logger): void * optional dependency loaded lazily so the core runs without it installed. */ export async function writeHtml(diff: DiffResult, outFile: string, log: Logger): Promise { + // No differences: write a small standalone report so `--html ` always + // produces a file (callers and CI artifact upload can rely on its presence). + if (!diff.hasChanges) { + const doc = ` + +Emitter diff + + +
Emitter diff β€” βœ… No differences between baseline and head output.
+`; + writeFileSync(outFile, doc, "utf8"); + log.success(`No differences; wrote empty HTML report to ${resolve(outFile)}`); + return; + } + // diff2html is an optional dependency, loaded lazily. Use a non-literal // specifier and a local type so an aggregate typecheck that doesn't install // this package's deps (e.g. the parent repo's `check:eng`, which includes @@ -145,12 +161,23 @@ export async function writeHtml(diff: DiffResult, outFile: string, log: Logger): matching: "lines", outputFormat: "side-by-side", }); + // Inline the diff2html stylesheet so the report renders offline (CI artifacts + // are downloaded and opened from disk). Fall back to the CDN link if the + // bundled CSS can't be located. + let styleTag: string; + try { + const require = createRequire(import.meta.url); + const cssPath = require.resolve("diff2html/bundles/css/diff2html.min.css"); + styleTag = ``; + } catch { + styleTag = ``; + } const doc = ` Emitter diff - +${styleTag} diff --git a/eng/emitter-diff/src/resolver.ts b/eng/emitter-diff/src/resolver.ts index 6f77a4fba07..8e14cabb2d5 100644 --- a/eng/emitter-diff/src/resolver.ts +++ b/eng/emitter-diff/src/resolver.ts @@ -11,7 +11,7 @@ import { tmpdir } from "node:os"; import { isAbsolute, join, resolve } from "node:path"; import type { ClassifiedRef, Logger } from "./types.js"; -import { ensureDir, runChecked } from "./util.js"; +import { ensureDir, run, runChecked } from "./util.js"; /** * Classify a ref string. Explicit prefixes (`npm:`, `local:`, `github:`, @@ -96,6 +96,7 @@ export async function resolveSource( ref: ClassifiedRef, workDir: string, log: Logger, + repoRoot?: string, ): Promise { if (ref.kind === "local") { if (!ref.path || !existsSync(ref.path)) { @@ -104,13 +105,22 @@ export async function resolveSource( return ref.path; } if (ref.kind === "github") { - return cloneGithub(ref, workDir, log); + return cloneGithub(ref, workDir, log, repoRoot); } throw new Error(`resolveSource cannot handle npm refs directly (ref: ${ref.raw})`); } -async function cloneGithub(ref: ClassifiedRef, workDir: string, log: Logger): Promise { - const repo = ref.repo ?? DEFAULT_REPO; +async function cloneGithub( + ref: ClassifiedRef, + workDir: string, + log: Logger, + repoRoot?: string, +): Promise { + // `gh:` (and any github ref without an explicit repo) means "this repo". + // Detect the current repo from its origin remote so forks/renames resolve + // correctly, falling back to the well-known repo only if detection fails. + const repo = + ref.repo ?? (repoRoot ? await detectOriginRepo(repoRoot) : undefined) ?? DEFAULT_REPO; const gitRef = ref.gitRef ?? "main"; const dest = ensureDir(join(workDir, `github-${repo.replace(/[/]/g, "_")}-${sanitize(gitRef)}`)); const cloneUrl = `https://github.com/${repo}.git`; @@ -122,16 +132,27 @@ async function cloneGithub(ref: ClassifiedRef, workDir: string, log: Logger): Pr const fetched = await runChecked("git", ["fetch", "--depth", "1", "origin", gitRef], { cwd: dest, }).catch(() => undefined); - if (!fetched) { - // SHA not directly fetchable on some servers; fall back to a full fetch. + if (fetched) { + // The targeted fetch put the requested ref at FETCH_HEAD. + await runChecked("git", ["checkout", "-q", "FETCH_HEAD"], { cwd: dest }); + } else { + // Some servers won't fetch a bare SHA directly; do a full fetch and then + // check the ref out by name (NOT FETCH_HEAD, which after a full fetch with + // no refspec may point at a branch head rather than the requested commit). await runChecked("git", ["fetch", "origin"], { cwd: dest }); - } - await runChecked("git", ["checkout", "-q", "FETCH_HEAD"], { cwd: dest }).catch(async () => { await runChecked("git", ["checkout", "-q", gitRef], { cwd: dest }); - }); + } return dest; } +/** Parse `owner/repo` from the current checkout's origin remote, if it is a GitHub remote. */ +async function detectOriginRepo(repoRoot: string): Promise { + const res = await run("git", ["-C", repoRoot, "remote", "get-url", "origin"]); + if (res.code !== 0) return undefined; + const m = res.stdout.trim().match(/github\.com[:/]([^/]+)\/(.+?)(?:\.git)?$/i); + return m ? `${m[1]}/${m[2]}` : undefined; +} + /** * Install a published npm package version into an isolated dir and return the * path to the installed package (which ships a prebuilt `dist`). From 174b1cb475608f5abe54edeceff0a747d1d6a7e8 Mon Sep 17 00:00:00 2001 From: Libba Lawrence Date: Wed, 1 Jul 2026 09:07:41 -0700 Subject: [PATCH 12/52] Fix emitter-diff path/dep handling for external baselines - cli.ts: absolutize --work-dir (resolve, not bare join). The python adapter runs regenerate.ts with a different cwd, so a relative work-dir made --generatedFolder/--pluginDir resolve against the wrong directory: outputs landed elsewhere while the diff engine compared empty dirs -> silent false 'no differences'. Now every path handed to an adapter is absolute. - cli.ts: reject --specs npm: before building emitters (fast-fail). - python.ts: ensureDeps() runs 'npm ci' when node_modules is missing so a fresh gh:/github: clone builds instead of failing with 'cannot find module'. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- eng/emitter-diff/src/adapters/python.ts | 23 +++++++++++++++--- eng/emitter-diff/src/cli.ts | 31 ++++++++++++++++++------- 2 files changed, 42 insertions(+), 12 deletions(-) diff --git a/eng/emitter-diff/src/adapters/python.ts b/eng/emitter-diff/src/adapters/python.ts index 37f1bbaf403..e334cf77fe6 100644 --- a/eng/emitter-diff/src/adapters/python.ts +++ b/eng/emitter-diff/src/adapters/python.ts @@ -54,12 +54,29 @@ async function isBuilt(dir: string): Promise { return existsSync(join(dir, "dist", "emitter", "index.js")); } +/** + * Ensure the package's npm dependencies are installed. A fresh source checkout + * (a github clone or a bare local path) has no `node_modules`, so `npm run + * build` would fail to resolve its types/deps. http-client-python is + * npm-managed (it ships its own package-lock.json), so `npm ci` here is safe. + */ +async function ensureDeps(dir: string, ctx: AdapterContext): Promise { + if (existsSync(join(dir, "node_modules"))) return; + ctx.log.warn(`No node_modules at ${dir}; installing dependencies (npm ci)...`); + const res = await run("npm", ["ci"], { cwd: dir, inherit: true }); + if (res.code !== 0 || !existsSync(join(dir, "node_modules"))) { + throw new Error( + `Could not install dependencies at ${dir} (npm ci). Run \`npm ci\` there manually and retry.`, + ); + } +} + async function ensureBuilt(dir: string, ctx: AdapterContext): Promise { if (await isBuilt(dir)) return; + // A source checkout may not have its deps installed yet; install them first + // so the build can resolve modules/types. + await ensureDeps(dir, ctx); ctx.log.warn(`Emitter at ${dir} is not built; attempting build...`); - // Best-effort build. http-client-python is npm-managed (its own - // package-lock.json); building an arbitrary source checkout may require a - // prior `npm ci`, so surface a clear error if it fails. const res = await run("npm", ["run", "build"], { cwd: dir, inherit: true }); if (res.code !== 0 || !(await isBuilt(dir))) { throw new Error( diff --git a/eng/emitter-diff/src/cli.ts b/eng/emitter-diff/src/cli.ts index 4cec29160a0..91977e51e5a 100644 --- a/eng/emitter-diff/src/cli.ts +++ b/eng/emitter-diff/src/cli.ts @@ -6,7 +6,7 @@ * and diffs the output. All language specifics live behind the selected adapter; * this file contains zero language logic. */ -import { join } from "node:path"; +import { join, resolve } from "node:path"; import { parseArgs } from "node:util"; import { diffDirs, openInVsCode, printDiff, printSummary, writeHtml, writePatch } from "./diff.js"; @@ -114,7 +114,14 @@ async function main(): Promise { // Repo root = current git working tree. const repoRoot = (await runChecked("git", ["rev-parse", "--show-toplevel"])).stdout.trim(); - const workDir = ensureDir(values["work-dir"] ? join(values["work-dir"]) : defaultWorkDir()); + // Absolutize the work dir. Adapters may run emitter scripts with a different + // cwd (python's regenerate.ts runs in packages/http-client-python), so every + // path handed to them β€” the resolved emitter dir and the baseline/head output + // dirs β€” must be absolute or outputs land in the wrong tree and the diff is + // silently empty (a false "no differences"). + const workDir = ensureDir( + values["work-dir"] ? resolve(values["work-dir"]) : defaultWorkDir(), + ); log.info(`${color.dim("work dir:")} ${workDir}`); const ctx: AdapterContext = { @@ -144,6 +151,17 @@ async function main(): Promise { return 2; } + // Classify the specs ref up front (if any) so an invalid --specs fails fast, + // before the expensive emitter builds. `all`/omitted => adapter default. + let specsRef: ClassifiedRef | undefined; + if (values.specs && values.specs.toLowerCase() !== "all") { + specsRef = classifyRef(values.specs, repoRoot); + if (specsRef.kind === "npm") { + log.error("--specs as an npm version is not supported; use a local folder or github ref."); + return 2; + } + } + // Resolve emitters. const baselineRef = classifyRef(values.baseline, repoRoot); const headRef: ClassifiedRef | "current" = values.head @@ -155,14 +173,9 @@ async function main(): Promise { log.step("Preparing head emitter"); const headEmitter = await adapter.prepareEmitter(headRef, ctx); - // Resolve specs source (local/github). `all`/omitted => adapter default (repo). + // Materialize the specs source now that emitters are ready. let specsDir: string | undefined; - if (values.specs && values.specs.toLowerCase() !== "all") { - const specsRef = classifyRef(values.specs, repoRoot); - if (specsRef.kind === "npm") { - log.error("--specs as an npm version is not supported; use a local folder or github ref."); - return 2; - } + if (specsRef) { specsDir = await resolveSrc(specsRef, workDir, log, repoRoot); } From a2335721a805ebc5ee0cacfa2d080d545cfd44e3 Mon Sep 17 00:00:00 2001 From: Libba Lawrence Date: Wed, 1 Jul 2026 09:10:15 -0700 Subject: [PATCH 13/52] Drop per-file list from emitter-diff PR comment; link the HTML instead The sticky comment now shows only the one-line summary (file count, +/-) and the emitter-diff-html artifact link, not an enumerated list of changed files. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- .github/workflows/ci-emitter-diff-python.yml | 9 ++------- 1 file changed, 2 insertions(+), 7 deletions(-) diff --git a/.github/workflows/ci-emitter-diff-python.yml b/.github/workflows/ci-emitter-diff-python.yml index 1dac8e83039..d535fbd4343 100644 --- a/.github/workflows/ci-emitter-diff-python.yml +++ b/.github/workflows/ci-emitter-diff-python.yml @@ -3,8 +3,8 @@ name: "python / emitter diff" # Generates code with the current checkout's emitter and with the approved # baseline emitter (the commit SHA in eng/emitter-diff/baselines/python.sha), # then diffs the two. The rendered HTML diff is uploaded as a per-PR -# artifact, and a sticky PR comment summarizes the changed files (+/-) with a -# link to download it, so reviewers can see exactly how an emitter change +# artifact, and a sticky PR comment summarizes the change (file count, +/-) +# with a link to download it, so reviewers can see exactly how an emitter change # affects generated SDKs. Powered by the language-agnostic eng/emitter-diff tool. # # Python's generator uses a native two-phase pipeline (TypeSpec emits YAML, then @@ -176,11 +176,6 @@ jobs: body += `βœ… **No changes** β€” generated output matches the approved baseline.\n`; } else { body += `❌ **${files.length} file(s) changed** Β· +${insertions} / -${deletions}\n\n`; - const shown = files.slice(0, 50); - body += `
Changed files\n\n` + - shown.map((f) => `- \`${f}\``).join("\n") + - (files.length > shown.length ? `\n- …and ${files.length - shown.length} more` : "") + - `\n
\n\n`; if (htmlExists) { body += `πŸ“„ Download the **emitter-diff-html** artifact from the ` + `[workflow run](${runUrl}) for the full side-by-side rendered diff.\n\n`; From 17c65eeef608ede2642da378a6cbfce3e27be252 Mon Sep 17 00:00:00 2001 From: Libba Lawrence Date: Wed, 1 Jul 2026 09:27:04 -0700 Subject: [PATCH 14/52] Remove --vscode diff option from emitter-diff (HTML report is sufficient) Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- eng/emitter-diff/README.md | 56 ++------------------------ eng/emitter-diff/src/cli.ts | 16 ++------ eng/emitter-diff/src/diff.ts | 77 ++---------------------------------- 3 files changed, 9 insertions(+), 140 deletions(-) diff --git a/eng/emitter-diff/README.md b/eng/emitter-diff/README.md index 84dbdbe7a98..bec74fb0d80 100644 --- a/eng/emitter-diff/README.md +++ b/eng/emitter-diff/README.md @@ -15,7 +15,7 @@ contains no language-specific logic. ``` baseline emitter ─┐ β”œβ”€ generate (adapter) ─► /baseline ─┐ - specs ────────────────────── β”œβ”€β–Ί git diff ─► terminal / VS Code / HTML + specs ────────────────────── β”œβ”€β–Ί git diff ─► terminal / HTML β”œβ”€ generate (adapter) ─► /head β”€β”€β”€β”€β”€β”˜ head emitter β”€β”€β”€β”€β”€β”˜ └─► (optional) run test suites ``` @@ -53,14 +53,13 @@ npx tsx eng/emitter-diff/src/cli.ts --emitter python --baseline 0.34.0 ### Common options By default the tool writes a **clickable HTML report** (`emitter-diff.html`) into the work dir and -prints a `file://` link to it. Use `--vscode` for a live VS Code diff, `--terminal` for the full -patch in your shell, or `--patch`/`--html` to write to a specific file. +prints a `file://` link to it. Use `--terminal` for the full patch in your shell, or +`--patch`/`--html` to write to a specific file. | Option | Description | | ----------------------- | ------------------------------------------------------------------------------------- | | `--name ` | Filter which specs/packages are generated | | `--html ` | Write the rendered HTML report to this path (default: `/emitter-diff.html`) | -| `--vscode` | Open the diff in VS Code instead of writing HTML | | `--terminal` | Print the full colored patch to the terminal instead | | `--patch ` | Write the raw unified diff to a file | | `--fail-on-diff` | Exit non-zero when output differs (CI gating) | @@ -70,8 +69,6 @@ patch in your shell, or `--patch`/`--html` to write to a specific file. | `--opt key=value` | Repeatable adapter-specific option (e.g. `--opt flavor=azure`) | | `-- ` | Everything after `--` is forwarded to the adapter | -> `--open` is kept as an alias for `--vscode`. - ### Examples ```bash @@ -79,10 +76,6 @@ patch in your shell, or `--patch`/`--html` to write to a specific file. npx tsx eng/emitter-diff/src/cli.ts --emitter python --baseline 0.34.0 \ --opt flavor=azure --name authentication-api-key -# Open the diff live in VS Code instead: -npx tsx eng/emitter-diff/src/cli.ts --emitter python --baseline 0.34.0 \ - --opt flavor=azure --name authentication-api-key --vscode - # Compare two source folders and write an HTML report to a specific path: npx tsx eng/emitter-diff/src/cli.ts --emitter python \ --baseline local:/path/to/old/http-client-python \ @@ -95,49 +88,6 @@ npx tsx eng/emitter-diff/src/cli.ts --emitter python \ flavor=azure --run-tests --test-env test,mypy,pyright < sha > --opt ``` -## Viewing the diff in VS Code - -`--vscode` gives you a native, side-by-side source diff of the two generated trees. VS Code has -no CLI to diff two _folders_ (`code --diff` only compares two files), so the tool stages the -comparison as a throwaway git working tree under `/vscode-diff`: the **baseline** tree -is committed, the **head** tree is overlaid on top and left staged. Opening that folder shows -every changed generated file in the **Source Control** panel with red/green diffs β€” click any -file for the side-by-side view. - -```bash -# Keep the scratch dir so it survives the run, and open the diff in VS Code: -npx tsx eng/emitter-diff/src/cli.ts --emitter python \ - --baseline npm:0.60.0 --opt flavor=azure --name encode/duration \ - --work-dir ./emitter-diff-out --vscode -``` - -If you generated the trees without `--vscode` (or want to reopen later), build the same view by -hand from the `baseline/` and `head/` folders under your `--work-dir` and open it in VS Code: - -```bash -cd ./emitter-diff-out -git init -q vscode-diff -cp -r baseline/. vscode-diff/ -git -C vscode-diff add -A && git -C vscode-diff commit -qm baseline -# overlay head on top, keeping .git -find vscode-diff -mindepth 1 -maxdepth 1 ! -name .git -exec rm -rf {} + -cp -r head/. vscode-diff/ -git -C vscode-diff add -A -code vscode-diff # browse changes in the Source Control panel -``` - -```powershell -# PowerShell equivalent of the overlay step: -cd .\emitter-diff-out -git init -q vscode-diff -Copy-Item -Recurse -Force .\baseline\* .\vscode-diff -git -C vscode-diff add -A; git -C vscode-diff commit -qm baseline -Get-ChildItem .\vscode-diff -Force | Where-Object Name -ne ".git" | Remove-Item -Recurse -Force -Copy-Item -Recurse -Force .\head\* .\vscode-diff -git -C vscode-diff add -A -code vscode-diff -``` - ## CI integration `.github/workflows/ci-emitter-diff-python.yml` runs on PRs that touch the python emitter or this diff --git a/eng/emitter-diff/src/cli.ts b/eng/emitter-diff/src/cli.ts index 91977e51e5a..c6760bf994f 100644 --- a/eng/emitter-diff/src/cli.ts +++ b/eng/emitter-diff/src/cli.ts @@ -9,7 +9,7 @@ import { join, resolve } from "node:path"; import { parseArgs } from "node:util"; -import { diffDirs, openInVsCode, printDiff, printSummary, writeHtml, writePatch } from "./diff.js"; +import { diffDirs, printDiff, printSummary, writeHtml, writePatch } from "./diff.js"; import { getAdapter, listAdapters } from "./registry.js"; import { classifyRef, @@ -42,7 +42,6 @@ ${color.bold("Options:")} --work-dir Scratch dir (default: a temp dir). --html Write the rendered HTML diff to this path. Default output: a clickable HTML report in the work dir. - --vscode Open the diff in VS Code instead of writing HTML. --terminal Print the full colored patch to the terminal instead. --patch Write the raw unified diff to a file. --fail-on-diff Exit non-zero when output differs (CI gating). Exit @@ -74,8 +73,6 @@ async function main(): Promise { specs: { type: "string" }, name: { type: "string" }, "work-dir": { type: "string" }, - open: { type: "boolean" }, - vscode: { type: "boolean" }, terminal: { type: "boolean" }, patch: { type: "string" }, html: { type: "string" }, @@ -119,9 +116,7 @@ async function main(): Promise { // path handed to them β€” the resolved emitter dir and the baseline/head output // dirs β€” must be absolute or outputs land in the wrong tree and the diff is // silently empty (a false "no differences"). - const workDir = ensureDir( - values["work-dir"] ? resolve(values["work-dir"]) : defaultWorkDir(), - ); + const workDir = ensureDir(values["work-dir"] ? resolve(values["work-dir"]) : defaultWorkDir()); log.info(`${color.dim("work dir:")} ${workDir}`); const ctx: AdapterContext = { @@ -220,14 +215,10 @@ async function main(): Promise { // Decide how to present the diff. Explicit flags win; otherwise the default // is a clickable HTML report written to the work dir. - const wantsVsCode = Boolean(values.vscode || values.open); const wantsTerminal = Boolean(values.terminal); const wantsPatch = Boolean(values.patch); const htmlTarget = - values.html ?? - (!wantsVsCode && !wantsTerminal && !wantsPatch - ? join(workDir, "emitter-diff.html") - : undefined); + values.html ?? (!wantsTerminal && !wantsPatch ? join(workDir, "emitter-diff.html") : undefined); if (!diff.hasChanges) { log.success("No differences between baseline and head output."); @@ -239,7 +230,6 @@ async function main(): Promise { if (wantsPatch) writePatch(diff, values.patch as string, log); if (htmlTarget) await writeHtml(diff, htmlTarget, log); - if (wantsVsCode) await openInVsCode(baselineOut, headOut, workDir, log); // Optionally run test suites. if (values["run-tests"]) { diff --git a/eng/emitter-diff/src/diff.ts b/eng/emitter-diff/src/diff.ts index 731f4bdf04d..4a4a2d7c47c 100644 --- a/eng/emitter-diff/src/diff.ts +++ b/eng/emitter-diff/src/diff.ts @@ -2,16 +2,15 @@ * Diff engine. One canonical unified patch (`git diff --no-index`) is the * source of truth; it is then rendered for whichever environment is in use: * - terminal: colored patch + summary - * - local `--open`: VS Code folder diff * - CI `--html`: rendered via diff2html (optional dependency, lazily loaded) */ -import { cpSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs"; +import { readFileSync, writeFileSync } from "node:fs"; import { createRequire } from "node:module"; -import { basename, dirname, join, resolve } from "node:path"; +import { basename, dirname, resolve } from "node:path"; import { pathToFileURL } from "node:url"; import type { Logger } from "./types.js"; -import { color, run, runChecked } from "./util.js"; +import { color, run } from "./util.js"; export interface DiffResult { /** The unified patch text (empty when there are no differences). */ @@ -190,73 +189,3 @@ ${body} log.success(`Wrote HTML diff to ${abs}`); log.info(`${color.bold("Open it:")} ${pathToFileURL(abs).href}`); } - -/** - * Open a native side-by-side diff of the two generated trees in VS Code. - * - * VS Code has no CLI to diff two folders (`code --diff` only compares two - * files), so we materialize the comparison as a throwaway git working-tree - * change: commit the baseline tree, then overlay the head tree on top and leave - * it unstaged. Opening that folder surfaces every changed generated file in the - * Source Control view with red/green side-by-side diffs. - */ -export async function openInVsCode( - baselineDir: string, - headDir: string, - workDir: string, - log: Logger, -): Promise { - log.step("Preparing VS Code diff"); - const repo = join(workDir, "vscode-diff"); - rmSync(repo, { recursive: true, force: true }); - mkdirSync(repo, { recursive: true }); - - const git = (args: string[]) => - runChecked("git", [ - "-C", - repo, - "-c", - "user.email=emitter-diff@local", - "-c", - "user.name=emitter-diff", - "-c", - "commit.gpgsign=false", - "-c", - "core.autocrlf=false", - ...args, - ]); - - await git(["init", "-q"]); - // Commit the baseline tree as the starting point. - cpSync(baselineDir, repo, { recursive: true }); - await git(["add", "-A"]); - await git(["commit", "-q", "-m", "baseline", "--allow-empty"]); - - // Overlay the head tree (keeping .git), then stage so VS Code shows the diff. - for (const entry of readdirSync(repo)) { - if (entry === ".git") continue; - rmSync(join(repo, entry), { recursive: true, force: true }); - } - cpSync(headDir, repo, { recursive: true }); - // Drop all index entries first, then re-add. A plain `git add -A` decides a - // file is unchanged from (size, mtime) and skips re-hashing it; because the - // baseline commit and the head overlay are written within the same second, - // a same-size content edit would be treated as clean and never staged (so it - // would silently not appear in VS Code). Clearing the index forces git to - // re-hash every file's content, surfacing every real modification. - await git(["rm", "-r", "--cached", "-q", "--", "."]); - await git(["add", "-A"]); - - const result = await run("code", [repo]); - if (result.code !== 0) { - log.warn( - "Could not launch VS Code (`code` not on PATH?). Open the folder manually " + - `and use the Source Control view to browse the diff: ${repo}`, - ); - return; - } - log.success( - `Opened ${repo} in VS Code β€” use the Source Control panel to browse the diff ` + - "(baseline = last commit, head = working tree).", - ); -} From 7e27c74ae8a250b3e880ba454451ba41b3f6e372 Mon Sep 17 00:00:00 2001 From: Libba Lawrence Date: Wed, 1 Jul 2026 10:04:16 -0700 Subject: [PATCH 15/52] Harden emitter-diff: fix CI injection, validate git refs, drop emojis Security: - Pass the untrusted workflow_dispatch baseline input (and derived values) via env vars instead of interpolating GitHub Actions expressions into run: bash (Actions expression injection) - Validate git ref/repo and use "git checkout --end-of-options" (arg injection) - Add "npm install --ignore-scripts" when materializing a baseline package - Drop the remote CDN CSS fallback so the HTML report never fetches off-box Cleanup: - De-duplicate the two HTML report templates into one htmlDoc() helper - Remove emojis from CLI output, job summary, and PR comment Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- .github/workflows/ci-emitter-diff-python.yml | 67 ++++++++++++-------- eng/emitter-diff/src/diff.ts | 46 ++++++-------- eng/emitter-diff/src/resolver.ts | 35 +++++++++- eng/emitter-diff/src/util.ts | 2 +- 4 files changed, 95 insertions(+), 55 deletions(-) diff --git a/.github/workflows/ci-emitter-diff-python.yml b/.github/workflows/ci-emitter-diff-python.yml index d535fbd4343..a3c56294ac0 100644 --- a/.github/workflows/ci-emitter-diff-python.yml +++ b/.github/workflows/ci-emitter-diff-python.yml @@ -63,8 +63,14 @@ jobs: - name: Determine baseline id: baseline + # The dispatch input is untrusted; pass it through `env` and reference it + # only as a shell variable so it can never be interpolated into the script + # body (GitHub Actions expression injection). + env: + BASELINE_INPUT: ${{ github.event.inputs.baseline || '' }} + RUNNER_TEMP: ${{ runner.temp }} run: | - input="${{ github.event.inputs.baseline }}" + input="$BASELINE_INPUT" if [ -z "$input" ]; then sha_file="eng/emitter-diff/baselines/python.sha" base_sha="$(grep -vE '^[[:space:]]*(#|$)' "$sha_file" | head -n1 | tr -d '[:space:]')" @@ -73,9 +79,9 @@ jobs: exit 1 fi echo "Approved baseline SHA: $base_sha (from $sha_file)" - git worktree add "${{ runner.temp }}/baseline" "$base_sha" - (cd "${{ runner.temp }}/baseline/packages/http-client-python" && npm ci && npm run build && npm run install) - input="local:${{ runner.temp }}/baseline/packages/http-client-python" + git worktree add "$RUNNER_TEMP/baseline" "$base_sha" + (cd "$RUNNER_TEMP/baseline/packages/http-client-python" && npm ci && npm run build && npm run install) + input="local:$RUNNER_TEMP/baseline/packages/http-client-python" echo "sha=$base_sha" >> "$GITHUB_OUTPUT" fi echo "ref=$input" >> "$GITHUB_OUTPUT" @@ -84,6 +90,11 @@ jobs: - name: Run emitter diff id: diff working-directory: eng/emitter-diff + # `BASELINE_REF` derives from the untrusted dispatch input, so keep it in + # `env` and reference it as "$BASELINE_REF" rather than interpolating it. + env: + BASELINE_REF: ${{ steps.baseline.outputs.ref }} + RUNNER_TEMP: ${{ runner.temp }} run: | set +e # Run via plain (non-recursive) `pnpm exec` so the tool's real exit code @@ -92,34 +103,38 @@ jobs: # which would mask the "diff present" code (2) as a hard error (1). pnpm exec tsx src/cli.ts \ --emitter python \ - --baseline "${{ steps.baseline.outputs.ref }}" \ - --work-dir "${{ runner.temp }}/emitter-diff" \ - --html "${{ runner.temp }}/emitter-diff.html" \ - --patch "${{ runner.temp }}/emitter-diff.patch" \ + --baseline "$BASELINE_REF" \ + --work-dir "$RUNNER_TEMP/emitter-diff" \ + --html "$RUNNER_TEMP/emitter-diff.html" \ + --patch "$RUNNER_TEMP/emitter-diff.patch" \ --fail-on-diff \ - | tee "${{ runner.temp }}/emitter-diff.log" + | tee "$RUNNER_TEMP/emitter-diff.log" echo "status=${PIPESTATUS[0]}" >> "$GITHUB_OUTPUT" - name: Write job summary if: always() + env: + BASELINE_SHA: ${{ steps.baseline.outputs.sha }} + STATUS: ${{ steps.diff.outputs.status }} + RUNNER_TEMP: ${{ runner.temp }} run: | { echo "## Emitter diff" echo "" - echo "Baseline (approved): \`${{ steps.baseline.outputs.sha }}\` vs current checkout." + echo "Baseline (approved): \`$BASELINE_SHA\` vs current checkout." echo "" - if [ "${{ steps.diff.outputs.status }}" = "2" ]; then - echo "❌ **Generated output changed vs the approved baseline.**" + if [ "$STATUS" = "2" ]; then + echo "**Generated output changed vs the approved baseline.**" echo "" echo "If this change is intended, approve it by updating" echo "\`eng/emitter-diff/baselines/python.sha\` to a commit on your branch that" echo "contains your emitter changes, then push." - elif [ "${{ steps.diff.outputs.status }}" = "0" ]; then - echo "βœ… Generated output matches the approved baseline." + elif [ "$STATUS" = "0" ]; then + echo "Generated output matches the approved baseline." fi echo "" echo '```' - grep -E "Diff summary:" "${{ runner.temp }}/emitter-diff.log" || echo "No summary captured." + grep -E "Diff summary:" "$RUNNER_TEMP/emitter-diff.log" || echo "No summary captured." echo '```' echo "" echo "Download the **emitter-diff-html** artifact for the full rendered diff." @@ -164,20 +179,20 @@ jobs: } const htmlExists = fs.existsSync(process.env.HTML_FILE); - let body = `${marker}\n## 🐍 Python emitter diff\n\n` + + let body = `${marker}\n## Python emitter diff\n\n` + `Approved baseline \`${process.env.BASELINE}\` vs this PR's checkout.\n\n`; if (status !== "0" && status !== "2") { // Hard error (build/venv/generate threw) β€” not a diff. Don't claim "no changes". - body += `⚠️ **emitter-diff failed to run** (exit \`${status}\`). This is a tool/build ` + + body += `**emitter-diff failed to run** (exit \`${status}\`). This is a tool/build ` + `error, not a generated-output diff. See the ` + `[workflow run](${runUrl}) logs` + (htmlExists ? ` and the **emitter-diff-html** artifact` : "") + `.\n`; } else if (status === "0") { - body += `βœ… **No changes** β€” generated output matches the approved baseline.\n`; + body += `**No changes** β€” generated output matches the approved baseline.\n`; } else { - body += `❌ **${files.length} file(s) changed** Β· +${insertions} / -${deletions}\n\n`; + body += `**${files.length} file(s) changed** Β· +${insertions} / -${deletions}\n\n`; if (htmlExists) { - body += `πŸ“„ Download the **emitter-diff-html** artifact from the ` + + body += `Download the **emitter-diff-html** artifact from the ` + `[workflow run](${runUrl}) for the full side-by-side rendered diff.\n\n`; } body += `**This check fails until the change is approved.** If the new output is ` + @@ -198,16 +213,18 @@ jobs: - name: Enforce baseline approval if: always() + env: + STATUS: ${{ steps.diff.outputs.status }} + BASELINE_SHA: ${{ steps.baseline.outputs.sha }} run: | - status="${{ steps.diff.outputs.status }}" - if [ "$status" = "2" ]; then - echo "::error::Generated output differs from the approved baseline (${{ steps.baseline.outputs.sha }})." + if [ "$STATUS" = "2" ]; then + echo "::error::Generated output differs from the approved baseline ($BASELINE_SHA)." echo "Review the emitter-diff-html artifact. If the change is intended, approve it by" echo "updating eng/emitter-diff/baselines/python.sha to a commit on your branch that" echo "contains your emitter changes, then push." exit 1 - elif [ "$status" != "0" ]; then - echo "::error::emitter-diff failed (exit $status). See the log and artifact." + elif [ "$STATUS" != "0" ]; then + echo "::error::emitter-diff failed (exit $STATUS). See the log and artifact." exit 1 fi echo "Generated output matches the approved baseline." diff --git a/eng/emitter-diff/src/diff.ts b/eng/emitter-diff/src/diff.ts index 4a4a2d7c47c..d85561f77c0 100644 --- a/eng/emitter-diff/src/diff.ts +++ b/eng/emitter-diff/src/diff.ts @@ -120,6 +120,17 @@ export function writePatch(diff: DiffResult, outFile: string, log: Logger): void log.success(`Wrote unified diff to ${outFile}`); } +const BASE_STYLE = ``; + +/** Assemble a self-contained HTML report from a summary line and optional body. */ +function htmlDoc(summaryHtml: string, bodyHtml = "", headExtra = ""): string { + return ` + +Emitter diff${headExtra}${BASE_STYLE} +
Emitter diff — ${summaryHtml}
${bodyHtml} +`; +} + /** * Render the patch to a self-contained HTML file via diff2html. diff2html is an * optional dependency loaded lazily so the core runs without it installed. @@ -128,14 +139,7 @@ export async function writeHtml(diff: DiffResult, outFile: string, log: Logger): // No differences: write a small standalone report so `--html ` always // produces a file (callers and CI artifact upload can rely on its presence). if (!diff.hasChanges) { - const doc = ` - -Emitter diff - - -
Emitter diff β€” βœ… No differences between baseline and head output.
-`; - writeFileSync(outFile, doc, "utf8"); + writeFileSync(outFile, htmlDoc("No differences between baseline and head output."), "utf8"); log.success(`No differences; wrote empty HTML report to ${resolve(outFile)}`); return; } @@ -160,31 +164,19 @@ export async function writeHtml(diff: DiffResult, outFile: string, log: Logger): matching: "lines", outputFormat: "side-by-side", }); - // Inline the diff2html stylesheet so the report renders offline (CI artifacts - // are downloaded and opened from disk). Fall back to the CDN link if the - // bundled CSS can't be located. - let styleTag: string; + // Inline the diff2html stylesheet so the report renders fully offline (CI + // artifacts are downloaded and opened from disk). Never fall back to a remote + // CDN β€” the report must not fetch anything when opened locally. + let styleTag = ""; try { const require = createRequire(import.meta.url); const cssPath = require.resolve("diff2html/bundles/css/diff2html.min.css"); styleTag = ``; } catch { - styleTag = ``; + log.warn("diff2html CSS not found; the HTML report will be unstyled."); } - const doc = ` - - - -Emitter diff -${styleTag} - - - -
Emitter diff β€” ${diff.filesChanged} file(s), +${diff.insertions} / -${diff.deletions}
-${body} - -`; - writeFileSync(outFile, doc, "utf8"); + const summary = `${diff.filesChanged} file(s), +${diff.insertions} / -${diff.deletions}`; + writeFileSync(outFile, htmlDoc(summary, body, styleTag), "utf8"); const abs = resolve(outFile); log.success(`Wrote HTML diff to ${abs}`); log.info(`${color.bold("Open it:")} ${pathToFileURL(abs).href}`); diff --git a/eng/emitter-diff/src/resolver.ts b/eng/emitter-diff/src/resolver.ts index 8e14cabb2d5..c4298997ea7 100644 --- a/eng/emitter-diff/src/resolver.ts +++ b/eng/emitter-diff/src/resolver.ts @@ -88,6 +88,24 @@ export function describeRef(ref: ClassifiedRef, packageName: string): string { const DEFAULT_REPO = "microsoft/typespec"; +/** + * Reject refs/repos that could be misread by git as options or that carry shell + * metacharacters. Args are already passed as arrays (no shell), so this guards + * against argument injection (a leading `-` becoming a git flag) and malformed + * input rather than shell injection. + */ +function assertSafeGitRef(gitRef: string): void { + if (!gitRef || gitRef.startsWith("-") || /[\0\r\n]/.test(gitRef)) { + throw new Error(`Invalid git ref: ${JSON.stringify(gitRef)}`); + } +} + +function assertSafeRepo(repo: string): void { + if (!/^[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$/.test(repo)) { + throw new Error(`Invalid repo (expected owner/repo): ${JSON.stringify(repo)}`); + } +} + /** * Materialize a local-or-github ref into a source directory. npm refs are * handled by {@link installNpmPackage} (the package name is adapter-specific). @@ -122,6 +140,8 @@ async function cloneGithub( const repo = ref.repo ?? (repoRoot ? await detectOriginRepo(repoRoot) : undefined) ?? DEFAULT_REPO; const gitRef = ref.gitRef ?? "main"; + assertSafeRepo(repo); + assertSafeGitRef(gitRef); const dest = ensureDir(join(workDir, `github-${repo.replace(/[/]/g, "_")}-${sanitize(gitRef)}`)); const cloneUrl = `https://github.com/${repo}.git`; @@ -139,8 +159,9 @@ async function cloneGithub( // Some servers won't fetch a bare SHA directly; do a full fetch and then // check the ref out by name (NOT FETCH_HEAD, which after a full fetch with // no refspec may point at a branch head rather than the requested commit). + // `--end-of-options` stops git from treating the ref as a flag. await runChecked("git", ["fetch", "origin"], { cwd: dest }); - await runChecked("git", ["checkout", "-q", gitRef], { cwd: dest }); + await runChecked("git", ["checkout", "-q", "--end-of-options", gitRef], { cwd: dest }); } return dest; } @@ -168,10 +189,20 @@ export async function installNpmPackage( ); log.step(`Installing ${packageName}@${version}`); // Create a throwaway package root and install just the one package there. + // `--ignore-scripts` blocks lifecycle scripts from the downloaded package: the + // emitter ships a prebuilt `dist`, and per-version setup (venv/build) is done + // explicitly by the adapter, so no install hooks are needed here. await runChecked("npm", ["init", "-y"], { cwd: dir }); await runChecked( "npm", - ["install", `${packageName}@${version}`, "--no-audit", "--no-fund", "--no-save"], + [ + "install", + `${packageName}@${version}`, + "--no-audit", + "--no-fund", + "--no-save", + "--ignore-scripts", + ], { cwd: dir }, ); const pkgDir = join(dir, "node_modules", packageName); diff --git a/eng/emitter-diff/src/util.ts b/eng/emitter-diff/src/util.ts index 3ef50e4c7d2..a090d2a7b78 100644 --- a/eng/emitter-diff/src/util.ts +++ b/eng/emitter-diff/src/util.ts @@ -31,7 +31,7 @@ export function createLogger(): Logger { warn: (m) => console.warn(`${color.yellow("warn")} ${m}`), error: (m) => console.error(`${color.red("error")} ${m}`), step: (m) => console.log(`${color.cyan("β€Ί")} ${color.bold(m)}`), - success: (m) => console.log(`${color.green("βœ“")} ${m}`), + success: (m) => console.log(`${color.green("ok")} ${m}`), }; /* eslint-enable no-console */ } From dcd4ca98880d8c22b7e1a78e04b7b5f790ed4a5a Mon Sep 17 00:00:00 2001 From: Libba Lawrence Date: Wed, 1 Jul 2026 10:33:56 -0700 Subject: [PATCH 16/52] Replace committed baseline SHA with merge-base + PR-label approval The baseline is now the git merge-base with the PR base branch instead of a pinned SHA file, so it survives squash-merge / rebase / force-push. Diff approval is granted by adding the `emitter-diff-approved` label to the PR; labeled/unlabeled events re-run the check. Removes eng/emitter-diff/baselines/python.sha. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- .github/workflows/ci-emitter-diff-python.yml | 102 ++++++++++++------- eng/emitter-diff/README.md | 25 ++--- eng/emitter-diff/baselines/python.sha | 6 -- 3 files changed, 80 insertions(+), 53 deletions(-) delete mode 100644 eng/emitter-diff/baselines/python.sha diff --git a/.github/workflows/ci-emitter-diff-python.yml b/.github/workflows/ci-emitter-diff-python.yml index a3c56294ac0..e7956ac3435 100644 --- a/.github/workflows/ci-emitter-diff-python.yml +++ b/.github/workflows/ci-emitter-diff-python.yml @@ -1,11 +1,17 @@ name: "python / emitter diff" -# Generates code with the current checkout's emitter and with the approved -# baseline emitter (the commit SHA in eng/emitter-diff/baselines/python.sha), -# then diffs the two. The rendered HTML diff is uploaded as a per-PR -# artifact, and a sticky PR comment summarizes the change (file count, +/-) -# with a link to download it, so reviewers can see exactly how an emitter change -# affects generated SDKs. Powered by the language-agnostic eng/emitter-diff tool. +# Generates code with the current checkout's emitter and with the emitter as of +# the base-branch commit this PR is based on (the merge-base), then diffs the two. +# The rendered HTML diff is uploaded as a per-PR artifact and a sticky PR comment +# summarizes the change with a link to download it, so reviewers can see exactly +# how an emitter change affects generated SDKs. Powered by the language-agnostic +# eng/emitter-diff tool. +# +# The check fails while generated output differs from the baseline UNTIL a +# maintainer adds the `emitter-diff-approved` label to the PR. The label (not a +# committed SHA) is the approval token, so it survives squash-merge / rebase / +# force-push, and the check re-runs automatically when the label is added or +# removed. # # Python's generator uses a native two-phase pipeline (TypeSpec emits YAML, then # a batched Python subprocess writes the .py files) with a venv co-located with @@ -14,6 +20,7 @@ name: "python / emitter diff" on: pull_request: + types: [opened, synchronize, reopened, labeled, unlabeled] branches: - main - release/* @@ -24,7 +31,7 @@ on: workflow_dispatch: inputs: baseline: - description: "Baseline emitter ref (npm version, local path, or github ref). Defaults to the approved baseline SHA file." + description: "Baseline emitter ref (npm version, local path, or github ref). Defaults to the PR's merge-base with its base branch." required: false default: "" @@ -63,22 +70,26 @@ jobs: - name: Determine baseline id: baseline - # The dispatch input is untrusted; pass it through `env` and reference it - # only as a shell variable so it can never be interpolated into the script - # body (GitHub Actions expression injection). + # The dispatch input is untrusted; pass everything through `env` and + # reference only shell variables so nothing is interpolated into the + # script body (GitHub Actions expression injection). env: BASELINE_INPUT: ${{ github.event.inputs.baseline || '' }} + BASE_REF: ${{ github.event.pull_request.base.ref || github.event.repository.default_branch }} RUNNER_TEMP: ${{ runner.temp }} run: | input="$BASELINE_INPUT" if [ -z "$input" ]; then - sha_file="eng/emitter-diff/baselines/python.sha" - base_sha="$(grep -vE '^[[:space:]]*(#|$)' "$sha_file" | head -n1 | tr -d '[:space:]')" + # Baseline = the base-branch commit this PR is based on (merge-base). + # It is always a real commit on the target branch, so it survives + # squash-merge / rebase / force-push (unlike a pinned branch SHA). + git fetch --no-tags origin "$BASE_REF" + base_sha="$(git merge-base FETCH_HEAD HEAD)" if [ -z "$base_sha" ]; then - echo "::error::No approved baseline SHA found in $sha_file" + echo "::error::Could not determine a merge-base with $BASE_REF." exit 1 fi - echo "Approved baseline SHA: $base_sha (from $sha_file)" + echo "Baseline (merge-base with $BASE_REF): $base_sha" git worktree add "$RUNNER_TEMP/baseline" "$base_sha" (cd "$RUNNER_TEMP/baseline/packages/http-client-python" && npm ci && npm run build && npm run install) input="local:$RUNNER_TEMP/baseline/packages/http-client-python" @@ -116,21 +127,25 @@ jobs: env: BASELINE_SHA: ${{ steps.baseline.outputs.sha }} STATUS: ${{ steps.diff.outputs.status }} + APPROVED: ${{ contains(github.event.pull_request.labels.*.name, 'emitter-diff-approved') }} RUNNER_TEMP: ${{ runner.temp }} run: | { echo "## Emitter diff" echo "" - echo "Baseline (approved): \`$BASELINE_SHA\` vs current checkout." + echo "Baseline (merge-base): \`$BASELINE_SHA\` vs current checkout." echo "" if [ "$STATUS" = "2" ]; then - echo "**Generated output changed vs the approved baseline.**" - echo "" - echo "If this change is intended, approve it by updating" - echo "\`eng/emitter-diff/baselines/python.sha\` to a commit on your branch that" - echo "contains your emitter changes, then push." + if [ "$APPROVED" = "true" ]; then + echo "**Generated output changed** β€” approved via the \`emitter-diff-approved\` label." + else + echo "**Generated output changed vs the baseline.**" + echo "" + echo "If this change is intended, add the \`emitter-diff-approved\` label to this PR" + echo "to accept it." + fi elif [ "$STATUS" = "0" ]; then - echo "Generated output matches the approved baseline." + echo "Generated output matches the baseline." fi echo "" echo '```' @@ -156,6 +171,7 @@ jobs: env: BASELINE: ${{ steps.baseline.outputs.sha }} STATUS: ${{ steps.diff.outputs.status }} + APPROVED: ${{ contains(github.event.pull_request.labels.*.name, 'emitter-diff-approved') }} PATCH_FILE: ${{ runner.temp }}/emitter-diff.patch HTML_FILE: ${{ runner.temp }}/emitter-diff.html with: @@ -164,6 +180,7 @@ jobs: const marker = ""; const runUrl = `${context.serverUrl}/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId}`; const status = process.env.STATUS; + const approved = process.env.APPROVED === "true"; // Parse the unified patch directly so the numbers match the tool exactly. let patch = ""; @@ -180,7 +197,7 @@ jobs: const htmlExists = fs.existsSync(process.env.HTML_FILE); let body = `${marker}\n## Python emitter diff\n\n` + - `Approved baseline \`${process.env.BASELINE}\` vs this PR's checkout.\n\n`; + `Baseline \`${process.env.BASELINE}\` (merge-base) vs this PR's checkout.\n\n`; if (status !== "0" && status !== "2") { // Hard error (build/venv/generate threw) β€” not a diff. Don't claim "no changes". body += `**emitter-diff failed to run** (exit \`${status}\`). This is a tool/build ` + @@ -188,16 +205,19 @@ jobs: `[workflow run](${runUrl}) logs` + (htmlExists ? ` and the **emitter-diff-html** artifact` : "") + `.\n`; } else if (status === "0") { - body += `**No changes** β€” generated output matches the approved baseline.\n`; + body += `**No changes** β€” generated output matches the baseline.\n`; } else { body += `**${files.length} file(s) changed** Β· +${insertions} / -${deletions}\n\n`; if (htmlExists) { body += `Download the **emitter-diff-html** artifact from the ` + `[workflow run](${runUrl}) for the full side-by-side rendered diff.\n\n`; } - body += `**This check fails until the change is approved.** If the new output is ` + - `intended, update \`eng/emitter-diff/baselines/python.sha\` to a commit on this ` + - `branch that contains your emitter changes, then push.\n`; + if (approved) { + body += `This change is **approved** via the \`emitter-diff-approved\` label.\n`; + } else { + body += `**This check fails until the change is approved.** If the new output is ` + + `intended, add the \`emitter-diff-approved\` label to this PR to accept it.\n`; + } } body += `\n_Generated by \`eng/emitter-diff\`._`; @@ -211,20 +231,32 @@ jobs: await github.rest.issues.createComment({ owner, repo, issue_number, body }); } - - name: Enforce baseline approval + - name: Enforce approval if: always() env: STATUS: ${{ steps.diff.outputs.status }} + APPROVED: ${{ contains(github.event.pull_request.labels.*.name, 'emitter-diff-approved') }} BASELINE_SHA: ${{ steps.baseline.outputs.sha }} run: | - if [ "$STATUS" = "2" ]; then - echo "::error::Generated output differs from the approved baseline ($BASELINE_SHA)." - echo "Review the emitter-diff-html artifact. If the change is intended, approve it by" - echo "updating eng/emitter-diff/baselines/python.sha to a commit on your branch that" - echo "contains your emitter changes, then push." - exit 1 - elif [ "$STATUS" != "0" ]; then + # Hard tool/build failure (not a diff) always fails. + if [ "$STATUS" != "0" ] && [ "$STATUS" != "2" ]; then echo "::error::emitter-diff failed (exit $STATUS). See the log and artifact." exit 1 fi - echo "Generated output matches the approved baseline." + # Only PRs carry the approval label; manual/dispatch runs are informational. + if [ "$GITHUB_EVENT_NAME" != "pull_request" ]; then + echo "Not a pull_request event; skipping the approval gate." + exit 0 + fi + if [ "$STATUS" = "2" ]; then + if [ "$APPROVED" = "true" ]; then + echo "Generated output differs from the baseline ($BASELINE_SHA), but the PR carries" + echo "the 'emitter-diff-approved' label. Passing." + exit 0 + fi + echo "::error::Generated output differs from the baseline ($BASELINE_SHA)." + echo "Review the emitter-diff-html artifact. If the change is intended, add the" + echo "'emitter-diff-approved' label to this PR to accept it." + exit 1 + fi + echo "Generated output matches the baseline." diff --git a/eng/emitter-diff/README.md b/eng/emitter-diff/README.md index bec74fb0d80..d9ac5dd78e2 100644 --- a/eng/emitter-diff/README.md +++ b/eng/emitter-diff/README.md @@ -85,28 +85,29 @@ npx tsx eng/emitter-diff/src/cli.ts --emitter python \ # Diff against a GitHub sha and run pytest + type checks on the head output: npx tsx eng/emitter-diff/src/cli.ts --emitter python \ --baseline github:microsoft/typespec@ \ - flavor=azure --run-tests --test-env test,mypy,pyright < sha > --opt + --test-env test,mypy,pyright --opt flavor=azure < sha > --run-tests ``` ## CI integration `.github/workflows/ci-emitter-diff-python.yml` runs on PRs that touch the python emitter or this -tool. The **approved baseline** is a commit SHA stored in -`eng/emitter-diff/baselines/python.sha`. CI builds the python emitter (and a venv) for both the -PR's checkout and a worktree of that approved commit, diffs the two, and then: +tool. The **baseline** is the base-branch commit the PR is based on (the `git merge-base` with the +target branch) β€” always a real commit on the target branch, so it survives squash-merge, rebase, +and force-push. CI builds the python emitter (and a venv) for both the PR's checkout and a worktree +of that merge-base commit, diffs the two, and then: - uploads the rendered **`emitter-diff-html`** artifact (full side-by-side diff; downloadable from the workflow run β€” GitHub artifacts are zip downloads, so they can't be rendered inline in a comment), - writes a job-summary with the diff totals, and -- posts a **sticky PR comment** (updated in place on each push) listing the changed files and - `+`/`-` counts with a link to download the artifact. - -**Approval gate:** if the generated output differs from the approved baseline, the -`--fail-on-diff` run exits with code `2` and the job **fails**. To approve an intended change, -update `eng/emitter-diff/baselines/python.sha` to a commit on your branch that contains your -emitter changes, then push. Once the baseline SHA points at a commit whose emitter matches the -PR's emitter, the diff is empty and the check passes. +- posts a **sticky PR comment** (updated in place on each push) with the changed-file and `+`/`-` + counts and a link to download the artifact. + +**Approval gate:** if the generated output differs from the baseline, the `--fail-on-diff` run +exits with code `2` and the job **fails until the change is approved**. To approve an intended +change, add the **`emitter-diff-approved`** label to the PR. The label β€” not a committed SHA β€” is +the approval token, so it is unaffected by history rewrites; the workflow also triggers on +`labeled`/`unlabeled`, so adding or removing the label re-runs the check automatically. The comment step needs `pull-requests: write`. PRs **from forks** get a read-only token, so the comment is best-effort there (`continue-on-error`) β€” the artifact and job-summary still work. diff --git a/eng/emitter-diff/baselines/python.sha b/eng/emitter-diff/baselines/python.sha deleted file mode 100644 index d75a167710b..00000000000 --- a/eng/emitter-diff/baselines/python.sha +++ /dev/null @@ -1,6 +0,0 @@ -# Approved baseline for the python emitter-diff gate. -# This is the commit whose generated output is currently blessed. CI generates -# code with the emitter at this commit and with the PR's emitter, and fails if -# they differ. To approve a new generated output, update the SHA below to a -# commit on your branch that contains your emitter changes, then push. -37199629393b92015668f107b3ac2502ca734f53 From 02a7cea56cf75e3517c3c8169d7fa650d9754cdb Mon Sep 17 00:00:00 2001 From: Libba Lawrence Date: Wed, 1 Jul 2026 12:13:59 -0700 Subject: [PATCH 17/52] Make emitter-diff check informational (pass unless real error) The workflow no longer fails on a generated-output diff or gates on a label. It runs the tool without --fail-on-diff, so a diff exits 0 and only a real tool/build error fails the job. Diffs are reported via job summary, a sticky PR comment, and the HTML artifact. Drops the label trigger, the approval gate, and the emitter-diff-approved label requirement. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- .github/workflows/ci-emitter-diff-python.yml | 75 +++++--------------- eng/emitter-diff/README.md | 9 ++- 2 files changed, 22 insertions(+), 62 deletions(-) diff --git a/.github/workflows/ci-emitter-diff-python.yml b/.github/workflows/ci-emitter-diff-python.yml index e7956ac3435..a4a2e0eb84b 100644 --- a/.github/workflows/ci-emitter-diff-python.yml +++ b/.github/workflows/ci-emitter-diff-python.yml @@ -7,11 +7,9 @@ name: "python / emitter diff" # how an emitter change affects generated SDKs. Powered by the language-agnostic # eng/emitter-diff tool. # -# The check fails while generated output differs from the baseline UNTIL a -# maintainer adds the `emitter-diff-approved` label to the PR. The label (not a -# committed SHA) is the approval token, so it survives squash-merge / rebase / -# force-push, and the check re-runs automatically when the label is added or -# removed. +# This check is informational: it always passes unless the tool hits a real +# tool/build error. A generated-output diff does not fail the PR β€” it is only +# reported (job summary + PR comment + HTML artifact) for reviewers to eyeball. # # Python's generator uses a native two-phase pipeline (TypeSpec emits YAML, then # a batched Python subprocess writes the .py files) with a venv co-located with @@ -20,7 +18,6 @@ name: "python / emitter diff" on: pull_request: - types: [opened, synchronize, reopened, labeled, unlabeled] branches: - main - release/* @@ -112,13 +109,15 @@ jobs: # propagates. `pnpm --filter exec` collapses any non-zero child exit # into pnpm's own generic exit 1 (ERR_PNPM_RECURSIVE_EXEC_FIRST_FAIL), # which would mask the "diff present" code (2) as a hard error (1). + # No `--fail-on-diff`: this check is informational and never fails on a + # diff. A real tool/build error still surfaces via a non-zero exit code + # (checked in the "Fail on tool error" step below). pnpm exec tsx src/cli.ts \ --emitter python \ --baseline "$BASELINE_REF" \ --work-dir "$RUNNER_TEMP/emitter-diff" \ --html "$RUNNER_TEMP/emitter-diff.html" \ --patch "$RUNNER_TEMP/emitter-diff.patch" \ - --fail-on-diff \ | tee "$RUNNER_TEMP/emitter-diff.log" echo "status=${PIPESTATUS[0]}" >> "$GITHUB_OUTPUT" @@ -126,8 +125,6 @@ jobs: if: always() env: BASELINE_SHA: ${{ steps.baseline.outputs.sha }} - STATUS: ${{ steps.diff.outputs.status }} - APPROVED: ${{ contains(github.event.pull_request.labels.*.name, 'emitter-diff-approved') }} RUNNER_TEMP: ${{ runner.temp }} run: | { @@ -135,19 +132,6 @@ jobs: echo "" echo "Baseline (merge-base): \`$BASELINE_SHA\` vs current checkout." echo "" - if [ "$STATUS" = "2" ]; then - if [ "$APPROVED" = "true" ]; then - echo "**Generated output changed** β€” approved via the \`emitter-diff-approved\` label." - else - echo "**Generated output changed vs the baseline.**" - echo "" - echo "If this change is intended, add the \`emitter-diff-approved\` label to this PR" - echo "to accept it." - fi - elif [ "$STATUS" = "0" ]; then - echo "Generated output matches the baseline." - fi - echo "" echo '```' grep -E "Diff summary:" "$RUNNER_TEMP/emitter-diff.log" || echo "No summary captured." echo '```' @@ -171,7 +155,6 @@ jobs: env: BASELINE: ${{ steps.baseline.outputs.sha }} STATUS: ${{ steps.diff.outputs.status }} - APPROVED: ${{ contains(github.event.pull_request.labels.*.name, 'emitter-diff-approved') }} PATCH_FILE: ${{ runner.temp }}/emitter-diff.patch HTML_FILE: ${{ runner.temp }}/emitter-diff.html with: @@ -180,7 +163,6 @@ jobs: const marker = ""; const runUrl = `${context.serverUrl}/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId}`; const status = process.env.STATUS; - const approved = process.env.APPROVED === "true"; // Parse the unified patch directly so the numbers match the tool exactly. let patch = ""; @@ -194,32 +176,27 @@ jobs: else if (line.startsWith("+") && !line.startsWith("+++")) insertions++; else if (line.startsWith("-") && !line.startsWith("---")) deletions++; } + const hasChanges = patch.trim().length > 0; const htmlExists = fs.existsSync(process.env.HTML_FILE); let body = `${marker}\n## Python emitter diff\n\n` + `Baseline \`${process.env.BASELINE}\` (merge-base) vs this PR's checkout.\n\n`; - if (status !== "0" && status !== "2") { + if (status !== "0") { // Hard error (build/venv/generate threw) β€” not a diff. Don't claim "no changes". body += `**emitter-diff failed to run** (exit \`${status}\`). This is a tool/build ` + `error, not a generated-output diff. See the ` + `[workflow run](${runUrl}) logs` + (htmlExists ? ` and the **emitter-diff-html** artifact` : "") + `.\n`; - } else if (status === "0") { + } else if (!hasChanges) { body += `**No changes** β€” generated output matches the baseline.\n`; } else { body += `**${files.length} file(s) changed** Β· +${insertions} / -${deletions}\n\n`; if (htmlExists) { body += `Download the **emitter-diff-html** artifact from the ` + - `[workflow run](${runUrl}) for the full side-by-side rendered diff.\n\n`; - } - if (approved) { - body += `This change is **approved** via the \`emitter-diff-approved\` label.\n`; - } else { - body += `**This check fails until the change is approved.** If the new output is ` + - `intended, add the \`emitter-diff-approved\` label to this PR to accept it.\n`; + `[workflow run](${runUrl}) for the full side-by-side rendered diff.\n`; } } - body += `\n_Generated by \`eng/emitter-diff\`._`; + body += `\n_Generated by \`eng/emitter-diff\`. This check is informational and does not block the PR._`; const { owner, repo } = context.repo; const issue_number = context.issue.number; @@ -231,32 +208,16 @@ jobs: await github.rest.issues.createComment({ owner, repo, issue_number, body }); } - - name: Enforce approval + - name: Fail on tool error if: always() env: STATUS: ${{ steps.diff.outputs.status }} - APPROVED: ${{ contains(github.event.pull_request.labels.*.name, 'emitter-diff-approved') }} - BASELINE_SHA: ${{ steps.baseline.outputs.sha }} run: | - # Hard tool/build failure (not a diff) always fails. - if [ "$STATUS" != "0" ] && [ "$STATUS" != "2" ]; then - echo "::error::emitter-diff failed (exit $STATUS). See the log and artifact." - exit 1 - fi - # Only PRs carry the approval label; manual/dispatch runs are informational. - if [ "$GITHUB_EVENT_NAME" != "pull_request" ]; then - echo "Not a pull_request event; skipping the approval gate." - exit 0 - fi - if [ "$STATUS" = "2" ]; then - if [ "$APPROVED" = "true" ]; then - echo "Generated output differs from the baseline ($BASELINE_SHA), but the PR carries" - echo "the 'emitter-diff-approved' label. Passing." - exit 0 - fi - echo "::error::Generated output differs from the baseline ($BASELINE_SHA)." - echo "Review the emitter-diff-html artifact. If the change is intended, add the" - echo "'emitter-diff-approved' label to this PR to accept it." + # Informational check: a generated-output diff does NOT fail the PR + # (the tool is run without --fail-on-diff, so a diff still exits 0). + # Only a real tool/build error (non-zero exit) fails the job. + if [ "$STATUS" != "0" ]; then + echo "::error::emitter-diff failed (exit $STATUS). See the log and the emitter-diff-html artifact." exit 1 fi - echo "Generated output matches the baseline." + echo "emitter-diff ran successfully (informational; diffs are reported, not enforced)." diff --git a/eng/emitter-diff/README.md b/eng/emitter-diff/README.md index d9ac5dd78e2..b988a15de6d 100644 --- a/eng/emitter-diff/README.md +++ b/eng/emitter-diff/README.md @@ -103,11 +103,10 @@ of that merge-base commit, diffs the two, and then: - posts a **sticky PR comment** (updated in place on each push) with the changed-file and `+`/`-` counts and a link to download the artifact. -**Approval gate:** if the generated output differs from the baseline, the `--fail-on-diff` run -exits with code `2` and the job **fails until the change is approved**. To approve an intended -change, add the **`emitter-diff-approved`** label to the PR. The label β€” not a committed SHA β€” is -the approval token, so it is unaffected by history rewrites; the workflow also triggers on -`labeled`/`unlabeled`, so adding or removing the label re-runs the check automatically. +**Informational:** the check **always passes unless the tool hits a real tool/build error** β€” a +generated-output diff does not fail the PR. CI runs the tool without `--fail-on-diff`, so a diff +still exits `0`; only a non-zero exit (a build/venv/generate failure) fails the job. Reviewers use +the PR comment and the HTML artifact to eyeball the diff. The comment step needs `pull-requests: write`. PRs **from forks** get a read-only token, so the comment is best-effort there (`continue-on-error`) β€” the artifact and job-summary still work. From a1c01182d1be5dcf367aa727752bdbfdcd8e5e0f Mon Sep 17 00:00:00 2001 From: Libba Lawrence Date: Wed, 1 Jul 2026 12:38:31 -0700 Subject: [PATCH 18/52] Simplify emitter-diff: zero-dep HTML report, drop run-tests - Replace diff2html with a self-contained, GitHub-style HTML renderer (inline CSS, light/dark, no external requests). Runtime deps now empty. - Remove diff2html from package.json, pnpm catalog, and lockfile. - Drop the --run-tests/--test-env/--test-target surface and the adapter runTests contract; parallel generation and --sequential are unchanged. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- eng/emitter-diff/README.md | 43 ++++---- eng/emitter-diff/package.json | 3 - eng/emitter-diff/src/adapters/python.ts | 40 +------ eng/emitter-diff/src/cli.ts | 41 +------ eng/emitter-diff/src/diff.ts | 141 ++++++++++++++++-------- eng/emitter-diff/src/types.ts | 17 +-- pnpm-lock.yaml | 33 ------ pnpm-workspace.yaml | 1 - 8 files changed, 125 insertions(+), 194 deletions(-) diff --git a/eng/emitter-diff/README.md b/eng/emitter-diff/README.md index b988a15de6d..aab8f7804b1 100644 --- a/eng/emitter-diff/README.md +++ b/eng/emitter-diff/README.md @@ -1,13 +1,13 @@ # @typespec/emitter-diff A language-agnostic tool for **diffing the generated code produced by two versions of a -TypeSpec emitter** β€” and optionally running that emitter's generated-code test suites. +TypeSpec emitter**. It generates code from the test specs twice (a **baseline** emitter and a **head** emitter), then shows the diff between the two outputs. Use it locally during development and in CI on PRs. Each language emitter (python, and later java/rust/go/ts) plugs in via a small **adapter** that -wraps that emitter's own generation/test commands. The core (ref resolution, diffing, orchestration) +wraps that emitter's own generation command. The core (ref resolution, diffing, orchestration) contains no language-specific logic. ## How it works @@ -17,12 +17,11 @@ contains no language-specific logic. β”œβ”€ generate (adapter) ─► /baseline ─┐ specs ────────────────────── β”œβ”€β–Ί git diff ─► terminal / HTML β”œβ”€ generate (adapter) ─► /head β”€β”€β”€β”€β”€β”˜ - head emitter β”€β”€β”€β”€β”€β”˜ └─► (optional) run test suites + head emitter β”€β”€β”€β”€β”€β”˜ ``` - The **adapter** wraps the emitter's existing commands. For python that is - `packages/http-client-python/eng/scripts/ci/regenerate.ts` (generation) and - `eng/scripts/ci/run-tests.ts` (suites). + `packages/http-client-python/eng/scripts/ci/regenerate.ts` (generation). - The regenerate _driver_ always comes from the current checkout; only the emitter build it points at (`--pluginDir`) changes between baseline and head, isolating the diff to emitter behavior. @@ -56,18 +55,16 @@ By default the tool writes a **clickable HTML report** (`emitter-diff.html`) int prints a `file://` link to it. Use `--terminal` for the full patch in your shell, or `--patch`/`--html` to write to a specific file. -| Option | Description | -| ----------------------- | ------------------------------------------------------------------------------------- | -| `--name ` | Filter which specs/packages are generated | -| `--html ` | Write the rendered HTML report to this path (default: `/emitter-diff.html`) | -| `--terminal` | Print the full colored patch to the terminal instead | -| `--patch ` | Write the raw unified diff to a file | -| `--fail-on-diff` | Exit non-zero when output differs (CI gating) | -| `--run-tests` | Run the adapter's test suites on the output | -| `--test-env ` | Suites to run, e.g. `test,lint,mypy,pyright` | -| `--test-target ` | `head` (default) \| `baseline` \| `both` | -| `--opt key=value` | Repeatable adapter-specific option (e.g. `--opt flavor=azure`) | -| `-- ` | Everything after `--` is forwarded to the adapter | +| Option | Description | +| ------------------ | ------------------------------------------------------------------------------------- | +| `--name ` | Filter which specs/packages are generated | +| `--html ` | Write the rendered HTML report to this path (default: `/emitter-diff.html`) | +| `--terminal` | Print the full colored patch to the terminal instead | +| `--patch ` | Write the raw unified diff to a file | +| `--fail-on-diff` | Exit non-zero when output differs (CI gating) | +| `--opt key=value` | Repeatable adapter-specific option (e.g. `--opt flavor=azure`) | +| `--sequential` | Generate baseline then head one at a time (default: both in parallel) | +| `-- ` | Everything after `--` is forwarded to the adapter | ### Examples @@ -82,10 +79,9 @@ npx tsx eng/emitter-diff/src/cli.ts --emitter python \ --head local:/path/to/new/http-client-python \ --html diff.html -# Diff against a GitHub sha and run pytest + type checks on the head output: +# Diff against a GitHub sha: npx tsx eng/emitter-diff/src/cli.ts --emitter python \ - --baseline github:microsoft/typespec@ \ - --test-env test,mypy,pyright --opt flavor=azure < sha > --run-tests + --baseline github:microsoft/typespec@ flavor=azure < sha > --opt ``` ## CI integration @@ -113,8 +109,8 @@ comment is best-effort there (`continue-on-error`) β€” the artifact and job-summ ## Adding a new language adapter -1. Implement `EmitterAdapter` (`src/types.ts`) β€” `prepareEmitter`, `generate`, optional `runTests` β€” - wrapping that emitter's own commands (e.g. rust's `npm run tspcompile`, ts's `gen-spector`). +1. Implement `EmitterAdapter` (`src/types.ts`) β€” `prepareEmitter` and `generate` β€” wrapping that + emitter's own commands (e.g. rust's `npm run tspcompile`, ts's `gen-spector`). 2. Register it in `src/registry.ts`. That's the only wiring needed β€” the orchestrator, ref resolver, and diff engine are @@ -123,7 +119,8 @@ language-agnostic and require no changes. ## Notes & limitations - External `--specs` folders must mirror the `http-specs` / `azure-http-specs` layout. -- `--html` uses the optional `diff2html` dependency (declared in this package's `package.json`). +- `--html` renders a self-contained, GitHub-style HTML report (inline CSS, no external requests). + The tool has **zero runtime dependencies** β€” the diff itself is `git diff --no-index`. - **Python's native two-phase pipeline needs a venv per emitter version.** `regenerate.ts` compiles TypeSpec to YAML in-process and then runs a batched Python subprocess (`eng/scripts/setup/run_batch.py`) that writes the `.py` files using a venv co-located with the diff --git a/eng/emitter-diff/package.json b/eng/emitter-diff/package.json index 958490123c1..19b7aca3340 100644 --- a/eng/emitter-diff/package.json +++ b/eng/emitter-diff/package.json @@ -16,9 +16,6 @@ "build": "tsc -p .", "typecheck": "tsc -p ." }, - "dependencies": { - "diff2html": "catalog:" - }, "devDependencies": { "@types/node": "catalog:", "tsx": "catalog:", diff --git a/eng/emitter-diff/src/adapters/python.ts b/eng/emitter-diff/src/adapters/python.ts index e334cf77fe6..47c985c29f1 100644 --- a/eng/emitter-diff/src/adapters/python.ts +++ b/eng/emitter-diff/src/adapters/python.ts @@ -2,18 +2,17 @@ * typespec-python adapter. * * This is the only python-aware code in the tool. It satisfies the generic - * {@link EmitterAdapter} contract by wrapping the python package's own scripts: - * - generation β†’ `eng/scripts/ci/regenerate.ts` (driven with `--pluginDir` - * (emitter build) + `--generatedFolder` (output root) overrides so any - * emitter build can target any output dir). - * - test suites β†’ `eng/scripts/ci/run-tests.ts` (pytest/lint/mypy/pyright...). + * {@link EmitterAdapter} contract by wrapping the python package's own + * generation script `eng/scripts/ci/regenerate.ts` (driven with `--pluginDir` + * (emitter build) + `--generatedFolder` (output root) overrides so any emitter + * build can target any output dir). * * The regenerate *driver* always comes from the current checkout; only the * `--pluginDir` it points at changes between baseline and head. Specs are also * pinned to the current checkout so the diff isolates emitter behavior rather * than driver/spec differences. */ -import { cpSync, existsSync, rmSync } from "node:fs"; +import { existsSync } from "node:fs"; import { join } from "node:path"; import { describeRef } from "../resolver.js"; @@ -23,7 +22,6 @@ import type { EmitterAdapter, GenerateRequest, ResolvedEmitter, - RunTestsRequest, } from "../types.js"; import { run, runChecked } from "../util.js"; @@ -186,34 +184,6 @@ export const pythonAdapter: EmitterAdapter = { ctx.log.step(`Generating with ${request.emitter.label} β†’ ${request.outputDir}`); await runScript(ctx, "eng/scripts/ci/regenerate.ts", args, { prefix: request.logPrefix }); }, - - async runTests(request: RunTestsRequest, ctx: AdapterContext): Promise { - // The python test harness is wired to /tests/generated. The diff - // tool's output dir holds the generated tree under `tests/generated` - // (see generate()), so sync that subtree there, then run the runner. - const generatedRoot = join(pkgDir(ctx), "tests", "generated"); - const source = firstExisting([ - join(request.outputDir, "tests", "generated"), - request.outputDir, - ])!; - ctx.log.step(`Syncing ${source} into ${generatedRoot} for test run`); - rmSync(generatedRoot, { recursive: true, force: true }); - cpSync(source, generatedRoot, { recursive: true }); - - // `--generator` runs the suites against the generated packages (as opposed - // to the emitter's own unit tests). - const args: string[] = ["--generator"]; - if (request.envs && request.envs.length > 0) { - args.push("--env", request.envs.join(",")); - } - const flavor = request.options.flavor; - if (flavor) args.push("--flavor", flavor); - if (request.nameFilter) args.push("--name", request.nameFilter); - args.push(...request.passthrough); - - ctx.log.step("Running python test suites"); - await runScript(ctx, "eng/scripts/ci/run-tests.ts", args); - }, }; function firstExisting(paths: string[]): string | undefined { diff --git a/eng/emitter-diff/src/cli.ts b/eng/emitter-diff/src/cli.ts index c6760bf994f..33011412a8f 100644 --- a/eng/emitter-diff/src/cli.ts +++ b/eng/emitter-diff/src/cli.ts @@ -46,9 +46,6 @@ ${color.bold("Options:")} --patch Write the raw unified diff to a file. --fail-on-diff Exit non-zero when output differs (CI gating). Exit code 2 means "diff present"; 1 means a hard error. - --run-tests Run the adapter's test suites on the output. - --test-env Suites to run (adapter-defined), e.g. test,lint,mypy. - --test-target head | baseline | both (default: head). --opt key=value Repeatable adapter-specific option (e.g. --opt flavor=azure). --sequential Generate baseline then head one at a time (default: generate both in parallel with prefixed logs). @@ -77,9 +74,6 @@ async function main(): Promise { patch: { type: "string" }, html: { type: "string" }, "fail-on-diff": { type: "boolean" }, - "run-tests": { type: "boolean" }, - "test-env": { type: "string" }, - "test-target": { type: "string", default: "head" }, opt: { type: "string", multiple: true }, sequential: { type: "boolean" }, help: { type: "boolean", short: "h" }, @@ -138,14 +132,6 @@ async function main(): Promise { options[entry.slice(0, eq)] = entry.slice(eq + 1); } - // Validate --test-target early so a typo fails loudly rather than silently - // running no suites. - const testTarget = values["test-target"] ?? "head"; - if (!["head", "baseline", "both"].includes(testTarget)) { - log.error(`Invalid --test-target '${testTarget}'. Expected head | baseline | both.`); - return 2; - } - // Classify the specs ref up front (if any) so an invalid --specs fails fast, // before the expensive emitter builds. `all`/omitted => adapter default. let specsRef: ClassifiedRef | undefined; @@ -229,32 +215,7 @@ async function main(): Promise { } if (wantsPatch) writePatch(diff, values.patch as string, log); - if (htmlTarget) await writeHtml(diff, htmlTarget, log); - - // Optionally run test suites. - if (values["run-tests"]) { - if (!adapter.runTests) { - log.warn(`Adapter '${adapter.name}' does not support --run-tests yet.`); - } else { - const envs = values["test-env"] - ?.split(",") - .map((s) => s.trim()) - .filter(Boolean); - const target = testTarget; - const targets: Array<{ label: string; dir: string }> = []; - if (target === "head" || target === "both") targets.push({ label: "head", dir: headOut }); - if (target === "baseline" || target === "both") - targets.push({ label: "baseline", dir: baselineOut }); - - for (const t of targets) { - log.step(`Running test suites on ${t.label} output`); - await adapter.runTests( - { outputDir: t.dir, envs, nameFilter: values.name, options, passthrough }, - ctx, - ); - } - } - } + if (htmlTarget) writeHtml(diff, htmlTarget, log); if (values["fail-on-diff"] && diff.hasChanges) { log.error("Differences detected and --fail-on-diff is set."); diff --git a/eng/emitter-diff/src/diff.ts b/eng/emitter-diff/src/diff.ts index d85561f77c0..5cb1c13a104 100644 --- a/eng/emitter-diff/src/diff.ts +++ b/eng/emitter-diff/src/diff.ts @@ -2,10 +2,9 @@ * Diff engine. One canonical unified patch (`git diff --no-index`) is the * source of truth; it is then rendered for whichever environment is in use: * - terminal: colored patch + summary - * - CI `--html`: rendered via diff2html (optional dependency, lazily loaded) + * - CI `--html`: a self-contained, GitHub-style HTML report (inline CSS, no deps) */ -import { readFileSync, writeFileSync } from "node:fs"; -import { createRequire } from "node:module"; +import { writeFileSync } from "node:fs"; import { basename, dirname, resolve } from "node:path"; import { pathToFileURL } from "node:url"; @@ -120,63 +119,117 @@ export function writePatch(diff: DiffResult, outFile: string, log: Logger): void log.success(`Wrote unified diff to ${outFile}`); } -const BASE_STYLE = ``; +// Self-contained report styling. Kept inline so the HTML renders fully offline +// (CI artifacts are downloaded and opened from disk) with zero dependencies. +const REPORT_CSS = ` +:root { color-scheme: light dark; } +* { box-sizing: border-box; } +body { margin: 0; font-family: system-ui, sans-serif; color: #1f2328; background: #fff; } +.summary { padding: 12px 16px; background: #f6f8fa; border-bottom: 1px solid #d0d7de; position: sticky; top: 0; } +.file { border: 1px solid #d0d7de; border-radius: 6px; margin: 16px; overflow: hidden; } +.file-header { padding: 8px 12px; background: #f6f8fa; border-bottom: 1px solid #d0d7de; font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: 12px; font-weight: 600; display: flex; justify-content: space-between; gap: 12px; } +.file-header .stat .add { color: #1a7f37; } +.file-header .stat .del { color: #cf222e; } +pre.hunks { margin: 0; overflow-x: auto; font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: 12px; line-height: 1.5; tab-size: 2; } +pre.hunks span { display: block; padding: 0 12px; white-space: pre; } +.add { background: #e6ffec; } +.del { background: #ffebe9; } +.hunk { background: #ddf4ff; color: #57606a; } +.meta { color: #8c959f; } +@media (prefers-color-scheme: dark) { + body { color: #e6edf3; background: #0d1117; } + .summary, .file-header { background: #161b22; border-color: #30363d; } + .file { border-color: #30363d; } + .add { background: #12261e; } .del { background: #25171c; } .hunk { background: #121d2f; color: #7d8590; } +}`; + +/** HTML-escape text embedded in the report. */ +function esc(s: string): string { + return s.replace(/&/g, "&").replace(//g, ">"); +} + +/** A single file's slice of a unified patch. */ +interface FileDiff { + name: string; + insertions: number; + deletions: number; + lines: string[]; +} + +/** Split a unified patch into per-file groups, capturing the display name and per-file stats. */ +function splitFiles(patch: string): FileDiff[] { + const files: FileDiff[] = []; + let cur: FileDiff | undefined; + for (const line of patch.split("\n")) { + if (line.startsWith("diff --git") || line.startsWith("diff --no-index")) { + cur = { name: "", insertions: 0, deletions: 0, lines: [] }; + files.push(cur); + continue; + } + if (!cur) continue; + // Prefer the post-image path (`+++ b/`) for the display name. + if (line.startsWith("+++ ")) { + cur.name = line.slice(4).replace(/^b\//, "").replace(/^"|"$/g, ""); + continue; + } + if (line.startsWith("--- ")) { + if (!cur.name) cur.name = line.slice(4).replace(/^a\//, ""); + continue; + } + cur.lines.push(line); + if (line.startsWith("+") && !line.startsWith("+++")) cur.insertions++; + else if (line.startsWith("-") && !line.startsWith("---")) cur.deletions++; + } + return files.filter((f) => f.lines.some((l) => l.startsWith("@@"))); +} + +/** Render one file's diff lines as colored, escaped `` rows. */ +function renderFileBody(lines: string[]): string { + const rows: string[] = []; + for (const line of lines) { + if (line.startsWith("@@")) rows.push(`${esc(line)}`); + else if (line.startsWith("+")) rows.push(`${esc(line)}`); + else if (line.startsWith("-")) rows.push(`${esc(line)}`); + else if (line.startsWith("index ") || line.startsWith("new file") || line.startsWith("deleted")) + rows.push(`${esc(line)}`); + else rows.push(`${esc(line)}`); + } + return rows.join(""); +} -/** Assemble a self-contained HTML report from a summary line and optional body. */ -function htmlDoc(summaryHtml: string, bodyHtml = "", headExtra = ""): string { +/** Assemble the full self-contained HTML document. */ +function htmlDoc(summaryHtml: string, bodyHtml = ""): string { return ` -Emitter diff${headExtra}${BASE_STYLE} +Emitter diff
Emitter diff — ${summaryHtml}
${bodyHtml} `; } /** - * Render the patch to a self-contained HTML file via diff2html. diff2html is an - * optional dependency loaded lazily so the core runs without it installed. + * Render the unified patch to a self-contained HTML file. The patch produced by + * {@link diffDirs} is the source of truth; this parses it into a GitHub-style + * colored diff with inline CSS, so the report has zero runtime dependencies and + * opens offline. */ -export async function writeHtml(diff: DiffResult, outFile: string, log: Logger): Promise { - // No differences: write a small standalone report so `--html ` always - // produces a file (callers and CI artifact upload can rely on its presence). +export function writeHtml(diff: DiffResult, outFile: string, log: Logger): void { + // No differences: still write a report so `--html ` always produces a + // file (callers and CI artifact upload can rely on its presence). if (!diff.hasChanges) { writeFileSync(outFile, htmlDoc("No differences between baseline and head output."), "utf8"); log.success(`No differences; wrote empty HTML report to ${resolve(outFile)}`); return; } - // diff2html is an optional dependency, loaded lazily. Use a non-literal - // specifier and a local type so an aggregate typecheck that doesn't install - // this package's deps (e.g. the parent repo's `check:eng`, which includes - // `core/eng`) doesn't fail to resolve it β€” we validate availability at runtime. - type Diff2Html = { html(patch: string, options: Record): string }; - const specifier: string = "diff2html"; - let mod: Diff2Html; - try { - mod = (await import(specifier)) as unknown as Diff2Html; - } catch { - throw new Error( - "Rendering --html requires the 'diff2html' package. Install it in eng/emitter-diff " + - "(it is declared as a dependency) or run with `pnpm` so it is available.", - ); - } - const body = mod.html(diff.patch, { - drawFileList: true, - matching: "lines", - outputFormat: "side-by-side", - }); - // Inline the diff2html stylesheet so the report renders fully offline (CI - // artifacts are downloaded and opened from disk). Never fall back to a remote - // CDN β€” the report must not fetch anything when opened locally. - let styleTag = ""; - try { - const require = createRequire(import.meta.url); - const cssPath = require.resolve("diff2html/bundles/css/diff2html.min.css"); - styleTag = ``; - } catch { - log.warn("diff2html CSS not found; the HTML report will be unstyled."); - } + const body = splitFiles(diff.patch) + .map((f) => { + const stat = `+${f.insertions} -${f.deletions}`; + return `
${esc(f.name)}${stat}
${renderFileBody(f.lines)}
`; + }) + .join("\n"); + const summary = `${diff.filesChanged} file(s), +${diff.insertions} / -${diff.deletions}`; - writeFileSync(outFile, htmlDoc(summary, body, styleTag), "utf8"); + writeFileSync(outFile, htmlDoc(summary, body), "utf8"); const abs = resolve(outFile); log.success(`Wrote HTML diff to ${abs}`); log.info(`${color.bold("Open it:")} ${pathToFileURL(abs).href}`); diff --git a/eng/emitter-diff/src/types.ts b/eng/emitter-diff/src/types.ts index d89a00582cc..b0140afab7c 100644 --- a/eng/emitter-diff/src/types.ts +++ b/eng/emitter-diff/src/types.ts @@ -79,19 +79,9 @@ export interface GenerateRequest { logPrefix?: string; } -export interface RunTestsRequest { - /** The generated output tree to run suites against. */ - outputDir: string; - /** Adapter-defined suite/environment names (e.g. `test`, `lint`, `mypy`). */ - envs?: string[]; - nameFilter?: string; - options: Record; - passthrough: string[]; -} - /** - * Per-language plugin. A thin wrapper over an emitter's own generate and test - * commands. The core never reaches around this contract. + * Per-language plugin. A thin wrapper over an emitter's own generate command. + * The core never reaches around this contract. */ export interface EmitterAdapter { /** Stable id used by `--emitter` (e.g. `python`). */ @@ -108,9 +98,6 @@ export interface EmitterAdapter { /** Generate code into `request.outputDir` using `request.emitter`. */ generate(request: GenerateRequest, ctx: AdapterContext): Promise; - - /** Optional: run the emitter's test suites against an output tree. */ - runTests?(request: RunTestsRequest, ctx: AdapterContext): Promise; } export interface Logger { diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 2c54eb05577..bde8ee57bc6 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -288,9 +288,6 @@ catalogs: decimal.js: specifier: ^10.6.0 version: 10.6.0 - diff2html: - specifier: ^3.4.48 - version: 3.4.56 ecmarkup: specifier: ~23.0.2 version: 23.0.2 @@ -630,10 +627,6 @@ importers: e2e: {} eng/emitter-diff: - dependencies: - diff2html: - specifier: 'catalog:' - version: 3.4.56 devDependencies: '@types/node': specifier: 'catalog:' @@ -6375,10 +6368,6 @@ packages: '@polka/url@1.0.0-next.29': resolution: {integrity: sha512-wwQAWhWSuHaag8c4q/KN/vCoeOJYshAIvMQwD4GpSb3OiZklFfvAgmj0VCBBImRpuF/aFgIRzllXlVX93Jevww==} - '@profoundlogic/hogan@3.0.4': - resolution: {integrity: sha512-pmNVGuooS30Mm7YbZd5T7E5zYVO6D5Ct91sn4T39mUvMUc3sCGridcnhAufL1/Bz2QzAtzEn0agNrdk3+5yWzw==} - hasBin: true - '@reflink/reflink-darwin-arm64@0.1.19': resolution: {integrity: sha512-ruy44Lpepdk1FqDz38vExBY/PVUsjxZA+chd9wozjUH9JjuDT/HEaQYA6wYN9mf041l0yLVar6BCZuWABJvHSA==} engines: {node: '>= 10'} @@ -9118,10 +9107,6 @@ packages: devlop@1.1.0: resolution: {integrity: sha512-RWmIqhcFf1lRYBvNmr7qTNuyCt/7/ns2jbpp1+PalgE/rDQcBT0fioSMUpJ93irlUhC5hrg4cYqe6U+0ImW0rA==} - diff2html@3.4.56: - resolution: {integrity: sha512-u9gfn+BlbHcyO7vItCIC4z49LJDUt31tODzOfAuJ5R1E7IdlRL6KjugcB9zOpejD+XiR+dDZbsnHSQ3g6A/u8A==} - engines: {node: '>=12'} - diff@5.2.2: resolution: {integrity: sha512-vtcDfH3TOjP8UekytvnHH1o1P4FcUdt4eQ1Y+Abap1tk/OB2MWQvcwS2ClCd1zuIhc3JKOx6p3kod8Vfys3E+A==} engines: {node: '>=0.3.1'} @@ -9933,10 +9918,6 @@ packages: resolution: {integrity: sha512-EqYpWyTF2s8nMfttfBA2yLKPNoZCO33pLS4MnbXQ4hECf1TKujCt1Kq7QAdrio7roL4+CqsfjqwYj4tYgq0pJQ==} engines: {node: '>=12.0.0'} - highlight.js@11.11.1: - resolution: {integrity: sha512-Xwwo44whKBVCYoliBQwaPvtd/2tYFkRQtXDWj1nackaV2JPXx3L0+Jvd8/qCJ2p+ML0/XVkJ2q+Mr+UVdpJK5w==} - engines: {node: '>=12.0.0'} - hosted-git-info@4.1.0: resolution: {integrity: sha512-kyCuEOWjJqZuDbRHzL8V93NzQhwIB71oFWSyzVo+KPZI+pnQPPxucdkrOZvkLRnrf5URsQM+IJ09Dw29cRALIA==} engines: {node: '>=10'} @@ -18569,10 +18550,6 @@ snapshots: '@polka/url@1.0.0-next.29': {} - '@profoundlogic/hogan@3.0.4': - dependencies: - nopt: 1.0.10 - '@reflink/reflink-darwin-arm64@0.1.19': optional: true @@ -21792,13 +21769,6 @@ snapshots: dependencies: dequal: 2.0.3 - diff2html@3.4.56: - dependencies: - '@profoundlogic/hogan': 3.0.4 - diff: 8.0.4 - optionalDependencies: - highlight.js: 11.11.1 - diff@5.2.2: {} diff@8.0.4: {} @@ -22911,9 +22881,6 @@ snapshots: highlight.js@11.0.1: {} - highlight.js@11.11.1: - optional: true - hosted-git-info@4.1.0: dependencies: lru-cache: 6.0.0 diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml index fbaa8589069..034c7605462 100644 --- a/pnpm-workspace.yaml +++ b/pnpm-workspace.yaml @@ -102,7 +102,6 @@ catalog: cspell: ^10.0.0 debounce: ^3.0.0 decimal.js: ^10.6.0 - diff2html: ^3.4.48 ecmarkup: ~23.0.2 env-paths: ^4.0.0 es-module-shims: ^2.8.0 From 722e7563534606cb2b41660391aa705374a53a10 Mon Sep 17 00:00:00 2001 From: Libba Lawrence Date: Wed, 1 Jul 2026 13:03:30 -0700 Subject: [PATCH 19/52] Run emitter-diff as plain node scripts, not a package Now that the tool has zero runtime dependencies, it no longer needs to be a workspace package. Deleting the package.json and its name removes any npm dependency-confusion surface, and the tool runs with plain ode (Node 24 strips TypeScript natively) instead of tsx. - Delete eng/emitter-diff/package.json; drop it from pnpm-workspace.yaml. - Rewrite relative imports to .ts extensions and set allowImportingTsExtensions so ode runs it and sc typechecks. - Invoke via ode src/cli.ts in CI, the shebang, and the README. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- .github/workflows/ci-emitter-diff-python.yml | 13 ++++------- eng/emitter-diff/README.md | 18 +++++++-------- eng/emitter-diff/package.json | 24 -------------------- eng/emitter-diff/src/adapters/python.ts | 6 ++--- eng/emitter-diff/src/cli.ts | 12 +++++----- eng/emitter-diff/src/diff.ts | 4 ++-- eng/emitter-diff/src/registry.ts | 4 ++-- eng/emitter-diff/src/resolver.ts | 4 ++-- eng/emitter-diff/src/util.ts | 2 +- eng/emitter-diff/tsconfig.json | 1 + pnpm-lock.yaml | 12 ---------- pnpm-workspace.yaml | 1 - 12 files changed, 31 insertions(+), 70 deletions(-) delete mode 100644 eng/emitter-diff/package.json diff --git a/.github/workflows/ci-emitter-diff-python.yml b/.github/workflows/ci-emitter-diff-python.yml index a4a2e0eb84b..f25df119269 100644 --- a/.github/workflows/ci-emitter-diff-python.yml +++ b/.github/workflows/ci-emitter-diff-python.yml @@ -105,14 +105,11 @@ jobs: RUNNER_TEMP: ${{ runner.temp }} run: | set +e - # Run via plain (non-recursive) `pnpm exec` so the tool's real exit code - # propagates. `pnpm --filter exec` collapses any non-zero child exit - # into pnpm's own generic exit 1 (ERR_PNPM_RECURSIVE_EXEC_FIRST_FAIL), - # which would mask the "diff present" code (2) as a hard error (1). - # No `--fail-on-diff`: this check is informational and never fails on a - # diff. A real tool/build error still surfaces via a non-zero exit code - # (checked in the "Fail on tool error" step below). - pnpm exec tsx src/cli.ts \ + # Run with plain `node` (Node 24 runs TypeScript natively) so the tool's + # real exit code propagates. No `--fail-on-diff`: this check is + # informational and never fails on a diff. A real tool/build error still + # surfaces via a non-zero exit code (checked in "Fail on tool error"). + node src/cli.ts \ --emitter python \ --baseline "$BASELINE_REF" \ --work-dir "$RUNNER_TEMP/emitter-diff" \ diff --git a/eng/emitter-diff/README.md b/eng/emitter-diff/README.md index aab8f7804b1..28203b1c4bd 100644 --- a/eng/emitter-diff/README.md +++ b/eng/emitter-diff/README.md @@ -1,4 +1,4 @@ -# @typespec/emitter-diff +# emitter-diff A language-agnostic tool for **diffing the generated code produced by two versions of a TypeSpec emitter**. @@ -28,13 +28,13 @@ contains no language-specific logic. ## Usage ```bash -# From the repo root, via pnpm: -pnpm --filter @typespec/emitter-diff exec tsx src/cli.ts --emitter python --baseline 0.34.0 - -# Or directly with Node 22+ (native TS): -npx tsx eng/emitter-diff/src/cli.ts --emitter python --baseline 0.34.0 +# Run directly with Node 24+ (native TypeScript, no build step, no dependencies): +node eng/emitter-diff/src/cli.ts --emitter python --baseline 0.34.0 ``` +> This tool is a set of plain `.ts` scripts β€” not an installed package. Node 24 runs TypeScript +> natively, so there is nothing to build or install. Typecheck with `npx tsc -p eng/emitter-diff`. + ### Refs (`--baseline`, `--head`, `--specs`) | Syntax | Meaning | @@ -70,17 +70,17 @@ prints a `file://` link to it. Use `--terminal` for the full patch in your shell ```bash # Default: writes a clickable emitter-diff.html and prints a file:// link. -npx tsx eng/emitter-diff/src/cli.ts --emitter python --baseline 0.34.0 \ +node eng/emitter-diff/src/cli.ts --emitter python --baseline 0.34.0 \ --opt flavor=azure --name authentication-api-key # Compare two source folders and write an HTML report to a specific path: -npx tsx eng/emitter-diff/src/cli.ts --emitter python \ +node eng/emitter-diff/src/cli.ts --emitter python \ --baseline local:/path/to/old/http-client-python \ --head local:/path/to/new/http-client-python \ --html diff.html # Diff against a GitHub sha: -npx tsx eng/emitter-diff/src/cli.ts --emitter python \ +node eng/emitter-diff/src/cli.ts --emitter python \ --baseline github:microsoft/typespec@ flavor=azure < sha > --opt ``` diff --git a/eng/emitter-diff/package.json b/eng/emitter-diff/package.json deleted file mode 100644 index 19b7aca3340..00000000000 --- a/eng/emitter-diff/package.json +++ /dev/null @@ -1,24 +0,0 @@ -{ - "name": "@typespec/emitter-diff", - "version": "0.1.0", - "private": true, - "description": "Diff generated code across TypeSpec emitter versions and run generated-code tests, for all language emitters in this repo.", - "type": "module", - "main": "src/cli.ts", - "bin": { - "emitter-diff": "./src/cli.ts" - }, - "engines": { - "node": ">=22.0.0" - }, - "scripts": { - "emitter-diff": "tsx src/cli.ts", - "build": "tsc -p .", - "typecheck": "tsc -p ." - }, - "devDependencies": { - "@types/node": "catalog:", - "tsx": "catalog:", - "typescript": "catalog:" - } -} diff --git a/eng/emitter-diff/src/adapters/python.ts b/eng/emitter-diff/src/adapters/python.ts index 47c985c29f1..17e119bc4b3 100644 --- a/eng/emitter-diff/src/adapters/python.ts +++ b/eng/emitter-diff/src/adapters/python.ts @@ -15,15 +15,15 @@ import { existsSync } from "node:fs"; import { join } from "node:path"; -import { describeRef } from "../resolver.js"; +import { describeRef } from "../resolver.ts"; import type { AdapterContext, ClassifiedRef, EmitterAdapter, GenerateRequest, ResolvedEmitter, -} from "../types.js"; -import { run, runChecked } from "../util.js"; +} from "../types.ts"; +import { run, runChecked } from "../util.ts"; const PACKAGE_NAME = "@typespec/http-client-python"; const PKG_REL = "packages/http-client-python"; diff --git a/eng/emitter-diff/src/cli.ts b/eng/emitter-diff/src/cli.ts index 33011412a8f..608d32d4aba 100644 --- a/eng/emitter-diff/src/cli.ts +++ b/eng/emitter-diff/src/cli.ts @@ -1,4 +1,4 @@ -#!/usr/bin/env -S npx tsx +#!/usr/bin/env -S node /** * emitter-diff β€” language-agnostic CLI. * @@ -9,16 +9,16 @@ import { join, resolve } from "node:path"; import { parseArgs } from "node:util"; -import { diffDirs, printDiff, printSummary, writeHtml, writePatch } from "./diff.js"; -import { getAdapter, listAdapters } from "./registry.js"; +import { diffDirs, printDiff, printSummary, writeHtml, writePatch } from "./diff.ts"; +import { getAdapter, listAdapters } from "./registry.ts"; import { classifyRef, defaultWorkDir, installNpmPackage as installNpm, resolveSource as resolveSrc, -} from "./resolver.js"; -import type { AdapterContext, ClassifiedRef } from "./types.js"; -import { color, createLogger, ensureDir, runChecked } from "./util.js"; +} from "./resolver.ts"; +import type { AdapterContext, ClassifiedRef } from "./types.ts"; +import { color, createLogger, ensureDir, runChecked } from "./util.ts"; const HELP = `${color.bold("emitter-diff")} β€” diff generated code across emitter versions diff --git a/eng/emitter-diff/src/diff.ts b/eng/emitter-diff/src/diff.ts index 5cb1c13a104..c42b7c7906e 100644 --- a/eng/emitter-diff/src/diff.ts +++ b/eng/emitter-diff/src/diff.ts @@ -8,8 +8,8 @@ import { writeFileSync } from "node:fs"; import { basename, dirname, resolve } from "node:path"; import { pathToFileURL } from "node:url"; -import type { Logger } from "./types.js"; -import { color, run } from "./util.js"; +import type { Logger } from "./types.ts"; +import { color, run } from "./util.ts"; export interface DiffResult { /** The unified patch text (empty when there are no differences). */ diff --git a/eng/emitter-diff/src/registry.ts b/eng/emitter-diff/src/registry.ts index 6b7bd59db55..b57bddfc846 100644 --- a/eng/emitter-diff/src/registry.ts +++ b/eng/emitter-diff/src/registry.ts @@ -1,6 +1,6 @@ /** Adapter registry. New languages register here; the core is otherwise agnostic. */ -import { pythonAdapter } from "./adapters/python.js"; -import type { EmitterAdapter } from "./types.js"; +import { pythonAdapter } from "./adapters/python.ts"; +import type { EmitterAdapter } from "./types.ts"; const adapters: Record = { [pythonAdapter.name]: pythonAdapter, diff --git a/eng/emitter-diff/src/resolver.ts b/eng/emitter-diff/src/resolver.ts index c4298997ea7..edde8d1aa9d 100644 --- a/eng/emitter-diff/src/resolver.ts +++ b/eng/emitter-diff/src/resolver.ts @@ -10,8 +10,8 @@ import { existsSync, mkdtempSync } from "node:fs"; import { tmpdir } from "node:os"; import { isAbsolute, join, resolve } from "node:path"; -import type { ClassifiedRef, Logger } from "./types.js"; -import { ensureDir, run, runChecked } from "./util.js"; +import type { ClassifiedRef, Logger } from "./types.ts"; +import { ensureDir, run, runChecked } from "./util.ts"; /** * Classify a ref string. Explicit prefixes (`npm:`, `local:`, `github:`, diff --git a/eng/emitter-diff/src/util.ts b/eng/emitter-diff/src/util.ts index a090d2a7b78..b779c3b7cc0 100644 --- a/eng/emitter-diff/src/util.ts +++ b/eng/emitter-diff/src/util.ts @@ -5,7 +5,7 @@ import { spawn, type SpawnOptions } from "node:child_process"; import { mkdirSync } from "node:fs"; -import type { Logger } from "./types.js"; +import type { Logger } from "./types.ts"; // ---- Minimal ANSI colors (no picocolors dependency) ---- diff --git a/eng/emitter-diff/tsconfig.json b/eng/emitter-diff/tsconfig.json index f51bfa6da96..013eaa2a374 100644 --- a/eng/emitter-diff/tsconfig.json +++ b/eng/emitter-diff/tsconfig.json @@ -7,6 +7,7 @@ "strict": true, "skipLibCheck": true, "noEmit": true, + "allowImportingTsExtensions": true, "verbatimModuleSyntax": true, "esModuleInterop": true, "forceConsistentCasingInFileNames": true, diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index bde8ee57bc6..0209fdfc111 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -626,18 +626,6 @@ importers: e2e: {} - eng/emitter-diff: - devDependencies: - '@types/node': - specifier: 'catalog:' - version: 26.0.0 - tsx: - specifier: 'catalog:' - version: 4.22.4 - typescript: - specifier: 'catalog:' - version: 6.0.3 - packages/asset-emitter: devDependencies: '@types/node': diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml index 034c7605462..7aa0552c415 100644 --- a/pnpm-workspace.yaml +++ b/pnpm-workspace.yaml @@ -1,6 +1,5 @@ packages: - packages/* - - eng/emitter-diff - e2e - website - "!packages/http-client-csharp/**" From c2e2e99498da27d864068ebfdd4f77d3e1599284 Mon Sep 17 00:00:00 2001 From: Libba Lawrence Date: Wed, 1 Jul 2026 13:16:10 -0700 Subject: [PATCH 20/52] Allow .ts extension imports in eng typecheck Running emitter-diff with plain node requires .ts import specifiers, but the repo-wide check:eng gate (tsconfig.eng.json, --noEmit) rejected them. Enable allowImportingTsExtensions there so the tool stays covered by the existing typecheck. Also reword the ensureDeps comment: http-client-python commits its own package-lock.json to the repo (lockfiles aren't in the published tarball), which is why npm ci works on a source checkout. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- eng/emitter-diff/src/adapters/python.ts | 3 ++- tsconfig.eng.json | 3 +++ 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/eng/emitter-diff/src/adapters/python.ts b/eng/emitter-diff/src/adapters/python.ts index 17e119bc4b3..81d4784e346 100644 --- a/eng/emitter-diff/src/adapters/python.ts +++ b/eng/emitter-diff/src/adapters/python.ts @@ -56,7 +56,8 @@ async function isBuilt(dir: string): Promise { * Ensure the package's npm dependencies are installed. A fresh source checkout * (a github clone or a bare local path) has no `node_modules`, so `npm run * build` would fail to resolve its types/deps. http-client-python is - * npm-managed (it ships its own package-lock.json), so `npm ci` here is safe. + * npm-managed and commits its own package-lock.json to the repo, so a source + * checkout already has the lockfile that `npm ci` needs. */ async function ensureDeps(dir: string, ctx: AdapterContext): Promise { if (existsSync(join(dir, "node_modules"))) return; diff --git a/tsconfig.eng.json b/tsconfig.eng.json index 1d3264dce65..8d395c4e598 100644 --- a/tsconfig.eng.json +++ b/tsconfig.eng.json @@ -1,5 +1,8 @@ { "extends": "./tsconfig.base.json", + "compilerOptions": { + "allowImportingTsExtensions": true + }, "include": ["eng"], "exclude": ["eng/vitest.config.ts"] } From abe62b08681c5ca15ac4beb22ce10089daf9be69 Mon Sep 17 00:00:00 2001 From: Libba Lawrence Date: Wed, 1 Jul 2026 16:15:44 -0700 Subject: [PATCH 21/52] Log baseline/head output dirs after generation A local run now prints the exact generated trees the diff compares, so developers can open the head (current checkout) output directly instead of inferring it from the work dir. Language-agnostic: lives in cli.ts, labeled per side by the resolved emitter. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- eng/emitter-diff/src/cli.ts | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/eng/emitter-diff/src/cli.ts b/eng/emitter-diff/src/cli.ts index 608d32d4aba..6f7e6e85c96 100644 --- a/eng/emitter-diff/src/cli.ts +++ b/eng/emitter-diff/src/cli.ts @@ -196,6 +196,13 @@ async function main(): Promise { await adapter.generate(headReq, ctx); } + // Point at the generated trees the diff compares, so a local run can open the + // head output directly. Head is the current checkout unless --head overrode it. + log.info( + `${color.dim("baseline output:")} ${baselineOut} ${color.dim(`(${baselineEmitter.label})`)}`, + ); + log.info(`${color.cyan("head output:")} ${headOut} ${color.dim(`(${headEmitter.label})`)}`); + // Diff. const diff = await diffDirs(baselineOut, headOut, log); From 4601b99da3925e51472b21fb80da0063aa63b128 Mon Sep 17 00:00:00 2001 From: Libba Lawrence Date: Wed, 1 Jul 2026 17:01:29 -0700 Subject: [PATCH 22/52] Slim down emitter-diff CI workflow Cut the python workflow to ~half its size: - trim explanatory comment headers - drop the hand-rolled github-script patch parser; reuse the tool's own 'Diff summary:' line (ANSI-stripped) as a step output for the PR comment - drop the redundant job-summary step and the now-unused --patch output - collapse 'Fail on tool error' to a one-liner Behavior is unchanged: sticky PR comment, HTML artifact, informational-only (fails only on a tool/build error, never on a diff). Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- .github/workflows/ci-emitter-diff-python.yml | 155 ++++--------------- 1 file changed, 31 insertions(+), 124 deletions(-) diff --git a/.github/workflows/ci-emitter-diff-python.yml b/.github/workflows/ci-emitter-diff-python.yml index f25df119269..018cfd419f8 100644 --- a/.github/workflows/ci-emitter-diff-python.yml +++ b/.github/workflows/ci-emitter-diff-python.yml @@ -1,26 +1,12 @@ name: "python / emitter diff" -# Generates code with the current checkout's emitter and with the emitter as of -# the base-branch commit this PR is based on (the merge-base), then diffs the two. -# The rendered HTML diff is uploaded as a per-PR artifact and a sticky PR comment -# summarizes the change with a link to download it, so reviewers can see exactly -# how an emitter change affects generated SDKs. Powered by the language-agnostic -# eng/emitter-diff tool. -# -# This check is informational: it always passes unless the tool hits a real -# tool/build error. A generated-output diff does not fail the PR β€” it is only -# reported (job summary + PR comment + HTML artifact) for reviewers to eyeball. -# -# Python's generator uses a native two-phase pipeline (TypeSpec emits YAML, then -# a batched Python subprocess writes the .py files) with a venv co-located with -# each emitter version. So this workflow builds + sets up a venv for both the -# head checkout and a worktree of the baseline commit before diffing. +# Diffs generated code between this PR's emitter and the merge-base baseline. +# Informational only: reports a sticky PR comment + HTML artifact, and fails the +# job only on a tool/build error (never on a diff). See eng/emitter-diff. on: pull_request: - branches: - - main - - release/* + branches: [main, release/*] paths: - "packages/http-client-python/**" - "eng/emitter-diff/**" @@ -28,7 +14,7 @@ on: workflow_dispatch: inputs: baseline: - description: "Baseline emitter ref (npm version, local path, or github ref). Defaults to the PR's merge-base with its base branch." + description: "Baseline emitter ref (npm version, local path, or github ref). Defaults to the PR merge-base." required: false default: "" @@ -48,28 +34,19 @@ jobs: - uses: actions/checkout@v6 with: fetch-depth: 0 - - uses: ./.github/actions/setup - - uses: actions/setup-python@v5 with: python-version: "3.12" - - name: Install repo dependencies (emitter-diff tool) run: pnpm install - - name: Build + venv for head emitter working-directory: packages/http-client-python - run: | - npm ci - npm run build - npm run install + run: npm ci && npm run build && npm run install - name: Determine baseline id: baseline - # The dispatch input is untrusted; pass everything through `env` and - # reference only shell variables so nothing is interpolated into the - # script body (GitHub Actions expression injection). + # Dispatch input is untrusted: pass via env, reference only as "$VAR". env: BASELINE_INPUT: ${{ github.event.inputs.baseline || '' }} BASE_REF: ${{ github.event.pull_request.base.ref || github.event.repository.default_branch }} @@ -77,18 +54,12 @@ jobs: run: | input="$BASELINE_INPUT" if [ -z "$input" ]; then - # Baseline = the base-branch commit this PR is based on (merge-base). - # It is always a real commit on the target branch, so it survives - # squash-merge / rebase / force-push (unlike a pinned branch SHA). + # merge-base = a real commit on the base branch; survives squash/rebase. git fetch --no-tags origin "$BASE_REF" base_sha="$(git merge-base FETCH_HEAD HEAD)" - if [ -z "$base_sha" ]; then - echo "::error::Could not determine a merge-base with $BASE_REF." - exit 1 - fi - echo "Baseline (merge-base with $BASE_REF): $base_sha" + [ -n "$base_sha" ] || { echo "::error::No merge-base with $BASE_REF."; exit 1; } git worktree add "$RUNNER_TEMP/baseline" "$base_sha" - (cd "$RUNNER_TEMP/baseline/packages/http-client-python" && npm ci && npm run build && npm run install) + ( cd "$RUNNER_TEMP/baseline/packages/http-client-python" && npm ci && npm run build && npm run install ) input="local:$RUNNER_TEMP/baseline/packages/http-client-python" echo "sha=$base_sha" >> "$GITHUB_OUTPUT" fi @@ -98,43 +69,23 @@ jobs: - name: Run emitter diff id: diff working-directory: eng/emitter-diff - # `BASELINE_REF` derives from the untrusted dispatch input, so keep it in - # `env` and reference it as "$BASELINE_REF" rather than interpolating it. env: BASELINE_REF: ${{ steps.baseline.outputs.ref }} RUNNER_TEMP: ${{ runner.temp }} run: | set +e - # Run with plain `node` (Node 24 runs TypeScript natively) so the tool's - # real exit code propagates. No `--fail-on-diff`: this check is - # informational and never fails on a diff. A real tool/build error still - # surfaces via a non-zero exit code (checked in "Fail on tool error"). + # Node 24 runs TypeScript natively; no --fail-on-diff (informational). + # A tool/build error still exits non-zero (checked in "Fail on tool error"). node src/cli.ts \ - --emitter python \ - --baseline "$BASELINE_REF" \ + --emitter python --baseline "$BASELINE_REF" \ --work-dir "$RUNNER_TEMP/emitter-diff" \ --html "$RUNNER_TEMP/emitter-diff.html" \ - --patch "$RUNNER_TEMP/emitter-diff.patch" \ | tee "$RUNNER_TEMP/emitter-diff.log" echo "status=${PIPESTATUS[0]}" >> "$GITHUB_OUTPUT" - - - name: Write job summary - if: always() - env: - BASELINE_SHA: ${{ steps.baseline.outputs.sha }} - RUNNER_TEMP: ${{ runner.temp }} - run: | - { - echo "## Emitter diff" - echo "" - echo "Baseline (merge-base): \`$BASELINE_SHA\` vs current checkout." - echo "" - echo '```' - grep -E "Diff summary:" "$RUNNER_TEMP/emitter-diff.log" || echo "No summary captured." - echo '```' - echo "" - echo "Download the **emitter-diff-html** artifact for the full rendered diff." - } >> "$GITHUB_STEP_SUMMARY" + # Reuse the tool's own summary line (strip ANSI) instead of re-parsing. + summary="$(sed -r 's/\x1b\[[0-9;]*m//g' "$RUNNER_TEMP/emitter-diff.log" \ + | grep -oE 'Diff summary: [0-9]+ file\(s\), \+[0-9]+ / -[0-9]+' | head -1)" + echo "summary=${summary:-No changes to generated output.}" >> "$GITHUB_OUTPUT" - name: Upload HTML diff if: always() @@ -150,71 +101,27 @@ jobs: continue-on-error: true uses: actions/github-script@v7 env: - BASELINE: ${{ steps.baseline.outputs.sha }} + BASELINE: ${{ steps.baseline.outputs.sha || steps.baseline.outputs.ref }} STATUS: ${{ steps.diff.outputs.status }} - PATCH_FILE: ${{ runner.temp }}/emitter-diff.patch - HTML_FILE: ${{ runner.temp }}/emitter-diff.html + SUMMARY: ${{ steps.diff.outputs.summary }} with: script: | - const fs = require("fs"); const marker = ""; const runUrl = `${context.serverUrl}/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId}`; - const status = process.env.STATUS; - - // Parse the unified patch directly so the numbers match the tool exactly. - let patch = ""; - try { patch = fs.readFileSync(process.env.PATCH_FILE, "utf8"); } catch {} - const lines = patch.split("\n"); - const files = []; - let insertions = 0, deletions = 0; - for (const line of lines) { - const m = line.match(/^diff --git a\/(.+?) b\/(.+)$/); - if (m) files.push(m[2]); - else if (line.startsWith("+") && !line.startsWith("+++")) insertions++; - else if (line.startsWith("-") && !line.startsWith("---")) deletions++; - } - const hasChanges = patch.trim().length > 0; - const htmlExists = fs.existsSync(process.env.HTML_FILE); - - let body = `${marker}\n## Python emitter diff\n\n` + - `Baseline \`${process.env.BASELINE}\` (merge-base) vs this PR's checkout.\n\n`; - if (status !== "0") { - // Hard error (build/venv/generate threw) β€” not a diff. Don't claim "no changes". - body += `**emitter-diff failed to run** (exit \`${status}\`). This is a tool/build ` + - `error, not a generated-output diff. See the ` + - `[workflow run](${runUrl}) logs` + - (htmlExists ? ` and the **emitter-diff-html** artifact` : "") + `.\n`; - } else if (!hasChanges) { - body += `**No changes** β€” generated output matches the baseline.\n`; - } else { - body += `**${files.length} file(s) changed** Β· +${insertions} / -${deletions}\n\n`; - if (htmlExists) { - body += `Download the **emitter-diff-html** artifact from the ` + - `[workflow run](${runUrl}) for the full side-by-side rendered diff.\n`; - } - } - body += `\n_Generated by \`eng/emitter-diff\`. This check is informational and does not block the PR._`; - - const { owner, repo } = context.repo; - const issue_number = context.issue.number; - const { data: comments } = await github.rest.issues.listComments({ owner, repo, issue_number }); - const existing = comments.find((c) => c.body && c.body.includes(marker)); - if (existing) { - await github.rest.issues.updateComment({ owner, repo, comment_id: existing.id, body }); - } else { - await github.rest.issues.createComment({ owner, repo, issue_number, body }); - } + const { STATUS, SUMMARY, BASELINE } = process.env; + let body = `${marker}\n### Python emitter diff\nBaseline \`${BASELINE}\` vs this PR.\n\n`; + body += STATUS !== "0" + ? `⚠️ **emitter-diff failed** (exit \`${STATUS}\`) β€” tool/build error, not a diff. See the [run](${runUrl}).\n` + : `${SUMMARY}\n\nFull rendered diff: **emitter-diff-html** artifact on the [run](${runUrl}).\n`; + body += `\n_Informational check (eng/emitter-diff); does not block the PR._`; + const { owner, repo } = context.repo, issue_number = context.issue.number; + const { data } = await github.rest.issues.listComments({ owner, repo, issue_number }); + const hit = data.find((c) => c.body && c.body.includes(marker)); + if (hit) await github.rest.issues.updateComment({ owner, repo, comment_id: hit.id, body }); + else await github.rest.issues.createComment({ owner, repo, issue_number, body }); - name: Fail on tool error if: always() env: STATUS: ${{ steps.diff.outputs.status }} - run: | - # Informational check: a generated-output diff does NOT fail the PR - # (the tool is run without --fail-on-diff, so a diff still exits 0). - # Only a real tool/build error (non-zero exit) fails the job. - if [ "$STATUS" != "0" ]; then - echo "::error::emitter-diff failed (exit $STATUS). See the log and the emitter-diff-html artifact." - exit 1 - fi - echo "emitter-diff ran successfully (informational; diffs are reported, not enforced)." + run: '[ "$STATUS" = "0" ] || { echo "::error::emitter-diff failed (exit $STATUS)."; exit 1; }' From 02e640013265da6a276f3db1122598bb9472e30a Mon Sep 17 00:00:00 2001 From: Libba Lawrence Date: Thu, 2 Jul 2026 15:25:26 -0700 Subject: [PATCH 23/52] start addressing comments (now a default script for python but if want diff configs can run script directly in terminal) -- need to check on cache implementation locally --- ...r-diff-regenerate-flags-2026-6-30-0-0-0.md | 7 - .github/workflows/ci-emitter-diff-python.yml | 19 +- eng/emitter-diff/README.md | 73 +++--- eng/emitter-diff/src/adapters/python.ts | 95 +------ eng/emitter-diff/src/baseline-cache.ts | 104 ++++++++ eng/emitter-diff/src/cli.ts | 239 +++++++++++++----- eng/emitter-diff/src/resolver.ts | 145 ++++++++--- eng/emitter-diff/src/types.ts | 24 +- .../eng/scripts/ci/regenerate.ts | 84 +++--- packages/http-client-python/package.json | 3 +- 10 files changed, 499 insertions(+), 294 deletions(-) delete mode 100644 .chronus/changes/emitter-diff-regenerate-flags-2026-6-30-0-0-0.md create mode 100644 eng/emitter-diff/src/baseline-cache.ts diff --git a/.chronus/changes/emitter-diff-regenerate-flags-2026-6-30-0-0-0.md b/.chronus/changes/emitter-diff-regenerate-flags-2026-6-30-0-0-0.md deleted file mode 100644 index bd9efd2c41f..00000000000 --- a/.chronus/changes/emitter-diff-regenerate-flags-2026-6-30-0-0-0.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -changeKind: internal -packages: - - "@typespec/http-client-python" ---- - -Add `--httpSpecsDir`, `--azureSpecsDir`, and `--no-baseline` flags to `regenerate.ts` so the language-agnostic `eng/emitter-diff` tool can drive code generation against pinned specs without cloning the published baseline. diff --git a/.github/workflows/ci-emitter-diff-python.yml b/.github/workflows/ci-emitter-diff-python.yml index 018cfd419f8..d0724b6ae38 100644 --- a/.github/workflows/ci-emitter-diff-python.yml +++ b/.github/workflows/ci-emitter-diff-python.yml @@ -40,9 +40,6 @@ jobs: python-version: "3.12" - name: Install repo dependencies (emitter-diff tool) run: pnpm install - - name: Build + venv for head emitter - working-directory: packages/http-client-python - run: npm ci && npm run build && npm run install - name: Determine baseline id: baseline @@ -58,9 +55,7 @@ jobs: git fetch --no-tags origin "$BASE_REF" base_sha="$(git merge-base FETCH_HEAD HEAD)" [ -n "$base_sha" ] || { echo "::error::No merge-base with $BASE_REF."; exit 1; } - git worktree add "$RUNNER_TEMP/baseline" "$base_sha" - ( cd "$RUNNER_TEMP/baseline/packages/http-client-python" && npm ci && npm run build && npm run install ) - input="local:$RUNNER_TEMP/baseline/packages/http-client-python" + input="gh:$base_sha" echo "sha=$base_sha" >> "$GITHUB_OUTPUT" fi echo "ref=$input" >> "$GITHUB_OUTPUT" @@ -68,17 +63,17 @@ jobs: - name: Run emitter diff id: diff - working-directory: eng/emitter-diff + working-directory: packages/http-client-python env: BASELINE_REF: ${{ steps.baseline.outputs.ref }} RUNNER_TEMP: ${{ runner.temp }} run: | set +e - # Node 24 runs TypeScript natively; no --fail-on-diff (informational). - # A tool/build error still exits non-zero (checked in "Fail on tool error"). - node src/cli.ts \ - --emitter python --baseline "$BASELINE_REF" \ - --work-dir "$RUNNER_TEMP/emitter-diff" \ + # Script wraps emitter-diff entrypoint. No --fail-on-diff (informational); + # tool/build errors still exit non-zero (checked in "Fail on tool error"). + npm run diff-spector-tests -- \ + --ci \ + --baseline "$BASELINE_REF" \ --html "$RUNNER_TEMP/emitter-diff.html" \ | tee "$RUNNER_TEMP/emitter-diff.log" echo "status=${PIPESTATUS[0]}" >> "$GITHUB_OUTPUT" diff --git a/eng/emitter-diff/README.md b/eng/emitter-diff/README.md index 28203b1c4bd..c8582bb5dcb 100644 --- a/eng/emitter-diff/README.md +++ b/eng/emitter-diff/README.md @@ -6,17 +6,17 @@ TypeSpec emitter**. It generates code from the test specs twice (a **baseline** emitter and a **head** emitter), then shows the diff between the two outputs. Use it locally during development and in CI on PRs. -Each language emitter (python, and later java/rust/go/ts) plugs in via a small **adapter** that +Each language emitter plugs in via a small **adapter** that wraps that emitter's own generation command. The core (ref resolution, diffing, orchestration) contains no language-specific logic. ## How it works -``` +```text baseline emitter ─┐ - β”œβ”€ generate (adapter) ─► /baseline ─┐ + β”œβ”€ generate ─► /baseline ─┐ specs ────────────────────── β”œβ”€β–Ί git diff ─► terminal / HTML - β”œβ”€ generate (adapter) ─► /head β”€β”€β”€β”€β”€β”˜ + β”œβ”€ generate ─► /head β”€β”€β”€β”€β”€β”˜ head emitter β”€β”€β”€β”€β”€β”˜ ``` @@ -29,75 +29,62 @@ contains no language-specific logic. ```bash # Run directly with Node 24+ (native TypeScript, no build step, no dependencies): -node eng/emitter-diff/src/cli.ts --emitter python --baseline 0.34.0 +node eng/emitter-diff/src/cli.ts --emitter python ``` > This tool is a set of plain `.ts` scripts β€” not an installed package. Node 24 runs TypeScript > natively, so there is nothing to build or install. Typecheck with `npx tsc -p eng/emitter-diff`. -### Refs (`--baseline`, `--head`, `--specs`) +### Refs + +#### Emitter refs (`--baseline`, `--head`) | Syntax | Meaning | | --------------------------------- | -------------------------------------- | | `npm:1.2.3` or `1.2.3` | a published package version (prebuilt) | | `local:/path` or `./path` | a local source folder | | `github:owner/repo@` | a GitHub source at a ref | -| `gh:` | the current repo at a ref | +| `gh:` | `microsoft/typespec` at a ref | -`--head` defaults to the **current checkout**. `--specs` defaults to **all** repo specs. +`--head` defaults to the **current checkout**. `--baseline` defaults to `gh:upstream/main` when present, otherwise `gh:origin/main` (`origin/HEAD` as a fallback). -> `--baseline`/`--head` accept all three ref kinds. `--specs` accepts **local** or **github** -> refs only (npm versions aren't a valid spec source) β€” an `npm:` spec ref is rejected. +Use `--name` to filter which packages/specs are generated. ### Common options By default the tool writes a **clickable HTML report** (`emitter-diff.html`) into the work dir and -prints a `file://` link to it. Use `--terminal` for the full patch in your shell, or -`--patch`/`--html` to write to a specific file. - -| Option | Description | -| ------------------ | ------------------------------------------------------------------------------------- | -| `--name ` | Filter which specs/packages are generated | -| `--html ` | Write the rendered HTML report to this path (default: `/emitter-diff.html`) | -| `--terminal` | Print the full colored patch to the terminal instead | -| `--patch ` | Write the raw unified diff to a file | -| `--fail-on-diff` | Exit non-zero when output differs (CI gating) | -| `--opt key=value` | Repeatable adapter-specific option (e.g. `--opt flavor=azure`) | -| `--sequential` | Generate baseline then head one at a time (default: both in parallel) | -| `-- ` | Everything after `--` is forwarded to the adapter | +prints a `file://` link to it. Use `--html` to write to a specific file. + +- `--name `: Filter which specs/packages are generated. +- `--html `: Write the rendered HTML report to this path (default: `/emitter-diff.html`). +- `--generated-code-path `: Override the adapter generated-code subpath under each side output root. +- `--fail-on-diff`: Exit non-zero when output differs (CI gating). ### Examples ```bash -# Default: writes a clickable emitter-diff.html and prints a file:// link. -node eng/emitter-diff/src/cli.ts --emitter python --baseline 0.34.0 \ - --opt flavor=azure --name authentication-api-key +# Explicit baseline version: +node eng/emitter-diff/src/cli.ts --emitter python --baseline 0.34.0 --name authentication-api-key # Compare two source folders and write an HTML report to a specific path: -node eng/emitter-diff/src/cli.ts --emitter python \ - --baseline local:/path/to/old/http-client-python \ +node eng/emitter-diff/src/cli.ts --emitter python --baseline local:/path/to/old/http-client-python \ --head local:/path/to/new/http-client-python \ --html diff.html +# Override the adapter generated-code subpath under each side output root: +node eng/emitter-diff/src/cli.ts --emitter python --generated-code-path tests/generated + # Diff against a GitHub sha: node eng/emitter-diff/src/cli.ts --emitter python \ - --baseline github:microsoft/typespec@ flavor=azure < sha > --opt + --baseline github:microsoft/typespec@ ``` ## CI integration -`.github/workflows/ci-emitter-diff-python.yml` runs on PRs that touch the python emitter or this -tool. The **baseline** is the base-branch commit the PR is based on (the `git merge-base` with the -target branch) β€” always a real commit on the target branch, so it survives squash-merge, rebase, -and force-push. CI builds the python emitter (and a venv) for both the PR's checkout and a worktree +`.github/workflows/ci-emitter-diff-.yml` runs on PRs that touch the language emitter or this tool. The **baseline** is the base-branch commit the PR is based on (the `git merge-base` with the target branch). CI builds the emitter for both the PR's checkout and a worktree of that merge-base commit, diffs the two, and then: -- uploads the rendered **`emitter-diff-html`** artifact (full side-by-side diff; downloadable from - the workflow run β€” GitHub artifacts are zip downloads, so they can't be rendered inline in a - comment), -- writes a job-summary with the diff totals, and -- posts a **sticky PR comment** (updated in place on each push) with the changed-file and `+`/`-` - counts and a link to download the artifact. +- posts a **sticky PR comment** (updated in place on each push) with the link to download the diff artifact. **Informational:** the check **always passes unless the tool hits a real tool/build error** β€” a generated-output diff does not fail the PR. CI runs the tool without `--fail-on-diff`, so a diff @@ -118,9 +105,15 @@ language-agnostic and require no changes. ## Notes & limitations -- External `--specs` folders must mirror the `http-specs` / `azure-http-specs` layout. +- For the current python regenerate flow, spec inputs come from each side's + dependencies (`node_modules/@typespec/http-specs` and + `node_modules/@azure-tools/azure-http-specs`). Use `--name` to filter. - `--html` renders a self-contained, GitHub-style HTML report (inline CSS, no external requests). The tool has **zero runtime dependencies** β€” the diff itself is `git diff --no-index`. +- For github refs (including fork repos), the resolver uses a detached, commit-keyed cached git + worktree under the temp directory, created from an isolated cache repo (not from your active + checkout). That keeps each version's build/venv isolated and allows repeated runs on the same + commit to reuse existing setup work. - **Python's native two-phase pipeline needs a venv per emitter version.** `regenerate.ts` compiles TypeSpec to YAML in-process and then runs a batched Python subprocess (`eng/scripts/setup/run_batch.py`) that writes the `.py` files using a venv co-located with the diff --git a/eng/emitter-diff/src/adapters/python.ts b/eng/emitter-diff/src/adapters/python.ts index 81d4784e346..d97c084ae00 100644 --- a/eng/emitter-diff/src/adapters/python.ts +++ b/eng/emitter-diff/src/adapters/python.ts @@ -72,8 +72,7 @@ async function ensureDeps(dir: string, ctx: AdapterContext): Promise { async function ensureBuilt(dir: string, ctx: AdapterContext): Promise { if (await isBuilt(dir)) return; - // A source checkout may not have its deps installed yet; install them first - // so the build can resolve modules/types. + // Source checkouts may not have dependencies installed yet. await ensureDeps(dir, ctx); ctx.log.warn(`Emitter at ${dir} is not built; attempting build...`); const res = await run("npm", ["run", "build"], { cwd: dir, inherit: true }); @@ -84,12 +83,7 @@ async function ensureBuilt(dir: string, ctx: AdapterContext): Promise { } } -/** - * Core's regenerate pipeline is two-phase: the TypeSpec compile emits YAML, then - * a batched Python subprocess (`run_batch.py`) writes the `.py` files using a - * venv co-located with the emitter at `/venv`. Each emitter version needs - * its own venv (built from that version's generator), so ensure one exists. - */ +/** Ensure the emitter has a local Python venv for generation. */ async function ensureVenv(dir: string, ctx: AdapterContext): Promise { if (existsSync(join(dir, "venv"))) return; ctx.log.warn(`No Python venv at ${dir}; creating one (npm run install)...`); @@ -118,17 +112,15 @@ export const pythonAdapter: EmitterAdapter = { } if (ref.kind === "npm") { - // npm versions ship a prebuilt dist + python generator. The native - // pipeline still needs a venv built from that generator, so create one. + // npm emitters are prebuilt but still need a venv. const dir = await ctx.installNpmPackage(PACKAGE_NAME, ref.version ?? "latest"); await ensureVenv(dir, ctx); return { dir, label: describeRef(ref, PACKAGE_NAME) }; } - // local / github: resolve to a source dir, then ensure it is built + has a venv. + // local/github refs may require a build and venv. const sourceRoot = await ctx.resolveSource(ref, PACKAGE_NAME); - // For a full-repo source (github clone or repo root), the emitter lives in - // packages/http-client-python; otherwise the resolved dir is the package itself. + // Full-repo sources contain the package under packages/http-client-python. const candidate = existsSync(join(sourceRoot, PKG_REL)) ? join(sourceRoot, PKG_REL) : sourceRoot; @@ -138,88 +130,17 @@ export const pythonAdapter: EmitterAdapter = { }, async generate(request: GenerateRequest, ctx: AdapterContext): Promise { - // The new in-process regenerate driver anchors generated output at - // `/../tests/generated/...`. Point generatedFolder at a - // `generator` subdir of the requested output dir so files land directly - // under request.outputDir/tests/generated, which the diff engine compares. - const args = [ - "--pluginDir", - request.emitter.dir, - "--generatedFolder", - join(request.outputDir, "generator"), - // Emit only fresh codegen β€” skip the azure-sdk-for-python baseline clone. - "--no-baseline", - ]; + // Regenerate writes under /../tests/generated/... + const generatedFolder = join(request.outputDir, request.generatedCodePath ?? "generator"); + const args = ["--pluginDir", request.emitter.dir, "--generatedFolder", generatedFolder]; const flavor = request.options.flavor; if (flavor) args.push("--flavor", flavor); if (request.nameFilter) args.push("--name", request.nameFilter); - // Specs are pinned to the current checkout so only the emitter differs - // between baseline and head. External specs (--specs) override that. - const httpSpecs = resolveHttpSpecs(request, ctx); - const azureSpecs = resolveAzureSpecs(request, ctx); - if (httpSpecs) args.push("--httpSpecsDir", httpSpecs); - if (azureSpecs) args.push("--azureSpecsDir", azureSpecs); - - // When the user explicitly pinned specs, warn (rather than silently falling - // back to the current checkout's specs) if the expected layout wasn't found. - if (request.specsDir) { - if (!httpSpecs) { - ctx.log.warn( - `--specs was given (${request.specsDir}) but no http-specs dir was found under it ` + - `(looked for http-specs/specs, packages/http-specs/specs, specs/). Falling back to defaults.`, - ); - } - if ((flavor === undefined || flavor === "azure") && !azureSpecs) { - ctx.log.warn( - `--specs was given (${request.specsDir}) but no azure-http-specs dir was found under it ` + - `(looked for azure-http-specs/specs, packages/azure-http-specs/specs, azure/specs). ` + - `Azure specs will use the current checkout's dependency.`, - ); - } - } - args.push(...request.passthrough); ctx.log.step(`Generating with ${request.emitter.label} β†’ ${request.outputDir}`); await runScript(ctx, "eng/scripts/ci/regenerate.ts", args, { prefix: request.logPrefix }); }, }; - -function firstExisting(paths: string[]): string | undefined { - return paths.find((p) => existsSync(p)); -} - -/** Default http-specs dir inside the current checkout's python package. */ -function defaultHttpSpecs(ctx: AdapterContext): string { - return join(pkgDir(ctx), "node_modules", "@typespec", "http-specs", "specs"); -} - -/** Default azure-http-specs dir inside the current checkout's python package. */ -function defaultAzureSpecs(ctx: AdapterContext): string { - return join(pkgDir(ctx), "node_modules", "@azure-tools", "azure-http-specs", "specs"); -} - -function resolveHttpSpecs(request: GenerateRequest, ctx: AdapterContext): string | undefined { - if (request.specsDir) { - return firstExisting([ - join(request.specsDir, "http-specs", "specs"), - join(request.specsDir, "packages", "http-specs", "specs"), - join(request.specsDir, "specs"), - request.specsDir, - ]); - } - return firstExisting([defaultHttpSpecs(ctx)]); -} - -function resolveAzureSpecs(request: GenerateRequest, ctx: AdapterContext): string | undefined { - if (request.specsDir) { - return firstExisting([ - join(request.specsDir, "azure-http-specs", "specs"), - join(request.specsDir, "packages", "azure-http-specs", "specs"), - join(request.specsDir, "azure", "specs"), - ]); - } - return firstExisting([defaultAzureSpecs(ctx)]); -} diff --git a/eng/emitter-diff/src/baseline-cache.ts b/eng/emitter-diff/src/baseline-cache.ts new file mode 100644 index 00000000000..ed31a562838 --- /dev/null +++ b/eng/emitter-diff/src/baseline-cache.ts @@ -0,0 +1,104 @@ +import { createHash } from "node:crypto"; +import { existsSync, readFileSync, renameSync, writeFileSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join, resolve, sep } from "node:path"; + +import { ensureDir, run } from "./util.ts"; + +export interface BaselineCacheProfileInput { + emitter: string; + baselineRef: string; + generatedCodePath?: string; + nameFilter?: string; + options: Record; + passthrough: string[]; +} + +export interface BaselineCacheIndexEntry { + baselineIdentity: string; + updatedAt: string; +} + +export type BaselineCacheIndex = Record; + +function stableJson(value: unknown): string { + if (value === null || typeof value !== "object") return JSON.stringify(value); + if (Array.isArray(value)) return `[${value.map(stableJson).join(",")}]`; + const obj = value as Record; + const keys = Object.keys(obj).sort(); + return `{${keys.map((k) => `${JSON.stringify(k)}:${stableJson(obj[k])}`).join(",")}}`; +} + +export function computeBaselineProfileKey(input: BaselineCacheProfileInput): string { + const raw = stableJson(input); + return createHash("sha256").update(raw).digest("hex").slice(0, 16); +} + +export async function detectBaselineIdentity(dir: string): Promise { + const gitHead = await run("git", ["rev-parse", "--verify", "HEAD"], { cwd: dir }); + if (gitHead.code === 0) { + const sha = gitHead.stdout.trim(); + if (sha) return `git:${sha}`; + } + + const manifest = join(dir, "package.json"); + if (existsSync(manifest)) { + try { + const parsed = JSON.parse(readFileSync(manifest, "utf8")) as { + name?: string; + version?: string; + }; + if (parsed.name && parsed.version) return `pkg:${parsed.name}@${parsed.version}`; + } catch { + // Fall through to path identity when package metadata cannot be read. + } + } + + // Last-resort identity for non-git/non-package dirs. + return `path:${resolve(dir)}`; +} + +export function baselineCachePaths(cacheKey: string): { dir: string; marker: string } { + const root = baselineCacheRoot(); + return { + dir: join(root, cacheKey), + marker: join(root, `${cacheKey}.done`), + }; +} + +function baselineCacheRoot(): string { + return ensureDir(join(tmpdir(), "emitter-diff-cache", "baseline-output")); +} + +function baselineCacheIndexPath(): string { + return join(baselineCacheRoot(), "index.json"); +} + +function isWithinDir(root: string, target: string): boolean { + const normalizedRoot = resolve(root); + const normalizedTarget = resolve(target); + return ( + normalizedTarget === normalizedRoot || normalizedTarget.startsWith(`${normalizedRoot}${sep}`) + ); +} + +export function isSafeBaselineCachePath(path: string): boolean { + return isWithinDir(baselineCacheRoot(), path); +} + +export function readBaselineCacheIndex(): BaselineCacheIndex { + const path = baselineCacheIndexPath(); + if (!existsSync(path)) return {}; + try { + return JSON.parse(readFileSync(path, "utf8")) as BaselineCacheIndex; + } catch { + return {}; + } +} + +export function writeBaselineCacheIndex(index: BaselineCacheIndex): void { + const targetPath = baselineCacheIndexPath(); + const tmpPath = `${targetPath}.${process.pid}.${Date.now()}.tmp`; + writeFileSync(tmpPath, `${JSON.stringify(index, null, 2)}\n`, "utf8"); + renameSync(tmpPath, targetPath); +} diff --git a/eng/emitter-diff/src/cli.ts b/eng/emitter-diff/src/cli.ts index 6f7e6e85c96..3a5630cc29d 100644 --- a/eng/emitter-diff/src/cli.ts +++ b/eng/emitter-diff/src/cli.ts @@ -6,10 +6,20 @@ * and diffs the output. All language specifics live behind the selected adapter; * this file contains zero language logic. */ -import { join, resolve } from "node:path"; +import { cpSync, existsSync, rmSync, writeFileSync } from "node:fs"; +import { join } from "node:path"; import { parseArgs } from "node:util"; -import { diffDirs, printDiff, printSummary, writeHtml, writePatch } from "./diff.ts"; +import { + baselineCachePaths, + computeBaselineProfileKey, + detectBaselineIdentity, + isSafeBaselineCachePath, + readBaselineCacheIndex, + writeBaselineCacheIndex, + type BaselineCacheIndex, +} from "./baseline-cache.ts"; +import { diffDirs, printSummary, writeHtml } from "./diff.ts"; import { getAdapter, listAdapters } from "./registry.ts"; import { classifyRef, @@ -18,41 +28,83 @@ import { resolveSource as resolveSrc, } from "./resolver.ts"; import type { AdapterContext, ClassifiedRef } from "./types.ts"; -import { color, createLogger, ensureDir, runChecked } from "./util.ts"; +import { color, createLogger, ensureDir, run, runChecked } from "./util.ts"; + +function shouldUseBaselineCache(ciMode: boolean): { enabled: boolean; reason?: string } { + if (ciMode) { + return { enabled: false, reason: "--ci" }; + } + + // Restrict caching to clearly local, interactive usage by default. + if (!process.stdout.isTTY || !process.stderr.isTTY) { + return { enabled: false, reason: "non-interactive terminal" }; + } + + return { enabled: true }; +} const HELP = `${color.bold("emitter-diff")} β€” diff generated code across emitter versions ${color.bold("Usage:")} - emitter-diff --emitter --baseline [options] + emitter-diff --emitter [options] ${color.bold("Required:")} --emitter Adapter to use. Available: ${listAdapters().join(", ")} - --baseline Old emitter to compare against. -${color.bold("Refs")} (for --baseline / --head / --specs): +${color.bold("Refs")} (for --baseline / --head): npm:1.2.3 | 1.2.3 a published package version local:/path | ./path a local folder github:owner/repo@ a GitHub source at a ref - gh: the current repo at a ref + gh: microsoft/typespec at a ref ${color.bold("Options:")} + --baseline Old emitter. Default: gh:upstream/main if present, + otherwise gh:origin/main. --head New emitter. Default: current checkout. - --specs Spec inputs: all (default) | local | github. + --generated-code-path + Override adapter generated-code subpath under each + side output root. --name Filter which specs/packages are generated. - --work-dir Scratch dir (default: a temp dir). + Baseline output is cached across local runs. + --ci CI mode: disable local baseline cache. --html Write the rendered HTML diff to this path. Default output: a clickable HTML report in the work dir. - --terminal Print the full colored patch to the terminal instead. - --patch Write the raw unified diff to a file. --fail-on-diff Exit non-zero when output differs (CI gating). Exit code 2 means "diff present"; 1 means a hard error. --opt key=value Repeatable adapter-specific option (e.g. --opt flavor=azure). - --sequential Generate baseline then head one at a time (default: - generate both in parallel with prefixed logs). -- Everything after -- is forwarded to the adapter. -h, --help Show this help. `; +async function resolveDefaultBaselineRef(repoRoot: string): Promise { + // Prefer upstream/main for fork workflows. + const upstreamMain = await run( + "git", + ["show-ref", "--verify", "--quiet", "refs/remotes/upstream/main"], + { cwd: repoRoot }, + ); + if (upstreamMain.code === 0) return "gh:upstream/main"; + + const originMain = await run( + "git", + ["show-ref", "--verify", "--quiet", "refs/remotes/origin/main"], + { cwd: repoRoot }, + ); + if (originMain.code === 0) return "gh:origin/main"; + + // Fall back to origin/HEAD (for example, origin/master). + const originHead = await run("git", ["symbolic-ref", "--quiet", "refs/remotes/origin/HEAD"], { + cwd: repoRoot, + }); + if (originHead.code === 0) { + const ref = originHead.stdout.trim().replace(/^refs\/remotes\//, ""); + if (ref) return `gh:${ref}`; + } + + // Final fallback for unusual clones. + return "gh:origin/main"; +} + async function main(): Promise { const rawArgs = process.argv.slice(2); @@ -67,15 +119,12 @@ async function main(): Promise { emitter: { type: "string" }, baseline: { type: "string" }, head: { type: "string" }, - specs: { type: "string" }, + "generated-code-path": { type: "string" }, name: { type: "string" }, - "work-dir": { type: "string" }, - terminal: { type: "boolean" }, - patch: { type: "string" }, + ci: { type: "boolean" }, html: { type: "string" }, "fail-on-diff": { type: "boolean" }, opt: { type: "string", multiple: true }, - sequential: { type: "boolean" }, help: { type: "boolean", short: "h" }, }, allowPositionals: false, @@ -91,11 +140,6 @@ async function main(): Promise { log.error("--emitter is required (no default). " + `Available: ${listAdapters().join(", ")}`); return 2; } - if (!values.baseline) { - log.error("--baseline is required."); - return 2; - } - if (!listAdapters().includes(values.emitter)) { log.error(`Unknown emitter '${values.emitter}'. Available: ${listAdapters().join(", ")}`); return 2; @@ -105,12 +149,8 @@ async function main(): Promise { // Repo root = current git working tree. const repoRoot = (await runChecked("git", ["rev-parse", "--show-toplevel"])).stdout.trim(); - // Absolutize the work dir. Adapters may run emitter scripts with a different - // cwd (python's regenerate.ts runs in packages/http-client-python), so every - // path handed to them β€” the resolved emitter dir and the baseline/head output - // dirs β€” must be absolute or outputs land in the wrong tree and the diff is - // silently empty (a false "no differences"). - const workDir = ensureDir(values["work-dir"] ? resolve(values["work-dir"]) : defaultWorkDir()); + // Use an absolute work dir because adapters may run from a different cwd. + const workDir = ensureDir(defaultWorkDir()); log.info(`${color.dim("work dir:")} ${workDir}`); const ctx: AdapterContext = { @@ -132,19 +172,12 @@ async function main(): Promise { options[entry.slice(0, eq)] = entry.slice(eq + 1); } - // Classify the specs ref up front (if any) so an invalid --specs fails fast, - // before the expensive emitter builds. `all`/omitted => adapter default. - let specsRef: ClassifiedRef | undefined; - if (values.specs && values.specs.toLowerCase() !== "all") { - specsRef = classifyRef(values.specs, repoRoot); - if (specsRef.kind === "npm") { - log.error("--specs as an npm version is not supported; use a local folder or github ref."); - return 2; - } - } - // Resolve emitters. - const baselineRef = classifyRef(values.baseline, repoRoot); + const baselineRefValue = values.baseline ?? (await resolveDefaultBaselineRef(repoRoot)); + if (!values.baseline) { + log.info(`${color.dim("baseline default:")} ${baselineRefValue}`); + } + const baselineRef = classifyRef(baselineRefValue, repoRoot); const headRef: ClassifiedRef | "current" = values.head ? classifyRef(values.head, repoRoot) : "current"; @@ -154,25 +187,72 @@ async function main(): Promise { log.step("Preparing head emitter"); const headEmitter = await adapter.prepareEmitter(headRef, ctx); - // Materialize the specs source now that emitters are ready. - let specsDir: string | undefined; - if (specsRef) { - specsDir = await resolveSrc(specsRef, workDir, log, repoRoot); - } - - // Generate both sides. By default baseline and head generate concurrently - // (their outputs, virtual envs, and temp YAML are isolated), roughly halving wall - // time at the cost of doubled peak CPU/memory and interleaved logs β€” so each - // side's output is tagged with a prefix. Use --sequential to generate one at - // a time (quieter logs, lower peak resource use). + // Baseline/head generate in parallel by default. const baselineOut = ensureDir(join(workDir, "baseline")); const headOut = ensureDir(join(workDir, "head")); - const parallel = !values.sequential; + const parallel = true; + const cacheDecision = shouldUseBaselineCache(Boolean(values.ci)); + const useBaselineCache = cacheDecision.enabled; + if (!useBaselineCache) { + log.info( + color.dim( + `baseline cache disabled${cacheDecision.reason ? ` (${cacheDecision.reason})` : ""}`, + ), + ); + } + const baselineIdentity = await detectBaselineIdentity(baselineEmitter.dir); + const baselineProfileKey = computeBaselineProfileKey({ + emitter: values.emitter, + baselineRef: baselineRefValue, + generatedCodePath: values["generated-code-path"], + nameFilter: values.name, + options, + passthrough, + }); + const baselineCache = baselineCachePaths(baselineProfileKey); + + const persistBaselineIndex = (index: BaselineCacheIndex): void => { + try { + writeBaselineCacheIndex(index); + } catch { + // Best effort cache cleanup. + } + }; + + let baselineReused = false; + if (useBaselineCache) { + try { + const index = readBaselineCacheIndex(); + const entry = index[baselineProfileKey]; + if (entry && entry.baselineIdentity === baselineIdentity) { + if ( + !isSafeBaselineCachePath(baselineCache.dir) || + !isSafeBaselineCachePath(baselineCache.marker) + ) { + log.warn("Ignoring unsafe baseline cache path; regenerating baseline."); + delete index[baselineProfileKey]; + persistBaselineIndex(index); + } else if (existsSync(baselineCache.marker) && existsSync(baselineCache.dir)) { + log.step("Reusing cached baseline output"); + rmSync(baselineOut, { recursive: true, force: true }); + cpSync(baselineCache.dir, baselineOut, { recursive: true, force: true }); + baselineReused = true; + } else { + log.info(color.dim("Baseline cache not found; regenerating baseline.")); + delete index[baselineProfileKey]; + persistBaselineIndex(index); + } + } + } catch (err) { + log.warn(`Could not read baseline cache index; regenerating baseline. ${String(err)}`); + } + } + const baselineReq = { emitter: baselineEmitter, - specsDir, outputDir: baselineOut, + generatedCodePath: values["generated-code-path"], nameFilter: values.name, options, passthrough, @@ -180,24 +260,50 @@ async function main(): Promise { }; const headReq = { emitter: headEmitter, - specsDir, outputDir: headOut, + generatedCodePath: values["generated-code-path"], nameFilter: values.name, options, passthrough, logPrefix: parallel ? color.cyan("[head] ") : undefined, }; - if (parallel) { + if (baselineReused) { + log.step("Generating head (baseline reused)"); + await adapter.generate(headReq, ctx); + } else { log.step("Generating baseline + head in parallel"); await Promise.all([adapter.generate(baselineReq, ctx), adapter.generate(headReq, ctx)]); - } else { - await adapter.generate(baselineReq, ctx); - await adapter.generate(headReq, ctx); } - // Point at the generated trees the diff compares, so a local run can open the - // head output directly. Head is the current checkout unless --head overrode it. + if (useBaselineCache && !baselineReused) { + try { + if ( + !isSafeBaselineCachePath(baselineCache.dir) || + !isSafeBaselineCachePath(baselineCache.marker) + ) { + throw new Error("unsafe cache path"); + } + + rmSync(baselineCache.dir, { recursive: true, force: true }); + cpSync(baselineOut, baselineCache.dir, { recursive: true, force: true }); + writeFileSync( + baselineCache.marker, + `${new Date().toISOString()} ${baselineIdentity}\n`, + "utf8", + ); + const index = readBaselineCacheIndex(); + index[baselineProfileKey] = { + baselineIdentity, + updatedAt: new Date().toISOString(), + }; + writeBaselineCacheIndex(index); + } catch (err) { + log.warn(`Could not update baseline cache. ${String(err)}`); + } + } + + // Log output roots used by the diff. log.info( `${color.dim("baseline output:")} ${baselineOut} ${color.dim(`(${baselineEmitter.label})`)}`, ); @@ -206,22 +312,15 @@ async function main(): Promise { // Diff. const diff = await diffDirs(baselineOut, headOut, log); - // Decide how to present the diff. Explicit flags win; otherwise the default - // is a clickable HTML report written to the work dir. - const wantsTerminal = Boolean(values.terminal); - const wantsPatch = Boolean(values.patch); - const htmlTarget = - values.html ?? (!wantsTerminal && !wantsPatch ? join(workDir, "emitter-diff.html") : undefined); + // Default to a clickable HTML report in the work dir unless --html is set. + const htmlTarget = values.html ?? join(workDir, "emitter-diff.html"); if (!diff.hasChanges) { log.success("No differences between baseline and head output."); - } else if (wantsTerminal) { - printDiff(diff, log); } else { printSummary(diff, log); } - if (wantsPatch) writePatch(diff, values.patch as string, log); if (htmlTarget) writeHtml(diff, htmlTarget, log); if (values["fail-on-diff"] && diff.hasChanges) { diff --git a/eng/emitter-diff/src/resolver.ts b/eng/emitter-diff/src/resolver.ts index edde8d1aa9d..3ddb540db33 100644 --- a/eng/emitter-diff/src/resolver.ts +++ b/eng/emitter-diff/src/resolver.ts @@ -6,12 +6,12 @@ * source checkout into a usable emitter is intentionally NOT done here β€” that * is language-specific and belongs to the adapter's `prepareEmitter`. */ -import { existsSync, mkdtempSync } from "node:fs"; +import { existsSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs"; import { tmpdir } from "node:os"; import { isAbsolute, join, resolve } from "node:path"; import type { ClassifiedRef, Logger } from "./types.ts"; -import { ensureDir, run, runChecked } from "./util.ts"; +import { ensureDir, runChecked } from "./util.ts"; /** * Classify a ref string. Explicit prefixes (`npm:`, `local:`, `github:`, @@ -34,7 +34,7 @@ export function classifyRef(raw: string, repoRoot: string): ClassifiedRef { return parseGithub(trimmed.slice(7), raw); } if (trimmed.startsWith("gh:")) { - // gh: => current repo at + // gh: => microsoft/typespec at return { kind: "github", raw, gitRef: trimmed.slice(3) }; } if (/^https?:\/\/github\.com\//i.test(trimmed)) { @@ -132,46 +132,91 @@ async function cloneGithub( ref: ClassifiedRef, workDir: string, log: Logger, - repoRoot?: string, + _repoRoot?: string, ): Promise { - // `gh:` (and any github ref without an explicit repo) means "this repo". - // Detect the current repo from its origin remote so forks/renames resolve - // correctly, falling back to the well-known repo only if detection fails. - const repo = - ref.repo ?? (repoRoot ? await detectOriginRepo(repoRoot) : undefined) ?? DEFAULT_REPO; + // `gh:` (and any github ref without an explicit repo) maps to + // microsoft/typespec explicitly. + const repo = ref.repo ?? DEFAULT_REPO; const gitRef = ref.gitRef ?? "main"; assertSafeRepo(repo); assertSafeGitRef(gitRef); + + // Prefer cached detached worktrees; fall back to a clone on failure. + try { + return await checkoutCachedWorktree(repo, gitRef, log); + } catch (err) { + log.warn( + `Could not use cached worktree for ${repo}@${gitRef}; falling back to a clone. ` + + String(err), + ); + } + const dest = ensureDir(join(workDir, `github-${repo.replace(/[/]/g, "_")}-${sanitize(gitRef)}`)); const cloneUrl = `https://github.com/${repo}.git`; log.step(`Fetching ${repo}@${gitRef}`); - // Shallow-clone then fetch the exact ref so both branches and SHAs work. + // Shallow-init and fetch the requested ref. await runChecked("git", ["init", "-q"], { cwd: dest }); await runChecked("git", ["remote", "add", "origin", cloneUrl], { cwd: dest }).catch(() => {}); const fetched = await runChecked("git", ["fetch", "--depth", "1", "origin", gitRef], { cwd: dest, }).catch(() => undefined); if (fetched) { - // The targeted fetch put the requested ref at FETCH_HEAD. + // Targeted fetch resolves to FETCH_HEAD. await runChecked("git", ["checkout", "-q", "FETCH_HEAD"], { cwd: dest }); } else { - // Some servers won't fetch a bare SHA directly; do a full fetch and then - // check the ref out by name (NOT FETCH_HEAD, which after a full fetch with - // no refspec may point at a branch head rather than the requested commit). - // `--end-of-options` stops git from treating the ref as a flag. + // Some servers reject bare SHA fetches; full-fetch and checkout by ref name. + // `--end-of-options` prevents treating the ref as a flag. await runChecked("git", ["fetch", "origin"], { cwd: dest }); await runChecked("git", ["checkout", "-q", "--end-of-options", gitRef], { cwd: dest }); } return dest; } -/** Parse `owner/repo` from the current checkout's origin remote, if it is a GitHub remote. */ -async function detectOriginRepo(repoRoot: string): Promise { - const res = await run("git", ["-C", repoRoot, "remote", "get-url", "origin"]); - if (res.code !== 0) return undefined; - const m = res.stdout.trim().match(/github\.com[:/]([^/]+)\/(.+?)(?:\.git)?$/i); - return m ? `${m[1]}/${m[2]}` : undefined; +async function checkoutCachedWorktree(repo: string, gitRef: string, log: Logger): Promise { + // Keep worktree cache isolated from the caller's git metadata. + const cacheRepo = await ensureCacheRepo(repo, log); + const sha = await fetchAndResolveCommit(cacheRepo, gitRef); + + const cacheRoot = ensureDir(join(tmpdir(), "emitter-diff-cache", "worktrees", repoPathKey(repo))); + const dest = join(cacheRoot, sha); + + if (existsSync(join(dest, ".git"))) { + log.info(`Reusing cached worktree ${repo}@${sha}`); + return dest; + } + + ensureDir(cacheRoot); + log.step(`Creating cached worktree ${repo}@${sha}`); + await runChecked("git", ["worktree", "add", "--detach", dest, sha], { cwd: cacheRepo }); + return dest; +} + +async function ensureCacheRepo(repo: string, _log: Logger): Promise { + const repoRoot = ensureDir(join(tmpdir(), "emitter-diff-cache", "repos", repoPathKey(repo))); + const gitDir = join(repoRoot, ".git"); + const cloneUrl = `https://github.com/${repo}.git`; + + if (!existsSync(gitDir)) { + await runChecked("git", ["init", "-q"], { cwd: repoRoot }); + } + + // Ensure remote points at the expected repo, without failing if it already exists. + await runChecked("git", ["remote", "add", "origin", cloneUrl], { cwd: repoRoot }).catch(() => {}); + await runChecked("git", ["remote", "set-url", "origin", cloneUrl], { cwd: repoRoot }); + return repoRoot; +} + +async function fetchAndResolveCommit(cacheRepo: string, gitRef: string): Promise { + // Resolve an immutable commit SHA from FETCH_HEAD. + await runChecked("git", ["fetch", "--depth", "1", "origin", gitRef], { cwd: cacheRepo }); + const sha = ( + await runChecked("git", ["rev-parse", "--verify", "FETCH_HEAD"], { cwd: cacheRepo }) + ).stdout.trim(); + if (!sha) { + throw new Error(`Could not resolve git ref '${gitRef}' from FETCH_HEAD.`); + } + return sha; } /** @@ -187,12 +232,26 @@ export async function installNpmPackage( const dir = ensureDir( join(workDir, `npm-${packageName.replace(/[@/]/g, "_")}-${sanitize(version)}`), ); + const pkgDir = join(dir, "node_modules", packageName); + if (existsSync(pkgDir)) { + assertInstalledPackageMetadata(pkgDir, packageName, version); + log.info(`Reusing installed ${packageName}@${version}`); + return pkgDir; + } + log.step(`Installing ${packageName}@${version}`); - // Create a throwaway package root and install just the one package there. - // `--ignore-scripts` blocks lifecycle scripts from the downloaded package: the - // emitter ships a prebuilt `dist`, and per-version setup (venv/build) is done - // explicitly by the adapter, so no install hooks are needed here. - await runChecked("npm", ["init", "-y"], { cwd: dir }); + // Create a deterministic throwaway package root and install just one + // dependency there. + const manifest = join(dir, "package.json"); + if (!existsSync(manifest)) { + writeFileSync( + manifest, + `${JSON.stringify({ name: "emitter-diff-cache", private: true, version: "0.0.0" }, null, 2)}\n`, + "utf8", + ); + } + + // Install only the requested package and skip lifecycle scripts. await runChecked( "npm", [ @@ -205,17 +264,43 @@ export async function installNpmPackage( ], { cwd: dir }, ); - const pkgDir = join(dir, "node_modules", packageName); - if (!existsSync(pkgDir)) { - throw new Error(`Installed ${packageName}@${version} but ${pkgDir} not found`); - } + assertInstalledPackageMetadata(pkgDir, packageName, version); return pkgDir; } +function assertInstalledPackageMetadata( + pkgDir: string, + expectedName: string, + expectedVersion: string, +): void { + const manifest = join(pkgDir, "package.json"); + if (!existsSync(manifest)) { + throw new Error(`Installed package manifest not found: ${manifest}`); + } + + let parsed: { name?: string; version?: string }; + try { + parsed = JSON.parse(readFileSync(manifest, "utf8")) as { name?: string; version?: string }; + } catch (err) { + throw new Error(`Could not parse installed package manifest at ${manifest}: ${String(err)}`); + } + + if (parsed.name !== expectedName || parsed.version !== expectedVersion) { + throw new Error( + `Installed package metadata mismatch at ${manifest}. ` + + `Expected ${expectedName}@${expectedVersion}, got ${parsed.name ?? ""}@${parsed.version ?? ""}.`, + ); + } +} + function sanitize(s: string): string { return s.replace(/[^a-z0-9._-]/gi, "-").slice(0, 40); } +function repoPathKey(repo: string): string { + return repo.replace(/[^a-z0-9._-]/gi, "-").toLowerCase(); +} + /** Create a fresh scratch dir under the OS temp dir when `--work-dir` is omitted. */ export function defaultWorkDir(): string { return mkdtempSync(join(tmpdir(), "emitter-diff-")); diff --git a/eng/emitter-diff/src/types.ts b/eng/emitter-diff/src/types.ts index b0140afab7c..fd2a95fcabc 100644 --- a/eng/emitter-diff/src/types.ts +++ b/eng/emitter-diff/src/types.ts @@ -1,10 +1,6 @@ /** - * Core, language-agnostic types for the emitter-diff tool. - * - * The orchestrator, ref resolver and diff engine depend only on the generic - * {@link EmitterAdapter} contract defined here. Nothing in this file (or in the - * core) knows anything about a specific language's tooling β€” all language - * details live behind an adapter. + * Core language-agnostic types for emitter-diff. + * Language-specific behavior stays behind {@link EmitterAdapter}. */ /** The three kinds of source a ref can point at. */ @@ -16,7 +12,7 @@ export type RefKind = "npm" | "local" | "github"; * Accepted user syntaxes (see {@link classifyRef}): * - npm: `npm:1.2.3`, `1.2.3`, `@scope/pkg@1.2.3` * - local: `local:/abs/or/rel/path`, or any existing filesystem path - * - github: `github:owner/repo@`, `gh:` (this repo), or an `https://github.com/...` url + * - github: `github:owner/repo@`, `gh:` (microsoft/typespec), or an `https://github.com/...` url */ export interface ClassifiedRef { kind: RefKind; @@ -26,13 +22,13 @@ export interface ClassifiedRef { version?: string; /** local: the absolute path on disk. */ path?: string; - /** github: `owner/repo` (defaults to the current repo when omitted). */ + /** github: `owner/repo` (defaults to `microsoft/typespec` when omitted). */ repo?: string; /** github: branch, tag or sha. */ gitRef?: string; } -/** A built/usable emitter, ready to be pointed at by the adapter's generate step. */ +/** A usable emitter prepared by an adapter. */ export interface ResolvedEmitter { /** Directory containing the usable emitter build. */ dir: string; @@ -61,20 +57,18 @@ export interface AdapterContext { export interface GenerateRequest { /** Resolved emitter build to generate with. */ emitter: ResolvedEmitter; - /** Resolved specs directory, or undefined to use the adapter's repo default. */ - specsDir?: string; /** Directory the generated code must be written to. */ outputDir: string; + /** Optional adapter generated-code subpath under `outputDir`. */ + generatedCodePath?: string; /** Optional name/pattern filter limiting which specs/packages are generated. */ nameFilter?: string; /** Adapter-specific options collected from repeatable `--opt key=value`. */ options: Record; - /** Everything after a `--` on the command line, forwarded verbatim. */ + /** Arguments after `--`, forwarded verbatim. */ passthrough: string[]; /** - * Optional prefix to tag each line of this generation's output with. Set when - * baseline and head generate concurrently so their interleaved logs stay - * attributable; when unset, output streams straight to the terminal. + * Optional log prefix used when baseline/head generate concurrently. */ logPrefix?: string; } diff --git a/packages/http-client-python/eng/scripts/ci/regenerate.ts b/packages/http-client-python/eng/scripts/ci/regenerate.ts index 9fdc12b8b52..adee33ea97b 100644 --- a/packages/http-client-python/eng/scripts/ci/regenerate.ts +++ b/packages/http-client-python/eng/scripts/ci/regenerate.ts @@ -40,9 +40,6 @@ const argv = parseArgs({ pluginDir: { type: "string" }, emitterName: { type: "string" }, generatedFolder: { type: "string" }, - httpSpecsDir: { type: "string" }, - azureSpecsDir: { type: "string" }, - "no-baseline": { type: "boolean" }, jobs: { type: "string", short: "j" }, help: { type: "boolean", short: "h" }, }, @@ -73,15 +70,6 @@ ${pc.bold("Options:")} ${pc.cyan("-j, --jobs ")} Number of parallel compilation tasks (default: 30 on Linux/Mac, 10 on Windows). - ${pc.cyan("--httpSpecsDir ")} - Override the @typespec/http-specs specs directory (used by emitter-diff). - - ${pc.cyan("--azureSpecsDir ")} - Override the @azure-tools/azure-http-specs specs directory (used by emitter-diff). - - ${pc.cyan("--no-baseline")} - Skip cloning the published-package baseline tree (used by emitter-diff). - ${pc.cyan("-h, --help")} Show this help message. @@ -106,19 +94,39 @@ const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url)); const PLUGIN_DIR = argv.values.pluginDir ? resolve(argv.values.pluginDir) : resolve(SCRIPT_DIR, "../../../"); -const AZURE_HTTP_SPECS = argv.values.azureSpecsDir - ? resolve(argv.values.azureSpecsDir) - : resolve(PLUGIN_DIR, "node_modules/@azure-tools/azure-http-specs/specs"); -const HTTP_SPECS = argv.values.httpSpecsDir - ? resolve(argv.values.httpSpecsDir) - : resolve(PLUGIN_DIR, "node_modules/@typespec/http-specs/specs"); + +function resolveSpecsDir(packageName: string, envOverride?: string): string { + const fromEnv = envOverride?.trim(); + if (fromEnv) { + const candidate = resolve(fromEnv); + if (existsSync(candidate)) return candidate; + } + + // Prefer specs from the selected plugin dir (baseline/head emitter), then + // fall back to the current checkout package and repo-root installs. + const candidates = [ + resolve(PLUGIN_DIR, `node_modules/${packageName}/specs`), + resolve(SCRIPT_DIR, `../../../node_modules/${packageName}/specs`), + resolve(SCRIPT_DIR, `../../../../node_modules/${packageName}/specs`), + resolve(SCRIPT_DIR, `../../../../../node_modules/${packageName}/specs`), + ]; + + for (const candidate of candidates) { + if (existsSync(candidate)) return candidate; + } + + // Keep the preferred plugin-dir location for diagnostics. + return candidates[0]; +} + +const AZURE_HTTP_SPECS = resolveSpecsDir( + "@azure-tools/azure-http-specs", + process.env.AZURE_HTTP_SPECS_DIR, +); +const HTTP_SPECS = resolveSpecsDir("@typespec/http-specs", process.env.HTTP_SPECS_DIR); const GENERATED_FOLDER = argv.values.generatedFolder ? resolve(argv.values.generatedFolder) : resolve(PLUGIN_DIR, "generator"); -// Directory that contains `tests/generated//`. Defaults to PLUGIN_DIR (since the -// default GENERATED_FOLDER is PLUGIN_DIR/generator), but tracks a custom --generatedFolder so -// the batch Python phase reads the same output tree the TypeScript phase wrote to. -const GENERATED_PARENT = resolve(GENERATED_FOLDER, ".."); const EMITTER_NAME = argv.values.emitterName || "@typespec/http-client-python"; const ctx: RegenerateContext = { @@ -151,7 +159,12 @@ async function collectConfigFiles(generatedDir: string, flavor: string): Promise return configFiles; } -function runBatchPythonProcessing(flavor: string, configCount: number, jobs: number): boolean { +function runBatchPythonProcessing( + flavor: string, + generatedFolder: string, + configCount: number, + jobs: number, +): boolean { if (configCount === 0) return true; console.log(pc.cyan(`\nRunning batch Python processing on ${configCount} specs...`)); @@ -170,9 +183,10 @@ function runBatchPythonProcessing(flavor: string, configCount: number, jobs: num const batchScript = join(PLUGIN_DIR, "eng", "scripts", "setup", "run_batch.py"); try { + const generatedRoot = resolve(generatedFolder, ".."); // Pass directory and flavor instead of individual config files to avoid command line length limits on Windows execSync( - `"${venvPath}" "${batchScript}" --generated-dir "${GENERATED_PARENT}" --flavor ${flavor} --jobs ${jobs}`, + `"${venvPath}" "${batchScript}" --generated-dir "${generatedRoot}" --flavor ${flavor} --jobs ${jobs}`, { stdio: "inherit", cwd: PLUGIN_DIR, @@ -200,8 +214,18 @@ async function regenerateFlavor( await preprocess(flavor, GENERATED_FOLDER); // Collect specs - const azureSpecs = flavor === "azure" ? await getSubdirectories(AZURE_HTTP_SPECS, flags) : []; - const standardSpecs = await getSubdirectories(HTTP_SPECS, flags); + const azureSpecs = + flavor === "azure" && existsSync(AZURE_HTTP_SPECS) + ? await getSubdirectories(AZURE_HTTP_SPECS, flags) + : []; + if (flavor === "azure" && !existsSync(AZURE_HTTP_SPECS)) { + console.warn(pc.yellow(`Azure specs not found at: ${AZURE_HTTP_SPECS}`)); + } + + const standardSpecs = existsSync(HTTP_SPECS) ? await getSubdirectories(HTTP_SPECS, flags) : []; + if (!existsSync(HTTP_SPECS)) { + console.warn(pc.yellow(`HTTP specs not found at: ${HTTP_SPECS}`)); + } const allSpecs = [...azureSpecs, ...standardSpecs]; // Build task groups (tasks for same spec run sequentially to avoid state pollution). @@ -237,7 +261,7 @@ async function regenerateFlavor( const configCount = (await collectConfigFiles(GENERATED_FOLDER, flavor)).length; // Use fewer Python jobs since Python processing is heavier const pyJobs = Math.max(4, jobs); - const pySuccess = runBatchPythonProcessing(flavor, configCount, pyJobs); + const pySuccess = runBatchPythonProcessing(flavor, GENERATED_FOLDER, configCount, pyJobs); const pyTime = (performance.now() - pyStartTime) / 1000; const totalTime = (performance.now() - startTime) / 1000; @@ -276,11 +300,7 @@ async function main() { const startTime = performance.now(); let success: boolean; - // `--no-baseline` skips cloning the published-package baseline tree; the - // emitter-diff tool generates each side fresh, so the baseline clone is noise. - if (!argv.values["no-baseline"]) { - await prepareBaselineOfGeneratedCode(GENERATED_FOLDER); - } + await prepareBaselineOfGeneratedCode(GENERATED_FOLDER); if (flavor) { success = await regenerateFlavor(flavor, name, debug, jobs); diff --git a/packages/http-client-python/package.json b/packages/http-client-python/package.json index 74cc71d9eab..b80fb2796cf 100644 --- a/packages/http-client-python/package.json +++ b/packages/http-client-python/package.json @@ -54,7 +54,8 @@ "ci:generated": "tsx ./eng/scripts/ci/run-tests.ts --generator --env=ci", "change:version": "pnpm chronus version --ignore-policies --only @typespec/http-client-python", "change:add": "pnpm chronus add", - "regen-docs": "node ../../packages/tspd/cmd/tspd.js doc . --enable-experimental --output-dir ../../website/src/content/docs/docs/emitters/clients/http-client-python/reference --skip-js" + "regen-docs": "node ../../packages/tspd/cmd/tspd.js doc . --enable-experimental --output-dir ../../website/src/content/docs/docs/emitters/clients/http-client-python/reference --skip-js", + "diff-spector-tests": "node ../../eng/emitter-diff/src/cli.ts --emitter python" }, "files": [ "dist/**", From 88fff4fd548dbae4bc96467bec2a3092f932c7d6 Mon Sep 17 00:00:00 2001 From: Libba Lawrence Date: Thu, 2 Jul 2026 15:44:14 -0700 Subject: [PATCH 24/52] Revert spec-dir resolution in regenerate.ts; keep only generatedFolder fix Spec versions rarely change, so pinning specs across baseline/head is unnecessary. Revert resolveSpecsDir + spec existence warnings back to main (hardcoded PLUGIN_DIR node_modules specs). Keep the batch-Python change so run_batch.py honors --generatedFolder, which the emitter-diff tool relies on to isolate baseline/head output trees. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- eng/emitter-diff/src/adapters/python.ts | 7 +-- .../eng/scripts/ci/regenerate.ts | 46 ++----------------- 2 files changed, 8 insertions(+), 45 deletions(-) diff --git a/eng/emitter-diff/src/adapters/python.ts b/eng/emitter-diff/src/adapters/python.ts index d97c084ae00..9f8c80c630e 100644 --- a/eng/emitter-diff/src/adapters/python.ts +++ b/eng/emitter-diff/src/adapters/python.ts @@ -8,9 +8,10 @@ * build can target any output dir). * * The regenerate *driver* always comes from the current checkout; only the - * `--pluginDir` it points at changes between baseline and head. Specs are also - * pinned to the current checkout so the diff isolates emitter behavior rather - * than driver/spec differences. + * `--pluginDir` it points at changes between baseline and head. Each emitter + * build resolves its own specs from its `node_modules`; spec versions rarely + * change, so any spec drift between baseline/head is treated as acceptable + * noise rather than pinned. */ import { existsSync } from "node:fs"; import { join } from "node:path"; diff --git a/packages/http-client-python/eng/scripts/ci/regenerate.ts b/packages/http-client-python/eng/scripts/ci/regenerate.ts index adee33ea97b..e4dc7d5910a 100644 --- a/packages/http-client-python/eng/scripts/ci/regenerate.ts +++ b/packages/http-client-python/eng/scripts/ci/regenerate.ts @@ -94,36 +94,8 @@ const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url)); const PLUGIN_DIR = argv.values.pluginDir ? resolve(argv.values.pluginDir) : resolve(SCRIPT_DIR, "../../../"); - -function resolveSpecsDir(packageName: string, envOverride?: string): string { - const fromEnv = envOverride?.trim(); - if (fromEnv) { - const candidate = resolve(fromEnv); - if (existsSync(candidate)) return candidate; - } - - // Prefer specs from the selected plugin dir (baseline/head emitter), then - // fall back to the current checkout package and repo-root installs. - const candidates = [ - resolve(PLUGIN_DIR, `node_modules/${packageName}/specs`), - resolve(SCRIPT_DIR, `../../../node_modules/${packageName}/specs`), - resolve(SCRIPT_DIR, `../../../../node_modules/${packageName}/specs`), - resolve(SCRIPT_DIR, `../../../../../node_modules/${packageName}/specs`), - ]; - - for (const candidate of candidates) { - if (existsSync(candidate)) return candidate; - } - - // Keep the preferred plugin-dir location for diagnostics. - return candidates[0]; -} - -const AZURE_HTTP_SPECS = resolveSpecsDir( - "@azure-tools/azure-http-specs", - process.env.AZURE_HTTP_SPECS_DIR, -); -const HTTP_SPECS = resolveSpecsDir("@typespec/http-specs", process.env.HTTP_SPECS_DIR); +const AZURE_HTTP_SPECS = resolve(PLUGIN_DIR, "node_modules/@azure-tools/azure-http-specs/specs"); +const HTTP_SPECS = resolve(PLUGIN_DIR, "node_modules/@typespec/http-specs/specs"); const GENERATED_FOLDER = argv.values.generatedFolder ? resolve(argv.values.generatedFolder) : resolve(PLUGIN_DIR, "generator"); @@ -214,18 +186,8 @@ async function regenerateFlavor( await preprocess(flavor, GENERATED_FOLDER); // Collect specs - const azureSpecs = - flavor === "azure" && existsSync(AZURE_HTTP_SPECS) - ? await getSubdirectories(AZURE_HTTP_SPECS, flags) - : []; - if (flavor === "azure" && !existsSync(AZURE_HTTP_SPECS)) { - console.warn(pc.yellow(`Azure specs not found at: ${AZURE_HTTP_SPECS}`)); - } - - const standardSpecs = existsSync(HTTP_SPECS) ? await getSubdirectories(HTTP_SPECS, flags) : []; - if (!existsSync(HTTP_SPECS)) { - console.warn(pc.yellow(`HTTP specs not found at: ${HTTP_SPECS}`)); - } + const azureSpecs = flavor === "azure" ? await getSubdirectories(AZURE_HTTP_SPECS, flags) : []; + const standardSpecs = await getSubdirectories(HTTP_SPECS, flags); const allSpecs = [...azureSpecs, ...standardSpecs]; // Build task groups (tasks for same spec run sequentially to avoid state pollution). From 05e1bea1918aa5f872e166538bbafa8e280b4347 Mon Sep 17 00:00:00 2001 From: Libba Lawrence Date: Thu, 2 Jul 2026 16:16:14 -0700 Subject: [PATCH 25/52] keep path diff for now --- eng/emitter-diff/README.md | 5 ++- eng/emitter-diff/src/adapters/python.ts | 7 ++- .../eng/scripts/ci/regenerate.ts | 44 +++++++++++++++++-- 3 files changed, 48 insertions(+), 8 deletions(-) diff --git a/eng/emitter-diff/README.md b/eng/emitter-diff/README.md index c8582bb5dcb..368e8bf4cab 100644 --- a/eng/emitter-diff/README.md +++ b/eng/emitter-diff/README.md @@ -58,6 +58,7 @@ prints a `file://` link to it. Use `--html` to write to a specific file. - `--name `: Filter which specs/packages are generated. - `--html `: Write the rendered HTML report to this path (default: `/emitter-diff.html`). - `--generated-code-path `: Override the adapter generated-code subpath under each side output root. + For Python, generated files land under `//tests/generated/...`. - `--fail-on-diff`: Exit non-zero when output differs (CI gating). ### Examples @@ -71,8 +72,8 @@ node eng/emitter-diff/src/cli.ts --emitter python --baseline local:/path/to/old/ --head local:/path/to/new/http-client-python \ --html diff.html -# Override the adapter generated-code subpath under each side output root: -node eng/emitter-diff/src/cli.ts --emitter python --generated-code-path tests/generated +# Place generated output under `libba` for each side (`/libba/tests/generated/...`): +node eng/emitter-diff/src/cli.ts --emitter python --generated-code-path libba # Diff against a GitHub sha: node eng/emitter-diff/src/cli.ts --emitter python \ diff --git a/eng/emitter-diff/src/adapters/python.ts b/eng/emitter-diff/src/adapters/python.ts index 9f8c80c630e..7d5546b9b51 100644 --- a/eng/emitter-diff/src/adapters/python.ts +++ b/eng/emitter-diff/src/adapters/python.ts @@ -131,8 +131,11 @@ export const pythonAdapter: EmitterAdapter = { }, async generate(request: GenerateRequest, ctx: AdapterContext): Promise { - // Regenerate writes under /../tests/generated/... - const generatedFolder = join(request.outputDir, request.generatedCodePath ?? "generator"); + // Regenerate writes under /../tests/generated/... . + // Anchor generatedFolder at //generator so final output lands under + // //tests/generated when a subpath override is provided. + const generatedSubpath = request.generatedCodePath ?? ""; + const generatedFolder = join(request.outputDir, generatedSubpath, "generator"); const args = ["--pluginDir", request.emitter.dir, "--generatedFolder", generatedFolder]; const flavor = request.options.flavor; diff --git a/packages/http-client-python/eng/scripts/ci/regenerate.ts b/packages/http-client-python/eng/scripts/ci/regenerate.ts index e4dc7d5910a..17df6e00e2c 100644 --- a/packages/http-client-python/eng/scripts/ci/regenerate.ts +++ b/packages/http-client-python/eng/scripts/ci/regenerate.ts @@ -94,8 +94,34 @@ const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url)); const PLUGIN_DIR = argv.values.pluginDir ? resolve(argv.values.pluginDir) : resolve(SCRIPT_DIR, "../../../"); -const AZURE_HTTP_SPECS = resolve(PLUGIN_DIR, "node_modules/@azure-tools/azure-http-specs/specs"); -const HTTP_SPECS = resolve(PLUGIN_DIR, "node_modules/@typespec/http-specs/specs"); + +function resolveSpecsDir(packageName: string, envOverride?: string): string { + const fromEnv = envOverride?.trim(); + if (fromEnv) { + const candidate = resolve(fromEnv); + if (existsSync(candidate)) return candidate; + } + + const candidates = [ + resolve(PLUGIN_DIR, `node_modules/${packageName}/specs`), + resolve(SCRIPT_DIR, `../../../node_modules/${packageName}/specs`), + resolve(SCRIPT_DIR, `../../../../node_modules/${packageName}/specs`), + resolve(SCRIPT_DIR, `../../../../../node_modules/${packageName}/specs`), + ]; + + for (const candidate of candidates) { + if (existsSync(candidate)) return candidate; + } + + // Keep the preferred plugin-dir location for diagnostics. + return candidates[0]; +} + +const AZURE_HTTP_SPECS = resolveSpecsDir( + "@azure-tools/azure-http-specs", + process.env.AZURE_HTTP_SPECS_DIR, +); +const HTTP_SPECS = resolveSpecsDir("@typespec/http-specs", process.env.HTTP_SPECS_DIR); const GENERATED_FOLDER = argv.values.generatedFolder ? resolve(argv.values.generatedFolder) : resolve(PLUGIN_DIR, "generator"); @@ -186,8 +212,18 @@ async function regenerateFlavor( await preprocess(flavor, GENERATED_FOLDER); // Collect specs - const azureSpecs = flavor === "azure" ? await getSubdirectories(AZURE_HTTP_SPECS, flags) : []; - const standardSpecs = await getSubdirectories(HTTP_SPECS, flags); + const azureSpecs = + flavor === "azure" && existsSync(AZURE_HTTP_SPECS) + ? await getSubdirectories(AZURE_HTTP_SPECS, flags) + : []; + if (flavor === "azure" && !existsSync(AZURE_HTTP_SPECS)) { + console.warn(pc.yellow(`Azure specs not found at: ${AZURE_HTTP_SPECS}`)); + } + + const standardSpecs = existsSync(HTTP_SPECS) ? await getSubdirectories(HTTP_SPECS, flags) : []; + if (!existsSync(HTTP_SPECS)) { + console.warn(pc.yellow(`HTTP specs not found at: ${HTTP_SPECS}`)); + } const allSpecs = [...azureSpecs, ...standardSpecs]; // Build task groups (tasks for same spec run sequentially to avoid state pollution). From 9925d6531a139cf050db4600c1d9eba7f72e6f02 Mon Sep 17 00:00:00 2001 From: Libba Lawrence Date: Thu, 2 Jul 2026 17:07:08 -0700 Subject: [PATCH 26/52] Fix emitter-diff CI: lint cause, spelling, changeset - resolver.ts: attach `cause` to re-thrown manifest parse error (oxlint preserve-caught-error) - README: replace nonsense `libba` placeholder with a real example - cspell: allow `Menlo` (font name in the HTML report CSS) - add chronus changeset for @typespec/http-client-python Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- .chronus/changes/emitter-diff-tool-2026-7-2-0-0-0.md | 7 +++++++ cspell.yaml | 1 + eng/emitter-diff/README.md | 4 ++-- eng/emitter-diff/src/resolver.ts | 4 +++- 4 files changed, 13 insertions(+), 3 deletions(-) create mode 100644 .chronus/changes/emitter-diff-tool-2026-7-2-0-0-0.md diff --git a/.chronus/changes/emitter-diff-tool-2026-7-2-0-0-0.md b/.chronus/changes/emitter-diff-tool-2026-7-2-0-0-0.md new file mode 100644 index 00000000000..f98df1379c4 --- /dev/null +++ b/.chronus/changes/emitter-diff-tool-2026-7-2-0-0-0.md @@ -0,0 +1,7 @@ +--- +changeKind: internal +packages: + - "@typespec/http-client-python" +--- + +Add a `diff-spector-tests` script wired to the new language-agnostic emitter-diff tool, and honor `--generatedFolder` in the batch Python phase of `regenerate.ts` diff --git a/cspell.yaml b/cspell.yaml index a28850f67f4..31cac9d7cc9 100644 --- a/cspell.yaml +++ b/cspell.yaml @@ -156,6 +156,7 @@ words: - MACVMIMAGEM - marshal - mday + - Menlo - methodsubscriptionid - mgmt - mgmtplane diff --git a/eng/emitter-diff/README.md b/eng/emitter-diff/README.md index 368e8bf4cab..d875b98dac8 100644 --- a/eng/emitter-diff/README.md +++ b/eng/emitter-diff/README.md @@ -72,8 +72,8 @@ node eng/emitter-diff/src/cli.ts --emitter python --baseline local:/path/to/old/ --head local:/path/to/new/http-client-python \ --html diff.html -# Place generated output under `libba` for each side (`/libba/tests/generated/...`): -node eng/emitter-diff/src/cli.ts --emitter python --generated-code-path libba +# Place generated output under a custom subpath for each side (`/generator/tests/generated/...`): +node eng/emitter-diff/src/cli.ts --emitter python --generated-code-path generator # Diff against a GitHub sha: node eng/emitter-diff/src/cli.ts --emitter python \ diff --git a/eng/emitter-diff/src/resolver.ts b/eng/emitter-diff/src/resolver.ts index 3ddb540db33..6a6974e5904 100644 --- a/eng/emitter-diff/src/resolver.ts +++ b/eng/emitter-diff/src/resolver.ts @@ -282,7 +282,9 @@ function assertInstalledPackageMetadata( try { parsed = JSON.parse(readFileSync(manifest, "utf8")) as { name?: string; version?: string }; } catch (err) { - throw new Error(`Could not parse installed package manifest at ${manifest}: ${String(err)}`); + throw new Error(`Could not parse installed package manifest at ${manifest}: ${String(err)}`, { + cause: err, + }); } if (parsed.name !== expectedName || parsed.version !== expectedVersion) { From 116e576181f96073069443d109b8311bba07389b Mon Sep 17 00:00:00 2001 From: Libba Lawrence Date: Mon, 6 Jul 2026 09:02:22 -0700 Subject: [PATCH 27/52] Run emitter-diff via tsx with .js import specifiers Align emitter-diff with the rest of eng/ (tsx + .js relative imports) instead of node native strip-types (.ts imports). This makes the tool pass the Azure/typespec-azure check:eng (tsc -p tsconfig.eng.json), which type-checks core/eng and rejected the .ts extension imports (TS5097) since Azure main lacks allowImportingTsExtensions. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- eng/emitter-diff/README.md | 17 +++++++++-------- eng/emitter-diff/src/adapters/python.ts | 6 +++--- eng/emitter-diff/src/baseline-cache.ts | 2 +- eng/emitter-diff/src/cli.ts | 14 +++++++------- eng/emitter-diff/src/diff.ts | 4 ++-- eng/emitter-diff/src/registry.ts | 4 ++-- eng/emitter-diff/src/resolver.ts | 4 ++-- eng/emitter-diff/src/util.ts | 2 +- eng/emitter-diff/tsconfig.json | 1 - packages/http-client-python/package.json | 2 +- 10 files changed, 28 insertions(+), 28 deletions(-) diff --git a/eng/emitter-diff/README.md b/eng/emitter-diff/README.md index d875b98dac8..9caf1795a2f 100644 --- a/eng/emitter-diff/README.md +++ b/eng/emitter-diff/README.md @@ -28,12 +28,13 @@ contains no language-specific logic. ## Usage ```bash -# Run directly with Node 24+ (native TypeScript, no build step, no dependencies): -node eng/emitter-diff/src/cli.ts --emitter python +# Run with tsx (no build step): +npx tsx eng/emitter-diff/src/cli.ts --emitter python ``` -> This tool is a set of plain `.ts` scripts β€” not an installed package. Node 24 runs TypeScript -> natively, so there is nothing to build or install. Typecheck with `npx tsc -p eng/emitter-diff`. +> This tool is a set of plain `.ts` scripts β€” not an installed package. It runs through `tsx` +> (a repo dev dependency), matching the rest of `eng/`, so there is nothing to build. Typecheck +> with `npx tsc -p eng/emitter-diff`. ### Refs @@ -65,18 +66,18 @@ prints a `file://` link to it. Use `--html` to write to a specific file. ```bash # Explicit baseline version: -node eng/emitter-diff/src/cli.ts --emitter python --baseline 0.34.0 --name authentication-api-key +npx tsx eng/emitter-diff/src/cli.ts --emitter python --baseline 0.34.0 --name authentication-api-key # Compare two source folders and write an HTML report to a specific path: -node eng/emitter-diff/src/cli.ts --emitter python --baseline local:/path/to/old/http-client-python \ +npx tsx eng/emitter-diff/src/cli.ts --emitter python --baseline local:/path/to/old/http-client-python \ --head local:/path/to/new/http-client-python \ --html diff.html # Place generated output under a custom subpath for each side (`/generator/tests/generated/...`): -node eng/emitter-diff/src/cli.ts --emitter python --generated-code-path generator +npx tsx eng/emitter-diff/src/cli.ts --emitter python --generated-code-path generator # Diff against a GitHub sha: -node eng/emitter-diff/src/cli.ts --emitter python \ +npx tsx eng/emitter-diff/src/cli.ts --emitter python \ --baseline github:microsoft/typespec@ ``` diff --git a/eng/emitter-diff/src/adapters/python.ts b/eng/emitter-diff/src/adapters/python.ts index 7d5546b9b51..868f75b609f 100644 --- a/eng/emitter-diff/src/adapters/python.ts +++ b/eng/emitter-diff/src/adapters/python.ts @@ -16,15 +16,15 @@ import { existsSync } from "node:fs"; import { join } from "node:path"; -import { describeRef } from "../resolver.ts"; +import { describeRef } from "../resolver.js"; import type { AdapterContext, ClassifiedRef, EmitterAdapter, GenerateRequest, ResolvedEmitter, -} from "../types.ts"; -import { run, runChecked } from "../util.ts"; +} from "../types.js"; +import { run, runChecked } from "../util.js"; const PACKAGE_NAME = "@typespec/http-client-python"; const PKG_REL = "packages/http-client-python"; diff --git a/eng/emitter-diff/src/baseline-cache.ts b/eng/emitter-diff/src/baseline-cache.ts index ed31a562838..1d633337f9d 100644 --- a/eng/emitter-diff/src/baseline-cache.ts +++ b/eng/emitter-diff/src/baseline-cache.ts @@ -3,7 +3,7 @@ import { existsSync, readFileSync, renameSync, writeFileSync } from "node:fs"; import { tmpdir } from "node:os"; import { join, resolve, sep } from "node:path"; -import { ensureDir, run } from "./util.ts"; +import { ensureDir, run } from "./util.js"; export interface BaselineCacheProfileInput { emitter: string; diff --git a/eng/emitter-diff/src/cli.ts b/eng/emitter-diff/src/cli.ts index 3a5630cc29d..c94a2b4c733 100644 --- a/eng/emitter-diff/src/cli.ts +++ b/eng/emitter-diff/src/cli.ts @@ -1,4 +1,4 @@ -#!/usr/bin/env -S node +#!/usr/bin/env -S npx tsx /** * emitter-diff β€” language-agnostic CLI. * @@ -18,17 +18,17 @@ import { readBaselineCacheIndex, writeBaselineCacheIndex, type BaselineCacheIndex, -} from "./baseline-cache.ts"; -import { diffDirs, printSummary, writeHtml } from "./diff.ts"; -import { getAdapter, listAdapters } from "./registry.ts"; +} from "./baseline-cache.js"; +import { diffDirs, printSummary, writeHtml } from "./diff.js"; +import { getAdapter, listAdapters } from "./registry.js"; import { classifyRef, defaultWorkDir, installNpmPackage as installNpm, resolveSource as resolveSrc, -} from "./resolver.ts"; -import type { AdapterContext, ClassifiedRef } from "./types.ts"; -import { color, createLogger, ensureDir, run, runChecked } from "./util.ts"; +} from "./resolver.js"; +import type { AdapterContext, ClassifiedRef } from "./types.js"; +import { color, createLogger, ensureDir, run, runChecked } from "./util.js"; function shouldUseBaselineCache(ciMode: boolean): { enabled: boolean; reason?: string } { if (ciMode) { diff --git a/eng/emitter-diff/src/diff.ts b/eng/emitter-diff/src/diff.ts index c42b7c7906e..5cb1c13a104 100644 --- a/eng/emitter-diff/src/diff.ts +++ b/eng/emitter-diff/src/diff.ts @@ -8,8 +8,8 @@ import { writeFileSync } from "node:fs"; import { basename, dirname, resolve } from "node:path"; import { pathToFileURL } from "node:url"; -import type { Logger } from "./types.ts"; -import { color, run } from "./util.ts"; +import type { Logger } from "./types.js"; +import { color, run } from "./util.js"; export interface DiffResult { /** The unified patch text (empty when there are no differences). */ diff --git a/eng/emitter-diff/src/registry.ts b/eng/emitter-diff/src/registry.ts index b57bddfc846..6b7bd59db55 100644 --- a/eng/emitter-diff/src/registry.ts +++ b/eng/emitter-diff/src/registry.ts @@ -1,6 +1,6 @@ /** Adapter registry. New languages register here; the core is otherwise agnostic. */ -import { pythonAdapter } from "./adapters/python.ts"; -import type { EmitterAdapter } from "./types.ts"; +import { pythonAdapter } from "./adapters/python.js"; +import type { EmitterAdapter } from "./types.js"; const adapters: Record = { [pythonAdapter.name]: pythonAdapter, diff --git a/eng/emitter-diff/src/resolver.ts b/eng/emitter-diff/src/resolver.ts index 6a6974e5904..fdced1ddfd3 100644 --- a/eng/emitter-diff/src/resolver.ts +++ b/eng/emitter-diff/src/resolver.ts @@ -10,8 +10,8 @@ import { existsSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs"; import { tmpdir } from "node:os"; import { isAbsolute, join, resolve } from "node:path"; -import type { ClassifiedRef, Logger } from "./types.ts"; -import { ensureDir, runChecked } from "./util.ts"; +import type { ClassifiedRef, Logger } from "./types.js"; +import { ensureDir, runChecked } from "./util.js"; /** * Classify a ref string. Explicit prefixes (`npm:`, `local:`, `github:`, diff --git a/eng/emitter-diff/src/util.ts b/eng/emitter-diff/src/util.ts index b779c3b7cc0..a090d2a7b78 100644 --- a/eng/emitter-diff/src/util.ts +++ b/eng/emitter-diff/src/util.ts @@ -5,7 +5,7 @@ import { spawn, type SpawnOptions } from "node:child_process"; import { mkdirSync } from "node:fs"; -import type { Logger } from "./types.ts"; +import type { Logger } from "./types.js"; // ---- Minimal ANSI colors (no picocolors dependency) ---- diff --git a/eng/emitter-diff/tsconfig.json b/eng/emitter-diff/tsconfig.json index 013eaa2a374..f51bfa6da96 100644 --- a/eng/emitter-diff/tsconfig.json +++ b/eng/emitter-diff/tsconfig.json @@ -7,7 +7,6 @@ "strict": true, "skipLibCheck": true, "noEmit": true, - "allowImportingTsExtensions": true, "verbatimModuleSyntax": true, "esModuleInterop": true, "forceConsistentCasingInFileNames": true, diff --git a/packages/http-client-python/package.json b/packages/http-client-python/package.json index b80fb2796cf..2736ee8d68d 100644 --- a/packages/http-client-python/package.json +++ b/packages/http-client-python/package.json @@ -55,7 +55,7 @@ "change:version": "pnpm chronus version --ignore-policies --only @typespec/http-client-python", "change:add": "pnpm chronus add", "regen-docs": "node ../../packages/tspd/cmd/tspd.js doc . --enable-experimental --output-dir ../../website/src/content/docs/docs/emitters/clients/http-client-python/reference --skip-js", - "diff-spector-tests": "node ../../eng/emitter-diff/src/cli.ts --emitter python" + "diff-spector-tests": "tsx ../../eng/emitter-diff/src/cli.ts --emitter python" }, "files": [ "dist/**", From 5371d101415da0218d0861d7e6093652ed9563b1 Mon Sep 17 00:00:00 2001 From: Libba Lawrence Date: Mon, 6 Jul 2026 09:43:08 -0700 Subject: [PATCH 28/52] edits --- eng/emitter-diff/README.md | 1 + eng/emitter-diff/src/resolver.ts | 2 +- .../generator/pygen/codegen/templates/init.py.jinja2 | 1 - 3 files changed, 2 insertions(+), 2 deletions(-) diff --git a/eng/emitter-diff/README.md b/eng/emitter-diff/README.md index 9caf1795a2f..c239a42ef8b 100644 --- a/eng/emitter-diff/README.md +++ b/eng/emitter-diff/README.md @@ -57,6 +57,7 @@ By default the tool writes a **clickable HTML report** (`emitter-diff.html`) int prints a `file://` link to it. Use `--html` to write to a specific file. - `--name `: Filter which specs/packages are generated. +- `--ci`: Disable baseline-output cache (intended for CI workflows). - `--html `: Write the rendered HTML report to this path (default: `/emitter-diff.html`). - `--generated-code-path `: Override the adapter generated-code subpath under each side output root. For Python, generated files land under `//tests/generated/...`. diff --git a/eng/emitter-diff/src/resolver.ts b/eng/emitter-diff/src/resolver.ts index fdced1ddfd3..80ba9fea25e 100644 --- a/eng/emitter-diff/src/resolver.ts +++ b/eng/emitter-diff/src/resolver.ts @@ -303,7 +303,7 @@ function repoPathKey(repo: string): string { return repo.replace(/[^a-z0-9._-]/gi, "-").toLowerCase(); } -/** Create a fresh scratch dir under the OS temp dir when `--work-dir` is omitted. */ +/** Create a fresh scratch dir under the OS temp dir for each run. */ export function defaultWorkDir(): string { return mkdtempSync(join(tmpdir(), "emitter-diff-")); } diff --git a/packages/http-client-python/generator/pygen/codegen/templates/init.py.jinja2 b/packages/http-client-python/generator/pygen/codegen/templates/init.py.jinja2 index 6cd44d9892a..007009e4bc9 100644 --- a/packages/http-client-python/generator/pygen/codegen/templates/init.py.jinja2 +++ b/packages/http-client-python/generator/pygen/codegen/templates/init.py.jinja2 @@ -1,6 +1,5 @@ {% import 'keywords.jinja2' as keywords %} # coding=utf-8 -# DEMO: emitter-diff sample change β€” revert before merge. {% if code_model.license_header %} {{ code_model.license_header }} {% endif %} From 0cf75f06a06640cfa5f9eaee5afeda96449f3b98 Mon Sep 17 00:00:00 2001 From: Libba Lawrence Date: Mon, 6 Jul 2026 09:55:17 -0700 Subject: [PATCH 29/52] Drop vestigial allowImportingTsExtensions from eng tsconfig No longer needed after emitter-diff switched to .js import specifiers; restores tsconfig.eng.json to match main. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- tsconfig.eng.json | 3 --- 1 file changed, 3 deletions(-) diff --git a/tsconfig.eng.json b/tsconfig.eng.json index 8d395c4e598..1d3264dce65 100644 --- a/tsconfig.eng.json +++ b/tsconfig.eng.json @@ -1,8 +1,5 @@ { "extends": "./tsconfig.base.json", - "compilerOptions": { - "allowImportingTsExtensions": true - }, "include": ["eng"], "exclude": ["eng/vitest.config.ts"] } From b3cefbd62ae1d6d3752b8997eb512e964bc4607f Mon Sep 17 00:00:00 2001 From: Libba Lawrence Date: Mon, 6 Jul 2026 10:00:06 -0700 Subject: [PATCH 30/52] Drop unused gpgsign cspell entry Orphaned when the tool moved off the command-runner design that used git -c commit.gpgsign=false; the word is no longer referenced anywhere. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- cspell.yaml | 1 - 1 file changed, 1 deletion(-) diff --git a/cspell.yaml b/cspell.yaml index 31cac9d7cc9..3a9b48e6c6d 100644 --- a/cspell.yaml +++ b/cspell.yaml @@ -98,7 +98,6 @@ words: - getpgid - ghapp - giacamo - - gpgsign - graalvm - Gson - Hdvcmxk From 7ba6cb5d0efb14c2a7d091ad0d28e2e245bda638 Mon Sep 17 00:00:00 2001 From: Libba Lawrence Date: Mon, 6 Jul 2026 12:37:39 -0700 Subject: [PATCH 31/52] no adapter --- .github/workflows/ci-emitter-diff-python.yml | 31 +- eng/emitter-diff/README.md | 170 ++++---- eng/emitter-diff/src/adapters/python.ts | 150 -------- eng/emitter-diff/src/baseline-cache.ts | 9 +- eng/emitter-diff/src/cli.ts | 362 +++++++++++------- eng/emitter-diff/src/diff.ts | 4 +- eng/emitter-diff/src/registry.ts | 52 ++- eng/emitter-diff/src/resolver.ts | 147 +++---- eng/emitter-diff/src/types.ts | 97 ++--- .../eng/scripts/ci/regenerate.ts | 56 +-- .../pygen/codegen/templates/version.py.jinja2 | 2 + 11 files changed, 492 insertions(+), 588 deletions(-) delete mode 100644 eng/emitter-diff/src/adapters/python.ts diff --git a/.github/workflows/ci-emitter-diff-python.yml b/.github/workflows/ci-emitter-diff-python.yml index d0724b6ae38..721b775918d 100644 --- a/.github/workflows/ci-emitter-diff-python.yml +++ b/.github/workflows/ci-emitter-diff-python.yml @@ -3,6 +3,10 @@ name: "python / emitter diff" # Diffs generated code between this PR's emitter and the merge-base baseline. # Informational only: reports a sticky PR comment + HTML artifact, and fails the # job only on a tool/build error (never on a diff). See eng/emitter-diff. +# +# The tool runs `npm run regenerate` verbatim in each tree. It auto-prepares the +# baseline tree it fetches from GitHub (via the preset's --setup: install + +# build + venv), so this workflow only builds the head (PR) emitter itself. on: pull_request: @@ -14,7 +18,7 @@ on: workflow_dispatch: inputs: baseline: - description: "Baseline emitter ref (npm version, local path, or github ref). Defaults to the PR merge-base." + description: "Baseline emitter ref (local path or github ref). Defaults to the PR merge-base. A gh:/github: ref is fetched and auto-prepared (install + build) by the tool; a local: path is used as-is." required: false default: "" @@ -38,7 +42,8 @@ jobs: - uses: actions/setup-python@v5 with: python-version: "3.12" - - name: Install repo dependencies (emitter-diff tool) + + - name: Install repo dependencies run: pnpm install - name: Determine baseline @@ -47,19 +52,25 @@ jobs: env: BASELINE_INPUT: ${{ github.event.inputs.baseline || '' }} BASE_REF: ${{ github.event.pull_request.base.ref || github.event.repository.default_branch }} - RUNNER_TEMP: ${{ runner.temp }} run: | input="$BASELINE_INPUT" - if [ -z "$input" ]; then + if [ -n "$input" ]; then + echo "ref=$input" >> "$GITHUB_OUTPUT" + echo "Baseline (explicit): $input" + else # merge-base = a real commit on the base branch; survives squash/rebase. git fetch --no-tags origin "$BASE_REF" base_sha="$(git merge-base FETCH_HEAD HEAD)" [ -n "$base_sha" ] || { echo "::error::No merge-base with $BASE_REF."; exit 1; } - input="gh:$base_sha" - echo "sha=$base_sha" >> "$GITHUB_OUTPUT" + # gh: = this repo at the merge-base. The tool fetches that tree + # and auto-preps it (install + build + venv) via the preset's --setup. + echo "ref=gh:$base_sha" >> "$GITHUB_OUTPUT" + echo "Baseline (merge-base): gh:$base_sha" fi - echo "ref=$input" >> "$GITHUB_OUTPUT" - echo "Baseline: $input" + + - name: Prepare head emitter (build + venv) + working-directory: packages/http-client-python + run: npm run setup - name: Run emitter diff id: diff @@ -69,8 +80,8 @@ jobs: RUNNER_TEMP: ${{ runner.temp }} run: | set +e - # Script wraps emitter-diff entrypoint. No --fail-on-diff (informational); - # tool/build errors still exit non-zero (checked in "Fail on tool error"). + # No --fail-on-diff (informational); tool/build errors still exit non-zero + # (checked in "Fail on tool error"). npm run diff-spector-tests -- \ --ci \ --baseline "$BASELINE_REF" \ diff --git a/eng/emitter-diff/README.md b/eng/emitter-diff/README.md index c239a42ef8b..b3d184981cf 100644 --- a/eng/emitter-diff/README.md +++ b/eng/emitter-diff/README.md @@ -3,125 +3,147 @@ A language-agnostic tool for **diffing the generated code produced by two versions of a TypeSpec emitter**. -It generates code from the test specs twice (a **baseline** emitter and a **head** emitter), -then shows the diff between the two outputs. Use it locally during development and in CI on PRs. +It runs the emitter's own regenerate command against a **baseline** source tree and a **head** +source tree, then shows the diff between the two generated outputs. Use it locally during +development and in CI on PRs. -Each language emitter plugs in via a small **adapter** that -wraps that emitter's own generation command. The core (ref resolution, diffing, orchestration) -contains no language-specific logic. +The tool contains **zero language logic**. An emitter integrates by naming three things β€” its +regenerate command, the package directory to run it in, and the generated-code directory to diff β€” +either as flags or via a built-in `--emitter` preset. ## How it works ```text - baseline emitter ─┐ - β”œβ”€ generate ─► /baseline ─┐ - specs ────────────────────── β”œβ”€β–Ί git diff ─► terminal / HTML - β”œβ”€ generate ─► /head β”€β”€β”€β”€β”€β”˜ - head emitter β”€β”€β”€β”€β”€β”˜ + baseline tree ─► run in ─► snapshot ─┐ + β”œβ”€β–Ί git diff ─► terminal / HTML + head tree ─────► run in ─► snapshot β”€β”˜ ``` -- The **adapter** wraps the emitter's existing commands. For python that is - `packages/http-client-python/eng/scripts/ci/regenerate.ts` (generation). -- The regenerate _driver_ always comes from the current checkout; only the emitter build it points - at (`--pluginDir`) changes between baseline and head, isolating the diff to emitter behavior. +- A **source tree** is resolved for each side (`--baseline` / `--head`). +- The **`--command`** is run verbatim (tokenized to argv β€” no shell) inside + `/`. This is the emitter's *unmodified* regenerate command; the tool does + not reach into it. +- The `/` subtree is snapshotted for each side and the + two snapshots are diffed. + +Because the tool just runs a command, **any emitter with a regenerate script works** β€” no per-language +plugin code. ## Usage ```bash -# Run with tsx (no build step): -npx tsx eng/emitter-diff/src/cli.ts --emitter python +# Using a built-in preset (fills in command + paths): +npx tsx eng/emitter-diff/src/cli.ts --emitter python --baseline gh: + +# Fully explicit (no preset needed): +npx tsx eng/emitter-diff/src/cli.ts \ + --command "npm run regenerate" \ + --emitter-path packages/http-client-python \ + --generated-code-path tests/generated \ + --baseline gh: ``` > This tool is a set of plain `.ts` scripts β€” not an installed package. It runs through `tsx` > (a repo dev dependency), matching the rest of `eng/`, so there is nothing to build. Typecheck > with `npx tsc -p eng/emitter-diff`. -### Refs +### Emitter config -#### Emitter refs (`--baseline`, `--head`) +| Flag | Meaning | +| -------------------------------- | ------------------------------------------------------------ | +| `--emitter ` | Built-in preset that fills in the three fields below. | +| `--command ` | Regenerate command, run verbatim in `--emitter-path`. | +| `--emitter-path ` | Package dir (relative to a tree root) to run the command in. | +| `--generated-code-path ` | Generated-code dir (relative to `--emitter-path`) to diff. | -| Syntax | Meaning | -| --------------------------------- | -------------------------------------- | -| `npm:1.2.3` or `1.2.3` | a published package version (prebuilt) | -| `local:/path` or `./path` | a local source folder | -| `github:owner/repo@` | a GitHub source at a ref | -| `gh:` | `microsoft/typespec` at a ref | +A preset supplies all three; each flag still overrides the preset value. To onboard a new language, +add a row to `EMITTER_DEFAULTS` in `src/registry.ts` β€” or just pass the three flags directly and +skip `--emitter`. -`--head` defaults to the **current checkout**. `--baseline` defaults to `gh:upstream/main` when present, otherwise `gh:origin/main` (`origin/HEAD` as a fallback). +### Refs -Use `--name` to filter which packages/specs are generated. +| Syntax | Meaning | +| --------------------------------- | ------------------------------------------ | +| `local:/path` or `./path` | a local source folder (run in place) | +| `github:owner/repo@` | a GitHub source at a ref | +| `gh:` | this repo (origin remote) at a ref | -### Common options +`--head` defaults to the **current working tree**. `--baseline` defaults to `gh:upstream/main` when +present, otherwise `gh:origin/main` (`origin/HEAD` as a fallback). -By default the tool writes a **clickable HTML report** (`emitter-diff.html`) into the work dir and -prints a `file://` link to it. Use `--html` to write to a specific file. +> **npm refs are rejected.** A published package has no source tree to run a regenerate command in, +> so pass a `local:` or `github:`/`gh:` source ref instead. -- `--name `: Filter which specs/packages are generated. -- `--ci`: Disable baseline-output cache (intended for CI workflows). -- `--html `: Write the rendered HTML report to this path (default: `/emitter-diff.html`). -- `--generated-code-path `: Override the adapter generated-code subpath under each side output root. - For Python, generated files land under `//tests/generated/...`. -- `--fail-on-diff`: Exit non-zero when output differs (CI gating). +### Command prep (`--setup`) -### Examples +The `--command` is run **as-is** β€” it does not install deps or build. Instead, prep is handled by +**`--setup`**, which runs **only in a tree the tool freshly fetched from GitHub** (a `gh:`/`github:` +ref). The current working tree and user-provided `local:` paths are assumed already built and are +**never touched** (so setup never mutates your checkout or a prepared CI worktree). -```bash -# Explicit baseline version: -npx tsx eng/emitter-diff/src/cli.ts --emitter python --baseline 0.34.0 --name authentication-api-key +- A **preset** supplies sensible setup defaults, so `--emitter python --baseline gh:main` installs + + builds the fetched baseline automatically (python: `pnpm install` β†’ `npm run setup`; typescript: + `pnpm install` β†’ `npm run build`). +- Override with one or more `--setup ` (each runs in order, in `/`), or + disable entirely with `--no-setup`. -# Compare two source folders and write an HTML report to a specific path: -npx tsx eng/emitter-diff/src/cli.ts --emitter python --baseline local:/path/to/old/http-client-python \ - --head local:/path/to/new/http-client-python \ - --html diff.html +Each `--setup` command β€” like `--command` β€” is tokenized to argv and run **without a shell**, so +multi-step pipelines (`&&`, `|`) are not supported; pass repeated `--setup` flags instead. -# Place generated output under a custom subpath for each side (`/generator/tests/generated/...`): -npx tsx eng/emitter-diff/src/cli.ts --emitter python --generated-code-path generator +### Common options -# Diff against a GitHub sha: -npx tsx eng/emitter-diff/src/cli.ts --emitter python \ - --baseline github:microsoft/typespec@ -``` +By default the tool writes a **clickable HTML report** (`emitter-diff.html`) into the work dir and +prints a `file://` link to it. + +- `--baseline ` / `--head `: the two source trees to compare. +- `--setup ` (repeatable) / `--no-setup`: prep commands for freshly fetched GitHub trees. +- `--work-dir `: scratch dir for snapshots (default: a fresh temp dir). +- `--ci`: disable the local baseline-output cache (intended for CI). +- `--html `: write the rendered HTML report to this path. +- `--fail-on-diff`: exit non-zero when output differs (exit `2` = diff present, `1` = hard error). +- `-- `: everything after `--` is appended to `--command` verbatim (e.g. to pass a name + filter through to the regenerate script). ## CI integration -`.github/workflows/ci-emitter-diff-.yml` runs on PRs that touch the language emitter or this tool. The **baseline** is the base-branch commit the PR is based on (the `git merge-base` with the target branch). CI builds the emitter for both the PR's checkout and a worktree -of that merge-base commit, diffs the two, and then: +`.github/workflows/ci-emitter-diff-.yml` runs on PRs that touch the language emitter or this +tool. The **baseline** is the base-branch commit the PR is based on (the `git merge-base` with the +target branch). Because the tool runs the regenerate command as-is, the workflow **prepares both +trees** (installs deps, builds the emitter, creates any venv) before invoking the tool, then: -- posts a **sticky PR comment** (updated in place on each push) with the link to download the diff artifact. +- posts a **sticky PR comment** (updated in place on each push) linking the diff artifact, and +- uploads the rendered **HTML report** as an artifact. **Informational:** the check **always passes unless the tool hits a real tool/build error** β€” a generated-output diff does not fail the PR. CI runs the tool without `--fail-on-diff`, so a diff -still exits `0`; only a non-zero exit (a build/venv/generate failure) fails the job. Reviewers use -the PR comment and the HTML artifact to eyeball the diff. +still exits `0`; only a non-zero exit (a build/venv/generate failure) fails the job. The comment step needs `pull-requests: write`. PRs **from forks** get a read-only token, so the -comment is best-effort there (`continue-on-error`) β€” the artifact and job-summary still work. +comment is best-effort there (`continue-on-error`) β€” the artifact and job summary still work. + +## Adding a new language -## Adding a new language adapter +Either add a preset row to `EMITTER_DEFAULTS` (`src/registry.ts`): -1. Implement `EmitterAdapter` (`src/types.ts`) β€” `prepareEmitter` and `generate` β€” wrapping that - emitter's own commands (e.g. rust's `npm run tspcompile`, ts's `gen-spector`). -2. Register it in `src/registry.ts`. +```ts +rust: { + command: "npm run tspcompile", + emitterPath: "packages/typespec-rust", + generatedCodePath: "test/generated", +}, +``` -That's the only wiring needed β€” the orchestrator, ref resolver, and diff engine are -language-agnostic and require no changes. +…or skip the preset entirely and pass `--command` / `--emitter-path` / +`--generated-code-path` directly. Either way, ensure each side's tree can actually run the +command (see **Command prep** above). The orchestrator, ref resolver, and diff engine need no +changes. ## Notes & limitations -- For the current python regenerate flow, spec inputs come from each side's - dependencies (`node_modules/@typespec/http-specs` and - `node_modules/@azure-tools/azure-http-specs`). Use `--name` to filter. - `--html` renders a self-contained, GitHub-style HTML report (inline CSS, no external requests). The tool has **zero runtime dependencies** β€” the diff itself is `git diff --no-index`. - For github refs (including fork repos), the resolver uses a detached, commit-keyed cached git worktree under the temp directory, created from an isolated cache repo (not from your active - checkout). That keeps each version's build/venv isolated and allows repeated runs on the same - commit to reuse existing setup work. -- **Python's native two-phase pipeline needs a venv per emitter version.** `regenerate.ts` - compiles TypeSpec to YAML in-process and then runs a batched Python subprocess - (`eng/scripts/setup/run_batch.py`) that writes the `.py` files using a venv co-located with the - emitter at `/venv`. The adapter therefore builds **and** creates a venv (`npm run -install`) for each side before generating. Because each version's venv is built from that - version's generator, a baseline must be a buildable **source** ref (`local`/`github`) or an npm - version whose package can run `npm run install`; the CI workflow uses a worktree of the PR base - commit as the baseline. + checkout). Repeated runs on the same commit reuse it. +- Spec inputs come from each side's own dependencies (e.g. `node_modules/@typespec/http-specs`). + Spec versions rarely change, so any drift between baseline/head is treated as acceptable noise. diff --git a/eng/emitter-diff/src/adapters/python.ts b/eng/emitter-diff/src/adapters/python.ts deleted file mode 100644 index 868f75b609f..00000000000 --- a/eng/emitter-diff/src/adapters/python.ts +++ /dev/null @@ -1,150 +0,0 @@ -/** - * typespec-python adapter. - * - * This is the only python-aware code in the tool. It satisfies the generic - * {@link EmitterAdapter} contract by wrapping the python package's own - * generation script `eng/scripts/ci/regenerate.ts` (driven with `--pluginDir` - * (emitter build) + `--generatedFolder` (output root) overrides so any emitter - * build can target any output dir). - * - * The regenerate *driver* always comes from the current checkout; only the - * `--pluginDir` it points at changes between baseline and head. Each emitter - * build resolves its own specs from its `node_modules`; spec versions rarely - * change, so any spec drift between baseline/head is treated as acceptable - * noise rather than pinned. - */ -import { existsSync } from "node:fs"; -import { join } from "node:path"; - -import { describeRef } from "../resolver.js"; -import type { - AdapterContext, - ClassifiedRef, - EmitterAdapter, - GenerateRequest, - ResolvedEmitter, -} from "../types.js"; -import { run, runChecked } from "../util.js"; - -const PACKAGE_NAME = "@typespec/http-client-python"; -const PKG_REL = "packages/http-client-python"; - -function pkgDir(ctx: AdapterContext): string { - return join(ctx.repoRoot, PKG_REL); -} - -/** Resolve `tsx` from the python package and run a script in its directory. */ -async function runScript( - ctx: AdapterContext, - scriptRelPath: string, - args: string[], - opts: { inherit?: boolean; prefix?: string } = {}, -): Promise { - const cwd = pkgDir(ctx); - const inherit = opts.inherit ?? opts.prefix === undefined; - await runChecked("npx", ["tsx", join(cwd, scriptRelPath), ...args], { - cwd, - inherit, - prefix: opts.prefix, - }); -} - -async function isBuilt(dir: string): Promise { - return existsSync(join(dir, "dist", "emitter", "index.js")); -} - -/** - * Ensure the package's npm dependencies are installed. A fresh source checkout - * (a github clone or a bare local path) has no `node_modules`, so `npm run - * build` would fail to resolve its types/deps. http-client-python is - * npm-managed and commits its own package-lock.json to the repo, so a source - * checkout already has the lockfile that `npm ci` needs. - */ -async function ensureDeps(dir: string, ctx: AdapterContext): Promise { - if (existsSync(join(dir, "node_modules"))) return; - ctx.log.warn(`No node_modules at ${dir}; installing dependencies (npm ci)...`); - const res = await run("npm", ["ci"], { cwd: dir, inherit: true }); - if (res.code !== 0 || !existsSync(join(dir, "node_modules"))) { - throw new Error( - `Could not install dependencies at ${dir} (npm ci). Run \`npm ci\` there manually and retry.`, - ); - } -} - -async function ensureBuilt(dir: string, ctx: AdapterContext): Promise { - if (await isBuilt(dir)) return; - // Source checkouts may not have dependencies installed yet. - await ensureDeps(dir, ctx); - ctx.log.warn(`Emitter at ${dir} is not built; attempting build...`); - const res = await run("npm", ["run", "build"], { cwd: dir, inherit: true }); - if (res.code !== 0 || !(await isBuilt(dir))) { - throw new Error( - `Could not build emitter at ${dir}. Build it manually (npm ci && npm run build) and retry.`, - ); - } -} - -/** Ensure the emitter has a local Python venv for generation. */ -async function ensureVenv(dir: string, ctx: AdapterContext): Promise { - if (existsSync(join(dir, "venv"))) return; - ctx.log.warn(`No Python venv at ${dir}; creating one (npm run install)...`); - const res = await run("npm", ["run", "install"], { cwd: dir, inherit: true }); - if (res.code !== 0 || !existsSync(join(dir, "venv"))) { - throw new Error( - `Could not create a Python venv at ${dir}. Run \`npm run install\` there manually and retry. ` + - `(The native two-phase pipeline needs a venv per emitter version.)`, - ); - } -} - -export const pythonAdapter: EmitterAdapter = { - name: "python", - packageName: PACKAGE_NAME, - - async prepareEmitter( - ref: ClassifiedRef | "current", - ctx: AdapterContext, - ): Promise { - if (ref === "current") { - const dir = pkgDir(ctx); - await ensureBuilt(dir, ctx); - await ensureVenv(dir, ctx); - return { dir, label: "current checkout" }; - } - - if (ref.kind === "npm") { - // npm emitters are prebuilt but still need a venv. - const dir = await ctx.installNpmPackage(PACKAGE_NAME, ref.version ?? "latest"); - await ensureVenv(dir, ctx); - return { dir, label: describeRef(ref, PACKAGE_NAME) }; - } - - // local/github refs may require a build and venv. - const sourceRoot = await ctx.resolveSource(ref, PACKAGE_NAME); - // Full-repo sources contain the package under packages/http-client-python. - const candidate = existsSync(join(sourceRoot, PKG_REL)) - ? join(sourceRoot, PKG_REL) - : sourceRoot; - await ensureBuilt(candidate, ctx); - await ensureVenv(candidate, ctx); - return { dir: candidate, label: describeRef(ref, PACKAGE_NAME) }; - }, - - async generate(request: GenerateRequest, ctx: AdapterContext): Promise { - // Regenerate writes under /../tests/generated/... . - // Anchor generatedFolder at //generator so final output lands under - // //tests/generated when a subpath override is provided. - const generatedSubpath = request.generatedCodePath ?? ""; - const generatedFolder = join(request.outputDir, generatedSubpath, "generator"); - const args = ["--pluginDir", request.emitter.dir, "--generatedFolder", generatedFolder]; - - const flavor = request.options.flavor; - if (flavor) args.push("--flavor", flavor); - if (request.nameFilter) args.push("--name", request.nameFilter); - - args.push(...request.passthrough); - - ctx.log.step(`Generating with ${request.emitter.label} β†’ ${request.outputDir}`); - await runScript(ctx, "eng/scripts/ci/regenerate.ts", args, { prefix: request.logPrefix }); - }, -}; diff --git a/eng/emitter-diff/src/baseline-cache.ts b/eng/emitter-diff/src/baseline-cache.ts index 1d633337f9d..c7b0b08b5b5 100644 --- a/eng/emitter-diff/src/baseline-cache.ts +++ b/eng/emitter-diff/src/baseline-cache.ts @@ -6,11 +6,12 @@ import { join, resolve, sep } from "node:path"; import { ensureDir, run } from "./util.js"; export interface BaselineCacheProfileInput { - emitter: string; + emitter?: string; baselineRef: string; - generatedCodePath?: string; - nameFilter?: string; - options: Record; + command: string; + emitterPath: string; + generatedCodePath: string; + setup: string[]; passthrough: string[]; } diff --git a/eng/emitter-diff/src/cli.ts b/eng/emitter-diff/src/cli.ts index c94a2b4c733..2a8f75807b1 100644 --- a/eng/emitter-diff/src/cli.ts +++ b/eng/emitter-diff/src/cli.ts @@ -1,12 +1,15 @@ #!/usr/bin/env -S npx tsx /** - * emitter-diff β€” language-agnostic CLI. + * emitter-diff β€” language-agnostic generated-code diff runner. * - * Generates code from the test specs with two emitter versions (baseline + head) - * and diffs the output. All language specifics live behind the selected adapter; - * this file contains zero language logic. + * It resolves a baseline and a head source tree, runs the emitter's own + * regenerate command verbatim inside `/` for each side, then + * diffs `/` between the two. The tool + * contains zero language logic: an emitter integrates by naming its regenerate + * command and two paths (directly, or via a built-in `--emitter` preset). */ -import { cpSync, existsSync, rmSync, writeFileSync } from "node:fs"; +import { createHash } from "node:crypto"; +import { cpSync, existsSync, readFileSync, rmSync, writeFileSync } from "node:fs"; import { join } from "node:path"; import { parseArgs } from "node:util"; @@ -20,59 +23,61 @@ import { type BaselineCacheIndex, } from "./baseline-cache.js"; import { diffDirs, printSummary, writeHtml } from "./diff.js"; -import { getAdapter, listAdapters } from "./registry.js"; -import { - classifyRef, - defaultWorkDir, - installNpmPackage as installNpm, - resolveSource as resolveSrc, -} from "./resolver.js"; -import type { AdapterContext, ClassifiedRef } from "./types.js"; +import { getEmitterDefaults, listEmitters } from "./registry.js"; +import { classifyRef, defaultWorkDir, describeRef, materializeTree } from "./resolver.js"; +import type { ClassifiedRef, EmitterConfig, Logger } from "./types.js"; import { color, createLogger, ensureDir, run, runChecked } from "./util.js"; function shouldUseBaselineCache(ciMode: boolean): { enabled: boolean; reason?: string } { if (ciMode) { return { enabled: false, reason: "--ci" }; } - // Restrict caching to clearly local, interactive usage by default. if (!process.stdout.isTTY || !process.stderr.isTTY) { return { enabled: false, reason: "non-interactive terminal" }; } - return { enabled: true }; } const HELP = `${color.bold("emitter-diff")} β€” diff generated code across emitter versions ${color.bold("Usage:")} - emitter-diff --emitter [options] - -${color.bold("Required:")} - --emitter Adapter to use. Available: ${listAdapters().join(", ")} + emitter-diff [--emitter ] --command --emitter-path \\ + --generated-code-path [options] + +${color.bold("What it does:")} + Runs verbatim inside / for a baseline tree and a + head tree, then diffs / between them. + A tree the tool fetches fresh from GitHub is first prepared with --setup (a + preset supplies install+build defaults); the current working tree and local: + paths are assumed already built and are never touched. + +${color.bold("Emitter config")} (a preset fills these; each is overridable): + --emitter Built-in preset. Available: ${listEmitters().join(", ") || "(none)"} + --command Regenerate command, e.g. "npm run regenerate". + --emitter-path Package dir (rel to tree root) to run the command in. + --generated-code-path + Generated-code dir (rel to --emitter-path) to diff. + --setup Prep command run in a freshly fetched GitHub tree before + (repeatable, runs in order; a preset supplies + defaults like install+build). Overrides preset defaults. + --no-setup Skip setup even when a preset defines it. ${color.bold("Refs")} (for --baseline / --head): - npm:1.2.3 | 1.2.3 a published package version - local:/path | ./path a local folder + local:/path | ./path a local source folder github:owner/repo@ a GitHub source at a ref - gh: microsoft/typespec at a ref + gh: this repo (origin remote) at a ref + (npm refs are rejected β€” a published package has no source tree to run in.) ${color.bold("Options:")} - --baseline Old emitter. Default: gh:upstream/main if present, + --baseline Old source tree. Default: gh:upstream/main if present, otherwise gh:origin/main. - --head New emitter. Default: current checkout. - --generated-code-path - Override adapter generated-code subpath under each - side output root. - --name Filter which specs/packages are generated. - Baseline output is cached across local runs. + --head New source tree. Default: the current working tree. + --work-dir Scratch dir for snapshots. Default: a fresh temp dir. --ci CI mode: disable local baseline cache. - --html Write the rendered HTML diff to this path. - Default output: a clickable HTML report in the work dir. - --fail-on-diff Exit non-zero when output differs (CI gating). Exit - code 2 means "diff present"; 1 means a hard error. - --opt key=value Repeatable adapter-specific option (e.g. --opt flavor=azure). - -- Everything after -- is forwarded to the adapter. + --html Write the rendered HTML diff (default: /emitter-diff.html). + --fail-on-diff Exit non-zero when output differs (2 = diff, 1 = error). + -- Everything after -- is appended to verbatim. -h, --help Show this help. `; @@ -105,10 +110,82 @@ async function resolveDefaultBaselineRef(repoRoot: string): Promise { return "gh:origin/main"; } +/** + * Split a command string into argv, honoring single/double quotes but WITHOUT + * invoking a shell. Multi-step pipelines (`&&`, `|`) are intentionally NOT + * supported β€” put prep in a package.json script or separate CI steps. + */ +function tokenizeCommand(command: string): string[] { + const tokens: string[] = []; + const re = /"([^"]*)"|'([^']*)'|(\S+)/g; + let m: RegExpExecArray | null; + while ((m = re.exec(command)) !== null) { + tokens.push(m[1] ?? m[2] ?? m[3]); + } + return tokens; +} + +/** Merge a `--emitter` preset (if any) with explicit flag overrides. */ +function resolveConfig( + values: { + emitter?: string; + command?: string; + "emitter-path"?: string; + "generated-code-path"?: string; + setup?: string[]; + "no-setup"?: boolean; + }, + log: Logger, +): EmitterConfig | undefined { + let preset: Partial = {}; + if (values.emitter) { + const defaults = getEmitterDefaults(values.emitter); + if (!defaults) { + log.error( + `Unknown --emitter '${values.emitter}'. Available: ${listEmitters().join(", ") || "(none)"}. ` + + `Pass --command / --emitter-path / --generated-code-path directly instead.`, + ); + return undefined; + } + preset = defaults; + } + + const command = values.command ?? preset.command; + const emitterPath = values["emitter-path"] ?? preset.emitterPath; + const generatedCodePath = + values["generated-code-path"] ?? preset.generatedCodePath; + + const missing: string[] = []; + if (!command) missing.push("--command"); + if (!emitterPath) missing.push("--emitter-path"); + if (!generatedCodePath) missing.push("--generated-code-path"); + if (missing.length > 0) { + log.error( + `Missing required emitter config: ${missing.join(", ")}. ` + + `Provide them as flags or select a preset with --emitter (available: ${ + listEmitters().join(", ") || "(none)" + }).`, + ); + return undefined; + } + + // Setup: explicit --setup wins, --no-setup forces none, else the preset's. + let setup: string[]; + if (values["no-setup"]) { + setup = []; + } else if (values.setup && values.setup.length > 0) { + setup = values.setup; + } else { + setup = preset.setup ?? []; + } + + return { command: command!, emitterPath: emitterPath!, generatedCodePath: generatedCodePath!, setup }; +} + async function main(): Promise { const rawArgs = process.argv.slice(2); - // Split off adapter passthrough after a standalone `--`. + // Split off command passthrough after a standalone `--`. const sepIndex = rawArgs.indexOf("--"); const ownArgs = sepIndex === -1 ? rawArgs : rawArgs.slice(0, sepIndex); const passthrough = sepIndex === -1 ? [] : rawArgs.slice(sepIndex + 1); @@ -117,14 +194,17 @@ async function main(): Promise { args: ownArgs, options: { emitter: { type: "string" }, + command: { type: "string" }, + "emitter-path": { type: "string" }, + "generated-code-path": { type: "string" }, + setup: { type: "string", multiple: true }, + "no-setup": { type: "boolean" }, baseline: { type: "string" }, head: { type: "string" }, - "generated-code-path": { type: "string" }, - name: { type: "string" }, + "work-dir": { type: "string" }, ci: { type: "boolean" }, html: { type: "string" }, "fail-on-diff": { type: "boolean" }, - opt: { type: "string", multiple: true }, help: { type: "boolean", short: "h" }, }, allowPositionals: false, @@ -136,43 +216,23 @@ async function main(): Promise { process.stdout.write(HELP); return 0; } - if (!values.emitter) { - log.error("--emitter is required (no default). " + `Available: ${listAdapters().join(", ")}`); - return 2; - } - if (!listAdapters().includes(values.emitter)) { - log.error(`Unknown emitter '${values.emitter}'. Available: ${listAdapters().join(", ")}`); - return 2; - } - const adapter = getAdapter(values.emitter); + + const config = resolveConfig(values, log); + if (!config) return 2; // Repo root = current git working tree. const repoRoot = (await runChecked("git", ["rev-parse", "--show-toplevel"])).stdout.trim(); - // Use an absolute work dir because adapters may run from a different cwd. - const workDir = ensureDir(defaultWorkDir()); + const workDir = ensureDir(values["work-dir"] ?? defaultWorkDir()); log.info(`${color.dim("work dir:")} ${workDir}`); - const ctx: AdapterContext = { - repoRoot, - workDir, - log, - resolveSource: (ref, _packageName) => resolveSrc(ref, workDir, log, repoRoot), - installNpmPackage: (packageName, version) => installNpm(packageName, version, workDir, log), - }; - - // Parse adapter options (--opt key=value). - const options: Record = {}; - for (const entry of values.opt ?? []) { - const eq = entry.indexOf("="); - if (eq === -1) { - log.error(`Invalid --opt '${entry}'. Expected key=value.`); - return 2; - } - options[entry.slice(0, eq)] = entry.slice(eq + 1); + const commandArgv = tokenizeCommand(config.command); + if (commandArgv.length === 0) { + log.error(`--command is empty.`); + return 2; } - // Resolve emitters. + // Resolve refs. npm refs are rejected by materializeTree. const baselineRefValue = values.baseline ?? (await resolveDefaultBaselineRef(repoRoot)); if (!values.baseline) { log.info(`${color.dim("baseline default:")} ${baselineRefValue}`); @@ -182,32 +242,96 @@ async function main(): Promise { ? classifyRef(values.head, repoRoot) : "current"; - log.step("Preparing baseline emitter"); - const baselineEmitter = await adapter.prepareEmitter(baselineRef, ctx); - log.step("Preparing head emitter"); - const headEmitter = await adapter.prepareEmitter(headRef, ctx); - - // Baseline/head generate in parallel by default. - const baselineOut = ensureDir(join(workDir, "baseline")); - const headOut = ensureDir(join(workDir, "head")); + log.step("Resolving baseline source tree"); + const baselineTree = await materializeTree(baselineRef, workDir, log, repoRoot); + const baselineLabel = describeRef(baselineRef, config.emitterPath); + + log.step("Resolving head source tree"); + const headTree = + headRef === "current" ? repoRoot : await materializeTree(headRef, workDir, log, repoRoot); + const headLabel = headRef === "current" ? "current working tree" : describeRef(headRef, config.emitterPath); + + const baselineSnap = ensureDir(join(workDir, "baseline")); + const headSnap = ensureDir(join(workDir, "head")); + + // Run inside /, then snapshot the generated dir. + const runSide = async ( + sideName: string, + tree: string, + snapDir: string, + label: string, + logPrefix: string | undefined, + runSetup: boolean, + ): Promise => { + const runDir = join(tree, config.emitterPath); + if (!existsSync(runDir)) { + throw new Error( + `Emitter path not found for ${label}: ${runDir} (--emitter-path ${config.emitterPath}).`, + ); + } + const generatedDir = join(runDir, config.generatedCodePath); + const inherit = logPrefix === undefined; + if (runSetup && config.setup && config.setup.length > 0) { + // Setup runs in a tree the tool materialized from GitHub. A cached worktree + // is reused across runs, so a sentinel keyed on the setup commands lets us + // prep it exactly once β€” re-running full setup (e.g. an isolated wheel + // build) on an already-prepared tree is both wasteful and flaky. Changing + // the setup commands changes the key and forces a re-prep. + const setupKey = createHash("sha256").update(JSON.stringify(config.setup)).digest("hex"); + const sentinel = join(tree, ".emitter-diff-setup-done"); + const alreadyPrepared = + existsSync(sentinel) && readFileSync(sentinel, "utf8").trim() === setupKey; + if (alreadyPrepared) { + log.info(color.dim(`${sideName} setup skipped (already prepared): ${label}`)); + } else { + for (const step of config.setup) { + const setupArgv = tokenizeCommand(step); + if (setupArgv.length === 0) continue; + log.step(`${sideName} setup: ${setupArgv.join(" ")} (in ${runDir})`); + await runChecked(setupArgv[0], setupArgv.slice(1), { + cwd: runDir, + inherit, + prefix: logPrefix, + }); + } + writeFileSync(sentinel, setupKey); + } + } + log.step( + `${sideName} output regeneration ${color.dim(`(${label}): ${commandArgv.join(" ")}`)}`, + ); + await runChecked(commandArgv[0], [...commandArgv.slice(1), ...passthrough], { + cwd: runDir, + inherit, + prefix: logPrefix, + }); + if (!existsSync(generatedDir)) { + throw new Error( + `Generated code not found after regenerating ${label}: ${generatedDir} ` + + `(--generated-code-path ${config.generatedCodePath}). ` + + `Did the command write there?`, + ); + } + rmSync(snapDir, { recursive: true, force: true }); + cpSync(generatedDir, snapDir, { recursive: true, force: true }); + }; - const parallel = true; + // ---- Baseline output cache (local, interactive only) ---- const cacheDecision = shouldUseBaselineCache(Boolean(values.ci)); const useBaselineCache = cacheDecision.enabled; if (!useBaselineCache) { log.info( - color.dim( - `baseline cache disabled${cacheDecision.reason ? ` (${cacheDecision.reason})` : ""}`, - ), + color.dim(`baseline cache disabled${cacheDecision.reason ? ` (${cacheDecision.reason})` : ""}`), ); } - const baselineIdentity = await detectBaselineIdentity(baselineEmitter.dir); + const baselineIdentity = await detectBaselineIdentity(baselineTree); const baselineProfileKey = computeBaselineProfileKey({ emitter: values.emitter, baselineRef: baselineRefValue, - generatedCodePath: values["generated-code-path"], - nameFilter: values.name, - options, + command: config.command, + emitterPath: config.emitterPath, + generatedCodePath: config.generatedCodePath, + setup: config.setup ?? [], passthrough, }); const baselineCache = baselineCachePaths(baselineProfileKey); @@ -215,8 +339,10 @@ async function main(): Promise { const persistBaselineIndex = (index: BaselineCacheIndex): void => { try { writeBaselineCacheIndex(index); - } catch { - // Best effort cache cleanup. + } catch (err) { + // Best effort: a failed index write only means the cache may be recomputed + // next run; it must never abort an otherwise-successful diff. + log.warn(`Could not persist baseline cache index (ignored). ${String(err)}`); } }; @@ -234,12 +360,11 @@ async function main(): Promise { delete index[baselineProfileKey]; persistBaselineIndex(index); } else if (existsSync(baselineCache.marker) && existsSync(baselineCache.dir)) { - log.step("Reusing cached baseline output"); - rmSync(baselineOut, { recursive: true, force: true }); - cpSync(baselineCache.dir, baselineOut, { recursive: true, force: true }); + log.step("Baseline output regeneration (reusing cached output)"); + rmSync(baselineSnap, { recursive: true, force: true }); + cpSync(baselineCache.dir, baselineSnap, { recursive: true, force: true }); baselineReused = true; } else { - log.info(color.dim("Baseline cache not found; regenerating baseline.")); delete index[baselineProfileKey]; persistBaselineIndex(index); } @@ -249,31 +374,18 @@ async function main(): Promise { } } - const baselineReq = { - emitter: baselineEmitter, - outputDir: baselineOut, - generatedCodePath: values["generated-code-path"], - nameFilter: values.name, - options, - passthrough, - logPrefix: parallel ? color.dim("[baseline] ") : undefined, - }; - const headReq = { - emitter: headEmitter, - outputDir: headOut, - generatedCodePath: values["generated-code-path"], - nameFilter: values.name, - options, - passthrough, - logPrefix: parallel ? color.cyan("[head] ") : undefined, - }; + // Setup runs only in a tree the tool freshly materialized from GitHub β€” never + // the current working tree or a user-provided local: path (assumed built). + const baselineSetup = baselineRef.kind === "github"; + const headSetup = headRef !== "current" && headRef.kind === "github"; if (baselineReused) { - log.step("Generating head (baseline reused)"); - await adapter.generate(headReq, ctx); + await runSide("Head", headTree, headSnap, headLabel, undefined, headSetup); } else { - log.step("Generating baseline + head in parallel"); - await Promise.all([adapter.generate(baselineReq, ctx), adapter.generate(headReq, ctx)]); + await Promise.all([ + runSide("Baseline", baselineTree, baselineSnap, baselineLabel, color.dim("[baseline] "), baselineSetup), + runSide("Head", headTree, headSnap, headLabel, color.cyan("[head] "), headSetup), + ]); } if (useBaselineCache && !baselineReused) { @@ -284,35 +396,20 @@ async function main(): Promise { ) { throw new Error("unsafe cache path"); } - rmSync(baselineCache.dir, { recursive: true, force: true }); - cpSync(baselineOut, baselineCache.dir, { recursive: true, force: true }); - writeFileSync( - baselineCache.marker, - `${new Date().toISOString()} ${baselineIdentity}\n`, - "utf8", - ); + cpSync(baselineSnap, baselineCache.dir, { recursive: true, force: true }); + writeFileSync(baselineCache.marker, `${new Date().toISOString()} ${baselineIdentity}\n`, "utf8"); const index = readBaselineCacheIndex(); - index[baselineProfileKey] = { - baselineIdentity, - updatedAt: new Date().toISOString(), - }; + index[baselineProfileKey] = { baselineIdentity, updatedAt: new Date().toISOString() }; writeBaselineCacheIndex(index); } catch (err) { log.warn(`Could not update baseline cache. ${String(err)}`); } } - // Log output roots used by the diff. - log.info( - `${color.dim("baseline output:")} ${baselineOut} ${color.dim(`(${baselineEmitter.label})`)}`, - ); - log.info(`${color.cyan("head output:")} ${headOut} ${color.dim(`(${headEmitter.label})`)}`); - // Diff. - const diff = await diffDirs(baselineOut, headOut, log); + const diff = await diffDirs(baselineSnap, headSnap, log); - // Default to a clickable HTML report in the work dir unless --html is set. const htmlTarget = values.html ?? join(workDir, "emitter-diff.html"); if (!diff.hasChanges) { @@ -325,8 +422,7 @@ async function main(): Promise { if (values["fail-on-diff"] && diff.hasChanges) { log.error("Differences detected and --fail-on-diff is set."); - // Exit code 2 is reserved for "diff present" so CI can distinguish an - // expected-but-unapproved diff from a hard failure (exit 1). + // Exit 2 = "diff present" so CI can distinguish it from a hard failure (1). return 2; } return 0; diff --git a/eng/emitter-diff/src/diff.ts b/eng/emitter-diff/src/diff.ts index 5cb1c13a104..ec1147e1743 100644 --- a/eng/emitter-diff/src/diff.ts +++ b/eng/emitter-diff/src/diff.ts @@ -231,6 +231,6 @@ export function writeHtml(diff: DiffResult, outFile: string, log: Logger): void const summary = `${diff.filesChanged} file(s), +${diff.insertions} / -${diff.deletions}`; writeFileSync(outFile, htmlDoc(summary, body), "utf8"); const abs = resolve(outFile); - log.success(`Wrote HTML diff to ${abs}`); - log.info(`${color.bold("Open it:")} ${pathToFileURL(abs).href}`); + log.success(`Successfully created HTML report.`); + log.info(`${color.bold("Open Diff:")} ${pathToFileURL(abs).href}`); } diff --git a/eng/emitter-diff/src/registry.ts b/eng/emitter-diff/src/registry.ts index 6b7bd59db55..d3f89d31436 100644 --- a/eng/emitter-diff/src/registry.ts +++ b/eng/emitter-diff/src/registry.ts @@ -1,20 +1,44 @@ -/** Adapter registry. New languages register here; the core is otherwise agnostic. */ -import { pythonAdapter } from "./adapters/python.js"; -import type { EmitterAdapter } from "./types.js"; +/** + * Built-in emitter presets. + * + * Each entry is pure data: the regenerate command plus where the emitter and + * its generated code live. `--emitter ` selects a preset; any field can + * still be overridden with `--command` / `--emitter-path` / + * `--generated-code-path`. New languages add a row here (or pass all + * three flags directly and skip `--emitter`). + */ +import type { EmitterConfig } from "./types.js"; -const adapters: Record = { - [pythonAdapter.name]: pythonAdapter, - // Future: ts, rust, java, go ... each wraps its own generate/test command. +// @azure-tools/typespec-ts (Azure/typespec-azure). `regen-test-baselines` runs +// gen-spector.js, which writes the in-tree spector baselines under +// test/azure-modular-integration/generated. +const typescript: EmitterConfig = { + command: "npm run regen-test-baselines", + emitterPath: "packages/typespec-ts", + generatedCodePath: "test/azure-modular-integration/generated", + setup: ["pnpm install", "npm run build"], }; -export function getAdapter(name: string): EmitterAdapter { - const adapter = adapters[name]; - if (!adapter) { - throw new Error(`Unknown emitter '${name}'. Available: ${Object.keys(adapters).join(", ")}`); - } - return adapter; +export const EMITTER_DEFAULTS: Record = { + python: { + command: "npm run regenerate", + emitterPath: "packages/http-client-python", + generatedCodePath: "tests/generated", + // http-client-python is excluded from the pnpm workspace + // (see pnpm-workspace.yaml), so it manages its own registry-versioned deps. + // Install them with npm (not pnpm), skipping the prepare/venv scripts, then + // run the package's own setup (build + venv/wheel install). + setup: ["npm install --ignore-scripts", "npm run setup"], + }, + typescript, + ts: typescript, + // Future: rust, java, go ... each just names its regenerate command and paths. +}; + +export function getEmitterDefaults(name: string): EmitterConfig | undefined { + return EMITTER_DEFAULTS[name]; } -export function listAdapters(): string[] { - return Object.keys(adapters); +export function listEmitters(): string[] { + return Object.keys(EMITTER_DEFAULTS); } diff --git a/eng/emitter-diff/src/resolver.ts b/eng/emitter-diff/src/resolver.ts index 80ba9fea25e..fc52779c5a8 100644 --- a/eng/emitter-diff/src/resolver.ts +++ b/eng/emitter-diff/src/resolver.ts @@ -6,12 +6,12 @@ * source checkout into a usable emitter is intentionally NOT done here β€” that * is language-specific and belongs to the adapter's `prepareEmitter`. */ -import { existsSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs"; +import { existsSync, mkdtempSync } from "node:fs"; import { tmpdir } from "node:os"; import { isAbsolute, join, resolve } from "node:path"; import type { ClassifiedRef, Logger } from "./types.js"; -import { ensureDir, runChecked } from "./util.js"; +import { ensureDir, run, runChecked } from "./util.js"; /** * Classify a ref string. Explicit prefixes (`npm:`, `local:`, `github:`, @@ -34,8 +34,14 @@ export function classifyRef(raw: string, repoRoot: string): ClassifiedRef { return parseGithub(trimmed.slice(7), raw); } if (trimmed.startsWith("gh:")) { - // gh: => microsoft/typespec at - return { kind: "github", raw, gitRef: trimmed.slice(3) }; + // `gh:` => this repo (origin remote) at . Also tolerate the fuller + // `gh:owner/repo@ref` form (route it through the github parser) so users + // don't accidentally fold the repo into the ref. + const rest = trimmed.slice(3); + if (rest.includes("/") && rest.includes("@")) { + return parseGithub(rest, raw); + } + return { kind: "github", raw, gitRef: rest }; } if (/^https?:\/\/github\.com\//i.test(trimmed)) { return parseGithubUrl(trimmed, raw); @@ -86,7 +92,38 @@ export function describeRef(ref: ClassifiedRef, packageName: string): string { } } -const DEFAULT_REPO = "microsoft/typespec"; +const FALLBACK_REPO = "microsoft/typespec"; + +/** + * Best-effort `owner/repo` for the repo the tool is running in, parsed from its + * `origin` remote. This is what `gh:` (and any github ref without an + * explicit `owner/repo`) resolves against, so `gh:main` means "this repo at + * main" whether the tool runs in microsoft/typespec or a consumer like + * Azure/typespec-azure. Falls back to `microsoft/typespec` when origin can't be + * determined (e.g. no remote). + */ +async function detectOriginRepo(repoRoot: string | undefined, log: Logger): Promise { + if (!repoRoot) return FALLBACK_REPO; + try { + const res = await run("git", ["remote", "get-url", "origin"], { cwd: repoRoot }); + if (res.code === 0) { + const parsed = parseOwnerRepoFromUrl(res.stdout.trim()); + if (parsed) return parsed; + } + } catch { + // ignore β€” fall through to the default below. + } + log.warn(`Could not detect origin repo for gh: refs; defaulting to ${FALLBACK_REPO}.`); + return FALLBACK_REPO; +} + +/** Parse `owner/repo` from an https, ssh, or git@ GitHub remote URL. */ +function parseOwnerRepoFromUrl(url: string): string | undefined { + // https://github.com/owner/repo(.git) | git@github.com:owner/repo(.git) | + // ssh://git@github.com/owner/repo(.git) + const m = /github\.com[:/]([A-Za-z0-9._-]+)\/([A-Za-z0-9._-]+?)(?:\.git)?\/?$/.exec(url); + return m ? `${m[1]}/${m[2]}` : undefined; +} /** * Reject refs/repos that could be misread by git as options or that carry shell @@ -107,10 +144,15 @@ function assertSafeRepo(repo: string): void { } /** - * Materialize a local-or-github ref into a source directory. npm refs are - * handled by {@link installNpmPackage} (the package name is adapter-specific). + * Materialize a ref into a local source tree the regenerate command can run in. + * + * - `local` β†’ the folder itself (run in place). + * - `github` β†’ a detached, commit-keyed cached git worktree (or a shallow + * clone fallback). + * - `npm` β†’ rejected: a published package has no source tree to regenerate + * from. Use a `local`/`github` source ref instead. */ -export async function resolveSource( +export async function materializeTree( ref: ClassifiedRef, workDir: string, log: Logger, @@ -125,18 +167,21 @@ export async function resolveSource( if (ref.kind === "github") { return cloneGithub(ref, workDir, log, repoRoot); } - throw new Error(`resolveSource cannot handle npm refs directly (ref: ${ref.raw})`); + throw new Error( + `Cannot run a regenerate command against an npm ref (${ref.raw}). ` + + `A published package has no source tree; pass a local: or github:/gh: source ref instead.`, + ); } async function cloneGithub( ref: ClassifiedRef, workDir: string, log: Logger, - _repoRoot?: string, + repoRoot?: string, ): Promise { - // `gh:` (and any github ref without an explicit repo) maps to - // microsoft/typespec explicitly. - const repo = ref.repo ?? DEFAULT_REPO; + // A github ref without an explicit `owner/repo` (e.g. `gh:main`) maps to the + // repo the tool is running in, detected from its origin remote. + const repo = ref.repo ?? (await detectOriginRepo(repoRoot, log)); const gitRef = ref.gitRef ?? "main"; assertSafeRepo(repo); assertSafeGitRef(gitRef); @@ -219,82 +264,6 @@ async function fetchAndResolveCommit(cacheRepo: string, gitRef: string): Promise return sha; } -/** - * Install a published npm package version into an isolated dir and return the - * path to the installed package (which ships a prebuilt `dist`). - */ -export async function installNpmPackage( - packageName: string, - version: string, - workDir: string, - log: Logger, -): Promise { - const dir = ensureDir( - join(workDir, `npm-${packageName.replace(/[@/]/g, "_")}-${sanitize(version)}`), - ); - const pkgDir = join(dir, "node_modules", packageName); - if (existsSync(pkgDir)) { - assertInstalledPackageMetadata(pkgDir, packageName, version); - log.info(`Reusing installed ${packageName}@${version}`); - return pkgDir; - } - - log.step(`Installing ${packageName}@${version}`); - // Create a deterministic throwaway package root and install just one - // dependency there. - const manifest = join(dir, "package.json"); - if (!existsSync(manifest)) { - writeFileSync( - manifest, - `${JSON.stringify({ name: "emitter-diff-cache", private: true, version: "0.0.0" }, null, 2)}\n`, - "utf8", - ); - } - - // Install only the requested package and skip lifecycle scripts. - await runChecked( - "npm", - [ - "install", - `${packageName}@${version}`, - "--no-audit", - "--no-fund", - "--no-save", - "--ignore-scripts", - ], - { cwd: dir }, - ); - assertInstalledPackageMetadata(pkgDir, packageName, version); - return pkgDir; -} - -function assertInstalledPackageMetadata( - pkgDir: string, - expectedName: string, - expectedVersion: string, -): void { - const manifest = join(pkgDir, "package.json"); - if (!existsSync(manifest)) { - throw new Error(`Installed package manifest not found: ${manifest}`); - } - - let parsed: { name?: string; version?: string }; - try { - parsed = JSON.parse(readFileSync(manifest, "utf8")) as { name?: string; version?: string }; - } catch (err) { - throw new Error(`Could not parse installed package manifest at ${manifest}: ${String(err)}`, { - cause: err, - }); - } - - if (parsed.name !== expectedName || parsed.version !== expectedVersion) { - throw new Error( - `Installed package metadata mismatch at ${manifest}. ` + - `Expected ${expectedName}@${expectedVersion}, got ${parsed.name ?? ""}@${parsed.version ?? ""}.`, - ); - } -} - function sanitize(s: string): string { return s.replace(/[^a-z0-9._-]/gi, "-").slice(0, 40); } diff --git a/eng/emitter-diff/src/types.ts b/eng/emitter-diff/src/types.ts index fd2a95fcabc..e649b3bf453 100644 --- a/eng/emitter-diff/src/types.ts +++ b/eng/emitter-diff/src/types.ts @@ -1,18 +1,22 @@ /** * Core language-agnostic types for emitter-diff. - * Language-specific behavior stays behind {@link EmitterAdapter}. + * + * The tool is a generic command runner: it resolves a baseline and a head + * source tree, runs the emitter's own regenerate command verbatim inside each + * tree, then diffs the generated output. There is no per-language plugin code β€” + * an emitter integrates by describing three things (see {@link EmitterConfig}). */ /** The three kinds of source a ref can point at. */ export type RefKind = "npm" | "local" | "github"; /** - * A classified reference to either an emitter version or a specs source. + * A classified reference to an emitter source tree. * * Accepted user syntaxes (see {@link classifyRef}): - * - npm: `npm:1.2.3`, `1.2.3`, `@scope/pkg@1.2.3` + * - npm: `npm:1.2.3`, `1.2.3`, `@scope/pkg@1.2.3` (rejected β€” no source tree) * - local: `local:/abs/or/rel/path`, or any existing filesystem path - * - github: `github:owner/repo@`, `gh:` (microsoft/typespec), or an `https://github.com/...` url + * - github: `github:owner/repo@`, `gh:` (this repo's origin), or an `https://github.com/...` url */ export interface ClassifiedRef { kind: RefKind; @@ -22,76 +26,43 @@ export interface ClassifiedRef { version?: string; /** local: the absolute path on disk. */ path?: string; - /** github: `owner/repo` (defaults to `microsoft/typespec` when omitted). */ + /** github: `owner/repo` (defaults to this repo's origin remote when omitted). */ repo?: string; /** github: branch, tag or sha. */ gitRef?: string; } -/** A usable emitter prepared by an adapter. */ -export interface ResolvedEmitter { - /** Directory containing the usable emitter build. */ - dir: string; - /** Human-readable label for logs (e.g. `npm @typespec/http-client-python@0.34.0`). */ - label: string; -} - -/** Shared context handed to every adapter call. */ -export interface AdapterContext { - /** Repo root (the git working tree the tool was invoked from). */ - repoRoot: string; - /** Scratch directory the adapter may use for builds/installs. */ - workDir: string; - /** Structured logger. */ - log: Logger; +/** + * Everything the runner needs to diff one emitter. An emitter either passes + * these as flags or selects a named preset (see `EMITTER_DEFAULTS`) that fills + * them in; every field remains individually overridable. + */ +export interface EmitterConfig { /** - * Core helper that materializes a {@link ClassifiedRef} into a local source - * directory (handles `local` passthrough and `github` fetch). For `npm`, the - * adapter typically resolves the package itself via {@link installNpmPackage}. + * The regenerate command, run verbatim (tokenized to argv, no shell) inside + * `/` for each side. Example: `npm run regenerate`. */ - resolveSource(ref: ClassifiedRef, packageName: string): Promise; - /** Core helper that installs an npm package version and returns its dir. */ - installNpmPackage(packageName: string, version: string): Promise; -} - -export interface GenerateRequest { - /** Resolved emitter build to generate with. */ - emitter: ResolvedEmitter; - /** Directory the generated code must be written to. */ - outputDir: string; - /** Optional adapter generated-code subpath under `outputDir`. */ - generatedCodePath?: string; - /** Optional name/pattern filter limiting which specs/packages are generated. */ - nameFilter?: string; - /** Adapter-specific options collected from repeatable `--opt key=value`. */ - options: Record; - /** Arguments after `--`, forwarded verbatim. */ - passthrough: string[]; + command: string; /** - * Optional log prefix used when baseline/head generate concurrently. + * Path (relative to a source tree root) to the emitter package the command is + * run in. Example: `packages/http-client-python`. Use `.` for a repo-root + * emitter. */ - logPrefix?: string; -} - -/** - * Per-language plugin. A thin wrapper over an emitter's own generate command. - * The core never reaches around this contract. - */ -export interface EmitterAdapter { - /** Stable id used by `--emitter` (e.g. `python`). */ - readonly name: string; - /** npm package name, used when a ref is an npm version. */ - readonly packageName: string; - + emitterPath: string; /** - * Turn a classified ref (or the special `current` checkout) into a usable, - * built emitter. `npm` versions ship prebuilt; `local`/`github`/`current` - * may need a build, which is the adapter's responsibility. + * Path (relative to `emitterPath`) to the generated code the command writes. + * This subtree is snapshotted and diffed. Example: `tests/generated`. */ - prepareEmitter(ref: ClassifiedRef | "current", ctx: AdapterContext): Promise; - - /** Generate code into `request.outputDir` using `request.emitter`. */ - generate(request: GenerateRequest, ctx: AdapterContext): Promise; + generatedCodePath: string; + /** + * Optional prep commands run in order in `/` before the + * regenerate command β€” but ONLY for a tree the tool freshly materialized from + * GitHub (a `gh:`/`github:` ref). The current working tree and user-provided + * `local:` paths are assumed already built and are never touched. Each entry + * is tokenized to argv and run without a shell. Example: + * `["pnpm install", "npm run setup"]`. + */ + setup?: string[]; } export interface Logger { diff --git a/packages/http-client-python/eng/scripts/ci/regenerate.ts b/packages/http-client-python/eng/scripts/ci/regenerate.ts index 17df6e00e2c..e6c8cee1110 100644 --- a/packages/http-client-python/eng/scripts/ci/regenerate.ts +++ b/packages/http-client-python/eng/scripts/ci/regenerate.ts @@ -94,34 +94,8 @@ const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url)); const PLUGIN_DIR = argv.values.pluginDir ? resolve(argv.values.pluginDir) : resolve(SCRIPT_DIR, "../../../"); - -function resolveSpecsDir(packageName: string, envOverride?: string): string { - const fromEnv = envOverride?.trim(); - if (fromEnv) { - const candidate = resolve(fromEnv); - if (existsSync(candidate)) return candidate; - } - - const candidates = [ - resolve(PLUGIN_DIR, `node_modules/${packageName}/specs`), - resolve(SCRIPT_DIR, `../../../node_modules/${packageName}/specs`), - resolve(SCRIPT_DIR, `../../../../node_modules/${packageName}/specs`), - resolve(SCRIPT_DIR, `../../../../../node_modules/${packageName}/specs`), - ]; - - for (const candidate of candidates) { - if (existsSync(candidate)) return candidate; - } - - // Keep the preferred plugin-dir location for diagnostics. - return candidates[0]; -} - -const AZURE_HTTP_SPECS = resolveSpecsDir( - "@azure-tools/azure-http-specs", - process.env.AZURE_HTTP_SPECS_DIR, -); -const HTTP_SPECS = resolveSpecsDir("@typespec/http-specs", process.env.HTTP_SPECS_DIR); +const AZURE_HTTP_SPECS = resolve(PLUGIN_DIR, "node_modules/@azure-tools/azure-http-specs/specs"); +const HTTP_SPECS = resolve(PLUGIN_DIR, "node_modules/@typespec/http-specs/specs"); const GENERATED_FOLDER = argv.values.generatedFolder ? resolve(argv.values.generatedFolder) : resolve(PLUGIN_DIR, "generator"); @@ -157,12 +131,7 @@ async function collectConfigFiles(generatedDir: string, flavor: string): Promise return configFiles; } -function runBatchPythonProcessing( - flavor: string, - generatedFolder: string, - configCount: number, - jobs: number, -): boolean { +function runBatchPythonProcessing(flavor: string, configCount: number, jobs: number): boolean { if (configCount === 0) return true; console.log(pc.cyan(`\nRunning batch Python processing on ${configCount} specs...`)); @@ -181,10 +150,9 @@ function runBatchPythonProcessing( const batchScript = join(PLUGIN_DIR, "eng", "scripts", "setup", "run_batch.py"); try { - const generatedRoot = resolve(generatedFolder, ".."); // Pass directory and flavor instead of individual config files to avoid command line length limits on Windows execSync( - `"${venvPath}" "${batchScript}" --generated-dir "${generatedRoot}" --flavor ${flavor} --jobs ${jobs}`, + `"${venvPath}" "${batchScript}" --generated-dir "${PLUGIN_DIR}" --flavor ${flavor} --jobs ${jobs}`, { stdio: "inherit", cwd: PLUGIN_DIR, @@ -212,18 +180,8 @@ async function regenerateFlavor( await preprocess(flavor, GENERATED_FOLDER); // Collect specs - const azureSpecs = - flavor === "azure" && existsSync(AZURE_HTTP_SPECS) - ? await getSubdirectories(AZURE_HTTP_SPECS, flags) - : []; - if (flavor === "azure" && !existsSync(AZURE_HTTP_SPECS)) { - console.warn(pc.yellow(`Azure specs not found at: ${AZURE_HTTP_SPECS}`)); - } - - const standardSpecs = existsSync(HTTP_SPECS) ? await getSubdirectories(HTTP_SPECS, flags) : []; - if (!existsSync(HTTP_SPECS)) { - console.warn(pc.yellow(`HTTP specs not found at: ${HTTP_SPECS}`)); - } + const azureSpecs = flavor === "azure" ? await getSubdirectories(AZURE_HTTP_SPECS, flags) : []; + const standardSpecs = await getSubdirectories(HTTP_SPECS, flags); const allSpecs = [...azureSpecs, ...standardSpecs]; // Build task groups (tasks for same spec run sequentially to avoid state pollution). @@ -259,7 +217,7 @@ async function regenerateFlavor( const configCount = (await collectConfigFiles(GENERATED_FOLDER, flavor)).length; // Use fewer Python jobs since Python processing is heavier const pyJobs = Math.max(4, jobs); - const pySuccess = runBatchPythonProcessing(flavor, GENERATED_FOLDER, configCount, pyJobs); + const pySuccess = runBatchPythonProcessing(flavor, configCount, pyJobs); const pyTime = (performance.now() - pyStartTime) / 1000; const totalTime = (performance.now() - startTime) / 1000; diff --git a/packages/http-client-python/generator/pygen/codegen/templates/version.py.jinja2 b/packages/http-client-python/generator/pygen/codegen/templates/version.py.jinja2 index 2086d0fc1d7..acb3e831650 100644 --- a/packages/http-client-python/generator/pygen/codegen/templates/version.py.jinja2 +++ b/packages/http-client-python/generator/pygen/codegen/templates/version.py.jinja2 @@ -3,4 +3,6 @@ {{ code_model.license_header }} {% endif %} +# test + VERSION = "{{ code_model.options.get("package-version") }}" From b0502d11c0625752d05df14aed3125af689772a8 Mon Sep 17 00:00:00 2001 From: Libba Lawrence Date: Mon, 6 Jul 2026 12:58:01 -0700 Subject: [PATCH 32/52] update --- eng/emitter-diff/README.md | 30 ++++++++++++++- eng/emitter-diff/src/cli.ts | 66 ++++++++++++++++++++++++++------ eng/emitter-diff/src/resolver.ts | 24 ++++++++++++ 3 files changed, 106 insertions(+), 14 deletions(-) diff --git a/eng/emitter-diff/README.md b/eng/emitter-diff/README.md index b3d184981cf..7b1d71eff96 100644 --- a/eng/emitter-diff/README.md +++ b/eng/emitter-diff/README.md @@ -98,11 +98,37 @@ prints a `file://` link to it. - `--baseline ` / `--head `: the two source trees to compare. - `--setup ` (repeatable) / `--no-setup`: prep commands for freshly fetched GitHub trees. - `--work-dir `: scratch dir for snapshots (default: a fresh temp dir). +- `--sequential`: regenerate baseline then head one after another instead of in parallel. Useful on + a single machine where running both at once oversubscribes the CPU (each regenerate already fans + out across cores) or trips generator races. - `--ci`: disable the local baseline-output cache (intended for CI). - `--html `: write the rendered HTML report to this path. - `--fail-on-diff`: exit non-zero when output differs (exit `2` = diff present, `1` = hard error). -- `-- `: everything after `--` is appended to `--command` verbatim (e.g. to pass a name - filter through to the regenerate script). +- `-- `: everything after `--` is appended to `--command` verbatim on **both** sides, so the + diff stays apples-to-apples. Use it to regenerate only a subset of tests by forwarding the + regenerate script's own filter flags. + +### Regenerating a subset of tests + +The tool doesn't define its own test-filter flags β€” it forwards `-- ` to each emitter's +regenerate command, which owns the filtering. For the **Python** emitter (`regenerate.ts`): + +- `-n, --name `: case-insensitive substring match on package name. +- `-f, --flavor `: limit to one flavor. +- `-j, --jobs `: parallel job count. + +```sh +# Only the authentication packages, azure flavor +npx tsx ../../eng/emitter-diff/src/cli.ts --emitter python -- --name authentication --flavor azure + +# Via the package script (first `--` is npm's, second is emitter-diff's passthrough separator) +npm run diff-spector-tests -- -- --name type/array +``` + +`--name` filters the spec set already bundled in the package's `node_modules` +(`@azure-tools/azure-http-specs` + `@typespec/http-specs`); it does not point the test set at an +arbitrary folder or ref. Other emitters expose their own filter flags β€” pass whatever their +regenerate command accepts. ## CI integration diff --git a/eng/emitter-diff/src/cli.ts b/eng/emitter-diff/src/cli.ts index 2a8f75807b1..0d19892e05d 100644 --- a/eng/emitter-diff/src/cli.ts +++ b/eng/emitter-diff/src/cli.ts @@ -24,7 +24,7 @@ import { } from "./baseline-cache.js"; import { diffDirs, printSummary, writeHtml } from "./diff.js"; import { getEmitterDefaults, listEmitters } from "./registry.js"; -import { classifyRef, defaultWorkDir, describeRef, materializeTree } from "./resolver.js"; +import { classifyRef, defaultWorkDir, describeRef, materializeTree, resolveGithubIdentity } from "./resolver.js"; import type { ClassifiedRef, EmitterConfig, Logger } from "./types.js"; import { color, createLogger, ensureDir, run, runChecked } from "./util.js"; @@ -74,10 +74,14 @@ ${color.bold("Options:")} otherwise gh:origin/main. --head New source tree. Default: the current working tree. --work-dir Scratch dir for snapshots. Default: a fresh temp dir. + --sequential Regenerate baseline then head one after another instead + of in parallel (avoids CPU oversubscription / races). --ci CI mode: disable local baseline cache. --html Write the rendered HTML diff (default: /emitter-diff.html). --fail-on-diff Exit non-zero when output differs (2 = diff, 1 = error). - -- Everything after -- is appended to verbatim. + -- Everything after -- is appended to verbatim + on both sides (e.g. a regenerate --name/--filter flag to + diff only a subset of tests). -h, --help Show this help. `; @@ -152,8 +156,7 @@ function resolveConfig( const command = values.command ?? preset.command; const emitterPath = values["emitter-path"] ?? preset.emitterPath; - const generatedCodePath = - values["generated-code-path"] ?? preset.generatedCodePath; + const generatedCodePath = values["generated-code-path"] ?? preset.generatedCodePath; const missing: string[] = []; if (!command) missing.push("--command"); @@ -179,7 +182,12 @@ function resolveConfig( setup = preset.setup ?? []; } - return { command: command!, emitterPath: emitterPath!, generatedCodePath: generatedCodePath!, setup }; + return { + command: command!, + emitterPath: emitterPath!, + generatedCodePath: generatedCodePath!, + setup, + }; } async function main(): Promise { @@ -202,6 +210,7 @@ async function main(): Promise { baseline: { type: "string" }, head: { type: "string" }, "work-dir": { type: "string" }, + sequential: { type: "boolean" }, ci: { type: "boolean" }, html: { type: "string" }, "fail-on-diff": { type: "boolean" }, @@ -242,14 +251,24 @@ async function main(): Promise { ? classifyRef(values.head, repoRoot) : "current"; - log.step("Resolving baseline source tree"); - const baselineTree = await materializeTree(baselineRef, workDir, log, repoRoot); + // Baseline source tree is materialized lazily: a cheap SHA resolve up front + // lets a baseline-output cache hit skip the expensive worktree checkout + + // regenerate. Only a cache miss (or a non-github ref) pays for materializing. + let baselineTree: string | undefined; const baselineLabel = describeRef(baselineRef, config.emitterPath); + const ensureBaselineTree = async (): Promise => { + if (baselineTree === undefined) { + log.step("Resolving baseline source tree"); + baselineTree = await materializeTree(baselineRef, workDir, log, repoRoot); + } + return baselineTree; + }; log.step("Resolving head source tree"); const headTree = headRef === "current" ? repoRoot : await materializeTree(headRef, workDir, log, repoRoot); - const headLabel = headRef === "current" ? "current working tree" : describeRef(headRef, config.emitterPath); + const headLabel = + headRef === "current" ? "current working tree" : describeRef(headRef, config.emitterPath); const baselineSnap = ensureDir(join(workDir, "baseline")); const headSnap = ensureDir(join(workDir, "head")); @@ -321,10 +340,15 @@ async function main(): Promise { const useBaselineCache = cacheDecision.enabled; if (!useBaselineCache) { log.info( - color.dim(`baseline cache disabled${cacheDecision.reason ? ` (${cacheDecision.reason})` : ""}`), + color.dim( + `baseline cache disabled${cacheDecision.reason ? ` (${cacheDecision.reason})` : ""}`, + ), ); } - const baselineIdentity = await detectBaselineIdentity(baselineTree); + const baselineIdentity = + baselineRef.kind === "github" + ? await resolveGithubIdentity(baselineRef, repoRoot, log) + : await detectBaselineIdentity(await ensureBaselineTree()); const baselineProfileKey = computeBaselineProfileKey({ emitter: values.emitter, baselineRef: baselineRefValue, @@ -381,9 +405,21 @@ async function main(): Promise { if (baselineReused) { await runSide("Head", headTree, headSnap, headLabel, undefined, headSetup); + } else if (values.sequential) { + const baselineTreePath = await ensureBaselineTree(); + await runSide("Baseline", baselineTreePath, baselineSnap, baselineLabel, undefined, baselineSetup); + await runSide("Head", headTree, headSnap, headLabel, undefined, headSetup); } else { + const baselineTreePath = await ensureBaselineTree(); await Promise.all([ - runSide("Baseline", baselineTree, baselineSnap, baselineLabel, color.dim("[baseline] "), baselineSetup), + runSide( + "Baseline", + baselineTreePath, + baselineSnap, + baselineLabel, + color.dim("[baseline] "), + baselineSetup, + ), runSide("Head", headTree, headSnap, headLabel, color.cyan("[head] "), headSetup), ]); } @@ -398,7 +434,11 @@ async function main(): Promise { } rmSync(baselineCache.dir, { recursive: true, force: true }); cpSync(baselineSnap, baselineCache.dir, { recursive: true, force: true }); - writeFileSync(baselineCache.marker, `${new Date().toISOString()} ${baselineIdentity}\n`, "utf8"); + writeFileSync( + baselineCache.marker, + `${new Date().toISOString()} ${baselineIdentity}\n`, + "utf8", + ); const index = readBaselineCacheIndex(); index[baselineProfileKey] = { baselineIdentity, updatedAt: new Date().toISOString() }; writeBaselineCacheIndex(index); @@ -408,6 +448,8 @@ async function main(): Promise { } // Diff. + log.info(`${color.dim("Baseline Generated Output:")} ${baselineSnap}`); + log.info(`${color.dim("Head Generated Output:")} ${headSnap}`); const diff = await diffDirs(baselineSnap, headSnap, log); const htmlTarget = values.html ?? join(workDir, "emitter-diff.html"); diff --git a/eng/emitter-diff/src/resolver.ts b/eng/emitter-diff/src/resolver.ts index fc52779c5a8..520ca8ec19d 100644 --- a/eng/emitter-diff/src/resolver.ts +++ b/eng/emitter-diff/src/resolver.ts @@ -264,6 +264,30 @@ async function fetchAndResolveCommit(cacheRepo: string, gitRef: string): Promise return sha; } +/** + * Resolve a github ref to its immutable identity (`git:`) WITHOUT + * materializing a worktree. This is a shallow fetch only, so a caller can + * validate a commit-keyed output cache and skip the expensive checkout + + * regenerate entirely on a hit. The returned format matches the `git:` + * identity `detectBaselineIdentity` computes from a checked-out tree. + */ +export async function resolveGithubIdentity( + ref: ClassifiedRef, + repoRoot: string | undefined, + log: Logger, +): Promise { + if (ref.kind !== "github") { + throw new Error(`resolveGithubIdentity requires a github ref, got '${ref.kind}'.`); + } + const repo = ref.repo ?? (await detectOriginRepo(repoRoot, log)); + const gitRef = ref.gitRef ?? "main"; + assertSafeRepo(repo); + assertSafeGitRef(gitRef); + const cacheRepo = await ensureCacheRepo(repo, log); + const sha = await fetchAndResolveCommit(cacheRepo, gitRef); + return `git:${sha}`; +} + function sanitize(s: string): string { return s.replace(/[^a-z0-9._-]/gi, "-").slice(0, 40); } From 853a1203f814b8b25008b6d9ea8300df15e3580c Mon Sep 17 00:00:00 2001 From: Libba Lawrence Date: Mon, 6 Jul 2026 12:59:54 -0700 Subject: [PATCH 33/52] Format emitter-diff and document test-subset filtering Run prettier over eng/emitter-diff and document the -- passthrough for filtering which tests regenerate (Python --name/--flavor/--jobs), plus the --sequential flag. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- eng/emitter-diff/README.md | 24 ++++++++++++------------ eng/emitter-diff/src/cli.ts | 17 +++++++++++++++-- 2 files changed, 27 insertions(+), 14 deletions(-) diff --git a/eng/emitter-diff/README.md b/eng/emitter-diff/README.md index 7b1d71eff96..2f51f980c11 100644 --- a/eng/emitter-diff/README.md +++ b/eng/emitter-diff/README.md @@ -21,7 +21,7 @@ either as flags or via a built-in `--emitter` preset. - A **source tree** is resolved for each side (`--baseline` / `--head`). - The **`--command`** is run verbatim (tokenized to argv β€” no shell) inside - `/`. This is the emitter's *unmodified* regenerate command; the tool does + `/`. This is the emitter's _unmodified_ regenerate command; the tool does not reach into it. - The `/` subtree is snapshotted for each side and the two snapshots are diffed. @@ -49,12 +49,12 @@ npx tsx eng/emitter-diff/src/cli.ts \ ### Emitter config -| Flag | Meaning | -| -------------------------------- | ------------------------------------------------------------ | -| `--emitter ` | Built-in preset that fills in the three fields below. | -| `--command ` | Regenerate command, run verbatim in `--emitter-path`. | -| `--emitter-path ` | Package dir (relative to a tree root) to run the command in. | -| `--generated-code-path ` | Generated-code dir (relative to `--emitter-path`) to diff. | +| Flag | Meaning | +| ------------------------------ | ------------------------------------------------------------ | +| `--emitter ` | Built-in preset that fills in the three fields below. | +| `--command ` | Regenerate command, run verbatim in `--emitter-path`. | +| `--emitter-path ` | Package dir (relative to a tree root) to run the command in. | +| `--generated-code-path ` | Generated-code dir (relative to `--emitter-path`) to diff. | A preset supplies all three; each flag still overrides the preset value. To onboard a new language, add a row to `EMITTER_DEFAULTS` in `src/registry.ts` β€” or just pass the three flags directly and @@ -62,11 +62,11 @@ skip `--emitter`. ### Refs -| Syntax | Meaning | -| --------------------------------- | ------------------------------------------ | -| `local:/path` or `./path` | a local source folder (run in place) | -| `github:owner/repo@` | a GitHub source at a ref | -| `gh:` | this repo (origin remote) at a ref | +| Syntax | Meaning | +| --------------------------------- | ------------------------------------ | +| `local:/path` or `./path` | a local source folder (run in place) | +| `github:owner/repo@` | a GitHub source at a ref | +| `gh:` | this repo (origin remote) at a ref | `--head` defaults to the **current working tree**. `--baseline` defaults to `gh:upstream/main` when present, otherwise `gh:origin/main` (`origin/HEAD` as a fallback). diff --git a/eng/emitter-diff/src/cli.ts b/eng/emitter-diff/src/cli.ts index 0d19892e05d..cead22ae685 100644 --- a/eng/emitter-diff/src/cli.ts +++ b/eng/emitter-diff/src/cli.ts @@ -24,7 +24,13 @@ import { } from "./baseline-cache.js"; import { diffDirs, printSummary, writeHtml } from "./diff.js"; import { getEmitterDefaults, listEmitters } from "./registry.js"; -import { classifyRef, defaultWorkDir, describeRef, materializeTree, resolveGithubIdentity } from "./resolver.js"; +import { + classifyRef, + defaultWorkDir, + describeRef, + materializeTree, + resolveGithubIdentity, +} from "./resolver.js"; import type { ClassifiedRef, EmitterConfig, Logger } from "./types.js"; import { color, createLogger, ensureDir, run, runChecked } from "./util.js"; @@ -407,7 +413,14 @@ async function main(): Promise { await runSide("Head", headTree, headSnap, headLabel, undefined, headSetup); } else if (values.sequential) { const baselineTreePath = await ensureBaselineTree(); - await runSide("Baseline", baselineTreePath, baselineSnap, baselineLabel, undefined, baselineSetup); + await runSide( + "Baseline", + baselineTreePath, + baselineSnap, + baselineLabel, + undefined, + baselineSetup, + ); await runSide("Head", headTree, headSnap, headLabel, undefined, headSetup); } else { const baselineTreePath = await ensureBaselineTree(); From 8a18839e27abab8eff1d9eabd8e144c91aadebd1 Mon Sep 17 00:00:00 2001 From: Libba Lawrence Date: Mon, 6 Jul 2026 13:09:22 -0700 Subject: [PATCH 34/52] foward args --- eng/emitter-diff/src/cli.ts | 26 ++++++++++++++++++++++++-- 1 file changed, 24 insertions(+), 2 deletions(-) diff --git a/eng/emitter-diff/src/cli.ts b/eng/emitter-diff/src/cli.ts index cead22ae685..ff958b017eb 100644 --- a/eng/emitter-diff/src/cli.ts +++ b/eng/emitter-diff/src/cli.ts @@ -135,6 +135,27 @@ function tokenizeCommand(command: string): string[] { return tokens; } +/** + * Build the full argv (command args + passthrough) for a regenerate command. + * + * `npm`/`pnpm`/`yarn run