@brignano/driftwood 0.0.0

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+export { Model, Entity, Edge, View, Ignore, Level, emptyModel } from './model/schema.js';
+export { loadModel, dumpModel, validateModel, matches } from './model/validate.js';
+export type { Issue, ValidationResult } from './model/validate.js';
+export { mergeModels, formatConflicts } from './model/merge.js';
+export type { MergeResult, MergeConflict, SourcedModel } from './model/merge.js';
+export { Registry } from './registry.js';
+export { providers, defineProvider, terraformProvider, dynatraceProvider } from './providers/index.js';
+export type { Provider, ProviderContext, ProviderKind } from './providers/index.js';
+export { renderers, render, resolveRenderer } from './render/index.js';
+export { defineRenderer } from './render/types.js';
+export type { Renderer, RenderContext, Availability } from './render/types.js';
+export { importTerraformState, parseTerraformState } from './providers/terraform.js';
+export type { ImportOptions } from './providers/terraform.js';
+export { toModel as dynatraceToModel } from './providers/dynatrace.js';
+export { renderMermaid } from './render/mermaid.js';
+export { renderDot } from './render/dot.js';
+export { renderGraphvizSvg, detectTier, probeNativeDot } from './render/graphviz.js';
+export { selectEntities } from './render/select.js';
+export { reconcile, formatDrift, COMPARED_FIELDS } from './reconcile/index.js';
+export type { Drift, FieldChange, ComparedField } from './reconcile/index.js';
+export { loadConfig, observeAll, makeContext, Config } from './config.js';
+export type { LoadedConfig } from './config.js';

package/dist/index.js

@@ -0,0 +1,21 @@
+// Model
+export { Model, Entity, Edge, View, Ignore, Level, emptyModel } from './model/schema.js';
+export { loadModel, dumpModel, validateModel, matches } from './model/validate.js';
+export { mergeModels, formatConflicts } from './model/merge.js';
+// Extension points
+export { Registry } from './registry.js';
+export { providers, defineProvider, terraformProvider, dynatraceProvider } from './providers/index.js';
+export { renderers, render, resolveRenderer } from './render/index.js';
+export { defineRenderer } from './render/types.js';
+// Built-in providers
+export { importTerraformState, parseTerraformState } from './providers/terraform.js';
+export { toModel as dynatraceToModel } from './providers/dynatrace.js';
+// Renderers
+export { renderMermaid } from './render/mermaid.js';
+export { renderDot } from './render/dot.js';
+export { renderGraphvizSvg, detectTier, probeNativeDot } from './render/graphviz.js';
+export { selectEntities } from './render/select.js';
+// Reconciliation
+export { reconcile, formatDrift, COMPARED_FIELDS } from './reconcile/index.js';
+// Config
+export { loadConfig, observeAll, makeContext, Config } from './config.js';

package/dist/model/merge.d.ts

@@ -0,0 +1,32 @@
+import type { Model } from './schema.js';
+/**
+ * Combining what several providers observed into one model.
+ *
+ * The genuinely hard part is identity: Terraform calls it
+ * `aws_lambda_function.forwarder`, Dynatrace calls it `SERVICE-A1B2`, and
+ * nothing in either payload proves they're the same thing. This module does
+ * NOT guess. It applies the explicit `aliases` map from the committed model
+ * and otherwise keeps ids separate — a duplicated node is a visible, fixable
+ * problem, whereas a wrongly merged node silently corrupts the graph.
+ */
+export interface SourcedModel {
+    provider: string;
+    kind: 'declarative' | 'runtime';
+    model: Model;
+}
+export interface MergeConflict {
+    id: string;
+    field: 'kind' | 'name' | 'group' | 'platform';
+    values: Array<{
+        provider: string;
+        value: string | undefined;
+    }>;
+    /** The value that won, and why. */
+    resolved: string | undefined;
+}
+export interface MergeResult {
+    model: Model;
+    conflicts: MergeConflict[];
+}
+export declare function mergeModels(sources: SourcedModel[], aliases?: Record<string, string>): MergeResult;
+export declare function formatConflicts(conflicts: MergeConflict[]): string;

package/dist/model/merge.js

