@brignano/driftwood 0.0.0

package/dist/registry.js

@@ -0,0 +1,43 @@
+/**
+ * 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 class Registry {
+    label;
+    items = new Map();
+    constructor(label) {
+        this.label = label;
+    }
+    register(item) {
+        if (this.items.has(item.name)) {
+            throw new Error(`${this.label} '${item.name}' is already registered`);
+        }
+        this.items.set(item.name, item);
+        return this;
+    }
+    /** Replaces an existing entry. Used by tests and by deliberate overrides. */
+    override(item) {
+        this.items.set(item.name, item);
+        return this;
+    }
+    get(name) {
+        const item = this.items.get(name);
+        if (!item) {
+            throw new Error(`unknown ${this.label} '${name}' (available: ${this.names().join(', ') || 'none'})`);
+        }
+        return item;
+    }
+    has(name) {
+        return this.items.has(name);
+    }
+    names() {
+        return [...this.items.keys()].sort();
+    }
+    all() {
+        return this.names().map((n) => this.items.get(n));
+    }
+}

package/dist/render/dot.d.ts

@@ -0,0 +1,4 @@
+import type { Model } from '../model/schema.js';
+import type { RenderContext } from './types.js';
+export declare function renderDot(model: Model, ctx?: RenderContext): string;
+export declare const dotRenderer: import("./types.js").Renderer;

package/dist/render/dot.js

