@brignano/driftwood 0.0.0

package/dist/providers/dynatrace.d.ts

@@ -0,0 +1,70 @@
+import { z } from 'zod';
+import type { Model } from '../model/schema.js';
+/**
+ * Dynatrace Smartscape as a runtime provider.
+ *
+ * This is the counterpart to Terraform: Terraform says what is *supposed* to
+ * exist, Dynatrace says what is *actually running*. Reconciling the two is the
+ * point of the tool — a service Terraform declares but Dynatrace has never
+ * seen is a very different finding from one neither knows about.
+ *
+ * Read-only: this hits the Entities API v2 with a token that only needs
+ * `entities.read`. Nothing here mutates anything.
+ */
+export declare const dynatraceConfigSchema: z.ZodObject<{
+    /** Environment URL, e.g. https://abc12345.live.dynatrace.com */
+    url: z.ZodString;
+    /** Name of the env var holding the API token. Never the token itself. */
+    tokenEnv: z.ZodDefault<z.ZodString>;
+    /** Entity selectors to pull. Defaults cover the common topology types. */
+    entitySelectors: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    platform: z.ZodDefault<z.ZodString>;
+    /** Guards against pulling an enormous environment by accident. */
+    pageSize: z.ZodDefault<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    platform: string;
+    url: string;
+    tokenEnv: string;
+    entitySelectors: string[];
+    pageSize: number;
+}, {
+    url: string;
+    platform?: string | undefined;
+    tokenEnv?: string | undefined;
+    entitySelectors?: string[] | undefined;
+    pageSize?: number | undefined;
+}>;
+export type DynatraceConfig = z.infer<typeof dynatraceConfigSchema>;
+interface DtEntity {
+    entityId?: string;
+    displayName?: string;
+    type?: string;
+    fromRelationships?: Record<string, Array<{
+        id?: string;
+    }>>;
+}
+export declare function toModel(entities: DtEntity[], platform: string): Model;
+export declare const dynatraceProvider: import("./types.js").Provider<z.ZodObject<{
+    /** Environment URL, e.g. https://abc12345.live.dynatrace.com */
+    url: z.ZodString;
+    /** Name of the env var holding the API token. Never the token itself. */
+    tokenEnv: z.ZodDefault<z.ZodString>;
+    /** Entity selectors to pull. Defaults cover the common topology types. */
+    entitySelectors: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    platform: z.ZodDefault<z.ZodString>;
+    /** Guards against pulling an enormous environment by accident. */
+    pageSize: z.ZodDefault<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    platform: string;
+    url: string;
+    tokenEnv: string;
+    entitySelectors: string[];
+    pageSize: number;
+}, {
+    url: string;
+    platform?: string | undefined;
+    tokenEnv?: string | undefined;
+    entitySelectors?: string[] | undefined;
+    pageSize?: number | undefined;
+}>>;
+export {};

package/dist/providers/dynatrace.js

