@johnhenry/sitefile 0.0.0-stage → 0.0.0

package/lib/src/explain.d.ts

@@ -0,0 +1,64 @@
+import { type Operation, type Plan } from './planner.js';
+import type { BuildResult } from './executor.js';
+/** One line describing an operation: its keyword, source and destination (FOR destinations are not evaluated). */
+export declare function operationLabel(op: Operation): string;
+export type GraphNodeKind = 'import' | 'image' | 'plugin' | 'tool' | 'local' | 'operation' | 'stage' | 'site' | 'export';
+export type GraphEdgeKind = 'base' | 'input' | 'next' | 'export';
+export interface GraphNode {
+    readonly id: string;
+    readonly kind: GraphNodeKind;
+    readonly label: string;
+    readonly line?: number;
+}
+export interface GraphEdge {
+    readonly from: string;
+    readonly to: string;
+    readonly kind: GraphEdgeKind;
+}
+export interface Graph {
+    readonly file: string;
+    readonly target?: string;
+    readonly nodes: readonly GraphNode[];
+    readonly edges: readonly GraphEdge[];
+}
+/**
+ * The plan as a graph. Nodes: imports, plugins, tools, local paths read, operations (`op:<line>`), stages (their
+ * final trees), the EXPORT site files and the export. Edges point from what is read to what reads it: `base` (a
+ * stage's starting tree to its first operation), `next` (an operation's tree to the following operation, the
+ * last one to its stage), `input` (sources, plugins, tools and FOR/FEED lists) and `export`.
+ */
+export declare function planGraph(p: Plan): Graph;
+/** `id  label` per node, then one `  <- from (kind)` line per incoming edge, then a count. */
+export declare function graphText(g: Graph): string;
+/** Graphviz DOT (`sitefile graph --dot | dot -Tsvg > graph.svg`). */
+export declare function graphDot(g: Graph): string;
+export interface WhyEvent {
+    /** `Sitefile:12`: the instruction's line. */
+    readonly location: string;
+    /** The instruction, as `graph` labels it. */
+    readonly instruction: string;
+    /** Stage name, or `#n` for an unnamed stage. */
+    readonly stage: string;
+    /** The path in that stage's tree. */
+    readonly path: string;
+    readonly action: 'write' | 'overwrite';
+    readonly digest: string;
+    /** What the content came from: `./src/a.html`, `stage build:/out/a.html`, `import site:/a.html`, `<<EOF`, `plugin x`, `list posts`. */
+    readonly inputs: readonly string[];
+}
+export interface WhyReport {
+    readonly path: string;
+    readonly mode: string;
+    readonly size: number;
+    readonly digest: string;
+    readonly origin: string;
+    /** Oldest first; the last event wrote the file as exported. */
+    readonly history: readonly WhyEvent[];
+}
+/**
+ * Explain one exported file: every write to it (and to the files it was copied from in earlier stages) that
+ * changed it, oldest first. Writes of identical content are no-ops in the tree (the first writer stays the
+ * owner), so they are not listed. `result` must come from a build with `recordSteps`.
+ */
+export declare function why(result: BuildResult, raw: string, contextDir: string): WhyReport;
+export declare function whyText(r: WhyReport): string;

package/lib/src/explain.js

