@greenpandastudios/aug-cli 0.19.0

package/src/spec.js

@@ -0,0 +1,738 @@
+import { createHash } from 'node:crypto';
+import { existsSync, lstatSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { basename, dirname, join, relative, resolve } from 'node:path';
+import { fieldsOf, typeName } from "./ast.js";
+import { builtinFunctions, builtinProperties, collectionOperations, operationType } from "./builtins.js";
+import { callableDocumentation } from "./documentation.js";
+import { javadocBefore } from "./javadoc.js";
+import { libraryChild, libraryRelative } from "./libraries.js";
+import { compilerVersion } from "./package-manager.js";
+import { tyName } from "./types.js";
+const generated = '<!-- Generated by aug spec. Edit the August source, then regenerate. -->';
+const copied = '// Generated by aug spec. This is a copy of the installed dependency source.\n';
+const code = (value) => { const text = value.replaceAll('\n', '\\n'); const fence = '`'.repeat(1 + Math.max(0, ...(text.match(/`+/g) ?? []).map(part => part.length))); return fence + (text.startsWith('`') ? ' ' : '') + text + (text.endsWith('`') ? ' ' : '') + fence; };
+const url = (value) => value.replaceAll('\\', '/').split('/').map(encodeURIComponent).join('/');
+const anchor = (name) => 'symbol-' + name;
+const hash = (text) => createHash('sha256').update(text).digest('hex');
+const compare = (left, right) => left < right ? -1 : left > right ? 1 : 0;
+const unreachable = (node) => { throw new Error(`No specification renderer for ${node.kind}`); };
+/** Render checked code, never execute it. All paths and ordering are reproducible. */
+export function generateSpecs(checked, options = {}) {
+    if (checked.diagnostics.some(issue => issue.severity !== 'warning'))
+        throw new Error('Fix compiler errors before generating specifications');
+    const project = checked.project;
+    const owned = options.files ?? [...project.files.values()].filter(file => !file.builtin && !file.package);
+    const own = new Set(owned.map(file => file.path));
+    const docs = new Map(), sources = new Map();
+    for (const file of project.files.values()) {
+        if (own.has(file.path)) {
+            docs.set(file.path, file.path + '.md');
+            sources.set(file.path, file.path);
+            continue;
+        }
+        const scope = file.package && project.packages.scopes.get(file.package);
+        const identity = scope ? join('packages', scope.name, scope.version, relative(scope.sourceRoot, file.path)) :
+            join('august', compilerVersion(), libraryRelative(project.libraries, file.path));
+        const source = join(project.root, '.aug-spec', identity);
+        docs.set(file.path, source + '.md');
+        sources.set(file.path, source);
+    }
+    const queue = [...owned].sort((a, b) => compare(a.path, b.path));
+    const seen = new Set(), outputs = [];
+    for (let index = 0; index < queue.length; index++) {
+        const file = queue[index];
+        if (seen.has(file.path))
+            continue;
+        seen.add(file.path);
+        const writer = new SpecWriter(checked, file, docs, sources, own, path => {
+            const dependency = project.files.get(path);
+            if (dependency && !seen.has(path))
+                queue.push(dependency);
+        });
+        outputs.push({ path: docs.get(file.path), text: writer.render(), source: file.path });
+        if (!own.has(file.path))
+            outputs.push({ path: sources.get(file.path), text: copied + file.source, source: file.path });
+    }
+    return outputs.sort((a, b) => compare(a.path, b.path));
+}
+class SpecWriter {
+    checked;
+    file;
+    docs;
+    sources;
+    own;
+    enqueue;
+    used = new Map();
+    builtins = new Map();
+    properties = new Map();
+    locals = new Map();
+    constructor(checked, file, docs, sources, own, enqueue) {
+        this.checked = checked;
+        this.file = file;
+        this.docs = docs;
+        this.sources = sources;
+        this.own = own;
+        this.enqueue = enqueue;
+    }
+    definition(name) { return this.checked.project.scopes.get(this.file.path)?.get(name); }
+    use(def, method, field) {
+        if (!def || def.file === this.file.path)
+            return;
+        if (method && 'methods' in def.node && !def.node.methods.includes(method)) {
+            const owner = [...this.checked.project.definitions.values()].find(owner => 'methods' in owner.node && owner.node.methods.includes(method));
+            this.use(owner, method);
+            method = undefined;
+        }
+        let entry = this.used.get(def.id);
+        if (!entry) {
+            entry = { def, operations: new Set(), fields: new Set() };
+            this.used.set(def.id, entry);
+        }
+        if (method)
+            entry.operations.add(method);
+        if (field)
+            entry.fields.add(field);
+        this.enqueue(def.file);
+    }
+    link(def, name = def.name, label = name) {
+        this.use(def);
+        return `[${code(label)}](${url(relative(dirname(this.docs.get(this.file.path)), this.docs.get(def.file)))}#${encodeURIComponent(anchor(name))})`;
+    }
+    source(span) {
+        return `[source](${url(relative(dirname(this.docs.get(this.file.path)), this.sources.get(span.file)))}#L${span.line + (this.own.has(span.file) ? 0 : 1)})`;
+    }
+    heading(name, span, level = 2) {
+        return `<a id="${anchor(name)}"></a>\n\n${'#'.repeat(level)} ${code(name)}\n\n${this.source(span)}\n\n`;
+    }
+    type(type, file = this.file.path) {
+        const def = this.checked.project.scopes.get(file)?.get(type.name);
+        this.use(def);
+        type.args.forEach(arg => this.type(arg, file));
+        return def ? this.link(def, def.name, typeName(type)) : code(typeName(type));
+    }
+    notes(span, method, owner) {
+        const doc = method ? callableDocumentation(this.checked.project, method, owner) : javadocBefore(this.file.source, span.start);
+        return doc ? `**Author documentation**\n\n${doc.markdown}\n\n` : '';
+    }
+    generics(node) {
+        return node.typeParams.length ? 'Type parameters: ' + node.typeParams.map(name => code(name) +
+            (node.typeVariance?.[name] ? ` (${node.typeVariance[name] === 'out' ? 'produces values' : 'accepts values'})` : '') +
+            (node.typeConstraints?.[name]?.length ? ` must satisfy ${node.typeConstraints[name].map(type => this.type(type)).join(' and ')}` : '')).join('; ') + '.\n\n' : '';
+    }
+    inputs(params, fields = false, file = this.file.path) {
+        if (!params.length)
+            return '';
+        return '**Inputs**\n\n' + params.map(param => {
+            this.locals.set(param.name, param.type);
+            const parts = [`${code(param.label ?? param.name)} (${this.type(param.type, file)})`];
+            if (param.injected)
+                parts.push('injected; callers omit it');
+            else if (param.source)
+                parts.push(`read from the HTTP ${param.source.kind}${param.source.name ? ' named ' + code(param.source.name) : ''}${param.type.optional ? '; absent value becomes null' : ''}`);
+            else
+                parts.push(param.type.optional ? 'optional labeled input; omission becomes null' : 'required labeled input');
+            if (param.ownership === 'own')
+                parts.push('transfers ownership');
+            else if (param.ownership === 'borrow')
+                parts.push('allows exclusive mutation during the call');
+            if (fields)
+                parts.push(`stored as ${code(param.name)}${param.name.startsWith('_') ? ' (private)' : ''}${param.mutable ? ' and mutable' : ' and read-only after initialization'}`);
+            return '- ' + parts.join(' — ') + '.';
+        }).join('\n') + '\n\n';
+    }
+    contract(method) {
+        const effects = this.checked.effectContracts.get(method);
+        const layers = this.checked.interceptorPlans.get(method) ?? [];
+        const errors = [...new Set([...method.throws.map(type => { this.type(type, method.span.file); return typeName(type); }), ...layers.flatMap(layer => layer.errors.map(tyName))])];
+        const changes = effects?.changes ?? method.changes ?? [];
+        const uses = [...(effects?.uses.values() ?? method.uses ?? [])];
+        let text = this.generics(method) + this.inputs(method.params, false, method.span.file);
+        text += `Returns: ${method.returns.name === 'void' ? 'no value' : (method.returnOwnership === 'own' ? 'ownership of ' : '') + this.type(method.returns, method.span.file)}.\n\n`;
+        if (changes.length)
+            text += 'May change: ' + changes.map(code).join(', ') + '.\n\n';
+        if (uses.length)
+            text += 'Capabilities: ' + uses.map(effect => {
+                const def = 'capability' in effect ? effect.capability?.def : undefined;
+                const target = def ?? this.definition(effect.source);
+                const operation = target && 'methods' in target.node ? target.node.methods.find(method => method.name === effect.operation) : undefined;
+                this.use(target, operation);
+                return target ? this.link(target, operation ? `${target.name}.${operation.name}` : target.name, `${effect.source}.${effect.operation}`) : code(`${effect.source}.${effect.operation}`);
+            }).join(', ') + '.\n\n';
+        if (errors.length)
+            text += 'Can fail with ' + errors.map(code).join(', ') + '. Callers must catch or propagate these errors.\n\n';
+        if (method.endpoint) {
+            const endpoint = method.endpoint;
+            text += `HTTP route: ${code(endpoint.method)} ${code(endpoint.path)}. ` +
+                (endpoint.streams ? `Stream ${this.type(method.returns)} items. ` : `Use status ${endpoint.status} when the handler returns a body; a returned HttpResponse can set its own status. `) +
+                'An unhandled request failure returns status 500 and cancels its request tasks.\n\n';
+            if (endpoint.errors.length)
+                text += 'Declared HTTP failures: ' + endpoint.errors.map(error => `${this.type(error.type)} returns status ${error.status}`).join('; ') + '.\n\n';
+        }
+        return text;
+    }
+    layers(node) {
+        const layers = this.checked.interceptorPlans.get(node) ?? [];
+        const policies = node.kind === 'function' ? this.checked.httpPolicies.get(node) ?? [] : [];
+        if (!layers.length && !policies.length)
+            return '';
+        let text = '**Interceptors, in execution order**\n\n';
+        policies.forEach((policy, index) => {
+            text += `${index + 1}. ${this.policy(policy)}` +
+                (node.kind === 'function' && policy.dependencies.length ? ' Use ' + policy.dependencies.map(index => code(node.params[index].name)).join(', ') + '.' : '') + '\n';
+        });
+        layers.forEach((layer, index) => {
+            this.use(layer.definition, layer.around);
+            text += `${index + policies.length + 1}. Call ${this.link(layer.definition, `${layer.definition.name}.around`)}. ` +
+                'It can call the next layer or finish with its own result or failure. ' +
+                (layer.annotation.mappings.length ? 'Map ' + layer.annotation.mappings.map(mapping => code(mapping.source) + ' to ' + code(mapping.name)).join(', ') + '. ' : '') +
+                'Unselected inputs pass through.\n';
+        });
+        return text + '\nThe first layer wraps the remaining layers. HTTP policies run before wire decoding; custom interceptors run after decoding. Follow linked behavior to see its conditions, input changes, and calls to the next layer.\n\n';
+    }
+    policy(policy) {
+        const options = policy.options;
+        switch (policy.name) {
+            case 'RequireLogin': return 'Authenticate the request. If no identity is returned, finish with status 401.';
+            case 'RequirePermission': return `Authenticate the request and authorize permission ${code(String(options.permission))}. No identity returns 401; denied permission returns 403.`;
+            case 'LogRequest': return 'Call the request logger after transport completion or disconnect, in reverse layer order. Record disconnect as status 499. This layer observes rejections from layers inside it.';
+            case 'RateLimit': return `Allow ${options.requests} requests per ${options.seconds} seconds for each endpoint and trusted transport peer. Ignore forwarding headers. Excess requests return 429.`;
+            case 'Timeout': return `Set a deadline of ${options.milliseconds} milliseconds for the handler, child tasks, and response transport. Before output, expiry returns 504; after output, it closes the stream. Native calls finish before cooperative cancellation; buffered request reception precedes this deadline.`;
+            case 'Cors': return `Allow origins ${code(JSON.stringify(options.origins))}. ${options.credentials ? 'Allow' : 'Do not allow'} credentials. ` +
+                (options.headers ? `Allow request headers ${code(JSON.stringify(options.headers))}. ` : '') + 'A supplied disallowed origin returns 403. Preflight checks the route method and requested headers.';
+            case 'Compress': return 'Negotiate gzip. Respect existing Content-Encoding and bodyless statuses. Encode stream items as complete concatenated gzip members.';
+        }
+    }
+    receiver(expr) {
+        const checked = this.checked.expressionTypes.get(expr)?.def;
+        if (checked)
+            return checked;
+        const ref = expr.kind === 'name' ? this.locals.get(expr.name) : undefined;
+        if (ref)
+            return this.definition(ref.name);
+        if (expr.kind === 'resolve')
+            return this.checked.bindings.find(binding => binding.key === expr.name)?.exposedType.def;
+        if (expr.kind === 'call' && expr.callee.kind === 'name') {
+            const def = this.definition(expr.callee.name);
+            if (def?.node.kind === 'class')
+                return def;
+            if (def?.node.kind === 'function')
+                return this.definition(def.node.returns.name);
+        }
+        return undefined;
+    }
+    method(def, name, seen = new Set()) {
+        if (seen.has(def.id))
+            return;
+        seen.add(def.id);
+        if (!('methods' in def.node))
+            return;
+        const direct = def.node.methods.find(method => method.name === name);
+        if (direct)
+            return direct;
+        const refs = def.node.kind === 'class' ? def.node.implements : def.node.kind === 'interface' ? def.node.extends : [];
+        for (const ref of refs) {
+            const parent = this.checked.project.scopes.get(def.file)?.get(ref.name);
+            const inherited = parent && this.method(parent, name, seen);
+            if (inherited)
+                return inherited;
+        }
+    }
+    expression(expr, nested = false) {
+        switch (expr.kind) {
+            case 'literal': return expr.value === null ? 'null' : code(expr.numericText ?? JSON.stringify(expr.value));
+            case 'name': {
+                const def = !this.locals.has(expr.name) ? this.definition(expr.name) : undefined;
+                this.use(def);
+                return def ? this.link(def) : code(expr.name);
+            }
+            case 'member': {
+                const def = this.receiver(expr.object);
+                this.use(def, undefined, expr.name);
+                const name = expr.name, receiverType = this.checked.expressionTypes.get(expr.object)?.name;
+                const property = receiverType && builtinProperties[receiverType]?.find(property => property.name === name);
+                if (property)
+                    this.properties.set(receiverType + '.' + name, { ...property, type: this.checked.expressionTypes.get(expr) ? tyName(this.checked.expressionTypes.get(expr)) : property.type });
+                return `${code(name)} of ${this.expression(expr.object)}`;
+            }
+            case 'unary': {
+                if (expr.op === '!' && expr.value.kind === 'binary' && (expr.value.op === '==' || expr.value.op === '!='))
+                    return `${this.expression(expr.value.left, true)} ${expr.value.op === '==' ? 'does not equal' : 'equals'} ${this.expression(expr.value.right, true)}`;
+                return `${expr.op === '!' ? 'not' : 'the negative of'} (${this.expression(expr.value)})`;
+            }
+            case 'binary': {
+                const words = { '+': 'plus', '-': 'minus', '*': 'times', '/': 'divided by', '==': 'equals', '!=': 'does not equal', '<': 'is less than', '>': 'is greater than', '<=': 'is at most', '>=': 'is at least', '&&': 'and', '||': 'or' };
+                if (!words[expr.op])
+                    throw new Error(`No specification renderer for operator ${expr.op}`);
+                const textParts = this.stringParts(expr);
+                if (expr.op === '+' && textParts.length >= 3)
+                    return 'text formed by joining ' + textParts.map(part => this.expression(part)).join(', ') + ' in order';
+                const result = `${this.expression(expr.left, expr.left.kind === 'binary')} ${words[expr.op]} ${this.expression(expr.right, expr.right.kind === 'binary')}`;
+                return nested ? `(${result})` : result;
+            }
+            case 'collection': {
+                if (expr.collection === 'Map')
+                    return 'a map with ' + expr.items.filter((_, index) => index % 2 === 0).map((key, index) => `${this.expression(key)} mapped to ${this.expression(expr.items[index * 2 + 1])}`).join('; ');
+                return `a ${expr.collection === 'empty' ? 'context-typed empty collection' : expr.collection.toLowerCase()}` + (expr.items.length ? ' containing ' + expr.items.map(item => this.expression(item)).join(', ') : ' with no items');
+            }
+            case 'resolve': return `the instance provided for ${code(expr.name)}${expr.typeArgs.length ? ' with type arguments ' + expr.typeArgs.map(type => this.type(type)).join(', ') : ''}`;
+            case 'call': return this.call(expr);
+            case 'start': return `a child task that starts ${this.expression(expr.call)}; evaluate its receiver and inputs now, and run its operation concurrently`;
+            case 'wait': return `the results of waiting for ${expr.tasks.map(task => this.expression(task)).join(' and ')}; keep input order when returning a tuple or a list, join cleanup, and propagate the first failure`;
+            case 'handle': {
+                const plan = this.checked.actions.get(expr);
+                return `a deferred HTTP form action for ${plan ? this.link(plan.endpoint) : this.expression(expr.call)}` +
+                    (expr.call.kind === 'call' && expr.call.args.length ? '; inputs: ' + expr.call.args.map((value, index) => (expr.call.kind === 'call' ? code(expr.call.argLabels[index] ?? (value.kind === 'name' ? value.name : String(index + 1))) + ' from ' : '') + this.expression(value)).join('; ') : '') +
+                    '; capture supplied values when rendering, and read form inputs when submitted; send the form to that endpoint with its declared HTTP method';
+            }
+            case 'formInput': return 'the checked form input supplied when the HTTP form is submitted';
+            case 'markupText': return code(expr.text);
+            case 'markup': {
+                const def = this.definition(expr.tag);
+                this.use(def);
+                return (def ? 'the server component ' + this.link(def) : 'the HTML element ' + code(expr.tag || 'fragment')) +
+                    (expr.attributes.length ? ' with ' + expr.attributes.map(attribute => `${code(attribute.name)} = ${this.expression(attribute.value)}`).join(', ') : '') +
+                    (expr.children.length ? ' containing ' + expr.children.map(child => this.expression(child)).join(', ') : '') +
+                    ' (rendered on the server with embedded text escaped)';
+            }
+            default: return unreachable(expr);
+        }
+    }
+    call(expr) {
+        if (expr.callee.kind === 'name' && ['List', 'Set', 'Map'].includes(expr.callee.name) && !this.definition(expr.callee.name)) {
+            const name = expr.callee.name, types = expr.typeArgs.map(type => this.type(type));
+            const items = expr.args.map(arg => this.expression(arg));
+            const label = name === 'Map' ? 'map from ' + (types[0] ?? 'any') + ' to ' + (types[1] ?? 'any') :
+                name.toLowerCase() + ' of ' + (types[0] ?? 'any');
+            return items.length ? 'a ' + label + ' containing ' + items.join(', ') : 'an empty ' + label;
+        }
+        let target, method;
+        if (expr.callee.kind === 'name') {
+            const name = expr.callee.name;
+            const def = this.definition(expr.callee.name);
+            this.use(def);
+            if (def?.node.kind === 'class' && def.file !== this.file.path)
+                this.used.get(def.id).constructed = true;
+            method = def?.node.kind === 'function' ? def.node : undefined;
+            const builtin = !def && builtinFunctions.find(operation => operation.name === name);
+            if (builtin)
+                this.builtins.set(builtin.name, builtin);
+            target = def ? this.link(def) : code(expr.callee.name);
+        }
+        else if (expr.callee.kind === 'member') {
+            const name = expr.callee.name;
+            const def = this.receiver(expr.callee.object);
+            method = def && this.method(def, expr.callee.name);
+            this.use(def, method);
+            const receiver = this.checked.expressionTypes.get(expr.callee.object);
+            const receiverType = receiver?.name ?? (expr.callee.object.kind === 'name' ? this.locals.get(expr.callee.object.name)?.name : undefined);
+            const builtin = !def && receiverType && collectionOperations[receiverType]?.find(operation => operation.name === name);
+            if (builtin)
+                this.builtins.set((receiver ? tyName(receiver) : receiverType) + '.' + builtin.name, {
+                    ...builtin,
+                    parameters: builtin.parameters.map(param => ({ ...param, type: receiver ? tyName(operationType(param.type, receiver)) : param.type })),
+                    returns: this.checked.expressionTypes.get(expr) ? tyName(this.checked.expressionTypes.get(expr)) : builtin.returns,
+                });
+            // An inherited operation links to the interface that actually declares it.
+            const owner = method && [...this.checked.project.definitions.values()].find(def => 'methods' in def.node && def.node.methods.includes(method));
+            this.use(owner, method);
+            target = (owner ? this.link(owner, `${owner.name}.${method.name}`) : code(expr.callee.name)) + ' on ' + this.expression(expr.callee.object);
+        }
+        else
+            target = this.expression(expr.callee);
+        expr.typeArgs.forEach(type => this.type(type));
+        const plan = this.checked.callPlans.get(expr);
+        const parameters = method?.params ?? (expr.callee.kind === 'name' && this.definition(expr.callee.name)?.node.kind === 'class' ?
+            this.definition(expr.callee.name).node.fields : []);
+        const inputs = expr.args.map((arg, index) => {
+            const slot = plan?.sourceIndices.indexOf(index);
+            const label = expr.argLabels[index] ?? (slot !== undefined && slot >= 0 ? parameters[slot]?.label ?? parameters[slot]?.name : arg.kind === 'name' ? arg.name : undefined);
+            return (label ? code(label) + ' = ' : '') + (arg.kind === 'binary' ? '(' + this.expression(arg) + ')' : this.expression(arg));
+        });
+        let text = `call ${target}` + (expr.typeArgs.length ? ' with type arguments ' + expr.typeArgs.map(type => this.type(type)).join(', ') : '') + (inputs.length ? ' with ' + inputs.join('; ') : '');
+        const injected = parameters.flatMap((param, index) => param.injected ? [`${code(param.name)} from ${code(plan?.injectionSources?.[index] ?? plan?.bindingKeys[index] ?? typeName(param.type))}`] : []);
+        if (injected.length)
+            text += '; inject ' + injected.join(', ');
+        return text;
+    }
+    stringParts(expr) {
+        if (expr.kind === 'binary' && expr.op === '+' && this.checked.expressionTypes.get(expr)?.name === 'string')
+            return [...this.stringParts(expr.left), ...this.stringParts(expr.right)];
+        return [expr];
+    }
+    joinedText(target, value, depth) {
+        const parts = this.stringParts(value);
+        if (parts.length < 4)
+            return;
+        const indent = '  '.repeat(depth), child = '  '.repeat(depth + 1);
+        return `${indent}- Build ${target} by joining these text parts without separators, in order:\n` +
+            parts.map((part, index) => `${child}${index + 1}. ${this.expression(part)}\n`).join('');
+    }
+    statements(body, depth = 0) {
+        if (!body.length)
+            return '  '.repeat(depth) + '- Finish this block without another operation.\n';
+        return body.map(stmt => this.statement(stmt, depth)).join('');
+    }
+    statement(stmt, depth) {
+        const lead = '  '.repeat(depth) + '- ', nested = (body) => this.statements(body, depth + 1);
+        switch (stmt.kind) {
+            case 'assign': {
+                if (stmt.target.kind === 'name') {
+                    const type = stmt.declaredType ?? this.checked.expressionTypes.get(stmt.value);
+                    if (type)
+                        this.locals.set(stmt.target.name, { name: type.name, args: [], nullable: type.nullable, optional: type.optional, span: stmt.span });
+                    else if (stmt.value.kind === 'call' && stmt.value.callee.kind === 'name') {
+                        const def = this.definition(stmt.value.callee.name);
+                        if (def?.node.kind === 'class')
+                            this.locals.set(stmt.target.name, { name: def.name, args: [], nullable: false, span: stmt.span });
+                    }
+                }
+                const target = this.expression(stmt.target) + (stmt.declaredType ? ' of type ' + this.type(stmt.declaredType) : '');
+                return (this.joinedText(target, stmt.value, depth) ?? lead + `Set ${target} to ${this.expression(stmt.value)}.\n`) +
+                    (stmt.ownership === 'own' ? lead + 'This variable owns the value.\n' : '');
+            }
+            case 'destructure': return lead + `Split ${this.expression(stmt.value)} into ${stmt.names.map(code).join(', ')}, in that order.\n`;
+            case 'expr': return lead + (stmt.expr.kind === 'literal' && stmt.expr.value === null ? 'Continue without another operation' : stmt.expr.kind === 'call' ? 'Call ' + this.call(stmt.expr).slice(5) : 'Evaluate ' + this.expression(stmt.expr)) + '.\n';
+            case 'return': {
+                if (!stmt.value)
+                    return lead + 'Finish this operation without a result.\n';
+                const joined = this.joinedText('the return value', stmt.value, depth);
+                return joined ? joined + lead + 'Return that value.\n' : lead + 'Return ' + this.expression(stmt.value) + '.\n';
+            }
+            case 'throw': return lead + 'Fail with ' + this.expression(stmt.value) + '. Transfer control to a matching catch or propagate the failure.\n';
+            case 'yield': return lead + 'Send ' + this.expression(stmt.value) + ' as the next stream item. Honor backpressure before producing more items.\n';
+            case 'if': return lead + 'If ' + this.condition(stmt.test) + ':\n' + nested(stmt.then) + (stmt.otherwise.length ? lead + 'Otherwise:\n' + nested(stmt.otherwise) : '');
+            case 'while': return lead + 'While ' + this.condition(stmt.test) + ', repeat:\n' + nested(stmt.body) + '  '.repeat(depth + 1) + '- Check the condition again before the next iteration.\n';
+            case 'for': return lead + 'For each ' + stmt.names.map(code).join(' and ') + ' in a snapshot of ' + this.expression(stmt.iterable) + ', in iteration order:\n' + nested(stmt.body);
+            case 'match': return lead + 'Select the matching case for ' + this.expression(stmt.value) + ':\n' + stmt.cases.map(clause => {
+                const pattern = clause.pattern === 'else' ? 'Any remaining case' : clause.pattern === 'some' ? 'A present, non-null value, named ' + code(clause.name) :
+                    clause.pattern === 'type' ? 'A value that satisfies ' + this.type(clause.type) + ', named ' + code(clause.name) :
+                        clause.pattern === 'literal' ? this.expression(clause.literal) : 'A null value, including omitted optional input';
+                return '  '.repeat(depth + 1) + '- ' + pattern + ':\n' + this.statements(clause.body, depth + 2);
+            }).join('');
+            case 'try': return lead + 'Try these operations:\n' + nested(stmt.body) + stmt.catches.map(clause => lead + 'If they fail with ' + this.type(clause.type) + ', name the failure ' + code(clause.name) + ' and recover:\n' + nested(clause.body)).join('') +
+                (stmt.always ? lead + 'On both success and failure, perform cleanup:\n' + nested(stmt.always) : '');
+            case 'unsafe': return lead + 'Enter an unsafe boundary. Native calls use their declared contracts; their foreign implementation is outside this specification:\n' + nested(stmt.body);
+            case 'borrow': return lead + 'Grant exclusive mutable access to ' + code(stmt.name) + ' for this block, then end the borrow:\n' + nested(stmt.body);
+            case 'scope': return lead + 'Create a dependency and task scope. Join its child tasks and release scoped values before leaving:\n' + nested(stmt.body);
+            case 'lock': return lead + 'Lock ' + this.expression(stmt.value) + ', expose its mutable value as ' + code(stmt.name) + ', and release the lock on every exit:\n' + nested(stmt.body);
+            case 'freeze': return lead + 'Freeze ' + this.expression(stmt.value) + ' as ' + code(stmt.name) + '. Share the immutable value without copying it.\n';
+            case 'serve': return lead + 'Serve ' + stmt.names.map(name => { const def = this.definition(name); return def ? this.link(def) : code(name); }).join(', ') + ' on port ' + this.expression(stmt.port) + '.\n';
+            default: return unreachable(stmt);
+        }
+    }
+    condition(expr) {
+        return this.expression(expr) + (['binary', 'unary'].includes(expr.kind) ? '' : ' is true');
+    }
+    binding(binding) {
+        const info = this.checked.bindings.find(info => info.declaration === binding);
+        const def = this.definition(binding.target.name);
+        this.use(def);
+        const lifetime = binding.lifetime ?? info?.lifetime;
+        const key = binding.key + (binding.keyTypeArgs.length ? '<' + binding.keyTypeArgs.map(type => typeName(type)).join(', ') + '>' : '');
+        return (`Provide ${def ? this.link(def, def.name, typeName(binding.target)) : this.type(binding.target)} when ${code(key)} is requested. ` +
+            (lifetime === 'shared' ? 'Reuse one instance. ' : lifetime === 'scoped' ? 'Reuse one instance per explicit scope. ' : lifetime === 'fresh' ? 'Construct a fresh instance for each resolve. ' : 'Use a fresh instance when this provider retains state; otherwise reuse one instance. ') +
+            (binding.sharedMutation ? 'Permit explicit shared mutation. ' : '') +
+            (info?.dependencies.length ? 'Required dependencies: ' + info.dependencies.map(code).join(', ') + '. ' : '')).trimEnd() + '\n';
+    }
+    callable(method, owner) {
+        this.locals = new Map(owner && 'fields' in owner.node ? fieldsOf(owner.node).map(field => [field.name, field.type]) : []);
+        const name = owner && owner.node.kind !== 'function' ? `${owner.name}.${method.name}` : method.name;
+        return this.heading(name, method.span, owner && owner.node.kind !== 'function' ? 3 : 2) +
+            (method.name.startsWith('_') ? 'Private to its defining scope.\n\n' : '') + this.contract(method) + this.layers(method) +
+            (method.body ? '**What it does**\n\n' + this.statements(method.body) + '\n' : method.externC ? 'Native C operation. Its declared inputs, result, effects, and errors are the visible contract. The C implementation is outside this specification.\n\n' : 'Interface contract. A selected implementation supplies the behavior.\n\n') +
+            this.notes(method.annotations?.[0]?.span ?? method.span, method, owner);
+    }
+    declaration(item) {
+        switch (item.kind) {
+            case 'import': return '';
+            case 'export': {
+                const folder = this.file.builtin ? libraryChild(this.checked.project.libraries, dirname(this.file.path), item.name) : join(dirname(this.file.path), item.name);
+                const file = item.folder ? join(folder, 'export.aug') : join(dirname(this.file.path), item.from + '.aug');
+                this.enqueue(file);
+                return `- Export ${item.folder ? 'the folder ' : 'the declaration '}${code(item.name)} from [${code(basename(file))}](${url(relative(dirname(this.docs.get(this.file.path)), this.docs.get(file)))}${item.folder ? '' : '#' + encodeURIComponent(anchor(item.name))}).\n`;
+            }
+            case 'function': return this.callable(item);
+            case 'class': {
+                const def = this.definition(item.name);
+                this.locals = new Map();
+                let text = this.heading(item.name, item.span) + `${item.record ? 'Immutable record' : 'Behavioral class'}${item.name.startsWith('_') ? ', private to this file' : ''}.\n\n` + this.generics(item) +
+                    (item.implements.length ? 'Satisfies ' + item.implements.map(type => { const def = this.definition(type.name); return def ? this.link(def) : this.type(type); }).join(', ') + '.\n\n' : '') +
+                    this.notes(item.annotations?.[0]?.span ?? item.span) + this.inputs(item.fields, true) + this.layers(item);
+                if (item.validationErrors?.length)
+                    text += 'Construction can fail with ' + item.validationErrors.map(type => this.type(type)).join(', ') + '.\n\n';
+                if (item.stateFields?.length)
+                    text += '**Field initialization**\n\n' + item.stateFields.map(field => { this.locals.set(field.name, field.type); return `- Initialize ${code(field.name)} of type ${this.type(field.type)} to ${this.expression(field.initializer)}. ${field.mutable ? 'Mutable' : 'Read-only'} storage${field.name.startsWith('_') ? ', private to this class' : ''}.\n`; }).join('') + '\n';
+                if (item.constructorBody)
+                    text += this.heading(item.name + '.initialize', item.span, 3) + 'When execution reaches the original constructor, store inputs and initialize local fields, then run this block once before returning the object:\n\n' + this.statements(item.constructorBody) + '\n';
+                if (!item.record) {
+                    const defaults = this.checked.defaults.get(def.id);
+                    const inherited = [...(defaults?.values() ?? [])].filter(info => !item.methods.some(method => method.name === info.method.name));
+                    if (inherited.length)
+                        text += '**Inherited default behavior**\n\n' + inherited.map(info => { const parent = this.checked.project.definitions.get(info.from); this.use(parent, info.method); return '- ' + (parent ? this.link(parent, `${parent.name}.${info.method.name}`) : code(info.method.name)) + '.\n'; }).join('') + '\n';
+                }
+                return text + item.methods.map(method => this.callable(method, def)).join('');
+            }
+            case 'interface':
+            case 'interceptor': {
+                const def = this.definition(item.name);
+                this.locals = new Map();
+                let text = this.heading(item.name, item.span) + (item.kind === 'interceptor' ? 'Function or constructor middleware' : item.capability ? 'Capability interface' : 'Interface') +
+                    (item.name.startsWith('_') ? ', private to this file' : '') + '.\n\n' + this.generics(item) + this.notes(item.span);
+                if (item.kind === 'interface' && item.extends.length)
+                    text += 'Inherit contracts and default methods from ' + item.extends.map(type => { const def = this.definition(type.name); return def ? this.link(def) : this.type(type); }).join(', ') + '.\n\n';
+                if (item.kind === 'interceptor')
+                    text += this.inputs(item.fields, true) + 'Create a fresh interceptor for each invocation. Its around operation can delegate once, change selected inputs, or short-circuit with a compatible result or failure.\n\n';
+                return text + item.methods.map(method => this.callable(method, def)).join('');
+            }
+            case 'composition': return this.heading(item.name, item.span) + this.notes(item.span) + 'This composition declares these providers before startup:\n\n' + item.bindings.map(binding => '- ' + this.binding(binding)).join('') + '\n';
+            case 'bind': return '- ' + this.binding(item);
+            case 'include': {
+                const def = this.definition(item.name);
+                return '- Include the providers from ' + (def ? this.link(def) : code(item.name)) + ' before execution.\n';
+            }
+            case 'test': return this.tests(item);
+            default: return this.statement(item, 0);
+        }
+    }
+    tests(suite) {
+        this.locals = new Map();
+        let text = this.heading(this.testTitle(suite), suite.span) + 'Same-file ' + (suite.endpointSuite ? 'HTTP endpoint' : suite.functionSuite ? 'function' : 'class') + ' tests for ' + this.type(suite.type) + '. Each case gets isolated setup and dependency bindings.\n\n';
+        for (const group of suite.groups) {
+            this.locals = new Map();
+            text += '### Group ' + code(group.name) + '\n\n';
+            if (group.setup.length)
+                text += '**Setup before each case**\n\n' + group.setup.map(entry => this.declaration(entry)).join('') + '\n';
+            const setupLocals = new Map(this.locals);
+            for (const test of group.cases) {
+                this.locals = new Map(setupLocals);
+                text += '#### ' + code(test.name) + '\n\n' + this.source(test.span) + '\n\n';
+                if (test.parameters)
+                    text += 'Run once for each row of ' + test.rows.map(row => this.expression(row)).join('; ') + '. Bind row positions to ' + test.parameters.map(code).join(', ') + '.\n\n';
+                text += this.statements(test.body) + '\n';
+            }
+        }
+        return text;
+    }
+    testTitle(suite) {
+        return 'test ' + suite.type.name + (suite.name === suite.type.name ? '' : ' ' + suite.name);
+    }
+    dependencySurface() {
+        if (!this.used.size)
+            return '';
+        const entries = [...this.used.values()].sort((a, b) => compare(relative(this.checked.project.root, this.docs.get(a.def.file)) + ':' + a.def.name, relative(this.checked.project.root, this.docs.get(b.def.file)) + ':' + b.def.name));
+        let text = '## Dependencies used by this file\n\nOnly referenced types and operations appear here. Each name links to its complete specification.\n\n';
+        for (const entry of entries) {
+            const def = entry.def, node = def.node;
+            const kind = node.kind === 'class' && node.record ? 'record' : node.kind === 'interface' && node.capability ? 'capability interface' : node.kind;
+            text += '### ' + this.link(def) + '\n\n' + kind[0].toUpperCase() + kind.slice(1);
+            const imported = this.file.items.find(item => item.kind === 'import' && (this.checked.project.imports.get(item) ?? []).some(imported => imported.id === def.id));
+            if (imported?.kind === 'import')
+                text += ' from ' + code(imported.from.join('.')) + (imported.everything ? ' through import everything' : '');
+            text += '.\n\n';
+            if (node.kind === 'function')
+                text += this.dependencyOperation(node, def);
+            if (node.kind === 'class' && entry.constructed)
+                text += '- Construct with ' + this.shortInputs(node.fields, def.file) + ' → ' + this.link(def) +
+                    (node.validationErrors?.length ? '; can fail with ' + node.validationErrors.map(type => this.type(type, def.file)).join(', ') : '') + '.\n';
+            if (node.kind === 'class' && entry.fields.size)
+                for (const name of [...entry.fields].sort(compare)) {
+                    const field = fieldsOf(node).find(field => field.name === name);
+                    if (field)
+                        text += '- Read ' + code(name) + ' (' + this.type(field.type, def.file) + ')' + (field.mutable ? '; its owner can change it' : '') + '.\n';
+                }
+            if ('methods' in node)
+                for (const method of [...entry.operations].sort((a, b) => compare(a.name, b.name)))
+                    text += this.dependencyOperation(method, def);
+            if (node.kind !== 'function' && !entry.constructed && !entry.fields.size && !entry.operations.size)
+                text += 'Used as a type or provider.\n';
+            text += '\n';
+        }
+        return text;
+    }
+    shortInputs(params, file) {
+        return params.filter(param => !param.injected).map(param => code(param.label ?? param.name) + ': ' + this.type(param.type, file) +
+            (param.source ? ' from HTTP ' + param.source.kind + (param.source.name ? ' ' + code(param.source.name) : '') : '')).join(', ') || 'no caller inputs';
+    }
+    dependencyOperation(method, owner) {
+        const effects = this.checked.effectContracts.get(method), layers = this.checked.interceptorPlans.get(method) ?? [];
+        const changes = effects?.changes ?? method.changes ?? [];
+        const uses = [...(effects?.uses.values() ?? method.uses ?? [])];
+        const errors = [...new Set([...method.throws.map(type => typeName(type)), ...layers.flatMap(layer => layer.errors.map(tyName))])];
+        const name = owner.node.kind === 'function' ? owner.name : owner.name + '.' + method.name;
+        let text = '- ' + this.link(owner, name) + (method.typeParams.length ? '<' + method.typeParams.map(code).join(', ') + '>' : '') +
+            ' (' + this.shortInputs(method.params, method.span.file) + ') → ' + this.type(method.returns, method.span.file);
+        const injected = method.params.filter(param => param.injected);
+        if (injected.length)
+            text += '; inject ' + injected.map(param => code(param.name) + ': ' + this.type(param.type, method.span.file)).join(', ');
+        if (changes.length)
+            text += '; changes ' + changes.map(code).join(', ');
+        const otherUses = uses.filter(effect => effect.source !== owner.name || effect.operation !== method.name);
+        if (otherUses.length)
+            text += '; uses ' + otherUses.map(effect => {
+                const target = ('capability' in effect ? effect.capability?.def : undefined) ?? this.checked.project.scopes.get(method.span.file)?.get(effect.source);
+                const operation = target && 'methods' in target.node ? target.node.methods.find(method => method.name === effect.operation) : undefined;
+                this.use(target, operation);
+                return target ? this.link(target, operation ? `${target.name}.${operation.name}` : target.name, `${effect.source}.${effect.operation}`) : code(`${effect.source}.${effect.operation}`);
+            }).join(', ');
+        if (errors.length)
+            text += '; can fail with ' + errors.map(code).join(', ');
+        return text + '.\n';
+    }
+    fileOverview() {
+        const lines = [];
+        const declaration = (name) => `[${code(name)}](${url(basename(this.docs.get(this.file.path)))}#${encodeURIComponent(anchor(name))})`;
+        for (const item of this.file.items) {
+            switch (item.kind) {
+                case 'class':
+                    lines.push(`- ${declaration(item.name)} is ${item.record ? 'an immutable record' : 'a class'}${item.implements.length ? ' implementing ' + item.implements.map(type => code(typeName(type))).join(', ') : ''}.`);
+                    break;
+                case 'interface':
+                    lines.push(`- ${declaration(item.name)} is ${item.capability ? 'a capability interface' : 'an interface'}.`);
+                    break;
+                case 'interceptor':
+                    lines.push(`- ${declaration(item.name)} is an interceptor.`);
+                    break;
+                case 'function':
+                    lines.push(`- ${declaration(item.name)} ${item.endpoint ? `handles ${code(item.endpoint.method)} ${code(item.endpoint.path)}` : 'is a function'}${item.returns.name === 'void' ? '' : ` returning ${code(typeName(item.returns))}`}.`);
+                    break;
+                case 'composition':
+                    lines.push(`- ${declaration(item.name)} declares ${item.bindings.length} ${item.bindings.length === 1 ? 'provider' : 'providers'}.`);
+                    break;
+                case 'bind': break;
+                case 'include':
+                    lines.push(`- Include providers from ${code(item.name)}.`);
+                    break;
+                case 'export':
+                    lines.push(`- Export ${code(item.name)} from this folder.`);
+                    break;
+                case 'test':
+                    lines.push(`- ${declaration(this.testTitle(item))} is a same-file test suite.`);
+                    break;
+                default: break;
+            }
+        }
+        const providers = this.file.items.filter(item => item.kind === 'bind');
+        if (providers.length)
+            lines.push(`- Register ${providers.length} ${providers.length === 1 ? 'dependency provider' : 'dependency providers'} before startup.`);
+        const executable = this.file.items.filter(item => !['import', 'export', 'test', 'bind', 'include', 'class', 'interface', 'interceptor', 'function', 'composition'].includes(item.kind));
+        if (executable.some(item => item.kind === 'try'))
+            lines.push('- Run startup operations with checked error recovery.');
+        for (const item of executable)
+            if (item.kind === 'serve')
+                lines.push(`- Serve ${item.names.length} HTTP ${item.names.length === 1 ? 'route' : 'routes'}.`);
+        const otherSteps = executable.filter(item => item.kind !== 'try' && item.kind !== 'serve').length;
+        if (otherSteps)
+            lines.push(`- Run ${otherSteps} other startup ${otherSteps === 1 ? 'step' : 'steps'} in source order.`);
+        return lines.length ? '## In this file\n\n' + lines.join('\n') + '\n\n' : '';
+    }
+    render() {
+        const exports = this.file.items.filter(item => item.kind === 'export');
+        const declarations = this.file.items.filter(item => ['class', 'interface', 'interceptor', 'function', 'composition'].includes(item.kind));
+        const providers = this.file.items.filter(item => item.kind === 'bind' || item.kind === 'include');
+        const startup = this.file.items.filter(item => item.kind !== 'import' && item.kind !== 'export' && item.kind !== 'test' && item.kind !== 'bind' && item.kind !== 'include' && !declarations.includes(item));
+        // Render behavior first to discover the exact dependency surface, including wildcard imports.
+        const behavior = (exports.length ? '## Folder exports\n\n' + exports.map(item => this.declaration(item)).join('') + '\n' : '') +
+            (providers.length ? '## Dependency providers\n\nRegister these providers before startup. Their declaration order does not set initialization order; shared instances initialize in dependency order.\n\n' + providers.map(item => this.declaration(item)).join('') + '\n' : '') +
+            (startup.length ? '## Startup, in source order\n\n' + startup.map(item => this.declaration(item)).join('') + '\n' : '') +
+            declarations.sort((a, b) => Number('name' in a && a.name.startsWith('_')) - Number('name' in b && b.name.startsWith('_'))).map(item => this.declaration(item)).join('') +
+            this.file.items.filter(item => item.kind === 'test').map(item => this.declaration(item)).join('');
+        const surface = this.dependencySurface() + this.builtinSurface();
+        let config = '';
+        if (basename(this.file.path) === 'main.aug') {
+            const project = this.checked.project;
+            if (project.files.get(this.file.path)?.items.some(item => item.kind === 'serve'))
+                config += '## HTTP configuration\n\n' +
+                    `Listen on ${code(project.config.web.host)}. Limit request bodies to ${project.config.web.body_limit} bytes and buffered responses to ${project.config.web.response_limit} bytes.\n\n` +
+                    (project.config.web.tls.certificate ? 'Use TLS with the configured certificate and private key.\n\n' : '') +
+                    (project.config.web.http3 ? 'Enable HTTP/3 over TLS.\n\n' : '') +
+                    (project.config.openapi.enabled ? `Serve the OpenAPI document at ${code(project.config.openapi.path)} and API documentation at ${code(project.config.openapi.docs)}.\n\n` : '');
+        }
+        return generated + '\n\n# ' + code(basename(this.file.path)) + ' specification\n\n' +
+            `August ${compilerVersion()}. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.\n\n` +
+            this.fileOverview() + config + behavior + surface +
+            (behavior ? '' : 'This file declares no operations.\n') +
+            '## Shared language rules\n\nSee the [language reference](https://greenpandastudios.github.io/augscript/reference) for numeric, equality, ownership, and task rules.\n';
+    }
+    builtinSurface() {
+        if (!this.builtins.size && !this.properties.size)
+            return '';
+        return '## Built-in operations used by this file\n\n' + [...this.properties].sort(([a], [b]) => compare(a, b)).map(([name, property]) => `- ${code(name)} (${code(property.type)}): ${property.documentation}\n`).join('') +
+            [...this.builtins].sort(([a], [b]) => compare(a, b)).map(([name, operation]) => `- ${code(name)} (${operation.parameters.map(param => code(param.label) + ': ' + code(param.type)).join(', ') || 'no inputs'}) → ${code(operation.returns)}: ${operation.documentation}` +
+                (operation.changes ? ' Changes the receiver.' : '') +
+                (operation.errors?.length ? ' Can fail with ' + operation.errors.map(code).join(', ') + '.' : '') + '\n').join('') +
+            '\n[Full built-in reference](https://greenpandastudios.github.io/augscript/language-constructs).\n\n';
+    }
+}
+/** Check generated artifacts without writing; protect neighboring handwritten documents. */
+export function updateSpecs(checked, check = false, options = {}) {
+    const outputs = generateSpecs(checked, options), root = checked.project.root;
+    const manifest = join(root, '.aug-spec', 'manifest.json');
+    let previous = [];
+    if (options.manifest !== false && existsSync(manifest)) {
+        const saved = JSON.parse(readFileSync(manifest, 'utf8'));
+        if (saved.format !== 1 || !Array.isArray(saved.files) || saved.files.some(path => typeof path !== 'string' || relative(root, resolve(root, path)).startsWith('..') || !path.endsWith('.aug') && !path.endsWith('.aug.md')))
+            throw new Error('Invalid generated specification manifest');
+        previous = saved.files.map(path => resolve(root, path));
+    }
+    const names = new Set(outputs.map(output => output.path));
+    const removed = previous.filter(path => !names.has(path) && existsSync(path));
+    const stale = outputs.filter(output => !existsSync(output.path) || readFileSync(output.path, 'utf8') !== output.text).map(output => relative(root, output.path));
+    stale.push(...removed.map(path => relative(root, path)));
+    const manifestText = JSON.stringify({ format: 1, files: outputs.map(output => relative(root, output.path).replaceAll('\\', '/')), digest: hash(outputs.map(output => output.text).join('\0')) }, null, 2) + '\n';
+    if (options.manifest !== false && (!existsSync(manifest) || readFileSync(manifest, 'utf8') !== manifestText))
+        stale.push('.aug-spec/manifest.json');
+    if (check)
+        return { files: outputs.length, stale };
+    if (options.manifest !== false && (existsSync(dirname(manifest)) && lstatSync(dirname(manifest)).isSymbolicLink() || existsSync(manifest) && lstatSync(manifest).isSymbolicLink()))
+        throw new Error('Specification manifest must not be a symbolic link');
+    for (const output of outputs) {
+        let parent = dirname(output.path);
+        // Trust the project root, including platform aliases such as macOS /var.
+        while (parent !== root && !relative(root, parent).startsWith('..') && parent !== dirname(parent)) {
+            if (existsSync(parent) && lstatSync(parent).isSymbolicLink())
+                throw new Error(`Specification output directory is a symbolic link: ${parent}`);
+            parent = dirname(parent);
+        }
+        if (existsSync(output.path)) {
+            if (lstatSync(output.path).isSymbolicLink())
+                throw new Error(`Specification output is a symbolic link: ${output.path}`);
+            const text = readFileSync(output.path, 'utf8');
+            if (!text.startsWith(generated) && !text.startsWith(copied))
+                throw new Error(`Refusing to overwrite handwritten file ${output.path}`);
+        }
+    }
+    for (const output of outputs) {
+        if (existsSync(output.path) && readFileSync(output.path, 'utf8') === output.text)
+            continue;
+        mkdirSync(dirname(output.path), { recursive: true });
+        const temporary = output.path + '.aug-spec-tmp';
+        try {
+            writeFileSync(temporary, output.text, { flag: 'wx' });
+            renameSync(temporary, output.path);
+        }
+        finally {
+            if (existsSync(temporary))
+                rmSync(temporary);
+        }
+    }
+    for (const path of removed) {
+        const text = readFileSync(path, 'utf8');
+        if (text.startsWith(generated) || text.startsWith(copied))
+            rmSync(path);
+    }
+    if (options.manifest !== false) {
+        mkdirSync(dirname(manifest), { recursive: true });
+        if (!existsSync(manifest) || readFileSync(manifest, 'utf8') !== manifestText) {
+            const temporary = manifest + '.aug-spec-tmp';
+            try {
+                writeFileSync(temporary, manifestText, { flag: 'wx' });
+                renameSync(temporary, manifest);
+            }
+            finally {
+                if (existsSync(temporary))
+                    rmSync(temporary);
+            }
+        }
+    }
+    return { files: outputs.length, stale: [] };
+}