@@ -0,0 +1,117 @@
+import { z } from 'zod';
+import { emptyModel } from '../model/schema.js';
+import { defineProvider } from './types.js';
+/**
+ * Dynatrace Smartscape as a runtime provider.
+ *
+ * This is the counterpart to Terraform: Terraform says what is *supposed* to
+ * exist, Dynatrace says what is *actually running*. Reconciling the two is the
+ * point of the tool — a service Terraform declares but Dynatrace has never
+ * seen is a very different finding from one neither knows about.
+ *
+ * Read-only: this hits the Entities API v2 with a token that only needs
+ * `entities.read`. Nothing here mutates anything.
+ */
+export const dynatraceConfigSchema = z.object({
+    /** Environment URL, e.g. https://abc12345.live.dynatrace.com */
+    url: z.string().url(),
+    /** Name of the env var holding the API token. Never the token itself. */
+    tokenEnv: z.string().default('DYNATRACE_API_TOKEN'),
+    /** Entity selectors to pull. Defaults cover the common topology types. */
+    entitySelectors: z
+        .array(z.string())
+        .default(['type("SERVICE")', 'type("HOST")', 'type("PROCESS_GROUP")']),
+    platform: z.string().default('dynatrace'),
+    /** Guards against pulling an enormous environment by accident. */
+    pageSize: z.number().int().min(1).max(4000).default(500),
+});
+/** Maps a Dynatrace entity type to a group label. */
+function groupFor(type) {
+    if (!type)
+        return undefined;
+    return type.toLowerCase().replace(/_/g, '-');
+}
+export function toModel(entities, platform) {
+    const model = emptyModel('dynatrace');
+    const out = [];
+    const edges = [];
+    const known = new Set();
+    for (const e of entities) {
+        if (!e.entityId)
+            continue;
+        if (known.has(e.entityId))
+            continue;
+        known.add(e.entityId);
+        out.push({
+            id: e.entityId,
+            kind: e.type ?? 'UNKNOWN',
+            name: e.displayName ?? e.entityId,
+            group: groupFor(e.type),
+            platform,
+            source: 'dynatrace',
+            level: 'container',
+        });
+    }
+    for (const e of entities) {
+        if (!e.entityId)
+            continue;
+        for (const [relation, targets] of Object.entries(e.fromRelationships ?? {})) {
+            for (const t of targets ?? []) {
+                // Relationships routinely point at entity types outside the selector,
+                // which would otherwise produce dangling edges the validator rejects.
+                if (!t.id || !known.has(t.id) || t.id === e.entityId)
+                    continue;
+                if (edges.some((x) => x.from === e.entityId && x.to === t.id))
+                    continue;
+                edges.push({ from: e.entityId, to: t.id, kind: relation });
+            }
+        }
+    }
+    model.entities = out.sort((a, b) => a.id.localeCompare(b.id));
+    model.edges = edges.sort((a, b) => (a.from + a.to).localeCompare(b.from + b.to));
+    return model;
+}
+async function fetchAll(config, token) {
+    const collected = [];
+    for (const selector of config.entitySelectors) {
+        let pageKey;
+        do {
+            const url = new URL('/api/v2/entities', config.url);
+            if (pageKey) {
+                url.searchParams.set('nextPageKey', pageKey);
+            }
+            else {
+                url.searchParams.set('entitySelector', selector);
+                url.searchParams.set('pageSize', String(config.pageSize));
+                url.searchParams.set('fields', '+fromRelationships');
+            }
+            const res = await fetch(url, {
+                headers: { Authorization: `Api-Token ${token}`, Accept: 'application/json' },
+            });
+            if (!res.ok) {
+                throw new Error(`Dynatrace API ${res.status} ${res.statusText} for selector ${selector}`);
+            }
+            const body = (await res.json());
+            collected.push(...(body.entities ?? []));
+            pageKey = body.nextPageKey;
+        } while (pageKey);
+    }
+    return collected;
+}
+export const dynatraceProvider = defineProvider({
+    name: 'dynatrace',
+    description: 'Dynatrace Smartscape topology (Entities API v2, read-only)',
+    kind: 'runtime',
+    platforms: ['aws', 'gcp', 'azure', 'onprem', 'kubernetes'],
+    configSchema: dynatraceConfigSchema,
+    async observe(config, ctx) {
+        const token = ctx.secret(config.tokenEnv);
+        if (!token) {
+            throw new Error(`Dynatrace token not found. Set $${config.tokenEnv} to a token with the 'entities.read' scope.`);
+        }
+        ctx.log(`dynatrace: querying ${config.entitySelectors.length} selector(s)`);
+        const entities = await fetchAll(config, token);
+        ctx.log(`dynatrace: ${entities.length} entities`);
+        return toModel(entities, config.platform);
+    },
+});

package/dist/providers/index.d.ts

@@ -0,0 +1,12 @@
+import { Registry } from '../registry.js';
+import type { Provider } from './types.js';
+import { terraformProvider } from './terraform.js';
+import { dynatraceProvider } from './dynatrace.js';
+/**
+ * Built-in providers. Third parties register their own against the same
+ * registry — there is no separate plugin API to learn.
+ */
+export declare const providers: Registry<Provider<import("zod").ZodTypeAny>>;
+export { terraformProvider, dynatraceProvider };
+export type { Provider, ProviderContext, ProviderKind } from './types.js';
+export { defineProvider } from './types.js';

package/dist/providers/index.js

@@ -0,0 +1,12 @@
+import { Registry } from '../registry.js';
+import { terraformProvider } from './terraform.js';
+import { dynatraceProvider } from './dynatrace.js';
+/**
+ * Built-in providers. Third parties register their own against the same
+ * registry — there is no separate plugin API to learn.
+ */
+export const providers = new Registry('provider');
+providers.register(terraformProvider);
+providers.register(dynatraceProvider);
+export { terraformProvider, dynatraceProvider };
+export { defineProvider } from './types.js';

