@azure-tools/typespec-azure-examples 0.1.0 → 0.2.0-dev.2

package/README.md

@@ -1,7 +1,7 @@
 # @azure-tools/typespec-azure-examples
 
 Tooling for the Azure **unified examples format** (`examples.yaml`): the published JSON Schema
-and the `tsp-examples` CLI.
+and the `tsp-examples` CLI, plus the transitional `tsp-examples-migrate` tool.
 
 The unified examples format replaces the ~282K per-version `x-ms-examples` JSON files with a
 single version-aware `examples.yaml` per service (or `examples/<Interface>.yaml` for large
@@ -70,6 +70,49 @@ found (use `--warn-as-error` to also fail on warnings).
 - `{api-version}` is the only supported placeholder, and `api-version` must not appear as a
   request parameter.
 
+## `tsp-examples-migrate`
+
+> **Transitional tool.** Used to bulk-convert existing specs during rollout; it will be removed
+> once services author `examples.yaml` directly.
+
+Convert a service's existing `x-ms-examples` JSON into the unified format:
+
+```bash
+tsp-examples-migrate <spec-dir> --out <service-dir>
+```
+
+It crawls the versioned Swagger under `<spec-dir>` (the `stable/<version>/` and
+`preview/<version>/` layout), follows each operation's `x-ms-examples` `$ref`, and emits a single
+`examples.yaml` (or `examples/<Interface>.yaml` with `--split-by-interface`). The generated output
+is validated with the same rules as `tsp-examples validate` before it is written.
+
+If a `service.yaml` sits in `<spec-dir>` (or is passed with `--service`), its version list is
+treated as authoritative: it defines the version order and any on-disk swagger version _not_ listed
+there is ignored, so every generated `since` references a real service version.
+
+What it does:
+
+- Derives interface-relative operation keys from the Swagger `operationId` (`CaCertificates_Get` →
+  `CaCertificates.get`) under a single `$namespace` (detected from `/providers/<Namespace>/`, or
+  set with `--namespace`).
+- Buckets each example parameter into `request.path` / `query` / `headers` / `body` using the
+  operation's declared parameter locations, and drops the implicit `api-version`.
+- Normalizes embedded version strings (in `Location`, `Azure-AsyncOperation`, `nextLink`, ...) to
+  the `{api-version}` placeholder, then dedupes identical examples across versions into `since`
+  lineages — one base entry plus a `since` variant whenever the content changes.
+
+Options: `--out <dir>` (default `.`), `--namespace <ns>`, `--service <path>`,
+`--split-by-interface`, `--dry-run`, `--warn-as-error`.
+
+### Known limitation: examples removed in a later version
+
+The format has a `since` ("applies from") marker but no `until`/removal marker, so an example that
+existed in an earlier version but was **dropped** in a later one is still re-materialized for the
+later versions (its base entry applies from its first appearance onward). Migration flags each such
+lineage with an `example-removed-before-latest` **warning** so the author can confirm it still
+applies to later versions, or delete it. Services that rely on removing examples across versions are
+not yet fully supported.
+
 ## API
 
 ```ts
@@ -77,7 +120,10 @@ import {
   validateExamplesDir,
   validateExampleFiles,
   loadExampleFile,
+  migrate,
 } from "@azure-tools/typespec-azure-examples";
 
 const { diagnostics } = await validateExamplesDir("path/to/service");
+
+const { files } = await migrate("path/to/specs", { namespace: "Microsoft.EventGrid" });
 ```

package/dist/src/index.d.ts

@@ -5,6 +5,7 @@
  */
 export { discoverExampleFiles, validateExamplesDir, type ValidateDirResult } from "./discover.js";
 export { isQuotedScalar, loadExampleFile, locationAt, parseServiceVersions, positionAt, type LoadedExampleFile, type Position, } from "./loader.js";
+export * from "./migrate/index.js";
 export { defaultLegacyExampleFilename, slugify, stripJsonExtension } from "./naming.js";
 export { formatDiagnostics, formatSummary } from "./reporter.js";
 export { checkFilePlacement, checkSemantics, type SemanticContext } from "./rules.js";

package/dist/src/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,KAAK,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAClG,OAAO,EACL,cAAc,EACd,eAAe,EACf,UAAU,EACV,oBAAoB,EACpB,UAAU,EACV,KAAK,iBAAiB,EACtB,KAAK,QAAQ,GACd,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,4BAA4B,EAAE,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACxF,OAAO,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AACjE,OAAO,EAAE,kBAAkB,EAAE,cAAc,EAAE,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AACtF,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACjD,YAAY,EACV,kBAAkB,EAClB,iBAAiB,EACjB,cAAc,EACd,eAAe,EACf,cAAc,EACd,eAAe,GAChB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,KAAK,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAClG,OAAO,EACL,cAAc,EACd,eAAe,EACf,UAAU,EACV,oBAAoB,EACpB,UAAU,EACV,KAAK,iBAAiB,EACtB,KAAK,QAAQ,GACd,MAAM,aAAa,CAAC;AACrB,cAAc,oBAAoB,CAAC;AACnC,OAAO,EAAE,4BAA4B,EAAE,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACxF,OAAO,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AACjE,OAAO,EAAE,kBAAkB,EAAE,cAAc,EAAE,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AACtF,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACjD,YAAY,EACV,kBAAkB,EAClB,iBAAiB,EACjB,cAAc,EACd,eAAe,EACf,cAAc,EACd,eAAe,GAChB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC"}

package/dist/src/index.js

@@ -5,6 +5,7 @@
  */
 export { discoverExampleFiles, validateExamplesDir } from "./discover.js";
 export { isQuotedScalar, loadExampleFile, locationAt, parseServiceVersions, positionAt, } from "./loader.js";
+export * from "./migrate/index.js";
 export { defaultLegacyExampleFilename, slugify, stripJsonExtension } from "./naming.js";
 export { formatDiagnostics, formatSummary } from "./reporter.js";
 export { checkFilePlacement, checkSemantics } from "./rules.js";

package/dist/src/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,oBAAoB,EAAE,mBAAmB,EAA0B,MAAM,eAAe,CAAC;AAClG,OAAO,EACL,cAAc,EACd,eAAe,EACf,UAAU,EACV,oBAAoB,EACpB,UAAU,GAGX,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,4BAA4B,EAAE,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACxF,OAAO,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AACjE,OAAO,EAAE,kBAAkB,EAAE,cAAc,EAAwB,MAAM,YAAY,CAAC;AACtF,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AASjD,OAAO,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,oBAAoB,EAAE,mBAAmB,EAA0B,MAAM,eAAe,CAAC;AAClG,OAAO,EACL,cAAc,EACd,eAAe,EACf,UAAU,EACV,oBAAoB,EACpB,UAAU,GAGX,MAAM,aAAa,CAAC;AACrB,cAAc,oBAAoB,CAAC;AACnC,OAAO,EAAE,4BAA4B,EAAE,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACxF,OAAO,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AACjE,OAAO,EAAE,kBAAkB,EAAE,cAAc,EAAwB,MAAM,YAAY,CAAC;AACtF,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AASjD,OAAO,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC"}

package/dist/src/migrate/dedup.d.ts

@@ -0,0 +1,32 @@
+import type { MigratedVariant } from "./model.js";
+/** One example as collected from the crawl, prior to lineage collapsing. */
+export interface CollectedExample {
+    /** The API version this example was found under. */
+    readonly version: string;
+    /** The `x-ms-examples` map key, used as the lineage title. */
+    readonly exampleName: string;
+    /** The original `x-ms-examples` file name (basename of the `$ref`). */
+    readonly fileName: string;
+    /** The transformed + api-version-normalized variant content. */
+    readonly variant: MigratedVariant;
+}
+export interface BuildLineagesOptions {
+    /** The Swagger `operationId` of the operation (used to reconstruct the default file name/key). */
+    readonly operationId: string;
+    /** Ascending comparator over version strings (lowest/earliest first). */
+    readonly compareVersions: (a: string, b: string) => number;
+    /**
+     * The earliest version across the whole migration. When a lineage's first appearance is later
+     * than this, its base entry gets a `since` so migration stays faithful. When omitted, the
+     * earliest entry of each lineage is always the base (no `since`).
+     */
+    readonly baselineVersion?: string;
+}
+/**
+ * Collapse an operation's collected examples into unified variants: group by lineage (example
+ * name), order by version, keep one base entry, and emit a `since` variant only when the content
+ * changes from the previously-emitted entry. If the operation has a single lineage, the `title` is
+ * omitted (single-example case).
+ */
+export declare function buildLineages(examples: readonly CollectedExample[], options: BuildLineagesOptions): MigratedVariant[];
+//# sourceMappingURL=dedup.d.ts.map

package/dist/src/migrate/dedup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dedup.d.ts","sourceRoot":"","sources":["../../../src/migrate/dedup.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD,4EAA4E;AAC5E,MAAM,WAAW,gBAAgB;IAC/B,oDAAoD;IACpD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,8DAA8D;IAC9D,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,uEAAuE;IACvE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,gEAAgE;IAChE,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;CACnC;AAED,MAAM,WAAW,oBAAoB;IACnC,kGAAkG;IAClG,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,yEAAyE;IACzE,QAAQ,CAAC,eAAe,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;IAC3D;;;;OAIG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;CACnC;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,SAAS,gBAAgB,EAAE,EACrC,OAAO,EAAE,oBAAoB,GAC5B,eAAe,EAAE,CA2CnB"}

package/dist/src/migrate/dedup.js

@@ -0,0 +1,99 @@
+import { defaultLegacyExampleFilename, stripJsonExtension } from "../naming.js";
+/**
+ * Collapse an operation's collected examples into unified variants: group by lineage (example
+ * name), order by version, keep one base entry, and emit a `since` variant only when the content
+ * changes from the previously-emitted entry. If the operation has a single lineage, the `title` is
+ * omitted (single-example case).
+ */
+export function buildLineages(examples, options) {
+    const byName = new Map();
+    for (const example of examples) {
+        const group = byName.get(example.exampleName);
+        if (group)
+            group.push(example);
+        else
+            byName.set(example.exampleName, [example]);
+    }
+    const singleLineage = byName.size <= 1;
+    const result = [];
+    for (const [name, group] of byName) {
+        const ordered = [...group].sort((a, b) => options.compareVersions(a.version, b.version));
+        let lastContent;
+        let isFirst = true;
+        for (const entry of ordered) {
+            const content = canonicalize(entry.variant);
+            if (!isFirst && content === lastContent)
+                continue;
+            const variant = {
+                request: entry.variant.request,
+                responses: entry.variant.responses,
+            };
+            assignNaming(variant, {
+                operationId: options.operationId,
+                key: name,
+                fileName: entry.fileName,
+                singleLineage,
+            });
+            const introduceSince = !isFirst ||
+                (options.baselineVersion !== undefined && entry.version !== options.baselineVersion);
+            if (introduceSince)
+                variant.since = entry.version;
+            result.push(orderKeys(variant));
+            lastContent = content;
+            isFirst = false;
+        }
+    }
+    return result;
+}
+/** Stable, key-order-independent serialization used to compare variant content for equality. */
+function canonicalize(variant) {
+    return JSON.stringify(sortValue({ request: variant.request, responses: variant.responses }));
+}
+function sortValue(value) {
+    if (Array.isArray(value))
+        return value.map(sortValue);
+    if (value !== null && typeof value === "object") {
+        const out = {};
+        for (const key of Object.keys(value).sort()) {
+            out[key] = sortValue(value[key]);
+        }
+        return out;
+    }
+    return value;
+}
+/** Present keys in the canonical emission order: title, since, legacyFilename, request, responses. */
+function orderKeys(variant) {
+    return {
+        ...(variant.title !== undefined ? { title: variant.title } : {}),
+        ...(variant.since !== undefined ? { since: variant.since } : {}),
+        ...(variant.legacyFilename !== undefined ? { legacyFilename: variant.legacyFilename } : {}),
+        request: variant.request,
+        responses: variant.responses,
+    };
+}
+/**
+ * Assign the minimal `title` / `legacyFilename` needed for the emitter to reconstruct the original
+ * x-ms-examples key and file name. Both are omitted whenever they follow the default convention
+ * (key = `operationId`, file = `<operationId>.json`), so the common case stays clean.
+ */
+function assignNaming(variant, info) {
+    const { operationId, key, fileName, singleLineage } = info;
+    if (singleLineage) {
+        // Both key and file name are the defaults => nothing to store.
+        if (key === operationId && fileName === defaultLegacyExampleFilename(operationId)) {
+            return;
+        }
+        // The key is recoverable from the file name (`Foo.json` -> key `Foo`) => store only the file.
+        if (key === stripJsonExtension(fileName)) {
+            variant.legacyFilename = fileName;
+            return;
+        }
+    }
+    // Otherwise the key must be stored as `title` (also required to disambiguate multiple lineages);
+    // the file name only needs storing when it deviates from the `operationId`+`title` default.
+    variant.title = key;
+    if (fileName !== defaultLegacyExampleFilename(operationId, key)) {
+        variant.legacyFilename = fileName;
+    }
+}
+//# sourceMappingURL=dedup.js.map

package/dist/src/migrate/dedup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dedup.js","sourceRoot":"","sources":["../../../src/migrate/dedup.ts"],"names":[],"mappings":"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"}

package/dist/src/migrate/emit.d.ts

@@ -0,0 +1,28 @@
+import type { MigratedVariant } from "./model.js";
+/** A single emitted file: a repo-relative path and its serialized YAML content. */
+export interface EmittedFile {
+    readonly path: string;
+    readonly content: string;
+}
+/** One operation's key and its collapsed variants. */
+export interface OperationEntry {
+    readonly operationKey: string;
+    readonly variants: MigratedVariant[];
+}
+/**
+ * Build the plain object for an `examples.yaml` file: `$namespace` (optional) followed by one
+ * key per operation. Operations are emitted in sorted key order for deterministic output.
+ */
+export declare function buildExamplesObject(entries: readonly OperationEntry[], namespace: string | undefined): Record<string, unknown>;
+/** Serialize an examples object to YAML, force-quoting `since` values so they stay strings. */
+export declare function serializeExamplesYaml(object: Record<string, unknown>): string;
+/**
+ * Plan the output files. When `splitByInterface` is set (or the interface count exceeds
+ * `autoSplitThreshold`), each interface goes to `examples/<Interface>.yaml`; otherwise everything
+ * goes to a single top-level `examples.yaml`. Every file repeats `$namespace`.
+ */
+export declare function planFiles(entries: readonly OperationEntry[], namespace: string | undefined, options?: {
+    splitByInterface?: boolean;
+    autoSplitThreshold?: number;
+}): EmittedFile[];
+//# sourceMappingURL=emit.d.ts.map

package/dist/src/migrate/emit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"emit.d.ts","sourceRoot":"","sources":["../../../src/migrate/emit.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAGlD,mFAAmF;AACnF,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,sDAAsD;AACtD,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,QAAQ,EAAE,eAAe,EAAE,CAAC;CACtC;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,SAAS,cAAc,EAAE,EAClC,SAAS,EAAE,MAAM,GAAG,SAAS,GAC5B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAOzB;AAED,+FAA+F;AAC/F,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAyB7E;AAgBD;;;;GAIG;AACH,wBAAgB,SAAS,CACvB,OAAO,EAAE,SAAS,cAAc,EAAE,EAClC,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,OAAO,GAAE;IAAE,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAAC,kBAAkB,CAAC,EAAE,MAAM,CAAA;CAAO,GACxE,WAAW,EAAE,CA+Bf"}

package/dist/src/migrate/emit.js

@@ -0,0 +1,87 @@
+import { Document, isPair, isScalar, Scalar, visit } from "yaml";
+import { interfaceOf } from "./operation-key.js";
+/**
+ * Build the plain object for an `examples.yaml` file: `$namespace` (optional) followed by one
+ * key per operation. Operations are emitted in sorted key order for deterministic output.
+ */
+export function buildExamplesObject(entries, namespace) {
+    const object = {};
+    if (namespace !== undefined)
+        object.$namespace = namespace;
+    for (const entry of [...entries].sort((a, b) => a.operationKey.localeCompare(b.operationKey))) {
+        object[entry.operationKey] = entry.variants;
+    }
+    return object;
+}
+/** Serialize an examples object to YAML, force-quoting `since` values so they stay strings. */
+export function serializeExamplesYaml(object) {
+    const doc = new Document(object);
+    visit(doc, {
+        Pair(_, pair, path) {
+            if (isScalar(pair.key) &&
+                pair.key.value === "since" &&
+                isScalar(pair.value) &&
+                typeof pair.value.value === "string") {
+                pair.value.type = Scalar.QUOTE_DOUBLE;
+            }
+            // Emit response status codes as bare integer keys (`200:`), matching the RFC idiom.
+            // Converting the key to a number makes yaml render it unquoted.
+            if (isScalar(pair.key) &&
+                typeof pair.key.value === "string" &&
+                /^\d+$/.test(pair.key.value) &&
+                isUnderResponses(path)) {
+                pair.key.value = Number(pair.key.value);
+            }
+        },
+    });
+    return doc.toString();
+}
+/** Whether the visited node sits inside a `responses` mapping. */
+function isUnderResponses(path) {
+    // Only the status-code keys are direct children of a `responses` mapping. Walking up to the
+    // nearest enclosing Pair (rather than any ancestor) avoids rewriting numeric-looking keys nested
+    // inside a response body or headers, e.g. a body map key such as "001".
+    for (let i = path.length - 1; i >= 0; i--) {
+        const node = path[i];
+        if (isPair(node)) {
+            return isScalar(node.key) && node.key.value === "responses";
+        }
+    }
+    return false;
+}
+/**
+ * Plan the output files. When `splitByInterface` is set (or the interface count exceeds
+ * `autoSplitThreshold`), each interface goes to `examples/<Interface>.yaml`; otherwise everything
+ * goes to a single top-level `examples.yaml`. Every file repeats `$namespace`.
+ */
+export function planFiles(entries, namespace, options = {}) {
+    const interfaces = new Set(entries.map((e) => interfaceOf(e.operationKey)));
+    const shouldSplit = options.splitByInterface === true ||
+        (options.splitByInterface !== false &&
+            options.autoSplitThreshold !== undefined &&
+            interfaces.size > options.autoSplitThreshold);
+    if (!shouldSplit) {
+        return [
+            {
+                path: "examples.yaml",
+                content: serializeExamplesYaml(buildExamplesObject(entries, namespace)),
+            },
+        ];
+    }
+    const byInterface = new Map();
+    for (const entry of entries) {
+        const iface = interfaceOf(entry.operationKey);
+        const group = byInterface.get(iface);
+        if (group)
+            group.push(entry);
+        else
+            byInterface.set(iface, [entry]);
+    }
+    return [...byInterface.entries()]
+        .sort((a, b) => a[0].localeCompare(b[0]))
+        .map(([iface, group]) => ({
+        path: `examples/${iface}.yaml`,
+        content: serializeExamplesYaml(buildExamplesObject(group, namespace)),
+    }));
+}
+//# sourceMappingURL=emit.js.map

package/dist/src/migrate/emit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"emit.js","sourceRoot":"","sources":["../../../src/migrate/emit.ts"],"names":[],"mappings":"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"}

