Renhe Li (lirenhe) · Nov 3, 2026 · Sep 3, 2026 · Sep 4, 2026 · Sep 4, 2026 · Sep 4, 2026
@@ -1,3 +1,3 @@
 self-hosted-runner:
  labels:
    - 1ES.Pool=azsdk-pool-github-runners
@@ -15,6 +15,16 @@
     ignore:
       - ".+"
 
+  .github/workflows/sdk-breaking-change-analysis.yaml:
+    ignore:
+      # actionlint 1.7.12 predates GitHub's copilot-requests permission scope.
+      - 'unknown permission scope "copilot-requests"'
+
+  .github/workflows/sdk-breaking-change-mitigate.yaml:
+    ignore:
+      # actionlint 1.7.12 predates GitHub's copilot-requests permission scope.
+      - 'unknown permission scope "copilot-requests"'
+
   # Also generated by gh-aw
   # cspell:ignore agentics
   .github/workflows/agentics-maintenance.yml:

@@ -1,3 +1,3 @@
 {
  "name": "azure-rest-api-specs-github",
  "version": "0.0.0",
@@ -9,10 +9,12 @@
   },
   "dependencies": {
     "@apidevtools/json-schema-ref-parser": "catalog:",
+    "@azure-tools/spec-gen-sdk-runner": "workspace:*",
     "@azure-tools/specs-shared": "workspace:*",
     "@js-temporal/polyfill": "catalog:",
     "cross-spawn": "catalog:",
     "debug": "catalog:",
+    "fflate": "catalog:",
     "marked": "catalog:",
     "markdown-table": "catalog:",
     "minimatch": "catalog:",
@@ -38,7 +40,6 @@
     "@types/node": "catalog:",
     "@types/semver": "catalog:",
     "@vitest/utils": "catalog:",
-    "fflate": "catalog:",
     "semver": "catalog:",
     "tinybench": "catalog:"
   },

@@ -1,3 +1,3 @@
 # `.github/shared`

 Shared TypeScript helper library (`@azure-tools/specs-shared`) used by tooling and GitHub Actions
@@ -172,7 +172,8 @@
 - `link(label, url)` — create a link from trusted inline Markdown and a trusted destination.
 - `table([header, ...rows])` — render equal-width GFM rows, escaping pipes and preserving line breaks.
 - `unorderedList(items)` — render Markdown list items, indenting continuation lines.
-- `details(summary, body)` — create a collapsible block with a plain-text summary and Markdown body.
+- `details(summary, body, open = false)` — create a collapsible block with a plain-text summary
+  and Markdown body; pass `true` to expand it by default.
 
 Like [TypeSpec's Markdown helpers](https://github.com/microsoft/typespec/blob/main/packages/tspd/src/ref-doc/utils/markdown.ts),
 callers describe the document structure rather than hand-joining every line. Strings are trusted
@@ -218,6 +219,8 @@
 ### `sdk-types` — SDK language types & schemas
 
 - `SdkName` — frozen enum of SDK language identifiers (Go/Java/Js/Net/Python/Rust).
+- `getSdkLanguage(repo)` — returns the SDK language name (for example, `JavaScript` for
+  `azure-sdk-for-js` and `DotNet` for `azure-sdk-for-net`); throws for unsupported repositories.
 - `SdkNameSchema`, `APIViewRequestDataSchema`, `SpecGenSdkArtifactInfoSchema` — zod schemas (plus
   inferred TypeScript types) for SDK tooling payloads.
 - `sdkLabels` — per-language SDK label configuration.

@@ -1,3 +1,3 @@
 /** A document made of trusted Markdown blocks, nested sections, and optional content. */
 export type MarkdownDoc = string | MarkdownSection | MarkdownDoc[] | undefined;

@@ -6,16 +6,18 @@
   kind: "section";
   title: string;
   body: MarkdownDoc;
+  id?: string;
 }
 