package/dist/providers/terraform.d.ts

@@ -0,0 +1,61 @@
+import type { Model } from '../model/schema.js';
+/**
+ * Terraform state (format v4) as the first provider.
+ *
+ * Rationale from the brief: it's already a graph, already declarative, and it
+ * carries real cloud resource IDs — which sidesteps the identity-resolution
+ * problem that kills CMDBs. Entity id is the Terraform address, which is
+ * stable across plans and human-readable in a diff.
+ */
+interface TfInstance {
+    attributes?: Record<string, unknown>;
+    dependencies?: string[];
+}
+interface TfResource {
+    mode?: string;
+    type?: string;
+    name?: string;
+    module?: string;
+    provider?: string;
+    instances?: TfInstance[];
+}
+interface TfState {
+    version?: number;
+    resources?: TfResource[];
+}
+export interface ImportOptions {
+    /** Data sources describe things Terraform reads but doesn't own. */
+    includeDataSources?: boolean;
+    modelName?: string;
+}
+export declare function importTerraformState(state: TfState, opts?: ImportOptions): Model;
+export declare function parseTerraformState(source: string): TfState;
+import { z } from 'zod';
+export declare const terraformConfigSchema: z.ZodObject<{
+    /** Path to terraform.tfstate, or the output of `terraform show -json`. */
+    statePath: z.ZodString;
+    includeDataSources: z.ZodDefault<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    statePath: string;
+    includeDataSources: boolean;
+}, {
+    statePath: string;
+    includeDataSources?: boolean | undefined;
+}>;
+/**
+ * Terraform is platform-agnostic on purpose: the same provider covers AWS,
+ * GCP, Azure, vSphere, and on-prem, because the platform is simply whatever
+ * the state file declares. One provider, every target.
+ */
+export declare const terraformProvider: import("./types.js").Provider<z.ZodObject<{
+    /** Path to terraform.tfstate, or the output of `terraform show -json`. */
+    statePath: z.ZodString;
+    includeDataSources: z.ZodDefault<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    statePath: string;
+    includeDataSources: boolean;
+}, {
+    statePath: string;
+    includeDataSources?: boolean | undefined;
+}>>;
+export {};

package/dist/providers/terraform.js