package/dist/src/migrate/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * `tsp-examples-migrate`: convert classic `x-ms-examples` JSON into the unified `examples.yaml` format.
+ */
+export { buildLineages, type BuildLineagesOptions, type CollectedExample } from "./dedup.js";
+export { buildExamplesObject, planFiles, serializeExamplesYaml, type EmittedFile, type OperationEntry, } from "./emit.js";
+export { migrate, type MigrateOptions, type MigrateResult } from "./migrate.js";
+export type { MigratedRequest, MigratedResponse, MigratedVariant } from "./model.js";
+export { normalizeApiVersion, normalizeApiVersions } from "./normalize.js";
+export { deriveOperationKey, interfaceOf } from "./operation-key.js";
+export { collectParamLocations, crawlExamples, discoverSwaggerFiles, extractOperations, namespaceFromPaths, resolveLocalParam, resolveRefPath, versionFromPath, type CrawlResult, type CrawledExample, type ExtractedOperation, } from "./swagger.js";
+export { transformExample } from "./transform.js";
+export { comparatorFromOrder, defaultCompareVersions, earliestVersion, latestVersion, } from "./version-order.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/src/migrate/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/migrate/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAE,aAAa,EAAE,KAAK,oBAAoB,EAAE,KAAK,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAC7F,OAAO,EACL,mBAAmB,EACnB,SAAS,EACT,qBAAqB,EACrB,KAAK,WAAW,EAChB,KAAK,cAAc,GACpB,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,OAAO,EAAE,KAAK,cAAc,EAAE,KAAK,aAAa,EAAE,MAAM,cAAc,CAAC;AAChF,YAAY,EAAE,eAAe,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AACrF,OAAO,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAC3E,OAAO,EAAE,kBAAkB,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACrE,OAAO,EACL,qBAAqB,EACrB,aAAa,EACb,oBAAoB,EACpB,iBAAiB,EACjB,kBAAkB,EAClB,iBAAiB,EACjB,cAAc,EACd,eAAe,EACf,KAAK,WAAW,EAChB,KAAK,cAAc,EACnB,KAAK,kBAAkB,GACxB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,EACL,mBAAmB,EACnB,sBAAsB,EACtB,eAAe,EACf,aAAa,GACd,MAAM,oBAAoB,CAAC"}