@@ -0,0 +1,96 @@
+import { emptyModel } from './schema.js';
+const CONFLICT_FIELDS = ['kind', 'name', 'group', 'platform'];
+/**
+ * Declarative sources describe intent and own naming and grouping; runtime
+ * sources describe what's actually live. When both saw the same entity, the
+ * declarative value wins on these descriptive fields — a monitoring agent's
+ * display name is usually noisier than the IaC resource name.
+ */
+function preferred(candidates) {
+    const withValue = candidates.filter((c) => c.value !== undefined);
+    if (withValue.length === 0)
+        return undefined;
+    return (withValue.find((c) => c.kind === 'declarative') ?? withValue[0]).value;
+}
+export function mergeModels(sources, aliases = {}) {
+    const resolveId = (id) => aliases[id] ?? id;
+    const byId = new Map();
+    for (const src of sources) {
+        for (const entity of src.model.entities) {
+            const id = resolveId(entity.id);
+            const list = byId.get(id) ?? [];
+            list.push({ provider: src.provider, kind: src.kind, entity });
+            byId.set(id, list);
+        }
+    }
+    const entities = [];
+    const conflicts = [];
+    for (const [id, observations] of byId) {
+        const first = observations[0].entity;
+        const merged = { ...first, id, level: first.level };
+        for (const field of CONFLICT_FIELDS) {
+            const candidates = observations.map((o) => ({
+                provider: o.provider,
+                kind: o.kind,
+                value: o.entity[field],
+            }));
+            const distinct = [...new Set(candidates.map((c) => c.value).filter((v) => v !== undefined))];
+            const winner = preferred(candidates);
+            if (field === 'kind') {
+                merged.kind = winner ?? first.kind;
+            }
+            else {
+                merged[field] = winner;
+            }
+            if (distinct.length > 1) {
+                conflicts.push({
+                    id,
+                    field,
+                    values: candidates.map((c) => ({ provider: c.provider, value: c.value })),
+                    resolved: winner,
+                });
+            }
+        }
+        // Provenance: every provider that saw this entity, so a drift report can
+        // say "Terraform knows about it, Dynatrace has never seen it run".
+        merged.source = [...new Set(observations.map((o) => o.provider))].sort().join('+');
+        const tags = {};
+        for (const o of observations)
+            Object.assign(tags, o.entity.tags ?? {});
+        if (Object.keys(tags).length > 0)
+            merged.tags = tags;
+        entities.push(merged);
+    }
+    const known = new Set(entities.map((e) => e.id));
+    const edgeMap = new Map();
+    for (const src of sources) {
+        for (const edge of src.model.edges) {
+            const from = resolveId(edge.from);
+            const to = resolveId(edge.to);
+            // Aliasing can collapse two ids into one and turn an edge into a loop.
+            if (from === to)
+                continue;
+            if (!known.has(from) || !known.has(to))
+                continue;
+            const key = `${from} ${to}`;
+            if (!edgeMap.has(key))
+                edgeMap.set(key, { ...edge, from, to });
+        }
+    }
+    const model = emptyModel(sources[0]?.model.name ?? 'merged');
+    model.entities = entities.sort((a, b) => a.id.localeCompare(b.id));
+    model.edges = [...edgeMap.values()].sort((a, b) => (a.from + a.to).localeCompare(b.from + b.to));
+    model.aliases = aliases;
+    return { model, conflicts };
+}
+export function formatConflicts(conflicts) {
+    if (conflicts.length === 0)
+        return '';
+    const out = [`### Provider disagreements (${conflicts.length})`, '', '| Entity | Field | Values | Resolved |', '|---|---|---|---|'];
+    for (const c of conflicts) {
+        const values = c.values.map((v) => `${v.provider}=${v.value ?? '-'}`).join(', ');
+        out.push(`| \`${c.id}\` | ${c.field} | ${values} | ${c.resolved ?? '-'} |`);
+    }
+    out.push('');
+    return out.join('\n');
+}

package/dist/model/schema.d.ts