@@ -0,0 +1,132 @@
+import { emptyModel } from '../model/schema.js';
+function address(r) {
+    const base = `${r.type}.${r.name}`;
+    return r.module ? `${r.module}.${base}` : base;
+}
+/** `provider["registry.terraform.io/hashicorp/aws"]` -> `aws` */
+function providerName(raw) {
+    if (!raw)
+        return undefined;
+    const m = raw.match(/([^/"\]]+)"?\]?$/);
+    return m?.[1];
+}
+/**
+ * Terraform resource types are prefixed by provider (`aws_s3_bucket`), and the
+ * segment after that prefix is a good-enough grouping for a first diagram
+ * (`s3`, `lambda`, `route53`). Not clever, but stable and predictable.
+ */
+function groupFor(type) {
+    if (!type)
+        return undefined;
+    const parts = type.split('_');
+    if (parts.length < 2)
+        return type;
+    return parts[1];
+}
+/**
+ * Human label. Terraform has no universal "name" attribute, so try the
+ * conventional ones in order of specificity before falling back to the
+ * resource's local name.
+ */
+function displayName(r, attrs) {
+    const candidates = ['name', 'bucket', 'domain_name', 'function_name', 'identifier'];
+    for (const key of candidates) {
+        const v = attrs?.[key];
+        if (typeof v === 'string' && v.length > 0)
+            return v;
+    }
+    const tags = attrs?.['tags'];
+    if (tags && typeof tags === 'object' && 'Name' in tags) {
+        const n = tags['Name'];
+        if (typeof n === 'string' && n.length > 0)
+            return n;
+    }
+    return r.name ?? address(r);
+}
+export function importTerraformState(state, opts = {}) {
+    const model = emptyModel(opts.modelName ?? 'terraform');
+    const entities = [];
+    const edges = [];
+    const known = new Set();
+    const resources = state.resources ?? [];
+    for (const r of resources) {
+        if (!r.type || !r.name)
+            continue;
+        const isData = r.mode === 'data';
+        if (isData && !opts.includeDataSources)
+            continue;
+        const id = address(r);
+        if (known.has(id))
+            continue;
+        known.add(id);
+        const attrs = r.instances?.[0]?.attributes;
+        entities.push({
+            id,
+            kind: r.type,
+            name: displayName(r, attrs),
+            group: groupFor(r.type),
+            platform: providerName(r.provider),
+            source: 'terraform',
+            level: 'container',
+            ...(isData ? { tags: { mode: 'data' } } : {}),
+        });
+    }
+    for (const r of resources) {
+        if (!r.type || !r.name)
+            continue;
+        const from = address(r);
+        if (!known.has(from))
+            continue;
+        for (const inst of r.instances ?? []) {
+            for (const dep of inst.dependencies ?? []) {
+                // Dependencies on filtered-out resources (e.g. data sources) would
+                // produce dangling edges, which the validator rightly rejects.
+                if (!known.has(dep))
+                    continue;
+                if (dep === from)
+                    continue;
+                if (edges.some((e) => e.from === from && e.to === dep))
+                    continue;
+                edges.push({ from, to: dep, kind: 'depends-on' });
+            }
+        }
+    }
+    model.entities = entities.sort((a, b) => a.id.localeCompare(b.id));
+    model.edges = edges.sort((a, b) => (a.from + a.to).localeCompare(b.from + b.to));
+    return model;
+}
+export function parseTerraformState(source) {
+    const parsed = JSON.parse(source);
+    if (parsed.version !== undefined && parsed.version !== 4) {
+        throw new Error(`unsupported Terraform state version ${parsed.version} (expected 4)`);
+    }
+    return parsed;
+}
+// ---------------------------------------------------------------------------
+// Provider interface binding
+// ---------------------------------------------------------------------------
+import { readFileSync } from 'node:fs';
+import { z } from 'zod';
+import { defineProvider } from './types.js';
+export const terraformConfigSchema = z.object({
+    /** Path to terraform.tfstate, or the output of `terraform show -json`. */
+    statePath: z.string(),
+    includeDataSources: z.boolean().default(false),
+});
+/**
+ * Terraform is platform-agnostic on purpose: the same provider covers AWS,
+ * GCP, Azure, vSphere, and on-prem, because the platform is simply whatever
+ * the state file declares. One provider, every target.
+ */
+export const terraformProvider = defineProvider({
+    name: 'terraform',
+    description: 'Terraform state (format v4) — any platform Terraform manages',
+    kind: 'declarative',
+    platforms: ['*'],
+    configSchema: terraformConfigSchema,
+    observe(config, ctx) {
+        const path = ctx.resolvePath(config.statePath);
+        const state = parseTerraformState(readFileSync(path, 'utf8'));
+        return importTerraformState(state, { includeDataSources: config.includeDataSources });
+    },
+});

package/dist/providers/types.d.ts

@@ -0,0 +1,41 @@
+import type { ZodTypeAny, z } from 'zod';
+import type { Model } from '../model/schema.js';
+/**
+ * Where a provider gets its facts. This drives how conflicts are resolved when
+ * two providers describe the same entity: declarative sources describe intent,
+ * runtime sources describe what is actually running, and runtime wins on
+ * liveness while declarative wins on ownership and naming.
+ */
+export type ProviderKind = 'declarative' | 'runtime';
+export interface ProviderContext {
+    /** Resolves a secret by name. Never read process.env directly in a provider. */
+    secret(name: string): string | undefined;
+    /** Resolves a path relative to the config file's directory. */
+    resolvePath(p: string): string;
+    log(message: string): void;
+}
+/**
+ * The provider extension point.
+ *
+ * A provider observes some system and returns a `Model`. It never reads the
+ * committed model, never writes files, and never mutates infrastructure — it
+ * answers one question: "what is actually out there right now?"
+ *
+ * `configSchema` is a Zod schema so a config file can be validated with a
+ * useful error message before any network call is attempted.
+ */
+export interface Provider<S extends ZodTypeAny = ZodTypeAny> {
+    name: string;
+    description: string;
+    kind: ProviderKind;
+    /**
+     * Platforms this provider can describe: 'aws', 'gcp', 'azure', 'onprem',
+     * 'kubernetes', or '*' when it is platform-agnostic (Terraform is, because
+     * the platform is whatever the state file happens to contain).
+     */
+    platforms: string[];
+    configSchema: S;
+    observe(config: z.infer<S>, ctx: ProviderContext): Promise<Model> | Model;
+}
+/** Helper that preserves the config type through registration. */
+export declare function defineProvider<S extends ZodTypeAny>(p: Provider<S>): Provider<S>;

package/dist/providers/types.js

@@ -0,0 +1,4 @@
+/** Helper that preserves the config type through registration. */
+export function defineProvider(p) {
+    return p;
+}

package/dist/reconcile/index.d.ts

@@ -0,0 +1,40 @@
+import type { Edge, Entity, Model } from '../model/schema.js';
+/**
+ * Declared (the model in git) vs observed (what a provider found).
+ *
+ * The drift policy is the thing most likely to sink this in practice: report
+ * too much and every run becomes noise that gets muted, report too little and
+ * the model rots anyway. Default: structural facts count, metadata doesn't.
+ * A new tag is not drift. A new resource, a removed edge, or a changed kind is.
+ */
+export declare const COMPARED_FIELDS: readonly ["kind", "name", "group"];
+export type ComparedField = (typeof COMPARED_FIELDS)[number];
+export interface FieldChange {
+    id: string;
+    field: ComparedField;
+    declared: string | undefined;
+    observed: string | undefined;
+}
+export interface Drift {
+    entities: {
+        added: Entity[];
+        removed: Entity[];
+        changed: FieldChange[];
+    };
+    edges: {
+        added: Edge[];
+        removed: Edge[];
+    };
+    ignored: {
+        entities: number;
+        edges: number;
+    };
+    coverage: Array<{
+        scope: string;
+        reason: string;
+    }>;
+    hasDrift: boolean;
+}
+export declare function reconcile(declared: Model, observed: Model): Drift;
+/** Markdown, because the output's destination is a pull request body. */
+export declare function formatDrift(drift: Drift): string;

package/dist/reconcile/index.js

@@ -0,0 +1,146 @@
+import { matches } from '../model/validate.js';
+/**
+ * Declared (the model in git) vs observed (what a provider found).
+ *
+ * The drift policy is the thing most likely to sink this in practice: report
+ * too much and every run becomes noise that gets muted, report too little and
+ * the model rots anyway. Default: structural facts count, metadata doesn't.
+ * A new tag is not drift. A new resource, a removed edge, or a changed kind is.
+ */
+export const COMPARED_FIELDS = ['kind', 'name', 'group'];
+const edgeKey = (e) => `${e.from} ${e.to}`;
+function isIgnoredEntity(model, e) {
+    if (model.ignore.kinds.some((k) => matches(k, e.kind)))
+        return true;
+    return model.ignore.entities.some((p) => matches(p, e.id));
+}
+function isIgnoredEdge(model, edge) {
+    if (model.ignore.edges.some((i) => matches(i.from, edge.from) && matches(i.to, edge.to)))
+        return true;
+    // An edge touching an ignored entity is ignored by implication, otherwise
+    // ignoring a resource would still surface all of its edges as drift.
+    const ignoredId = (id) => model.ignore.entities.some((p) => matches(p, id));
+    return ignoredId(edge.from) || ignoredId(edge.to);
+}
+export function reconcile(declared, observed) {
+    const declaredById = new Map(declared.entities.map((e) => [e.id, e]));
+    const observedById = new Map(observed.entities.map((e) => [e.id, e]));
+    const added = [];
+    const removed = [];
+    const changed = [];
+    let ignoredEntities = 0;
+    for (const [id, obs] of observedById) {
+        if (declaredById.has(id))
+            continue;
+        if (isIgnoredEntity(declared, obs)) {
+            ignoredEntities++;
+            continue;
+        }
+        added.push(obs);
+    }
+    for (const [id, dec] of declaredById) {
+        if (observedById.has(id))
+            continue;
+        if (isIgnoredEntity(declared, dec)) {
+            ignoredEntities++;
+            continue;
+        }
+        removed.push(dec);
+    }
+    for (const [id, dec] of declaredById) {
+        const obs = observedById.get(id);
+        if (!obs)
+            continue;
+        if (isIgnoredEntity(declared, dec))
+            continue;
+        for (const field of COMPARED_FIELDS) {
+            if (dec[field] !== obs[field]) {
+                changed.push({ id, field, declared: dec[field], observed: obs[field] });
+            }
+        }
+    }
+    const declaredEdges = new Map(declared.edges.map((e) => [edgeKey(e), e]));
+    const observedEdges = new Map(observed.edges.map((e) => [edgeKey(e), e]));
+    const addedEdges = [];
+    const removedEdges = [];
+    let ignoredEdges = 0;
+    for (const [key, obs] of observedEdges) {
+        if (declaredEdges.has(key))
+            continue;
+        if (isIgnoredEdge(declared, obs)) {
+            ignoredEdges++;
+            continue;
+        }
+        addedEdges.push(obs);
+    }
+    for (const [key, dec] of declaredEdges) {
+        if (observedEdges.has(key))
+            continue;
+        if (isIgnoredEdge(declared, dec)) {
+            ignoredEdges++;
+            continue;
+        }
+        removedEdges.push(dec);
+    }
+    const hasDrift = added.length > 0 ||
+        removed.length > 0 ||
+        changed.length > 0 ||
+        addedEdges.length > 0 ||
+        removedEdges.length > 0;
+    return {
+        entities: { added, removed, changed },
+        edges: { added: addedEdges, removed: removedEdges },
+        ignored: { entities: ignoredEntities, edges: ignoredEdges },
+        coverage: declared.coverage,
+        hasDrift,
+    };
+}
+/** Markdown, because the output's destination is a pull request body. */
+export function formatDrift(drift) {
+    if (!drift.hasDrift) {
+        const parts = ['No drift. The model matches observed infrastructure.'];
+        if (drift.ignored.entities || drift.ignored.edges) {
+            parts.push(`\n_Ignored: ${drift.ignored.entities} entities, ${drift.ignored.edges} edges._`);
+        }
+        return parts.join('\n');
+    }
+    const out = ['## Architecture drift detected', ''];
+    const { added, removed, changed } = drift.entities;
+    if (added.length) {
+        out.push(`### Present in infrastructure, missing from the model (${added.length})`, '');
+        for (const e of added)
+            out.push(`- \`${e.id}\` - ${e.kind}${e.name ? ` (${e.name})` : ''}`);
+        out.push('');
+    }
+    if (removed.length) {
+        out.push(`### Declared in the model, not found in infrastructure (${removed.length})`, '');
+        for (const e of removed)
+            out.push(`- \`${e.id}\` - ${e.kind}${e.name ? ` (${e.name})` : ''}`);
+        out.push('');
+    }
+    if (changed.length) {
+        out.push(`### Changed (${changed.length})`, '', '| Entity | Field | Declared | Observed |', '|---|---|---|---|');
+        for (const c of changed) {
+            out.push(`| \`${c.id}\` | ${c.field} | ${c.declared ?? '-'} | ${c.observed ?? '-'} |`);
+        }
+        out.push('');
+    }
+    if (drift.edges.added.length || drift.edges.removed.length) {
+        out.push('### Relationships', '');
+        for (const e of drift.edges.added)
+            out.push(`- **added** \`${e.from}\` -> \`${e.to}\``);
+        for (const e of drift.edges.removed)
+            out.push(`- **removed** \`${e.from}\` -> \`${e.to}\``);
+        out.push('');
+    }
+    if (drift.ignored.entities || drift.ignored.edges) {
+        out.push(`_Ignored by policy: ${drift.ignored.entities} entities, ${drift.ignored.edges} edges._`, '');
+    }
+    if (drift.coverage.length) {
+        out.push('### Known coverage gaps', '', '_These are declared blind spots - absence here does not mean absence in reality._', '');
+        for (const c of drift.coverage)
+            out.push(`- \`${c.scope}\` - ${c.reason}`);
+        out.push('');
+    }
+    return out.join('\n');
+}

package/dist/registry.d.ts

@@ -0,0 +1,22 @@
+/**
+ * A tiny name -> implementation registry, shared by providers and renderers.
+ *
+ * Extension points are the whole point of this file: adding a provider or a
+ * renderer must never require editing core code. Built-ins register themselves
+ * at startup; third parties call `register()` with the same API, so a plugin
+ * is not a second-class citizen.
+ */
+export declare class Registry<T extends {
+    name: string;
+}> {
+    private readonly label;
+    private readonly items;
+    constructor(label: string);
+    register(item: T): this;
+    /** Replaces an existing entry. Used by tests and by deliberate overrides. */
+    override(item: T): this;
+    get(name: string): T;
+    has(name: string): boolean;
+    names(): string[];
+    all(): T[];
+}