package/dist/src/migrate/index.js

@@ -0,0 +1,12 @@
+/**
+ * `tsp-examples-migrate`: convert classic `x-ms-examples` JSON into the unified `examples.yaml` format.
+ */
+export { buildLineages } from "./dedup.js";
+export { buildExamplesObject, planFiles, serializeExamplesYaml, } from "./emit.js";
+export { migrate } from "./migrate.js";
+export { normalizeApiVersion, normalizeApiVersions } from "./normalize.js";
+export { deriveOperationKey, interfaceOf } from "./operation-key.js";
+export { collectParamLocations, crawlExamples, discoverSwaggerFiles, extractOperations, namespaceFromPaths, resolveLocalParam, resolveRefPath, versionFromPath, } from "./swagger.js";
+export { transformExample } from "./transform.js";
+export { comparatorFromOrder, defaultCompareVersions, earliestVersion, latestVersion, } from "./version-order.js";
+//# sourceMappingURL=index.js.map

package/dist/src/migrate/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/migrate/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAE,aAAa,EAAoD,MAAM,YAAY,CAAC;AAC7F,OAAO,EACL,mBAAmB,EACnB,SAAS,EACT,qBAAqB,GAGtB,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,OAAO,EAA2C,MAAM,cAAc,CAAC;AAEhF,OAAO,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAC3E,OAAO,EAAE,kBAAkB,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACrE,OAAO,EACL,qBAAqB,EACrB,aAAa,EACb,oBAAoB,EACpB,iBAAiB,EACjB,kBAAkB,EAClB,iBAAiB,EACjB,cAAc,EACd,eAAe,GAIhB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,EACL,mBAAmB,EACnB,sBAAsB,EACtB,eAAe,EACf,aAAa,GACd,MAAM,oBAAoB,CAAC"}