@@ -0,0 +1,92 @@
+import { defineRenderer } from './types.js';
+import { selectEntities } from './select.js';
+/**
+ * Graphviz DOT source.
+ *
+ * Emitting DOT needs no Graphviz installed — it's just text. That distinction
+ * matters: `dot` (this renderer) always works, while `graphviz` (rendering DOT
+ * to SVG) needs an engine. So even a locked-down machine can produce DOT for
+ * someone else to render, and nothing is lost by not having the binary.
+ */
+function quote(text) {
+    return text.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+}
+const SHAPES = [
+    [/(s3|bucket|rds|dynamodb|database|efs|volume|storage)/i, 'cylinder'],
+    [/(sqs|sns|queue|topic|kinesis|kafka|eventbridge)/i, 'parallelogram'],
+    [/(route53|dns|cloudfront|vpc|subnet|lb|gateway|cdn|zone|record)/i, 'ellipse'],
+    [/(iam|role|policy|secret|kms|cert|acm|auth)/i, 'hexagon'],
+];
+function shapeFor(kind) {
+    for (const [pattern, shape] of SHAPES)
+        if (pattern.test(kind))
+            return shape;
+    return 'box';
+}
+const HEALTH_COLORS = {
+    healthy: '#0f9d58',
+    degraded: '#f4b400',
+    down: '#db4437',
+};
+export function renderDot(model, ctx = {}) {
+    const view = ctx.view ? model.views.find((v) => v.id === ctx.view) : undefined;
+    if (ctx.view && !view) {
+        throw new Error(`unknown view: ${ctx.view} (have: ${model.views.map((v) => v.id).join(', ') || 'none'})`);
+    }
+    const entities = selectEntities(model, view);
+    const visible = new Set(entities.map((e) => e.id));
+    const lines = [
+        `digraph "${quote(model.name)}" {`,
+        `  rankdir=${ctx.direction === 'TD' ? 'TB' : 'LR'};`,
+        '  node [fontname="Helvetica" style=filled fillcolor="#ffffff"];',
+        '  edge [fontname="Helvetica" color="#666666"];',
+    ];
+    const grouped = new Map();
+    const ungrouped = [];
+    for (const e of entities) {
+        if (e.group) {
+            const list = grouped.get(e.group) ?? [];
+            list.push(e);
+            grouped.set(e.group, list);
+        }
+        else
+            ungrouped.push(e);
+    }
+    const nodeLine = (e, indent) => {
+        const label = `${e.name ?? e.id}\\n${e.kind}`;
+        const health = ctx.health?.[e.id];
+        const color = health ? ` fillcolor="${HEALTH_COLORS[health]}" fontcolor="#ffffff"` : '';
+        return `${indent}"${quote(e.id)}" [label="${quote(label)}" shape=${shapeFor(e.kind)}${color}];`;
+    };
+    let clusterIndex = 0;
+    for (const [group, members] of [...grouped.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+        lines.push(`  subgraph cluster_${clusterIndex++} {`);
+        lines.push(`    label="${quote(group)}";`);
+        lines.push('    style=rounded; color="#999999";');
+        for (const e of members)
+            lines.push(nodeLine(e, '    '));
+        lines.push('  }');
+    }
+    for (const e of ungrouped)
+        lines.push(nodeLine(e, '  '));
+    for (const edge of model.edges) {
+        if (!visible.has(edge.from) || !visible.has(edge.to))
+            continue;
+        const label = edge.label ? ` [label="${quote(edge.label)}"]` : '';
+        lines.push(`  "${quote(edge.from)}" -> "${quote(edge.to)}"${label};`);
+    }
+    lines.push('}');
+    return lines.join('\n') + '\n';
+}
+export const dotRenderer = defineRenderer({
+    name: 'dot',
+    description: 'Graphviz DOT source (no Graphviz installation required)',
+    extension: 'dot',
+    priority: 10,
+    async probe() {
+        return { available: true, via: 'built-in' };
+    },
+    async render(model, ctx) {
+        return renderDot(model, ctx);
+    },
+});

package/dist/render/graphviz.d.ts

@@ -0,0 +1,47 @@
+import type { Model } from '../model/schema.js';
+import type { RenderContext } from './types.js';
+/**
+ * Graphviz rendering to SVG. Graphviz is **bundled, not required**.
+ *
+ * The problem this project came from: `mingrammer/diagrams` requires the
+ * Graphviz *system binary*, which cannot clear corporate software approval.
+ * The answer isn't to drop Graphviz, nor to make it an optional extra the user
+ * has to go and find — it's to ship it in a form that needs no system package.
+ *
+ * `@hpcc-js/wasm-graphviz` is real Graphviz compiled to WebAssembly: same DOT
+ * semantics, same layouts, zero transitive dependencies, and the WASM is
+ * inlined into the JS so there is no separate binary to locate. It is a
+ * regular dependency, so `npm install` yields working Graphviz on any machine.
+ *
+ * Three tiers remain, in preference order:
+ *
+ *   1. native — the `dot` binary is on PATH. Preferred when present: faster on
+ *      very large graphs, and it honours a site's own Graphviz build/plugins.
+ *   2. wasm   — the bundled WASM build. The default. Works anywhere
+ *      WebAssembly does, with no admin rights and no system package.
+ *   3. none   — WebAssembly is switched off (a hardened or `--jitless`
+ *      runtime), so `--engine auto` falls back to Mermaid.
+ *
+ * Tier 3 is rare but real, which is why the fallback is not vestigial.
+ */
+export type GraphvizTier = 'native' | 'wasm' | 'none';
+/** Runs `dot -V` to see whether a usable native Graphviz is on PATH. */
+export declare function probeNativeDot(command?: string): Promise<boolean>;
+interface WasmGraphviz {
+    layout(source: string, format: string, engine: string): string;
+}
+/**
+ * Loads the bundled WASM build.
+ *
+ * Imported lazily rather than at module load: it is ~800KB, and a Mermaid-only
+ * render should never pay for it. Still wrapped in try/catch because
+ * WebAssembly can be disabled at runtime, and that must degrade to the Mermaid
+ * fallback rather than crash.
+ */
+export declare function loadWasmGraphviz(): Promise<WasmGraphviz | undefined>;
+/** Test seam: forget any cached WASM instance. */
+export declare function resetWasmCache(): void;
+export declare function detectTier(): Promise<GraphvizTier>;
+export declare function renderGraphvizSvg(model: Model, ctx?: RenderContext): Promise<string>;
+export declare const graphvizRenderer: import("./types.js").Renderer;
+export {};

package/dist/render/graphviz.js

@@ -0,0 +1,121 @@
+import { spawn } from 'node:child_process';
+import { renderDot } from './dot.js';
+import { defineRenderer } from './types.js';
+/** Runs `dot -V` to see whether a usable native Graphviz is on PATH. */
+export function probeNativeDot(command = 'dot') {
+    return new Promise((resolve) => {
+        let settled = false;
+        const done = (v) => {
+            if (!settled) {
+                settled = true;
+                resolve(v);
+            }
+        };
+        try {
+            const child = spawn(command, ['-V'], { stdio: 'ignore' });
+            child.on('error', () => done(false));
+            child.on('close', (code) => done(code === 0));
+            // A hung probe must never block a render; treat slow as absent.
+            setTimeout(() => {
+                child.kill();
+                done(false);
+            }, 2000).unref?.();
+        }
+        catch {
+            done(false);
+        }
+    });
+}
+let wasmCache;
+let wasmAttempted = false;
+/**
+ * Loads the bundled WASM build.
+ *
+ * Imported lazily rather than at module load: it is ~800KB, and a Mermaid-only
+ * render should never pay for it. Still wrapped in try/catch because
+ * WebAssembly can be disabled at runtime, and that must degrade to the Mermaid
+ * fallback rather than crash.
+ */
+export async function loadWasmGraphviz() {
+    if (wasmAttempted)
+        return wasmCache;
+    wasmAttempted = true;
+    try {
+        // `lib` is ES2022, which has no WebAssembly types; probe it off globalThis.
+        if (typeof globalThis.WebAssembly === 'undefined')
+            return undefined;
+        const { Graphviz } = await import('@hpcc-js/wasm-graphviz');
+        wasmCache = (await Graphviz.load());
+    }
+    catch {
+        wasmCache = undefined;
+    }
+    return wasmCache;
+}
+/** Test seam: forget any cached WASM instance. */
+export function resetWasmCache() {
+    wasmCache = undefined;
+    wasmAttempted = false;
+}
+export async function detectTier() {
+    if (await probeNativeDot())
+        return 'native';
+    if (await loadWasmGraphviz())
+        return 'wasm';
+    return 'none';
+}
+function runNativeDot(source, engine, format) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(engine, [`-T${format}`]);
+        let out = '';
+        let err = '';
+        child.stdout.on('data', (d) => (out += d));
+        child.stderr.on('data', (d) => (err += d));
+        child.on('error', reject);
+        child.on('close', (code) => {
+            if (code === 0)
+                resolve(out);
+            else
+                reject(new Error(`${engine} exited ${code}: ${err.trim()}`));
+        });
+        child.stdin.write(source);
+        child.stdin.end();
+    });
+}
+export async function renderGraphvizSvg(model, ctx = {}) {
+    const source = renderDot(model, ctx);
+    const tier = await detectTier();
+    if (tier === 'native')
+        return runNativeDot(source, 'dot', 'svg');
+    if (tier === 'wasm') {
+        const gv = await loadWasmGraphviz();
+        if (gv)
+            return gv.layout(source, 'svg', 'dot');
+    }
+    throw new Error('Graphviz is unavailable because WebAssembly is disabled in this runtime ' +
+        '(for example `node --jitless`). Install the `dot` binary, or use ' +
+        '--engine mermaid, which needs neither.');
+}
+export const graphvizRenderer = defineRenderer({
+    name: 'graphviz',
+    description: 'Graphviz-rendered SVG (bundled WASM build, or a native `dot` binary)',
+    extension: 'svg',
+    // Highest priority: Graphviz layout beats Mermaid's, and it is available by
+    // default. `auto` only drops past it where WebAssembly is switched off.
+    priority: 100,
+    async probe() {
+        const tier = await detectTier();
+        if (tier === 'native')
+            return { available: true, via: 'native dot binary' };
+        if (tier === 'wasm')
+            return { available: true, via: 'bundled @hpcc-js/wasm-graphviz' };
+        return {
+            available: false,
+            reason: 'WebAssembly is disabled in this runtime, so the bundled Graphviz cannot load — ' +
+                'install the `dot` binary or use --engine mermaid',
+        };
+    },
+    async render(model, ctx) {
+        return renderGraphvizSvg(model, ctx);
+    },
+});