@@ -0,0 +1,445 @@
+import { statSync } from 'node:fs';
+import path from 'node:path';
+import { SitefileError } from './errors.js';
+import { joinVirtual, normalizeVirtual } from './paths.js';
+import { importedStageRefs } from './planner.js';
+import { importedStage } from './language/ast.js';
+// `sitefile graph` and `sitefile why` (issue #94): the dependency graph of a plan, and the history of one
+// output file. Both outputs are part of the CLI contract and identical in the Rust port (rust/src/explain.rs).
+// ---------------------------------------------------------------- labels
+/** A context-relative path as written in a Sitefile: `./src`, `./` for the context root. */
+function localLabel(p) {
+    return './' + p;
+}
+/** A source as an operation label shows it. */
+function sourceLabel(ref) {
+    switch (ref.kind) {
+        case 'inline':
+            return `<<${ref.delimiter}`;
+        case 'stage':
+            return `--from=${ref.name} ${ref.path}`;
+        case 'local':
+            return localLabel(ref.path);
+        case 'import':
+            return ref.path === '/' ? `${ref.name}:` : `${ref.name}:${ref.path}`;
+    }
+}
+/** One line describing an operation: its keyword, source and destination (FOR destinations are not evaluated). */
+export function operationLabel(op) {
+    switch (op.kind) {
+        case 'COPY':
+            return `COPY ${sourceLabel(op.source)} ${op.dest}${op.destIsDir && op.dest !== '/' ? '/' : ''}`;
+        case 'RENDER':
+            return op.each
+                ? `RENDER ${sourceLabel(op.template)} FOR ${op.each.as} IN ${op.each.list}${op.each.by !== undefined ? ` BY ${op.each.by}` : ''}${op.each.page ? ` PAGE ${op.each.page.size}` : ''}`
+                : `RENDER ${sourceLabel(op.template)} TO ${op.dest}`;
+        case 'TRANSFORM':
+            return `TRANSFORM ${op.plugin}${op.source ? ` ${sourceLabel(op.source)}` : ''}${op.each ? ` FOR ${op.each.as} IN ${op.each.list}` : ''}`;
+        case 'SITEMAP':
+            return `SITEMAP ${op.dest}`;
+        case 'FEED':
+            return `FEED ${op.list} ${op.dest}`;
+        case 'FINGERPRINT':
+            return `FINGERPRINT ${op.patterns.join(' ')}`;
+        case 'CHECKLINKS':
+            return `CHECKLINKS${op.warn ? ' --warn' : ''}${op.external ? ' --external' : ''}`;
+    }
+}
+function stageLabel(stage) {
+    const b = stage.base;
+    const base = b.kind === 'scratch' ? 'scratch' : b.kind === 'local' ? localLabel(b.path) : b.kind === 'image' ? `image ${b.ref}${b.at !== undefined ? ` AT ${b.at}` : ''}` : b.name;
+    return `FROM ${base}${stage.name !== undefined ? ` AS ${stage.name}` : ''}`;
+}
+/** `build`, or `#2` for the second stage when it has no name. */
+function stageDisplay(stage, index) {
+    return stage.name ?? `#${index + 1}`;
+}
+function stageId(stage, index) {
+    return `stage:${stageDisplay(stage, index)}`;
+}
+/**
+ * The plan as a graph. Nodes: imports, plugins, tools, local paths read, operations (`op:<line>`), stages (their
+ * final trees), the EXPORT site files and the export. Edges point from what is read to what reads it: `base` (a
+ * stage's starting tree to its first operation), `next` (an operation's tree to the following operation, the
+ * last one to its stage), `input` (sources, plugins, tools and FOR/FEED lists) and `export`.
+ */
+export function planGraph(p) {
+    const nodes = [];
+    const locals = [];
+    const edges = [];
+    const seen = new Set();
+    const edge = (from, to, kind) => {
+        const key = `${from}\0${to}\0${kind}`;
+        if (seen.has(key))
+            return;
+        seen.add(key);
+        edges.push({ from, to, kind });
+    };
+    const local = (rel) => {
+        const id = `local:${localLabel(rel)}`;
+        if (!locals.some((n) => n.id === id))
+            locals.push({ id, kind: 'local', label: localLabel(rel) });
+        return id;
+    };
+    const imports = new Set(p.imports.map((i) => i.name));
+    const tools = new Set(p.tools.map((t) => t.name));
+    const stageIds = new Map();
+    const sourceNode = (ref) => {
+        switch (ref.kind) {
+            case 'inline':
+                return undefined;
+            case 'stage':
+                return stageIds.get(ref.name);
+            case 'local':
+                return local(ref.path);
+            case 'import':
+                return `import:${ref.name}`;
+        }
+    };
+    const list = (name) => (imports.has(name) ? `import:${name}` : undefined);
+    // An IMPORT … SCHEMA reads its schema file.
+    for (const i of p.imports)
+        if (i.schema)
+            edge(local(i.schema.path), `import:${i.name}`, 'input');
+    // Stages of imported Sitefiles (IMPORT … AS sitefile) are read like stages: one node each, fed by the import.
+    const importedStages = [];
+    for (const ref of importedStageRefs(p.stages)) {
+        const id = `stage:${ref.name}`;
+        if (stageIds.has(ref.name))
+            continue;
+        const line = p.imports.find((i) => i.name === ref.import)?.span.line;
+        importedStages.push({ id, kind: 'stage', label: `stage ${ref.stage} of IMPORT ${ref.import}`, ...(line !== undefined ? { line } : {}) });
+        stageIds.set(ref.name, id);
+        edge(`import:${ref.import}`, id, 'input');
+    }
+    const staged = [];
+    const images = [];
+    p.stages.forEach((stage, si) => {
+        const id = stageId(stage, si);
+        const ids = stage.operations.map((op) => `op:${op.span.line}`);
+        const first = ids[0] ?? id;
+        if (stage.base.kind === 'local')
+            edge(local(stage.base.path), first, 'base');
+        else if (stage.base.kind === 'image') {
+            const imageId = `image:${stage.base.ref}`;
+            if (!images.some((n) => n.id === imageId))
+                images.push({ id: imageId, kind: 'image', label: `image ${stage.base.ref}`, line: stage.span.line });
+            edge(imageId, first, 'base');
+        }
+        else if (stage.base.kind === 'stage') {
+            const from = stageIds.get(stage.base.name);
+            if (from)
+                edge(from, first, 'base');
+        }
+        stage.operations.forEach((op, i) => {
+            const opId = ids[i];
+            staged.push({ id: opId, kind: 'operation', label: operationLabel(op), line: op.span.line });
+            const inputs = [];
+            if (op.kind === 'COPY')
+                inputs.push(sourceNode(op.source));
+            if (op.kind === 'RENDER')
+                inputs.push(sourceNode(op.template), op.each ? list(op.each.list) : undefined);
+            if (op.kind === 'TRANSFORM') {
+                inputs.push(op.source ? sourceNode(op.source) : undefined, `${tools.has(op.plugin) ? 'tool' : 'plugin'}:${op.plugin}`, op.each ? list(op.each.list) : undefined);
+            }
+            if (op.kind === 'FEED')
+                inputs.push(list(op.list));
+            for (const from of inputs)
+                if (from !== undefined)
+                    edge(from, opId, 'input');
+            edge(opId, ids[i + 1] ?? id, 'next');
+        });
+        staged.push({ id, kind: 'stage', label: stageLabel(stage), line: stage.span.line });
+        if (stage.name !== undefined)
+            stageIds.set(stage.name, id);
+    });
+    const last = p.stages[p.stages.length - 1];
+    edge(stageId(last, p.stages.length - 1), 'export', 'export');
+    const site = [];
+    for (const [name, rules, kind] of [
+        ['_redirects', p.redirects, 'REDIRECT'],
+        ['_headers', p.headers, 'HEADER'],
+    ]) {
+        if (!rules.length)
+            continue;
+        const id = `site:${name}`;
+        site.push({ id, kind: 'site', label: `${joinVirtual(p.exportPath, name)} (${rules.length} ${kind} line${rules.length === 1 ? '' : 's'})`, line: rules[0].span.line });
+        edge(id, 'export', 'export');
+    }
+    nodes.push(...p.imports.map((i) => ({ id: `import:${i.name}`, kind: 'import', label: `IMPORT ${i.name} ${i.uri}${i.as ? ` AS ${i.as}` : ''}`, line: i.span.line })), ...p.plugins.map((pl) => ({ id: `plugin:${pl.name}`, kind: 'plugin', label: `PLUGIN ${pl.name} ${localLabel(pl.path)}`, line: pl.span.line })), ...p.tools.map((t) => ({ id: `tool:${t.name}`, kind: 'tool', label: `TOOL ${t.name}`, line: t.span.line })), ...images, ...importedStages, ...locals, ...staged, ...site, { id: 'export', kind: 'export', label: `EXPORT ${p.exportPath} AS ${p.exportFormat}${p.target !== undefined ? ` (--target ${p.target})` : ''}` });
+    return { file: p.file, ...(p.target !== undefined ? { target: p.target } : {}), nodes, edges };
+}
+/** `id  label` per node, then one `  <- from (kind)` line per incoming edge, then a count. */
+export function graphText(g) {
+    let out = '';
+    for (const n of g.nodes) {
+        out += `${n.id}  ${n.label}\n`;
+        for (const e of g.edges)
+            if (e.to === n.id)
+                out += `  <- ${e.from} (${e.kind})\n`;
+    }
+    return out + `${g.nodes.length} nodes, ${g.edges.length} edges\n`;
+}
+const DOT_SHAPES = {
+    import: 'cylinder',
+    image: 'tab',
+    plugin: 'component',
+    tool: 'component',
+    local: 'folder',
+    operation: 'box',
+    stage: 'box3d',
+    site: 'note',
+    export: 'doubleoctagon',
+};
+function dotString(s) {
+    return `"${s.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+}
+/** Graphviz DOT (`sitefile graph --dot | dot -Tsvg > graph.svg`). */
+export function graphDot(g) {
+    let out = 'digraph sitefile {\n  rankdir=LR;\n  node [shape=box];\n';
+    for (const n of g.nodes)
+        out += `  ${dotString(n.id)} [label=${dotString(n.label)}, shape=${DOT_SHAPES[n.kind]}];\n`;
+    for (const e of g.edges) {
+        const style = e.kind === 'input' ? ' [style=dashed]' : e.kind === 'next' ? '' : ' [style=bold]';
+        out += `  ${dotString(e.from)} -> ${dotString(e.to)}${style};\n`;
+    }
+    return out + '}\n';
+}
+function same(a, b) {
+    return a === b || (a !== undefined && b !== undefined && a.origin === b.origin && a.digest === b.digest && a.mode === b.mode);
+}
+/** `rel` of `full` below directory `dir` (`/x` for `/d/x` under `/d`). */
+function below(dir, full) {
+    return dir === '/' ? full : full.slice(dir.length);
+}
+/** `base` + `rel` where `base` is a virtual path (`/` for the root) and `rel` starts with `/`. */
+function under(base, rel) {
+    return base === '/' ? rel : base + rel;
+}
+/**
+ * Explain one exported file: every write to it (and to the files it was copied from in earlier stages) that
+ * changed it, oldest first. Writes of identical content are no-ops in the tree (the first writer stays the
+ * owner), so they are not listed. `result` must come from a build with `recordSteps`.
+ */
+export function why(result, raw, contextDir) {
+    const p = result.plan;
+    const steps = result.steps;
+    if (!steps)
+        throw new Error('why() needs a build with recordSteps');
+    const want = normalizeVirtual(raw.startsWith('/') ? raw : '/' + raw, undefined, 'path').path;
+    const node = result.output.get(want);
+    if (!node) {
+        if (result.output.isDirectory(want))
+            throw new SitefileError('E_NOT_FOUND', `'${want}' is a directory in the build output; name a file`);
+        throw new SitefileError('E_NOT_FOUND', `'${want}' is not in the build output`);
+    }
+    const root = {
+        plan: p,
+        steps,
+        prefix: '',
+        resource: (name) => result.resources.get(name),
+        isDir: (rel) => {
+            try {
+                return statSync(path.join(contextDir, rel)).isDirectory();
+            }
+            catch {
+                return false; // gone since the build: show the path as written
+            }
+        },
+        imported: result.imported ?? new Map(),
+        ...(result.renames ? { renames: result.renames } : {}),
+    };
+    const scopes = new Map();
+    /** The scope of a Sitefile imported by `scope` (its own messages, steps and context). */
+    const scopeOf = (unit, prefix) => {
+        let s = scopes.get(unit);
+        if (!s) {
+            s = {
+                plan: unit.plan,
+                steps: unit.steps ?? [],
+                prefix,
+                resource: (name) => unit.resources.get(name),
+                isDir: (rel) => unit.isDirectory(rel),
+                imported: unit.imported,
+                renames: unit.renames,
+            };
+            scopes.set(unit, s);
+        }
+        return s;
+    };
+    /** The scope and index of the stage `name` (`build`, or `theme+assets` for a stage of an imported Sitefile). */
+    const locate = (scope, name) => {
+        const imp = importedStage(name);
+        const unit = imp ? scope.imported.get(imp.import) : undefined;
+        if (imp && unit) {
+            const s = scopeOf(unit, `${scope.prefix}${imp.import}+`);
+            return { scope: s, index: unit.plan.stages.findIndex((st) => st.name === imp.stage) };
+        }
+        return { scope, index: scope.plan.stages.findIndex((st) => st.name === name) };
+    };
+    const finalOf = (scope, i) => scope.steps[i][scope.steps[i].length - 1];
+    /** Display and (for a stage) the file a source contributes to `file` written at `dest`. */
+    const copied = (scope, ref, dest, file) => {
+        const rel = file === dest ? undefined : below(dest, file);
+        switch (ref.kind) {
+            case 'inline':
+                return { input: `<<${ref.delimiter}` };
+            case 'local': {
+                const isDir = scope.isDir(ref.path);
+                const rest = isDir && rel !== undefined ? (ref.path === '' ? rel.slice(1) : ref.path + rel) : ref.path;
+                return { input: localLabel(rest) };
+            }
+            case 'import': {
+                const res = scope.resource(ref.name);
+                if (res?.kind !== 'tree')
+                    return { input: ref.path === '/' ? `import ${ref.name}` : `import ${ref.name}:${ref.path}` };
+                const inner = res.tree.isFile(ref.path) || rel === undefined ? ref.path : under(ref.path, rel);
+                return { input: `import ${ref.name}:${inner}` };
+            }
+            case 'stage': {
+                const loc = locate(scope, ref.name);
+                const tree = finalOf(loc.scope, loc.index);
+                const inner = tree.isFile(ref.path) || rel === undefined ? ref.path : under(ref.path, rel);
+                return { input: `stage ${ref.name}:${inner}`, ...(tree.isFile(inner) ? { from: { scope: loc.scope, stage: loc.index, path: inner } } : {}) };
+            }
+        }
+    };
+    const readLabel = (ref) => {
+        switch (ref.kind) {
+            case 'inline':
+                return `<<${ref.delimiter}`;
+            case 'local':
+                return localLabel(ref.path);
+            case 'import':
+                return ref.path === '/' ? `import ${ref.name}` : `import ${ref.name}:${ref.path}`;
+            case 'stage':
+                return `stage ${ref.name}:${ref.path}`;
+        }
+    };
+    /** The path `file` had before operation `upTo` of stage `si` when a FINGERPRINT there renamed it, and where. */
+    const renamedAt = (scope, si, file, upTo) => {
+        const ops = scope.plan.stages[si].operations;
+        for (let i = upTo - 1; i >= 0; i--) {
+            const op = ops[i];
+            if (op.kind !== 'FINGERPRINT')
+                continue;
+            const hit = scope.renames?.get(op.span.line)?.find(([, to]) => to === file);
+            if (hit)
+                return { index: i, from: hit[0] };
+        }
+        return undefined;
+    };
+    const history = (scope, si, file, upTo = scope.plan.stages[si].operations.length) => {
+        const sp = scope.plan;
+        const at = (line) => `${sp.file}:${line}`;
+        const stage = sp.stages[si];
+        const trees = scope.steps[si];
+        const display = scope.prefix + stageDisplay(stage, si);
+        // A renamed file: the history of its old path up to the FINGERPRINT, then the rename.
+        const rename = renamedAt(scope, si, file, upTo);
+        if (rename) {
+            const op = stage.operations[rename.index];
+            const node = trees[rename.index + 1].get(file);
+            const events = history(scope, si, rename.from, rename.index);
+            events.push({ location: at(op.span.line), instruction: operationLabel(op), stage: display, path: file, action: 'write', digest: node.digest, inputs: [`${rename.from} (renamed)`] });
+            return [...events, ...later(scope, si, file, rename.index + 1, upTo, node)];
+        }
+        const events = [];
+        const prev = trees[0].get(file);
+        if (prev) {
+            if (stage.base.kind === 'stage') {
+                const loc = locate(scope, stage.base.name);
+                events.push(...history(loc.scope, loc.index, file));
+            }
+            else if (stage.base.kind === 'local') {
+                const rest = stage.base.path === '' ? file.slice(1) : stage.base.path + file;
+                events.push({ location: at(stage.span.line), instruction: stageLabel(stage), stage: display, path: file, action: 'write', digest: prev.digest, inputs: [localLabel(rest)] });
+            }
+            else if (stage.base.kind === 'image') {
+                // The file's origin names the image, its digest and the path inside the layer.
+                events.push({ location: at(stage.span.line), instruction: stageLabel(stage), stage: display, path: file, action: 'write', digest: prev.digest, inputs: [prev.origin] });
+            }
+        }
+        return [...events, ...later(scope, si, file, 0, upTo, prev)];
+    };
+    /** The events of operations `from` to `upTo` (exclusive) of stage `si` that changed `file` (`prev`: before them). */
+    const later = (scope, si, file, from, upTo, prev) => {
+        const sp = scope.plan;
+        const at = (line) => `${sp.file}:${line}`;
+        const tools = new Set(sp.tools.map((t) => t.name));
+        const stage = sp.stages[si];
+        const trees = scope.steps[si];
+        const display = scope.prefix + stageDisplay(stage, si);
+        const events = [];
+        stage.operations.slice(from, upTo).forEach((op, k) => {
+            const i = from + k;
+            const next = trees[i + 1].get(file);
+            if (!next || same(prev, next)) {
+                prev = next;
+                return;
+            }
+            const inputs = [];
+            if (op.kind === 'COPY') {
+                const c = copied(scope, op.source, op.dest, file);
+                if (c.from)
+                    events.push(...history(c.from.scope, c.from.stage, c.from.path));
+                inputs.push(c.input);
+            }
+            else if (op.kind === 'RENDER') {
+                inputs.push(readLabel(op.template));
+                if (op.each)
+                    inputs.push(`list ${op.each.list}`);
+            }
+            else if (op.kind === 'TRANSFORM') {
+                // A directory TRANSFORM names the input file in each output's origin.
+                const perFile = `${at(op.span.line)} TRANSFORM `;
+                if (op.source)
+                    inputs.push(next.origin.startsWith(perFile) ? next.origin.slice(perFile.length) : readLabel(op.source));
+                inputs.push(`${tools.has(op.plugin) ? 'tool' : 'plugin'} ${op.plugin}`);
+                if (op.each)
+                    inputs.push(`list ${op.each.list}`);
+            }
+            else if (op.kind === 'SITEMAP')
+                inputs.push('the .html files in the tree');
+            else if (op.kind === 'CHECKLINKS')
+                return;
+            else if (op.kind === 'FINGERPRINT')
+                inputs.push(op.manifest === file ? 'the files it renamed' : 'references to renamed files');
+            else
+                inputs.push(`list ${op.list}`);
+            events.push({ location: at(op.span.line), instruction: operationLabel(op), stage: display, path: file, action: prev ? 'overwrite' : 'write', digest: next.digest, inputs });
+            prev = next;
+        });
+        return events;
+    };
+    const at = (line) => `${p.file}:${line}`;
+    const lastIndex = p.stages.length - 1;
+    const full = under(p.exportPath, want);
+    const events = history(root, lastIndex, full);
+    // The EXPORT site files are added after the last stage.
+    const before = finalOf(root, lastIndex).get(full);
+    const after = result.tree.get(full);
+    if (after && !same(before, after)) {
+        const [rules, kind] = full === joinVirtual(p.exportPath, '_redirects') ? [p.redirects, 'REDIRECT'] : [p.headers, 'HEADER'];
+        events.push({
+            location: at(rules[0].span.line),
+            instruction: kind,
+            stage: stageDisplay(p.stages[lastIndex], lastIndex),
+            path: full,
+            action: before ? 'overwrite' : 'write',
+            digest: after.digest,
+            inputs: rules.map((r) => `${at(r.span.line)} ${kind}`),
+        });
+    }
+    return { path: want, mode: node.mode.toString(8), size: node.bytes.byteLength, digest: node.digest, origin: node.origin, history: events };
+}
+export function whyText(r) {
+    let out = `${r.path}  ${r.mode}  ${r.size} bytes  ${r.digest}\n`;
+    r.history.forEach((e, i) => {
+        out += `  ${i + 1}. ${e.location} ${e.instruction}  [stage ${e.stage}]  ${e.action === 'write' ? 'wrote' : 'overwrote'} ${e.path}\n`;
+        for (const input of e.inputs)
+            out += `       from ${input}\n`;
+    });
+    return out;
+}
+//# sourceMappingURL=explain.js.map

package/lib/src/export-formats.d.ts

@@ -0,0 +1,16 @@
+import { type WriterOptions } from './archive-writers.js';
+import type { ExportFormat } from './language/ast.js';
+import type { Tree } from './tree.js';
+export type ArchiveFormat = Exclude<ExportFormat, 'directory' | 'oci'>;
+/** Single-file formats encoded by {@link encodeTree}. `oci` is handled separately (layout directory or OCI archive). */
+export declare function isArchiveFormat(f: ExportFormat): f is ArchiveFormat;
+/** Default output path relative to the context: `dist`, `dist.zip`, `dist.tar`, `dist.tar.gz`, `dist.wbn`. */
+export declare function defaultOutName(format: ExportFormat): string;
+export interface EncodeOptions extends WriterOptions {
+    /** Required for `wbn`: absolute https URL ending in `/`. */
+    readonly baseUrl?: string | undefined;
+}
+/** Serialize a tree in an archive format. Deterministic: see archive-writers.ts and wbn.ts. */
+export declare function encodeTree(tree: Tree, format: ArchiveFormat, options?: EncodeOptions): Uint8Array;
+/** The export format implied by an output file name, if it has an archive extension. */
+export declare function formatFromExtension(out: string): ExportFormat | undefined;

package/lib/src/export-formats.js

@@ -0,0 +1,52 @@
+import { writeTar, writeTgz, writeZip } from './archive-writers.js';
+import { writeWebBundle } from './wbn.js';
+/** Single-file formats encoded by {@link encodeTree}. `oci` is handled separately (layout directory or OCI archive). */
+export function isArchiveFormat(f) {
+    return f !== 'directory' && f !== 'oci';
+}
+/** Default output path relative to the context: `dist`, `dist.zip`, `dist.tar`, `dist.tar.gz`, `dist.wbn`. */
+export function defaultOutName(format) {
+    switch (format) {
+        case 'directory':
+            return 'dist';
+        case 'zip':
+            return 'dist.zip';
+        case 'tar':
+            return 'dist.tar';
+        case 'tgz':
+            return 'dist.tar.gz';
+        case 'wbn':
+            return 'dist.wbn';
+        case 'oci':
+            return 'dist.oci.tar';
+    }
+}
+/** Serialize a tree in an archive format. Deterministic: see archive-writers.ts and wbn.ts. */
+export function encodeTree(tree, format, options = {}) {
+    switch (format) {
+        case 'zip':
+            return writeZip(tree, options);
+        case 'tar':
+            return writeTar(tree, options);
+        case 'tgz':
+            return writeTgz(tree, options);
+        case 'wbn':
+            return writeWebBundle(tree, options.baseUrl);
+    }
+}
+/** The export format implied by an output file name, if it has an archive extension. */
+export function formatFromExtension(out) {
+    const name = out.toLowerCase();
+    if (name.endsWith('.oci.tar'))
+        return 'oci';
+    if (name.endsWith('.tar.gz') || name.endsWith('.tgz'))
+        return 'tgz';
+    if (name.endsWith('.tar'))
+        return 'tar';
+    if (name.endsWith('.zip'))
+        return 'zip';
+    if (name.endsWith('.wbn'))
+        return 'wbn';
+    return undefined;
+}
+//# sourceMappingURL=export-formats.js.map