package/dist/src/migrate/migrate.d.ts

@@ -0,0 +1,40 @@
+import type { ExampleDiagnostic } from "../types.js";
+import { type EmittedFile } from "./emit.js";
+/** Options controlling a migration run. */
+export interface MigrateOptions {
+    /** Override the detected `$namespace`. */
+    readonly namespace?: string;
+    /**
+     * Authoritative version order (e.g. from `service.yaml`). When omitted, a date-based heuristic
+     * is used over the versions discovered while crawling.
+     */
+    readonly versionOrder?: readonly string[];
+    /** Force (or disable) splitting output into `examples/<Interface>.yaml`. */
+    readonly splitByInterface?: boolean;
+    /** When `splitByInterface` is undefined, auto-split above this interface count. */
+    readonly autoSplitThreshold?: number;
+}
+/** The outcome of a migration run. */
+export interface MigrateResult {
+    /** The files to write (relative paths + serialized YAML). */
+    readonly files: EmittedFile[];
+    /** The namespace used (detected or overridden). */
+    readonly namespace?: string;
+    /** The versions discovered while crawling. */
+    readonly versions: string[];
+    /** The number of operations migrated. */
+    readonly operationCount: number;
+    /**
+     * Warnings surfaced during migration — currently, example lineages that stop appearing before the
+     * service's latest version. The unified format has no removal marker, so such an example is
+     * re-materialized for every version from its last appearance onward; the migrator flags it so the
+     * author can confirm it still applies (or remove it).
+     */
+    readonly diagnostics: ExampleDiagnostic[];
+}
+/**
+ * Migrate a tree of versioned Swagger specs with `x-ms-examples` into the unified `examples.yaml`
+ * format. Pure aside from reading the input tree (it does not write files).
+ */
+export declare function migrate(root: string, options?: MigrateOptions): Promise<MigrateResult>;
+//# sourceMappingURL=migrate.d.ts.map