package/dist/render/index.d.ts

@@ -0,0 +1,28 @@
+import { Registry } from '../registry.js';
+import type { Model } from '../model/schema.js';
+import type { Renderer, RenderContext } from './types.js';
+export declare const renderers: Registry<Renderer>;
+export interface Resolved {
+    renderer: Renderer;
+    via: string;
+    /** Set when `auto` wanted a higher-priority engine but it wasn't usable. */
+    fellBackFrom?: string;
+}
+/**
+ * Picks a renderer. `auto` walks engines by priority and takes the first that
+ * reports itself usable, so a machine with Graphviz gets Graphviz and a locked
+ * down one silently gets Mermaid — same command, same config, no failure.
+ */
+export declare function resolveRenderer(engine?: string): Promise<Resolved>;
+export declare function render(model: Model, ctx?: RenderContext, engine?: string): Promise<{
+    output: string;
+    renderer: Renderer;
+    via: string;
+    /** Set when `auto` wanted a higher-priority engine but it wasn't usable. */
+    fellBackFrom?: string;
+}>;
+export { renderMermaid } from './mermaid.js';
+export { renderDot } from './dot.js';
+export { renderGraphvizSvg, detectTier, probeNativeDot } from './graphviz.js';
+export { selectEntities } from './select.js';
+export type { Renderer, RenderContext, Availability } from './types.js';

