@glubean/sdk 0.2.0 → 0.2.2

package/dist/contract-artifacts.d.ts

@@ -0,0 +1,268 @@
+/**
+ * @module contract-artifacts
+ *
+ * Contract artifact registry — declarative extension point for
+ * "contracts → X" rendering (markdown / openapi / future proto / sdl /
+ * asyncapi / ...).
+ *
+ * Replaces the v0.1 per-adapter `toMarkdown?` / `toOpenApi?` hooks which
+ * (a) polluted the generic `ContractProtocolAdapter` interface with
+ * protocol-specific artifacts (OpenAPI is HTTP-only), (b) had dead
+ * declarations that nothing called, and (c) gave consumers no way to
+ * enumerate "which artifact kinds does this project support".
+ *
+ * See `internal/40-discovery/proposals/contract-artifact-registry.md` (v6).
+ *
+ * ## Concepts
+ *
+ * **ArtifactKind**: first-class description of an output format (name +
+ * merge strategy + empty skeleton + optional defaultRender). Per-contract
+ * Part and final merged Final are independently typed (markdown renders
+ * structured parts that the merge assembles into a document; openapi
+ * renders per-contract partial documents that the merge stitches together).
+ *
+ * **ContractProtocolAdapter.artifacts**: each adapter declares which
+ * kinds it produces. Mapping from kind name to per-contract renderer.
+ *
+ * **Consumers**: `renderArtifact(kind, contracts, options?, control?)`
+ * dispatches across all registered adapters; fallback to kind.defaultRender
+ * where the adapter doesn't implement the kind; ultimate fallback to
+ * kind.empty when no contract contributes a part.
+ *
+ * ## Types
+ *
+ * `KnownArtifacts` / `KnownArtifactParts` / `KnownArtifactOptions` are
+ * declared at the package root (`packages/sdk/src/index.ts`) so third-
+ * party plugins can augment via `declare module "@glubean/sdk"`. This file
+ * imports them as types from the root so declaration merging hits the
+ * same node.
+ */
+import type { ExtractedContractProjection } from "./contract-types.js";
+import type { OpenApiDocument, OpenApiOptions } from "./contract-http/openapi.js";
+/**
+ * Declarative description of an artifact format.
+ *
+ * @template Final    Final merged value type (what consumers receive).
+ * @template Part     Per-contract partial type (what producer / defaultRender
+ *                    emit). Defaults to Final; distinct when per-contract
+ *                    rendering is structured (e.g. markdown produces
+ *                    `{ body, feature, caseCount }` parts and the merge
+ *                    assembles a feature-grouped doc string).
+ * @template Options  Per-render options type. Threaded through the entire
+ *                    pipeline (producer / defaultRender / merge) so kinds
+ *                    whose options affect per-contract rendering (e.g. proto
+ *                    `package` per message) are as well-served as kinds whose
+ *                    options only affect the final merge (e.g. openapi
+ *                    `title`).
+ */
+export interface ArtifactKind<Final, Part = Final, Options = void> {
+    /** Kind identifier (snake-case or kebab-case). Unique across the registry. */
+    readonly name: string;
+    /**
+     * Combine per-contract parts into the final artifact. Called once per
+     * render; receives the collected parts and the same options that were
+     * passed to producers / defaultRender.
+     */
+    readonly merge: (parts: Part[], options?: Options) => Final;
+    /**
+     * Optional fallback: when an adapter has not declared a producer for this
+     * kind, use this function to render a per-contract Part from the generic
+     * `ExtractedContractProjection`. Omitted for kinds that only make sense
+     * for specific protocols (e.g. openapi has no defaultRender — non-HTTP
+     * contracts are skipped).
+     */
+    readonly defaultRender?: (projection: ExtractedContractProjection<unknown, unknown>, options?: Options) => Part;
+    /**
+     * Required: the value returned by `renderArtifact` when no contract
+     * contributes a part. Must be a valid Final. Lets `renderArtifact` promise
+     * `Final` (not `Final | undefined`) and forces kind authors to think
+     * about the zero-contribution scenario explicitly.
+     */
+    readonly empty: Final;
+}
+/**
+ * Register an artifact kind by name. Idempotent when re-registering the same
+ * kind object; throws when a different object tries to take the same name
+ * (protects against typo-level collisions across plugins).
+ *
+ * `defineArtifactKind` is the ergonomic entry; this is exported for advanced
+ * scenarios where a kind is built separately from its registration.
+ */
+export declare function registerArtifactKind<Final, Part, Options>(kind: ArtifactKind<Final, Part, Options>): void;
+/**
+ * Look up a registered kind by name. Used by `renderArtifactByName` and any
+ * other string-driven consumer (CLI --format, MCP tool inputs, etc.).
+ */
+export declare function getArtifactKind(name: string): ArtifactKind<unknown, unknown, unknown> | undefined;
+/** List all registered kind names (insertion order). */
+export declare function listArtifactKinds(): string[];
+/**
+ * Define and register an artifact kind in one call. Preferred entry point
+ * for kind authors (SDK built-ins + first-party plugins).
+ */
+export declare function defineArtifactKind<Final, Part = Final, Options = void>(spec: ArtifactKind<Final, Part, Options>): ArtifactKind<Final, Part, Options>;
+/**
+ * Test-only: clear the kind registry. Not exposed publicly; imported by
+ * `contract-artifacts.test.ts` via relative path.
+ *
+ * @internal
+ */
+export declare function __resetArtifactKindsForTesting(): void;
+/**
+ * Control knobs for a single render invocation (orthogonal to kind-specific
+ * options). Kept separate from `options` so adding new flags here doesn't
+ * require each kind author to know about them.
+ */
+export interface RenderArtifactControl {
+    /**
+     * Skip each adapter's `artifacts[kind]` producer even when defined; force
+     * all contracts through `kind.defaultRender`. For kinds without a
+     * defaultRender, contracts are skipped entirely.
+     *
+     * Used by CLI `--generic` for reproducible output across installed
+     * plugin versions, and by tests that assert default-render behavior.
+     */
+    preferDefaultRender?: boolean;
+}
+/**
+ * Summary of a render invocation — per-contract classification of how each
+ * contract contributed (or was skipped) + a `usedEmptyFallback` boolean.
+ */
+export interface ArtifactContribution {
+    contractId: string;
+    protocol: string;
+    /** Whether the part came from the adapter's producer or kind.defaultRender. */
+    source: "explicit-producer" | "default-render";
+}
+export interface ArtifactSkip {
+    contractId: string;
+    protocol: string;
+    reason: "no-producer-no-default-render" | "prefer-default-render-no-default";
+}
+export interface ArtifactRenderSummary<Final> {
+    /** Same value `renderArtifact` would have returned. */
+    value: Final;
+    /** Contracts that produced a part. */
+    contributions: ArtifactContribution[];
+    /** Contracts that did not produce a part (with reason). */
+    skipped: ArtifactSkip[];
+    /**
+     * True iff `value === kind.empty` was returned because zero parts were
+     * collected. False when `kind.merge(parts, options)` was called. Callers
+     * should use this instead of comparing `value === kind.empty`
+     * themselves — merge typically returns a fresh object for object-typed
+     * Final, so identity / structural equality are not reliable.
+     */
+    usedEmptyFallback: boolean;
+}
+/**
+ * Render an artifact of the given kind from a list of contracts. Threads
+ * `options` through the producer / defaultRender / merge pipeline. When no
+ * contract contributes a part, returns `kind.empty` (guaranteed valid
+ * `Final`).
+ *
+ * Strong-typed entry point: kind argument is a concrete `ArtifactKind<...>`
+ * object, so `options` type and return type are inferred at compile time.
+ */
+export declare function renderArtifact<Final, Part, Options>(kind: ArtifactKind<Final, Part, Options>, contracts: ReadonlyArray<ExtractedContractProjection<unknown, unknown>>, options?: Options, control?: RenderArtifactControl): Final;
+/**
+ * Render an artifact and return the full summary (value + contributions +
+ * skipped + usedEmptyFallback). Use this when you need to distinguish
+ * "zero contribution" from "merged to kind.empty-shaped value" — the
+ * `usedEmptyFallback` field is the authoritative signal (do not compare
+ * `value === kind.empty` yourself for object-typed Final).
+ */
+export declare function renderArtifactWithSummary<Final, Part, Options>(kind: ArtifactKind<Final, Part, Options>, contracts: ReadonlyArray<ExtractedContractProjection<unknown, unknown>>, options?: Options, control?: RenderArtifactControl): ArtifactRenderSummary<Final>;
+/**
+ * Look up a kind by name and render. Used by string-driven consumers
+ * (CLI --format <name>, MCP tools, agent introspection). Throws when the
+ * name is not registered — the error message includes the list of
+ * registered kinds so callers can surface it without extra lookups.
+ *
+ * Returns `unknown` since we don't know the Final type statically;
+ * callers that need a typed return should use `renderArtifact` directly
+ * with the kind object they import.
+ */
+export declare function renderArtifactByName(kindName: string, contracts: ReadonlyArray<ExtractedContractProjection<unknown, unknown>>, options?: unknown, control?: RenderArtifactControl): unknown;
+/**
+ * List the protocols whose adapter **explicitly declares a producer** for
+ * the given kind. Does NOT include protocols that would fall back to
+ * `kind.defaultRender`. Use `listArtifactCapability` for the three-way split.
+ */
+export declare function listArtifactProducers(kindName: string): string[];
+/**
+ * Static capability view — **based on installed adapters**, not on any
+ * particular project's contracts. Partitions protocols into:
+ *
+ *   - `explicit`    : adapter declares a producer for this kind
+ *   - `fallback`    : adapter has no producer but kind.defaultRender exists
+ *   - `unsupported` : adapter has no producer and kind has no defaultRender
+ *
+ * To answer "does **this project** produce the artifact?", use
+ * `renderArtifactWithSummary` and inspect `contributions` + `usedEmptyFallback`.
+ * The capability view cannot know how many contracts of each protocol exist
+ * in the caller's project.
+ */
+export declare function listArtifactCapability(kindName: string): {
+    explicit: string[];
+    fallback: string[];
+    unsupported: string[];
+};
+/**
+ * OpenAPI 3.1 artifact kind. Per-contract partials are produced by HTTP
+ * adapter's `artifacts.openapi` (see `contract-http/openapi.ts`); merge
+ * combines them into a full spec. No `defaultRender` — non-HTTP protocols
+ * don't map to OpenAPI and are skipped.
+ *
+ * Ported from MCP's former `contractsToOpenApi` — CAR-1 Phase 2.
+ */
+export declare const openapiArtifact: ArtifactKind<OpenApiDocument, OpenApiDocument, OpenApiOptions>;
+/**
+ * Per-contract structured data consumed by `assembleMarkdownDocument`.
+ * Carries raw fields; the merge step handles feature grouping,
+ * instanceName-aware labeling, doc header, and summary counts.
+ */
+export interface MarkdownPart {
+    contractId: string;
+    /** Display target — equivalent to `projection.target`. */
+    endpoint: string;
+    protocol: string;
+    description?: string;
+    feature?: string;
+    instanceName?: string;
+    deprecated?: string;
+    cases: Array<{
+        key: string;
+        description?: string;
+        /** "active" | "deferred" | "deprecated". */
+        lifecycle: "active" | "deferred" | "deprecated";
+        severity: "critical" | "warning" | "info";
+        defaultRun?: "always" | "opt-in";
+        requires?: "headless" | "browser" | "out-of-band";
+        deferredReason?: string;
+        deprecatedReason?: string;
+    }>;
+}
+/**
+ * Protocol-agnostic default renderer. Reads raw fields off the
+ * projection; every protocol gets a valid Part even if its adapter
+ * doesn't declare `artifacts.markdown`.
+ */
+export declare function genericMarkdownPart(projection: ExtractedContractProjection<unknown, unknown>): MarkdownPart;
+/**
+ * Feature-grouped, doc-level markdown assembly. Byte-for-byte output
+ * compatible with `formatMdOutline` from `packages/cli/src/commands/
+ * contracts.ts` (the legacy CLI markdown path).
+ *
+ * Structure:
+ *   # Contract Specification
+ *   Generated: YYYY-MM-DD | N cases | N active | ...
+ *
+ *   ## <feature>
+ *   🚫 **Deprecated:** ...   (if contract-level deprecated)
+ *   <description or endpoint intro>
+ *   - **case** — ...
+ */
+export declare function assembleMarkdownDocument(parts: MarkdownPart[]): string;
+export declare const markdownArtifact: ArtifactKind<string, MarkdownPart, void>;
+//# sourceMappingURL=contract-artifacts.d.ts.map