package/dist/src/migrate/migrate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrate.d.ts","sourceRoot":"","sources":["../../../src/migrate/migrate.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAErD,OAAO,EAAa,KAAK,WAAW,EAAuB,MAAM,WAAW,CAAC;AAY7E,2CAA2C;AAC3C,MAAM,WAAW,cAAc;IAC7B,0CAA0C;IAC1C,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B;;;OAGG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1C,4EAA4E;IAC5E,QAAQ,CAAC,gBAAgB,CAAC,EAAE,OAAO,CAAC;IACpC,mFAAmF;IACnF,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;CACtC;AAED,sCAAsC;AACtC,MAAM,WAAW,aAAa;IAC5B,6DAA6D;IAC7D,QAAQ,CAAC,KAAK,EAAE,WAAW,EAAE,CAAC;IAC9B,mDAAmD;IACnD,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,8CAA8C;IAC9C,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,CAAC;IAC5B,yCAAyC;IACzC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,EAAE,iBAAiB,EAAE,CAAC;CAC3C;AAED;;;GAGG;AACH,wBAAsB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,aAAa,CAAC,CAyDhG"}

package/dist/src/migrate/migrate.js

@@ -0,0 +1,98 @@
+import { buildLineages } from "./dedup.js";
+import { planFiles } from "./emit.js";
+import { normalizeApiVersion } from "./normalize.js";
+import { deriveOperationKey } from "./operation-key.js";
+import { crawlExamples } from "./swagger.js";
+import { transformExample } from "./transform.js";
+import { comparatorFromOrder, defaultCompareVersions, earliestVersion, latestVersion, } from "./version-order.js";
+/**
+ * Migrate a tree of versioned Swagger specs with `x-ms-examples` into the unified `examples.yaml`
+ * format. Pure aside from reading the input tree (it does not write files).
+ */
+export async function migrate(root, options = {}) {
+    const crawl = await crawlExamples(root);
+    const namespace = options.namespace ?? crawl.namespace;
+    const compareVersions = options.versionOrder
+        ? comparatorFromOrder(options.versionOrder)
+        : defaultCompareVersions;
+    const baselineVersion = options.versionOrder
+        ? options.versionOrder[0]
+        : earliestVersion(crawl.versions, compareVersions);
+    // When an authoritative version order is supplied (e.g. from `service.yaml`), it is the source of
+    // truth: examples found under on-disk versions that are not listed there are ignored, so the
+    // generated `since` values always reference a real service version.
+    const allowedVersions = options.versionOrder ? new Set(options.versionOrder) : undefined;
+    const byOperation = new Map();
+    const operationIds = new Map();
+    for (const crawled of crawl.examples) {
+        if (allowedVersions !== undefined && !allowedVersions.has(crawled.version))
+            continue;
+        const operationKey = deriveOperationKey(crawled.operationId);
+        operationIds.set(operationKey, crawled.operationId);
+        const variant = normalizeApiVersion(transformExample(crawled.doc, crawled.paramLocations), crawled.version);
+        const collected = {
+            version: crawled.version,
+            exampleName: crawled.exampleName,
+            fileName: crawled.fileName,
+            variant,
+        };
+        const group = byOperation.get(operationKey);
+        if (group)
+            group.push(collected);
+        else
+            byOperation.set(operationKey, [collected]);
+    }
+    const entries = [];
+    for (const [operationKey, collected] of byOperation) {
+        entries.push({
+            operationKey,
+            variants: buildLineages(collected, {
+                operationId: operationIds.get(operationKey),
+                compareVersions,
+                baselineVersion,
+            }),
+        });
+    }
+    const files = planFiles(entries, namespace, {
+        splitByInterface: options.splitByInterface,
+        autoSplitThreshold: options.autoSplitThreshold,
+    });
+    const versions = options.versionOrder ? [...options.versionOrder] : crawl.versions;
+    const diagnostics = collectRemovalDiagnostics(byOperation, versions, compareVersions);
+    return { files, namespace, versions, operationCount: entries.length, diagnostics };
+}
+/**
+ * Flag example lineages that stop appearing before the latest version. Because the unified format
+ * has no removal marker, such an example would be re-materialized for versions it never shipped in,
+ * so the author should confirm it still applies (or drop it).
+ */
+function collectRemovalDiagnostics(byOperation, versions, compareVersions) {
+    const latest = latestVersion(versions, compareVersions);
+    if (latest === undefined)
+        return [];
+    const diagnostics = [];
+    for (const [operationKey, collected] of byOperation) {
+        const lastByLineage = new Map();
+        for (const example of collected) {
+            const current = lastByLineage.get(example.exampleName);
+            if (current === undefined || compareVersions(example.version, current) > 0) {
+                lastByLineage.set(example.exampleName, example.version);
+            }
+        }
+        for (const [lineage, lastSeen] of lastByLineage) {
+            if (compareVersions(lastSeen, latest) < 0) {
+                diagnostics.push({
+                    code: "example-removed-before-latest",
+                    message: `Example "${lineage}" for operation "${operationKey}" last appears in "${lastSeen}", ` +
+                        `before the latest version "${latest}". The unified format has no removal marker, so it ` +
+                        `will be re-materialized for every version from "${lastSeen}" onward — confirm it still ` +
+                        `applies to later versions, or remove it.`,
+                    severity: "warning",
+                    file: "examples.yaml",
+                });
+            }
+        }
+    }
+    return diagnostics;
+}
+//# sourceMappingURL=migrate.js.map