@@ -0,0 +1,322 @@
+import { z } from 'zod';
+/**
+ * The model is the only thing that lives in git. Providers write into it,
+ * renderers read from it, and the reconciler diffs it against reality.
+ *
+ * `kind` is deliberately an open string rather than an enum — any provider
+ * must be able to emit its own vocabulary (`aws_s3_bucket`, `service`,
+ * `k8s_deployment`) without a schema change. Renderers map known kinds to
+ * shapes and fall back gracefully for the rest.
+ */
+export declare const Level: z.ZodEnum<["context", "container", "component"]>;
+export type Level = z.infer<typeof Level>;
+export declare const Entity: z.ZodObject<{
+    /** Stable identity. For Terraform this is the resource address. */
+    id: z.ZodString;
+    kind: z.ZodString;
+    name: z.ZodOptional<z.ZodString>;
+    /** Visual + logical grouping — becomes a subgraph when rendered. */
+    group: z.ZodOptional<z.ZodString>;
+    /** Where it runs: aws, gcp, azure, onprem, kubernetes. */
+    platform: z.ZodOptional<z.ZodString>;
+    /** Which provider observed it. Provenance, set by the merge step. */
+    source: z.ZodOptional<z.ZodString>;
+    level: z.ZodDefault<z.ZodEnum<["context", "container", "component"]>>;
+    /** Free-form metadata. Excluded from drift comparison by default. */
+    tags: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    kind: string;
+    level: "context" | "container" | "component";
+    name?: string | undefined;
+    group?: string | undefined;
+    platform?: string | undefined;
+    source?: string | undefined;
+    tags?: Record<string, string> | undefined;
+}, {
+    id: string;
+    kind: string;
+    name?: string | undefined;
+    group?: string | undefined;
+    platform?: string | undefined;
+    source?: string | undefined;
+    level?: "context" | "container" | "component" | undefined;
+    tags?: Record<string, string> | undefined;
+}>;
+export type Entity = z.infer<typeof Entity>;
+export declare const Edge: z.ZodObject<{
+    from: z.ZodString;
+    to: z.ZodString;
+    kind: z.ZodDefault<z.ZodString>;
+    label: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    kind: string;
+    from: string;
+    to: string;
+    label?: string | undefined;
+}, {
+    from: string;
+    to: string;
+    kind?: string | undefined;
+    label?: string | undefined;
+}>;
+export type Edge = z.infer<typeof Edge>;
+/**
+ * A scoped slice of the model. Flat Mermaid becomes unreadable past roughly
+ * 150 nodes, so views exist from v1 rather than being a later optimization.
+ * Patterns match an entity's id or group, and support a trailing `*`.
+ */
+export declare const View: z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodOptional<z.ZodString>;
+    level: z.ZodDefault<z.ZodEnum<["context", "container", "component"]>>;
+    include: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    exclude: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    level: "context" | "container" | "component";
+    include: string[];
+    exclude: string[];
+    title?: string | undefined;
+}, {
+    id: string;
+    level?: "context" | "container" | "component" | undefined;
+    title?: string | undefined;
+    include?: string[] | undefined;
+    exclude?: string[] | undefined;
+}>;
+export type View = z.infer<typeof View>;
+/** Intentional divergence, reviewed like code. */
+export declare const Ignore: z.ZodObject<{
+    entities: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    kinds: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    edges: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        from: z.ZodString;
+        to: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        from: string;
+        to: string;
+    }, {
+        from: string;
+        to: string;
+    }>, "many">>;
+}, "strip", z.ZodTypeAny, {
+    entities: string[];
+    kinds: string[];
+    edges: {
+        from: string;
+        to: string;
+    }[];
+}, {
+    entities?: string[] | undefined;
+    kinds?: string[] | undefined;
+    edges?: {
+        from: string;
+        to: string;
+    }[] | undefined;
+}>;
+export type Ignore = z.infer<typeof Ignore>;
+export declare const Model: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    name: z.ZodString;
+    entities: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        /** Stable identity. For Terraform this is the resource address. */
+        id: z.ZodString;
+        kind: z.ZodString;
+        name: z.ZodOptional<z.ZodString>;
+        /** Visual + logical grouping — becomes a subgraph when rendered. */
+        group: z.ZodOptional<z.ZodString>;
+        /** Where it runs: aws, gcp, azure, onprem, kubernetes. */
+        platform: z.ZodOptional<z.ZodString>;
+        /** Which provider observed it. Provenance, set by the merge step. */
+        source: z.ZodOptional<z.ZodString>;
+        level: z.ZodDefault<z.ZodEnum<["context", "container", "component"]>>;
+        /** Free-form metadata. Excluded from drift comparison by default. */
+        tags: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        kind: string;
+        level: "context" | "container" | "component";
+        name?: string | undefined;
+        group?: string | undefined;
+        platform?: string | undefined;
+        source?: string | undefined;
+        tags?: Record<string, string> | undefined;
+    }, {
+        id: string;
+        kind: string;
+        name?: string | undefined;
+        group?: string | undefined;
+        platform?: string | undefined;
+        source?: string | undefined;
+        level?: "context" | "container" | "component" | undefined;
+        tags?: Record<string, string> | undefined;
+    }>, "many">>;
+    edges: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        from: z.ZodString;
+        to: z.ZodString;
+        kind: z.ZodDefault<z.ZodString>;
+        label: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        kind: string;
+        from: string;
+        to: string;
+        label?: string | undefined;
+    }, {
+        from: string;
+        to: string;
+        kind?: string | undefined;
+        label?: string | undefined;
+    }>, "many">>;
+    views: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        title: z.ZodOptional<z.ZodString>;
+        level: z.ZodDefault<z.ZodEnum<["context", "container", "component"]>>;
+        include: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        exclude: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        level: "context" | "container" | "component";
+        include: string[];
+        exclude: string[];
+        title?: string | undefined;
+    }, {
+        id: string;
+        level?: "context" | "container" | "component" | undefined;
+        title?: string | undefined;
+        include?: string[] | undefined;
+        exclude?: string[] | undefined;
+    }>, "many">>;
+    ignore: z.ZodDefault<z.ZodObject<{
+        entities: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        kinds: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        edges: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            from: z.ZodString;
+            to: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            from: string;
+            to: string;
+        }, {
+            from: string;
+            to: string;
+        }>, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        entities: string[];
+        kinds: string[];
+        edges: {
+            from: string;
+            to: string;
+        }[];
+    }, {
+        entities?: string[] | undefined;
+        kinds?: string[] | undefined;
+        edges?: {
+            from: string;
+            to: string;
+        }[] | undefined;
+    }>>;
+    /**
+     * Cross-provider identity. Maps a provider's native id to the canonical
+     * entity id, so Dynatrace's `SERVICE-A1B2` and Terraform's
+     * `aws_lambda_function.forwarder` collapse into one node.
+     *
+     * This is deliberately manual. Automatic identity resolution across
+     * declarative and runtime sources is the hard, unsolved part of this
+     * problem, and guessing wrong silently corrupts the graph.
+     */
+    aliases: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+    /**
+     * Declared blind spots. Read-only credentials never see everything, and
+     * "unknown" must never be silently reported as "absent".
+     */
+    coverage: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        scope: z.ZodString;
+        reason: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        scope: string;
+        reason: string;
+    }, {
+        scope: string;
+        reason: string;
+    }>, "many">>;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    entities: {
+        id: string;
+        kind: string;
+        level: "context" | "container" | "component";
+        name?: string | undefined;
+        group?: string | undefined;
+        platform?: string | undefined;
+        source?: string | undefined;
+        tags?: Record<string, string> | undefined;
+    }[];
+    edges: {
+        kind: string;
+        from: string;
+        to: string;
+        label?: string | undefined;
+    }[];
+    version: 1;
+    views: {
+        id: string;
+        level: "context" | "container" | "component";
+        include: string[];
+        exclude: string[];
+        title?: string | undefined;
+    }[];
+    ignore: {
+        entities: string[];
+        kinds: string[];
+        edges: {
+            from: string;
+            to: string;
+        }[];
+    };
+    aliases: Record<string, string>;
+    coverage: {
+        scope: string;
+        reason: string;
+    }[];
+}, {
+    name: string;
+    version: 1;
+    entities?: {
+        id: string;
+        kind: string;
+        name?: string | undefined;
+        group?: string | undefined;
+        platform?: string | undefined;
+        source?: string | undefined;
+        level?: "context" | "container" | "component" | undefined;
+        tags?: Record<string, string> | undefined;
+    }[] | undefined;
+    edges?: {
+        from: string;
+        to: string;
+        kind?: string | undefined;
+        label?: string | undefined;
+    }[] | undefined;
+    views?: {
+        id: string;
+        level?: "context" | "container" | "component" | undefined;
+        title?: string | undefined;
+        include?: string[] | undefined;
+        exclude?: string[] | undefined;
+    }[] | undefined;
+    ignore?: {
+        entities?: string[] | undefined;
+        kinds?: string[] | undefined;
+        edges?: {
+            from: string;
+            to: string;
+        }[] | undefined;
+    } | undefined;
+    aliases?: Record<string, string> | undefined;
+    coverage?: {
+        scope: string;
+        reason: string;
+    }[] | undefined;
+}>;
+export type Model = z.infer<typeof Model>;
+export declare function emptyModel(name: string): Model;