package/dist/render/index.js

@@ -0,0 +1,42 @@
+import { Registry } from '../registry.js';
+import { mermaidRenderer } from './mermaid.js';
+import { dotRenderer } from './dot.js';
+import { graphvizRenderer } from './graphviz.js';
+export const renderers = new Registry('renderer');
+renderers.register(graphvizRenderer);
+renderers.register(mermaidRenderer);
+renderers.register(dotRenderer);
+/**
+ * Picks a renderer. `auto` walks engines by priority and takes the first that
+ * reports itself usable, so a machine with Graphviz gets Graphviz and a locked
+ * down one silently gets Mermaid — same command, same config, no failure.
+ */
+export async function resolveRenderer(engine = 'auto') {
+    if (engine !== 'auto') {
+        const renderer = renderers.get(engine);
+        const probe = await renderer.probe();
+        if (!probe.available) {
+            // An explicit choice fails loudly; only `auto` is allowed to substitute.
+            throw new Error(`renderer '${engine}' is not available: ${probe.reason ?? 'unknown reason'}`);
+        }
+        return { renderer, via: probe.via ?? 'unknown' };
+    }
+    const ordered = [...renderers.all()].sort((a, b) => b.priority - a.priority);
+    let skipped;
+    for (const renderer of ordered) {
+        const probe = await renderer.probe();
+        if (probe.available) {
+            return { renderer, via: probe.via ?? 'unknown', fellBackFrom: skipped };
+        }
+        skipped ??= renderer.name;
+    }
+    throw new Error('no renderer is available');
+}
+export async function render(model, ctx = {}, engine = 'auto') {
+    const resolved = await resolveRenderer(engine);
+    return { ...resolved, output: await resolved.renderer.render(model, ctx) };
+}
+export { renderMermaid } from './mermaid.js';
+export { renderDot } from './dot.js';
+export { renderGraphvizSvg, detectTier, probeNativeDot } from './graphviz.js';
+export { selectEntities } from './select.js';

package/dist/render/mermaid.d.ts

@@ -0,0 +1,5 @@
+import type { Model } from '../model/schema.js';
+import type { RenderContext } from './types.js';
+export type RenderOptions = RenderContext;
+export declare function renderMermaid(model: Model, opts?: RenderOptions): string;
+export declare const mermaidRenderer: import("./types.js").Renderer;

package/dist/render/mermaid.js