package/dist/src/migrate/migrate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrate.js","sourceRoot":"","sources":["../../../src/migrate/migrate.ts"],"names":[],"mappings":"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"}

package/dist/src/migrate/model.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Internal representation of a migrated example variant, prior to lineage assignment.
+ * Mirrors the `Example` shape in the schema but is mutable while being assembled.
+ */
+export interface MigratedRequest {
+    path?: Record<string, unknown>;
+    query?: Record<string, unknown>;
+    headers?: Record<string, unknown>;
+    body?: unknown;
+}
+export interface MigratedResponse {
+    headers?: Record<string, unknown>;
+    body?: unknown;
+}
+export interface MigratedVariant {
+    title?: string;
+    since?: string;
+    legacyFilename?: string;
+    request: MigratedRequest;
+    responses: Record<string, MigratedResponse>;
+}
+//# sourceMappingURL=model.d.ts.map

package/dist/src/migrate/model.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model.d.ts","sourceRoot":"","sources":["../../../src/migrate/model.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,OAAO,EAAE,eAAe,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;CAC7C"}

package/dist/src/migrate/model.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=model.js.map

package/dist/src/migrate/model.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"model.js","sourceRoot":"","sources":["../../../src/migrate/model.ts"],"names":[],"mappings":""}

package/dist/src/migrate/normalize.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Normalize embedded concrete API-version strings to the `{api-version}` placeholder.
+ *
+ * `x-ms-examples` frequently bake the api-version into header and body string values
+ * (`Location`, `Azure-AsyncOperation`, `nextLink`, ...). Replacing those with `{api-version}`
+ * lets otherwise-identical variants across versions collapse into a single lineage entry.
+ */
+/** Recursively replace occurrences of `version` in string values with `{api-version}`. */
+export declare function normalizeApiVersion<T>(value: T, version: string): T;
+/**
+ * Normalize using any of the provided versions (longest first, so more specific version strings
+ * win over prefixes).
+ */
+export declare function normalizeApiVersions<T>(value: T, versions: readonly string[]): T;
+//# sourceMappingURL=normalize.d.ts.map

package/dist/src/migrate/normalize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize.d.ts","sourceRoot":"","sources":["../../../src/migrate/normalize.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,0FAA0F;AAC1F,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,MAAM,GAAG,CAAC,CAEnE;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,CAAC,CAIhF"}