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..b2788cbe296 --- /dev/null +++ b/.github/workflows/ci-emitter-diff-python.yml @@ -0,0 +1,205 @@ +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 approved baseline SHA file." + 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 + 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" + + - 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" \ + --fail-on-diff \ + | tee "${{ runner.temp }}/emitter-diff.log" + echo "status=${PIPESTATUS[0]}" >> "$GITHUB_OUTPUT" + + - name: Write job summary + if: always() + run: | + { + echo "## Emitter diff" + echo "" + 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." + 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.sha }} + 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` + + `Approved baseline \`${process.env.BASELINE}\` vs this PR's checkout.\n\n`; + if (!hasChanges) { + 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`; + } + 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\`._`; + + 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 }); + } + + - 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/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 diff --git a/eng/emitter-diff/README.md b/eng/emitter-diff/README.md new file mode 100644 index 00000000000..61f4401588b --- /dev/null +++ b/eng/emitter-diff/README.md @@ -0,0 +1,180 @@ +# @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. 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 + 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. + +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/baselines/python.sha b/eng/emitter-diff/baselines/python.sha new file mode 100644 index 00000000000..ddcae32bc9a --- /dev/null +++ b/eng/emitter-diff/baselines/python.sha @@ -0,0 +1,10 @@ +# 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. +# +# 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 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..ddd83fdb712 --- /dev/null +++ b/eng/emitter-diff/src/adapters/python.ts @@ -0,0 +1,217 @@ +/** + * 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[], + 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")); +} + +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, { 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 { + 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..a526be5bd64 --- /dev/null +++ b/eng/emitter-diff/src/cli.ts @@ -0,0 +1,262 @@ +#!/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). 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). + -- 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 }, + sequential: { type: "boolean" }, + 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. 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")); + + 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); + + // 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."); + // 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; +} + +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..9505b013851 --- /dev/null +++ b/eng/emitter-diff/src/diff.ts @@ -0,0 +1,235 @@ +/** + * 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 { + // 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", + }); + 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..d89a00582cc --- /dev/null +++ b/eng/emitter-diff/src/types.ts @@ -0,0 +1,122 @@ +/** + * 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[]; + /** + * 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 { + /** 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..3ef50e4c7d2 --- /dev/null +++ b/eng/emitter-diff/src/util.ts @@ -0,0 +1,167 @@ +/** + * 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). 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; prefix?: string } = {}, +): 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 = ""; + + // 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) => { + 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; + 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; prefix?: string } = {}, +): 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..9fdc12b8b52 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,11 +106,19 @@ 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"); +// 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 = { @@ -152,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, @@ -256,7 +276,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