-/** Groups trusted inline Markdown and body blocks under a heading. */
-export function section(title: string, body: MarkdownDoc): MarkdownSection {
-  return { kind: "section", title, body };
+/** Groups trusted inline Markdown and body blocks under a heading with an optional anchor ID. */
+export function section(title: string, body: MarkdownDoc, id?: string): MarkdownSection {
+  return { kind: "section", title, body, ...(id === undefined ? {} : { id }) };
 }
 
 /** Renders document blocks with blank lines between them, omitting empty or absent blocks. */
 export function renderMarkdownDoc(doc: MarkdownDoc, heading = 1): string {
   const blocks: string[] = [];
+  const ids = new Set<string>();
 
   /** Flattens content while keeping nested heading levels local to each section. */
   function render(content: MarkdownDoc, level: number): void {
@@ -28,6 +30,18 @@
       if (!Number.isInteger(level) || level < 1 || level > 6) {
         throw new Error("Markdown headings must have a level from 1 to 6");
       }
+      if (content.id !== undefined) {
+        if (!/^[A-Za-z0-9_-]+$/.test(content.id)) {
+          throw new Error(
+            "Markdown heading IDs must contain only letters, digits, underscores or hyphens",
+          );
+        }
+        if (ids.has(content.id)) {
+          throw new Error(`Duplicate Markdown heading ID: ${content.id}`);
+        }
+        ids.add(content.id);
+        blocks.push(`<a name="${content.id}"></a>`);
+      }
       blocks.push(`${"#".repeat(level)} ${content.title}`);
       render(content.body, level + 1);
     }
@@ -105,9 +119,9 @@
 }
 
 /** Wraps a Markdown block in a GitHub details element with a plain-text summary. */
-export function details(summary: string, body: string): string {
+export function details(summary: string, body: string, open = false): string {
   return [
-    `<details><summary>${escapeHtml(summary)}</summary>`,
+    `<details${open ? " open" : ""}><summary>${escapeHtml(summary)}</summary>`,
     "",
     ...(body ? [body] : []),
     "",

@@ -1,3 +1,3 @@
 import * as z from "zod";

 /**
@@ -92,3 +92,11 @@
     buildFailed: undefined,
   },
 };
+
+export function getSdkLanguage(repo: SdkName): string {
+  const language = Object.entries(SdkName).find(([, repository]) => repository === repo)?.[0];
+  if (!language) {
+    throw new Error(`Unsupported SDK repository: ${repo}`);
+  }
+  return language === "Js" ? "JavaScript" : language === "Net" ? "DotNet" : language;
+}
@@ -1,3 +1,3 @@
 import { marked } from "marked";
 import { describe, expect, it } from "vitest";
 import {
@@ -47,6 +47,81 @@
     expect(renderMarkdownDoc(section("Title", "Body"), 6)).toBe("###### Title\n\nBody");
   });
 
+  it("preserves an explicit section ID and omits it when not supplied", () => {
+    expect(section("Title", "Body", "custom-id")).toEqual({
+      kind: "section",
+      title: "Title",
+      body: "Body",
+      id: "custom-id",
+    });
+    expect(section("Title", "Body")).not.toHaveProperty("id");
+    expect(section("Title", "Body", undefined)).not.toHaveProperty("id");
+  });
+
+  it("renders explicit anchors before headings without changing heading levels", () => {
+    const markdown = renderMarkdownDoc(
+      [
+        section(
+          "Analysis",
+          ["Body", section("Details", "Changes", "details_123")],
+          "breaking-change",
+        ),
+        section("Mitigation", undefined, "Mitigation"),
+        section("Without an ID", "Last"),
+      ],
+      2,
+    );
+    expect(markdown).toBe(d`
+      <a name="breaking-change"></a>
+
+      ## Analysis
+
+      Body
+
+      <a name="details_123"></a>
+
+      ### Details
+
+      Changes
+
+      <a name="Mitigation"></a>
+
+      ## Mitigation
+
+      ## Without an ID
+
+      Last
+    `);
+    expect(marked.parse(markdown)).toContain(
+      '<p><a name="breaking-change"></a></p>\n<h2>Analysis</h2>',
+    );
+  });
+
+  it.each(["", "has space", 'quote"id', "<tag>", "with/slash", "line\nbreak"])(
+    "rejects invalid heading ID %j",
+    (id) => {
+      expect(() => renderMarkdownDoc(section("Title", "Body", id))).toThrow(
+        "Markdown heading IDs must contain only letters, digits, underscores or hyphens",
+      );
+    },
+  );
+
+  it.each([
+    { doc: [section("First", "", "same-id"), section("Second", "", "same-id")] },
+    { doc: section("Parent", section("Child", "", "same-id"), "same-id") },
+  ])("rejects duplicate IDs across the document %#", ({ doc }) => {
+    expect(() => renderMarkdownDoc(doc)).toThrow("Duplicate Markdown heading ID: same-id");
+  });
+
+  it("allows repeated titles with distinct IDs and reuses IDs in separate renders", () => {
+    expect(renderMarkdownDoc([section("Title", "", "first"), section("Title", "", "second")])).toBe(
+      '<a name="first"></a>\n\n# Title\n\n<a name="second"></a>\n\n# Title',
+    );
+    const doc = section("Title", "", "reusable");
+    expect(renderMarkdownDoc(doc)).toBe('<a name="reusable"></a>\n\n# Title');
+    expect(renderMarkdownDoc(doc)).toBe('<a name="reusable"></a>\n\n# Title');
+  });
+
   it.each([0, -1, 1.5, 7])("rejects invalid heading level %s", (level) => {
     expect(() => renderMarkdownDoc(section("Title", ""), level)).toThrow("level from 1 to 6");
   });
@@ -175,4 +250,11 @@
     `);
     expect(details("Empty", "")).toBe("<details><summary>Empty</summary>\n\n\n</details>");
   });
+
+  it("supports expanded details without changing the default collapsed behavior", () => {
+    expect(details("<Changes>", "Body", true)).toBe(
+      "<details open><summary>&lt;Changes&gt;</summary>\n\nBody\n\n</details>",
+    );
+    expect(details("Changes", "Body", false)).toBe(details("Changes", "Body"));
+  });
 });
@@ -1,8 +1,30 @@
 import { describe, expect, it } from "vitest";
-import { sdkLabels, SpecGenSdkArtifactInfoSchema } from "../src/sdk-types.ts";
+import {
+  getSdkLanguage,
+  sdkLabels,
+  SdkName,
+  SpecGenSdkArtifactInfoSchema,
+} from "../src/sdk-types.ts";
 import { createMockSpecGenSdkArtifactInfo } from "./sdk-types.ts";
 
 describe("sdk-types", () => {
+  it.each([
+    [SdkName.Go, "Go"],
+    [SdkName.Java, "Java"],
+    [SdkName.Js, "JavaScript"],
+    [SdkName.Net, "DotNet"],
+    [SdkName.Python, "Python"],
+    [SdkName.Rust, "Rust"],
+  ])("returns the language name for %s", (repo, language) => {
+    expect(getSdkLanguage(repo)).toBe(language);
+  });
+
+  it("rejects unsupported SDK repositories", () => {
+    expect(() => getSdkLanguage("unknown-repository" as SdkName)).toThrow(
+      "Unsupported SDK repository: unknown-repository",
+    );
+  });
+
   it("defines sdkLabels", () => {
     // Ensures constant "sdkLabels" is considered "covered" by codecov
     expect(sdkLabels).toBeDefined();

@@ -1,3 +1,3 @@
 name: GitHub Actions - Test

 on:
@@ -11,6 +11,7 @@
       - pnpm-lock.yaml
       - pnpm-workspace.yaml
       - vitest.config.mts
+      - eng/tools/spec-gen-sdk-runner/**
       - eng/tools/vitest.base.config.ts
       - .npmrc
   pull_request:
@@ -21,6 +22,7 @@
       - pnpm-lock.yaml
       - pnpm-workspace.yaml
       - vitest.config.mts
+      - eng/tools/spec-gen-sdk-runner/**
       - eng/tools/vitest.base.config.ts
       - .npmrc
   workflow_dispatch:
@@ -58,6 +60,7 @@
           persist-credentials: false
           sparse-checkout: |
             .github
+            eng/tools/spec-gen-sdk-runner
 
       - if: ${{ github.event_name == 'pull_request' && matrix.os == 'ubuntu' }}
         name: Require compiled agentic workflow locks