@@ -0,0 +1,107 @@
+import { selectEntities } from './select.js';
+import { defineRenderer } from './types.js';
+/**
+ * Mermaid is the default renderer for one reason: it renders natively in
+ * GitHub and GitLab markdown, so the reader installs nothing. No Graphviz
+ * binary, no system package, no software-center ticket.
+ */
+/** Mermaid node ids can't contain dots, brackets, or quotes. */
+function nodeId(id) {
+    return 'n_' + id.replace(/[^a-zA-Z0-9_]/g, '_');
+}
+function escapeLabel(text) {
+    // Mermaid renders <br/> inside a quoted label; a raw newline breaks parsing.
+    return text.replace(/"/g, '&quot;').replace(/\n/g, '<br/>');
+}
+const KIND_PATTERNS = [
+    [/(s3|bucket|rds|dynamodb|db|database|efs|volume|storage)/i, 'storage'],
+    [/(sqs|sns|queue|topic|kinesis|kafka|eventbridge)/i, 'messaging'],
+    [/(route53|dns|cloudfront|vpc|subnet|lb|gateway|cdn|zone|record)/i, 'network'],
+    [/(iam|role|policy|secret|kms|cert|acm|auth)/i, 'identity'],
+    [/(lambda|ec2|ecs|function|instance|service|container|app)/i, 'compute'],
+];
+function shapeFor(kind) {
+    for (const [pattern, family] of KIND_PATTERNS) {
+        if (pattern.test(kind))
+            return family;
+    }
+    return 'compute';
+}
+function renderNode(e) {
+    const label = escapeLabel(`${e.name ?? e.id}\n${e.kind}`);
+    const id = nodeId(e.id);
+    switch (shapeFor(e.kind)) {
+        case 'storage':
+            return `${id}[("${label}")]`;
+        case 'messaging':
+            return `${id}[/"${label}"/]`;
+        case 'network':
+            return `${id}("${label}")`;
+        case 'identity':
+            return `${id}{{"${label}"}}`;
+        default:
+            return `${id}["${label}"]`;
+    }
+}
+export function renderMermaid(model, opts = {}) {
+    const view = opts.view ? model.views.find((v) => v.id === opts.view) : undefined;
+    if (opts.view && !view) {
+        throw new Error(`unknown view: ${opts.view} (have: ${model.views.map((v) => v.id).join(', ') || 'none'})`);
+    }
+    const entities = selectEntities(model, view);
+    const visible = new Set(entities.map((e) => e.id));
+    const lines = [`flowchart ${opts.direction ?? 'LR'}`];
+    // Group into subgraphs; ungrouped entities are emitted at the top level.
+    const grouped = new Map();
+    const ungrouped = [];
+    for (const e of entities) {
+        if (e.group) {
+            const list = grouped.get(e.group) ?? [];
+            list.push(e);
+            grouped.set(e.group, list);
+        }
+        else {
+            ungrouped.push(e);
+        }
+    }
+    for (const [group, members] of [...grouped.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+        lines.push(`    subgraph ${nodeId(group)}["${escapeLabel(group)}"]`);
+        for (const e of members)
+            lines.push(`        ${renderNode(e)}`);
+        lines.push('    end');
+    }
+    for (const e of ungrouped)
+        lines.push(`    ${renderNode(e)}`);
+    // An edge is only drawn when both ends survived the view filter.
+    for (const edge of model.edges) {
+        if (!visible.has(edge.from) || !visible.has(edge.to))
+            continue;
+        const label = edge.label ? `|"${escapeLabel(edge.label)}"|` : '';
+        lines.push(`    ${nodeId(edge.from)} -->${label} ${nodeId(edge.to)}`);
+    }
+    if (opts.health) {
+        lines.push('');
+        for (const [id, status] of Object.entries(opts.health)) {
+            if (!visible.has(id))
+                continue;
+            lines.push(`    class ${nodeId(id)} ${status};`);
+        }
+        lines.push('    classDef healthy fill:#0b6b3a,stroke:#0f9d58,color:#fff;');
+        lines.push('    classDef degraded fill:#7a5b00,stroke:#f4b400,color:#fff;');
+        lines.push('    classDef down fill:#7a1c1c,stroke:#db4437,color:#fff;');
+    }
+    return lines.join('\n') + '\n';
+}
+export const mermaidRenderer = defineRenderer({
+    name: 'mermaid',
+    description: 'Mermaid flowchart — renders natively in GitHub, zero install',
+    extension: 'mmd',
+    priority: 50,
+    async probe() {
+        // Always available: it is string generation with no engine behind it.
+        return { available: true, via: 'built-in' };
+    },
+    async render(model, ctx) {
+        return renderMermaid(model, ctx);
+    },
+});

package/dist/render/select.d.ts

@@ -0,0 +1,7 @@
+import type { Entity, Model, View } from '../model/schema.js';
+/**
+ * A view is a scoped slice of the model, matching entity ids or groups with an
+ * optional trailing `*`. Shared by every renderer so scoping behaves
+ * identically no matter which engine draws the picture.
+ */
+export declare function selectEntities(model: Model, view?: View): Entity[];

package/dist/render/select.js

@@ -0,0 +1,17 @@
+import { matches } from '../model/validate.js';
+/**
+ * A view is a scoped slice of the model, matching entity ids or groups with an
+ * optional trailing `*`. Shared by every renderer so scoping behaves
+ * identically no matter which engine draws the picture.
+ */
+export function selectEntities(model, view) {
+    if (!view)
+        return model.entities;
+    return model.entities.filter((e) => {
+        const target = [e.id, e.group ?? ''];
+        const included = view.include.length === 0 ||
+            view.include.some((p) => target.some((t) => t !== '' && matches(p, t)));
+        const excluded = view.exclude.some((p) => target.some((t) => t !== '' && matches(p, t)));
+        return included && !excluded;
+    });
+}

package/dist/render/types.d.ts

@@ -0,0 +1,33 @@
+import type { Model } from '../model/schema.js';
+export interface RenderContext {
+    view?: string;
+    direction?: 'LR' | 'TD';
+    /** Runtime health, applied at render time. Never committed to the model. */
+    health?: Record<string, 'healthy' | 'degraded' | 'down'>;
+}
+export interface Availability {
+    available: boolean;
+    /** How it will render, e.g. 'native dot binary', 'wasm', 'built-in'. */
+    via?: string;
+    /** Why it isn't available, and what to do about it. */
+    reason?: string;
+}
+/**
+ * The renderer extension point.
+ *
+ * `probe()` is what makes graceful degradation possible: a renderer reports
+ * whether it can actually run in this environment, so `--engine auto` can pick
+ * the best available one instead of failing. That is the whole answer to
+ * "Graphviz if we can install it, Mermaid if we can't".
+ */
+export interface Renderer {
+    name: string;
+    description: string;
+    /** File extension for the output, without a dot. */
+    extension: string;
+    /** Higher wins under `--engine auto`. */
+    priority: number;
+    probe(): Promise<Availability>;
+    render(model: Model, ctx: RenderContext): Promise<string>;
+}
+export declare function defineRenderer(r: Renderer): Renderer;

package/dist/render/types.js

@@ -0,0 +1,3 @@
+export function defineRenderer(r) {
+    return r;
+}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@brignano/driftwood",
+  "version": "0.0.0",
+  "description": "Architecture as code, reconciled with live infrastructure.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/brignano/driftwood.git"
+  },
+  "bugs": {
+    "url": "https://github.com/brignano/driftwood/issues"
+  },
+  "homepage": "https://github.com/brignano/driftwood#readme",
+  "keywords": [
+    "architecture",
+    "architecture-as-code",
+    "diagram",
+    "graphviz",
+    "mermaid",
+    "terraform",
+    "drift",
+    "infrastructure",
+    "cli"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "driftwood": "./dist/cli.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "npm run build",
+    "dev": "tsx src/cli.ts",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "dependencies": {
+    "@hpcc-js/wasm-graphviz": "^1.28.0",
+    "commander": "^12.1.0",
+    "yaml": "^2.5.1",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.7.4",
+    "tsx": "^4.19.1",
+    "typescript": "^5.6.2",
+    "vitest": "^2.1.2"
+  }
+}