package/dist/model/schema.js

@@ -0,0 +1,78 @@
+import { z } from 'zod';
+/**
+ * The model is the only thing that lives in git. Providers write into it,
+ * renderers read from it, and the reconciler diffs it against reality.
+ *
+ * `kind` is deliberately an open string rather than an enum — any provider
+ * must be able to emit its own vocabulary (`aws_s3_bucket`, `service`,
+ * `k8s_deployment`) without a schema change. Renderers map known kinds to
+ * shapes and fall back gracefully for the rest.
+ */
+export const Level = z.enum(['context', 'container', 'component']);
+export const Entity = z.object({
+    /** Stable identity. For Terraform this is the resource address. */
+    id: z.string().min(1),
+    kind: z.string().min(1),
+    name: z.string().optional(),
+    /** Visual + logical grouping — becomes a subgraph when rendered. */
+    group: z.string().optional(),
+    /** Where it runs: aws, gcp, azure, onprem, kubernetes. */
+    platform: z.string().optional(),
+    /** Which provider observed it. Provenance, set by the merge step. */
+    source: z.string().optional(),
+    level: Level.default('container'),
+    /** Free-form metadata. Excluded from drift comparison by default. */
+    tags: z.record(z.string()).optional(),
+});
+export const Edge = z.object({
+    from: z.string().min(1),
+    to: z.string().min(1),
+    kind: z.string().default('depends-on'),
+    label: z.string().optional(),
+});
+/**
+ * A scoped slice of the model. Flat Mermaid becomes unreadable past roughly
+ * 150 nodes, so views exist from v1 rather than being a later optimization.
+ * Patterns match an entity's id or group, and support a trailing `*`.
+ */
+export const View = z.object({
+    id: z.string().min(1),
+    title: z.string().optional(),
+    level: Level.default('container'),
+    include: z.array(z.string()).default([]),
+    exclude: z.array(z.string()).default([]),
+});
+/** Intentional divergence, reviewed like code. */
+export const Ignore = z.object({
+    entities: z.array(z.string()).default([]),
+    kinds: z.array(z.string()).default([]),
+    edges: z.array(z.object({ from: z.string(), to: z.string() })).default([]),
+});
+export const Model = z.object({
+    version: z.literal(1),
+    name: z.string().min(1),
+    entities: z.array(Entity).default([]),
+    edges: z.array(Edge).default([]),
+    views: z.array(View).default([]),
+    ignore: Ignore.default({ entities: [], kinds: [], edges: [] }),
+    /**
+     * Cross-provider identity. Maps a provider's native id to the canonical
+     * entity id, so Dynatrace's `SERVICE-A1B2` and Terraform's
+     * `aws_lambda_function.forwarder` collapse into one node.
+     *
+     * This is deliberately manual. Automatic identity resolution across
+     * declarative and runtime sources is the hard, unsolved part of this
+     * problem, and guessing wrong silently corrupts the graph.
+     */
+    aliases: z.record(z.string()).default({}),
+    /**
+     * Declared blind spots. Read-only credentials never see everything, and
+     * "unknown" must never be silently reported as "absent".
+     */
+    coverage: z
+        .array(z.object({ scope: z.string(), reason: z.string() }))
+        .default([]),
+});
+export function emptyModel(name) {
+    return Model.parse({ version: 1, name });
+}