package/dist/contract-artifacts.d.ts.map

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

package/dist/contract-artifacts.js

@@ -0,0 +1,402 @@
+/**
+ * @module contract-artifacts
+ *
+ * Contract artifact registry — declarative extension point for
+ * "contracts → X" rendering (markdown / openapi / future proto / sdl /
+ * asyncapi / ...).
+ *
+ * Replaces the v0.1 per-adapter `toMarkdown?` / `toOpenApi?` hooks which
+ * (a) polluted the generic `ContractProtocolAdapter` interface with
+ * protocol-specific artifacts (OpenAPI is HTTP-only), (b) had dead
+ * declarations that nothing called, and (c) gave consumers no way to
+ * enumerate "which artifact kinds does this project support".
+ *
+ * See `internal/40-discovery/proposals/contract-artifact-registry.md` (v6).
+ *
+ * ## Concepts
+ *
+ * **ArtifactKind**: first-class description of an output format (name +
+ * merge strategy + empty skeleton + optional defaultRender). Per-contract
+ * Part and final merged Final are independently typed (markdown renders
+ * structured parts that the merge assembles into a document; openapi
+ * renders per-contract partial documents that the merge stitches together).
+ *
+ * **ContractProtocolAdapter.artifacts**: each adapter declares which
+ * kinds it produces. Mapping from kind name to per-contract renderer.
+ *
+ * **Consumers**: `renderArtifact(kind, contracts, options?, control?)`
+ * dispatches across all registered adapters; fallback to kind.defaultRender
+ * where the adapter doesn't implement the kind; ultimate fallback to
+ * kind.empty when no contract contributes a part.
+ *
+ * ## Types
+ *
+ * `KnownArtifacts` / `KnownArtifactParts` / `KnownArtifactOptions` are
+ * declared at the package root (`packages/sdk/src/index.ts`) so third-
+ * party plugins can augment via `declare module "@glubean/sdk"`. This file
+ * imports them as types from the root so declaration merging hits the
+ * same node.
+ */
+import { getAdapter, listRegisteredProtocols, } from "./contract-core.js";
+import { emptyOpenApiDocument, mergeOpenApiParts, } from "./contract-http/openapi.js";
+// =============================================================================
+// Kind registry
+// =============================================================================
+const _kinds = new Map();
+/**
+ * Register an artifact kind by name. Idempotent when re-registering the same
+ * kind object; throws when a different object tries to take the same name
+ * (protects against typo-level collisions across plugins).
+ *
+ * `defineArtifactKind` is the ergonomic entry; this is exported for advanced
+ * scenarios where a kind is built separately from its registration.
+ */
+export function registerArtifactKind(kind) {
+    const existing = _kinds.get(kind.name);
+    if (existing) {
+        if (existing !== kind) {
+            throw new Error(`Artifact kind "${kind.name}" already registered with a different instance. ` +
+                `Ensure each kind is defined exactly once per process.`);
+        }
+        return;
+    }
+    _kinds.set(kind.name, kind);
+}
+/**
+ * Look up a registered kind by name. Used by `renderArtifactByName` and any
+ * other string-driven consumer (CLI --format, MCP tool inputs, etc.).
+ */
+export function getArtifactKind(name) {
+    return _kinds.get(name);
+}
+/** List all registered kind names (insertion order). */
+export function listArtifactKinds() {
+    return [..._kinds.keys()];
+}
+/**
+ * Define and register an artifact kind in one call. Preferred entry point
+ * for kind authors (SDK built-ins + first-party plugins).
+ */
+export function defineArtifactKind(spec) {
+    registerArtifactKind(spec);
+    return spec;
+}
+/**
+ * Test-only: clear the kind registry. Not exposed publicly; imported by
+ * `contract-artifacts.test.ts` via relative path.
+ *
+ * @internal
+ */
+export function __resetArtifactKindsForTesting() {
+    _kinds.clear();
+}
+/**
+ * Core render pipeline implementation — produces both a value and a
+ * detailed summary. `renderArtifact` is a thin wrapper returning just the
+ * value; `renderArtifactWithSummary` returns the full summary.
+ *
+ * Generic type `Final` / `Part` / `Options` instead of referring to the
+ * kind's generics directly so runtime-typed callers (renderArtifactByName)
+ * can pass `unknown`.
+ */
+function runRender(kind, contracts, options, control) {
+    const parts = [];
+    const contributions = [];
+    const skipped = [];
+    for (const c of contracts) {
+        const adapter = getAdapter(c.protocol);
+        const explicitProducer = !control?.preferDefaultRender
+            ? adapter?.artifacts?.[kind.name]
+            : undefined;
+        if (explicitProducer) {
+            parts.push(explicitProducer(c, options));
+            contributions.push({
+                contractId: c.id,
+                protocol: c.protocol,
+                source: "explicit-producer",
+            });
+            continue;
+        }
+        if (kind.defaultRender) {
+            parts.push(kind.defaultRender(c, options));
+            contributions.push({
+                contractId: c.id,
+                protocol: c.protocol,
+                source: "default-render",
+            });
+            continue;
+        }
+        skipped.push({
+            contractId: c.id,
+            protocol: c.protocol,
+            reason: control?.preferDefaultRender
+                ? "prefer-default-render-no-default"
+                : "no-producer-no-default-render",
+        });
+    }
+    if (parts.length === 0) {
+        return {
+            value: kind.empty,
+            contributions,
+            skipped,
+            usedEmptyFallback: true,
+        };
+    }
+    return {
+        value: kind.merge(parts, options),
+        contributions,
+        skipped,
+        usedEmptyFallback: false,
+    };
+}
+/**
+ * Render an artifact of the given kind from a list of contracts. Threads
+ * `options` through the producer / defaultRender / merge pipeline. When no
+ * contract contributes a part, returns `kind.empty` (guaranteed valid
+ * `Final`).
+ *
+ * Strong-typed entry point: kind argument is a concrete `ArtifactKind<...>`
+ * object, so `options` type and return type are inferred at compile time.
+ */
+export function renderArtifact(kind, contracts, options, control) {
+    return runRender(kind, contracts, options, control).value;
+}
+/**
+ * Render an artifact and return the full summary (value + contributions +
+ * skipped + usedEmptyFallback). Use this when you need to distinguish
+ * "zero contribution" from "merged to kind.empty-shaped value" — the
+ * `usedEmptyFallback` field is the authoritative signal (do not compare
+ * `value === kind.empty` yourself for object-typed Final).
+ */
+export function renderArtifactWithSummary(kind, contracts, options, control) {
+    return runRender(kind, contracts, options, control);
+}
+/**
+ * Look up a kind by name and render. Used by string-driven consumers
+ * (CLI --format <name>, MCP tools, agent introspection). Throws when the
+ * name is not registered — the error message includes the list of
+ * registered kinds so callers can surface it without extra lookups.
+ *
+ * Returns `unknown` since we don't know the Final type statically;
+ * callers that need a typed return should use `renderArtifact` directly
+ * with the kind object they import.
+ */
+export function renderArtifactByName(kindName, contracts, options, control) {
+    const kind = getArtifactKind(kindName);
+    if (!kind) {
+        const known = listArtifactKinds();
+        const hint = known.length > 0 ? known.join(", ") : "(none)";
+        throw new Error(`Unknown artifact kind "${kindName}". Registered kinds: ${hint}`);
+    }
+    return renderArtifact(kind, contracts, options, control);
+}
+// =============================================================================
+// Introspection
+// =============================================================================
+/**
+ * List the protocols whose adapter **explicitly declares a producer** for
+ * the given kind. Does NOT include protocols that would fall back to
+ * `kind.defaultRender`. Use `listArtifactCapability` for the three-way split.
+ */
+export function listArtifactProducers(kindName) {
+    return listRegisteredProtocols().filter((p) => {
+        const adapter = getAdapter(p);
+        return (adapter !== undefined &&
+            adapter.artifacts?.[kindName] !==
+                undefined);
+    });
+}
+/**
+ * Static capability view — **based on installed adapters**, not on any
+ * particular project's contracts. Partitions protocols into:
+ *
+ *   - `explicit`    : adapter declares a producer for this kind
+ *   - `fallback`    : adapter has no producer but kind.defaultRender exists
+ *   - `unsupported` : adapter has no producer and kind has no defaultRender
+ *
+ * To answer "does **this project** produce the artifact?", use
+ * `renderArtifactWithSummary` and inspect `contributions` + `usedEmptyFallback`.
+ * The capability view cannot know how many contracts of each protocol exist
+ * in the caller's project.
+ */
+export function listArtifactCapability(kindName) {
+    const kind = getArtifactKind(kindName);
+    const allProtocols = listRegisteredProtocols();
+    const explicit = listArtifactProducers(kindName);
+    const explicitSet = new Set(explicit);
+    const rest = allProtocols.filter((p) => !explicitSet.has(p));
+    if (kind?.defaultRender) {
+        return { explicit, fallback: rest, unsupported: [] };
+    }
+    return { explicit, fallback: [], unsupported: rest };
+}
+// =============================================================================
+// Built-in kinds
+// =============================================================================
+/**
+ * OpenAPI 3.1 artifact kind. Per-contract partials are produced by HTTP
+ * adapter's `artifacts.openapi` (see `contract-http/openapi.ts`); merge
+ * combines them into a full spec. No `defaultRender` — non-HTTP protocols
+ * don't map to OpenAPI and are skipped.
+ *
+ * Ported from MCP's former `contractsToOpenApi` — CAR-1 Phase 2.
+ */
+export const openapiArtifact = defineArtifactKind({
+    name: "openapi",
+    merge: (parts, options) => mergeOpenApiParts(parts, options),
+    empty: emptyOpenApiDocument,
+});
+/**
+ * Protocol-agnostic default renderer. Reads raw fields off the
+ * projection; every protocol gets a valid Part even if its adapter
+ * doesn't declare `artifacts.markdown`.
+ */
+export function genericMarkdownPart(projection) {
+    return {
+        contractId: projection.id,
+        endpoint: projection.target,
+        protocol: projection.protocol,
+        description: projection.description,
+        feature: projection.feature,
+        instanceName: projection.instanceName,
+        deprecated: projection.deprecated,
+        cases: projection.cases.map((c) => ({
+            key: c.key,
+            description: c.description,
+            lifecycle: c.lifecycle ??
+                (c.deprecatedReason
+                    ? "deprecated"
+                    : c.deferredReason
+                        ? "deferred"
+                        : "active"),
+            severity: c.severity ?? "warning",
+            defaultRun: c.defaultRun,
+            requires: c.requires,
+            deferredReason: c.deferredReason,
+            deprecatedReason: c.deprecatedReason,
+        })),
+    };
+}
+function computeMarkdownSummary(parts) {
+    let total = 0;
+    let deferred = 0;
+    let deprecated = 0;
+    let gated = 0;
+    for (const p of parts) {
+        for (const c of p.cases) {
+            total++;
+            if (c.lifecycle === "deprecated")
+                deprecated++;
+            else if (c.lifecycle === "deferred")
+                deferred++;
+            else if (c.requires === "browser" || c.requires === "out-of-band")
+                gated++;
+        }
+    }
+    return {
+        total,
+        active: total - deferred - deprecated - gated,
+        deferred,
+        deprecated,
+        gated,
+    };
+}
+function formatMarkdownCase(c) {
+    const desc = c.description ? ` — ${c.description}` : "";
+    if (c.lifecycle === "deprecated") {
+        const reason = c.deprecatedReason ?? "deprecated";
+        return `- ⊘ **${c.key}** — deprecated: ${reason}`;
+    }
+    if (c.lifecycle === "deferred") {
+        const reason = c.deferredReason ?? "deferred";
+        return `- ⊘ **${c.key}** — deferred: ${reason}`;
+    }
+    if (c.requires === "browser" || c.requires === "out-of-band") {
+        return `- ⊘ **${c.key}** — requires: ${c.requires}`;
+    }
+    const severityTag = c.severity === "critical" ? " 🔴" : c.severity === "info" ? " ℹ️" : "";
+    const suffix = c.defaultRun === "opt-in" ? " *(opt-in)*" : "";
+    return `- **${c.key}**${desc}${suffix}${severityTag}`;
+}
+/**
+ * Compute the effective feature key for a part — applies the
+ * instanceName-aware transform when the project has any instanced
+ * contract (matches CLI `hasInstances` pre-pass behavior).
+ */
+function displayFeature(part, hasInstances) {
+    if (hasInstances && part.instanceName) {
+        return `${part.instanceName}: ${part.feature ?? part.endpoint}`;
+    }
+    return part.feature ?? part.endpoint;
+}
+/**
+ * Feature-grouped, doc-level markdown assembly. Byte-for-byte output
+ * compatible with `formatMdOutline` from `packages/cli/src/commands/
+ * contracts.ts` (the legacy CLI markdown path).
+ *
+ * Structure:
+ *   # Contract Specification
+ *   Generated: YYYY-MM-DD | N cases | N active | ...
+ *
+ *   ## <feature>
+ *   🚫 **Deprecated:** ...   (if contract-level deprecated)
+ *   <description or endpoint intro>
+ *   - **case** — ...
+ */
+export function assembleMarkdownDocument(parts) {
+    if (parts.length === 0)
+        return "";
+    const hasInstances = parts.some((p) => !!p.instanceName);
+    // Group preserving insertion order
+    const groups = new Map();
+    for (const part of parts) {
+        const key = displayFeature(part, hasInstances);
+        const list = groups.get(key) ?? [];
+        list.push(part);
+        groups.set(key, list);
+    }
+    const summary = computeMarkdownSummary(parts);
+    const lines = [];
+    lines.push("# Contract Specification");
+    lines.push("");
+    const date = new Date().toISOString().slice(0, 10);
+    const summaryParts = [`Generated: ${date}`, `${summary.total} cases`];
+    if (summary.active > 0)
+        summaryParts.push(`${summary.active} active`);
+    if (summary.deferred > 0)
+        summaryParts.push(`${summary.deferred} deferred`);
+    if (summary.deprecated > 0)
+        summaryParts.push(`${summary.deprecated} deprecated`);
+    if (summary.gated > 0)
+        summaryParts.push(`${summary.gated} gated`);
+    lines.push(summaryParts.join(" | "));
+    lines.push("");
+    for (const [featureName, featureParts] of groups.entries()) {
+        lines.push(`## ${featureName}`);
+        lines.push("");
+        for (const contract of featureParts) {
+            const intro = contract.description ??
+                (featureName !== contract.endpoint ? contract.endpoint : undefined);
+            if (contract.deprecated) {
+                lines.push(`🚫 **Deprecated:** ${contract.deprecated}`);
+                lines.push("");
+            }
+            if (intro) {
+                lines.push(intro);
+                lines.push("");
+            }
+            for (const c of contract.cases) {
+                lines.push(formatMarkdownCase(c));
+            }
+            lines.push("");
+        }
+    }
+    return lines.join("\n").trimEnd() + "\n";
+}
+export const markdownArtifact = defineArtifactKind({
+    name: "markdown",
+    defaultRender: (projection) => genericMarkdownPart(projection),
+    merge: (parts) => assembleMarkdownDocument(parts),
+    empty: "",
+});
+//# sourceMappingURL=contract-artifacts.js.map