package/dist/model/validate.d.ts

@@ -0,0 +1,21 @@
+import { Model } from './schema.js';
+export interface Issue {
+    severity: 'error' | 'warning';
+    message: string;
+}
+export interface ValidationResult {
+    ok: boolean;
+    model?: Model;
+    issues: Issue[];
+}
+/** Matches an id or group against a pattern supporting a trailing `*`. */
+export declare function matches(pattern: string, value: string): boolean;
+/**
+ * Schema validation alone isn't enough — a model can be well-formed YAML and
+ * still be nonsense (an edge pointing at an entity that doesn't exist, two
+ * entities sharing an id). Those are the failures that would produce a broken
+ * diagram silently, so they're errors, not warnings.
+ */
+export declare function validateModel(raw: unknown): ValidationResult;
+export declare function loadModel(source: string): ValidationResult;
+export declare function dumpModel(model: Model): string;

package/dist/model/validate.js

@@ -0,0 +1,76 @@
+import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
+import { Model } from './schema.js';
+/** Matches an id or group against a pattern supporting a trailing `*`. */
+export function matches(pattern, value) {
+    if (pattern === '*')
+        return true;
+    if (pattern.endsWith('*'))
+        return value.startsWith(pattern.slice(0, -1));
+    return pattern === value;
+}
+/**
+ * Schema validation alone isn't enough — a model can be well-formed YAML and
+ * still be nonsense (an edge pointing at an entity that doesn't exist, two
+ * entities sharing an id). Those are the failures that would produce a broken
+ * diagram silently, so they're errors, not warnings.
+ */
+export function validateModel(raw) {
+    const parsed = Model.safeParse(raw);
+    if (!parsed.success) {
+        return {
+            ok: false,
+            issues: parsed.error.issues.map((i) => ({
+                severity: 'error',
+                message: `${i.path.join('.') || '(root)'}: ${i.message}`,
+            })),
+        };
+    }
+    const model = parsed.data;
+    const issues = [];
+    const ids = new Set();
+    for (const e of model.entities) {
+        if (ids.has(e.id)) {
+            issues.push({ severity: 'error', message: `duplicate entity id: ${e.id}` });
+        }
+        ids.add(e.id);
+    }
+    for (const edge of model.edges) {
+        if (!ids.has(edge.from)) {
+            issues.push({ severity: 'error', message: `edge references unknown entity: ${edge.from} (in ${edge.from} -> ${edge.to})` });
+        }
+        if (!ids.has(edge.to)) {
+            issues.push({ severity: 'error', message: `edge references unknown entity: ${edge.to} (in ${edge.from} -> ${edge.to})` });
+        }
+        if (edge.from === edge.to) {
+            issues.push({ severity: 'warning', message: `self-referencing edge on ${edge.from}` });
+        }
+    }
+    const viewIds = new Set();
+    for (const view of model.views) {
+        if (viewIds.has(view.id)) {
+            issues.push({ severity: 'error', message: `duplicate view id: ${view.id}` });
+        }
+        viewIds.add(view.id);
+        // A view that selects nothing is almost always a typo in a pattern.
+        const hit = model.entities.some((e) => view.include.length === 0
+            ? true
+            : view.include.some((p) => matches(p, e.id) || (e.group != null && matches(p, e.group))));
+        if (!hit) {
+            issues.push({ severity: 'warning', message: `view '${view.id}' matches no entities` });
+        }
+    }
+    return { ok: !issues.some((i) => i.severity === 'error'), model, issues };
+}
+export function loadModel(source) {
+    let raw;
+    try {
+        raw = parseYaml(source);
+    }
+    catch (err) {
+        return { ok: false, issues: [{ severity: 'error', message: `invalid YAML: ${err.message}` }] };
+    }
+    return validateModel(raw);
+}
+export function dumpModel(model) {
+    return stringifyYaml(model, { lineWidth: 0 });
+}