@greenpandastudios/aug-cli 0.19.0

package/src/native.js

@@ -0,0 +1,144 @@
+import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { basename, dirname, isAbsolute, join, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { loadConfig } from "./config.js";
+import { generateOpenApi } from "./openapi.js";
+import { nativeHome } from '../scripts/native-home.mjs';
+export function compileNative(root, generated, options = {}) {
+    const config = loadConfig(root).config;
+    const buildDir = join(root, '.aug-build', ...(options.testIndex === undefined ? [] : ['tests']));
+    mkdirSync(buildDir, { recursive: true });
+    if (config.openapi.enabled && options.checked && options.testIndex === undefined) {
+        const target = resolve(root, config.openapi.output);
+        mkdirSync(dirname(target), { recursive: true });
+        writeFileSync(target, JSON.stringify(generateOpenApi(options.checked).document, null, 2) + '\n');
+    }
+    const name = options.testIndex === undefined ? 'program' : `test-${options.testIndex}`;
+    const cPath = join(buildDir, `${name}.c`);
+    writeFileSync(cPath, generated);
+    const runtimeDir = resolve(dirname(fileURLToPath(import.meta.url)), '..', 'runtime');
+    const nativeRoot = nativeHome(resolve(runtimeDir, '..'));
+    const runtimePath = join(buildDir, 'aug_runtime.c');
+    copyFileSync(join(runtimeDir, 'aug_runtime.c'), runtimePath);
+    copyFileSync(join(runtimeDir, 'aug_runtime.h'), join(buildDir, 'aug_runtime.h'));
+    const valuesPath = join(buildDir, 'aug_values.c');
+    copyFileSync(join(runtimeDir, 'aug_values.c'), valuesPath);
+    const outputName = options.testIndex === undefined ? options.output ?? config.output ?? basename(root) : name;
+    const output = isAbsolute(outputName) ? outputName : join(buildDir, outputName);
+    const cc = process.env.CC ?? (existsSync('/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/clang') ?
+        '/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/clang' : 'clang');
+    const release = options.release ?? config.optimization === 'release';
+    const args = [release ? '-O2' : '-O0', '-g', '-std=c11', '-D_POSIX_C_SOURCE=200809L', '-Wall', '-Wextra',
+        '-pthread',
+        cPath, runtimePath, valuesPath, ...config.library_paths.map(path => `-L${resolve(root, path)}`), ...config.libraries.map(name => `-l${name}`), '-o', output];
+    const web = generated.includes('aug_http_') || generated.includes('_aug_http_') || generated.includes('aug_headers_');
+    if (web)
+        args.push('-DAUG_HTTP_RUNTIME');
+    if (generated.includes('aug_html_') || web) {
+        const htmlSource = join(buildDir, 'aug_html.c');
+        copyFileSync(join(runtimeDir, 'aug_html.c'), htmlSource);
+        args.push(htmlSource);
+    }
+    if (generated.includes('_aug_time_')) {
+        const timeSource = join(buildDir, 'aug_time.c');
+        copyFileSync(join(runtimeDir, 'aug_time.c'), timeSource);
+        args.push(timeSource);
+    }
+    if (web || generated.includes('aug_task_')) {
+        const taskSource = join(buildDir, 'aug_tasks.c');
+        copyFileSync(join(runtimeDir, 'aug_tasks.c'), taskSource);
+        const minicoro = join(nativeRoot, 'sources', 'minicoro');
+        if (!existsSync(join(minicoro, 'minicoro.h')))
+            throw new Error('Task dependency is missing. Run the compiler scripts/bootstrap-native.mjs with --extract-only; AUG_NATIVE_HOME selects its directory.');
+        args.push(taskSource, '-I' + minicoro, process.platform === 'darwin' ? '-D_DARWIN_C_SOURCE' : '-D_DEFAULT_SOURCE');
+    }
+    if (generated.includes('_aug_crypto_') || web) {
+        const prefix = join(nativeRoot, 'prefix');
+        const manifestPath = join(prefix, 'aug-native-manifest.json');
+        if (!existsSync(manifestPath))
+            throw new Error('Native libraries are not ready. Run node scripts/bootstrap-native.mjs in the compiler directory; AUG_NATIVE_HOME selects its directory.');
+        const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+        if (manifest.platform !== process.platform || manifest.architecture !== process.arch)
+            throw new Error(`Native dependencies target ${manifest.platform}/${manifest.architecture}; this compiler runs on ${process.platform}/${process.arch}. Build dependencies on this host.`);
+        const cryptoPath = join(buildDir, 'aug_crypto.c');
+        copyFileSync(join(runtimeDir, 'aug_crypto.c'), cryptoPath);
+        args.push(cryptoPath, '-I' + join(prefix, 'include'), '-L' + join(prefix, 'lib'), '-Wl,-rpath,' + join(prefix, 'lib'), '-lgnutls', '-lnettle', '-lhogweed', '-lgmp', '-pthread');
+        if (web) {
+            args.push(process.platform === 'darwin' ? '-D_DARWIN_C_SOURCE' : '-D_DEFAULT_SOURCE');
+            const webPath = join(buildDir, 'aug_http.c');
+            copyFileSync(join(runtimeDir, 'aug_http.c'), webPath);
+            args.push(webPath, join(prefix, 'lib', 'libwebsockets.a'), '-lz');
+            if (process.platform === 'darwin')
+                args.push('-framework', 'CoreFoundation', '-framework', 'SystemConfiguration');
+        }
+    }
+    if (generated.includes('_aug_json_') || generated.includes('aug_json_') || web) {
+        const jsonSource = join(buildDir, 'aug_json.c');
+        copyFileSync(join(runtimeDir, 'aug_json.c'), jsonSource);
+        const yyjson = join(nativeRoot, 'sources', 'yyjson', 'src');
+        if (!existsSync(join(yyjson, 'yyjson.c')))
+            throw new Error('JSON dependency is missing. Run node scripts/bootstrap-native.mjs --extract-only.');
+        args.push(jsonSource, join(yyjson, 'yyjson.c'), '-I' + yyjson);
+    }
+    const sdk = '/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk';
+    if (process.platform === 'darwin' && existsSync(sdk) && !process.env.SDKROOT)
+        args.unshift('-isysroot', sdk);
+    const compile = spawnSync(cc, args, { encoding: 'utf8', cwd: root });
+    if (compile.error)
+        throw compile.error;
+    const error = compile.status === 0 ? '' : compile.stderr || compile.stdout || 'C compiler failed';
+    const diagnostics = [];
+    for (const match of error.matchAll(/^(.+\.aug):(\d+):(\d+):\s*(?:fatal )?error:\s*(.+)$/gm))
+        diagnostics.push({ file: match[1], line: Number(match[2]), column: Number(match[3]), code: 'NATIVE', message: match[4] });
+    if (compile.status === 0 && options.checked) {
+        const version = JSON.parse(readFileSync(resolve(runtimeDir, '..', 'package.json'), 'utf8')).version;
+        writeFileSync(output + '.augmap.json', JSON.stringify({ version, compiler: cc, arguments: args,
+            generatedHash: createHash('sha256').update(generated).digest('hex'),
+            sources: [...options.checked.project.files.values()].map(file => ({ path: file.path, hash: createHash('sha256').update(file.source).digest('hex') })),
+            symbols: [...options.checked.project.definitions.values()].map((def, index) => ({ name: def.name, native: `aug_${index}_${def.name}`, location: def.node.span })) }, null, 2) + '\n');
+    }
+    return { output, status: compile.status ?? 1, error, diagnostics };
+}
+/** Merge per-process native statement counts, retaining unexecuted locations. */
+export function writeCoverage(root, reports) {
+    const files = new Map();
+    for (const path of reports)
+        if (existsSync(path))
+            for (const row of readFileSync(path, 'utf8').trim().split('\n')) {
+                const match = /^(.*)\t(\d+)\t(\d+)$/.exec(row);
+                if (!match)
+                    continue;
+                const lines = files.get(match[1]) ?? new Map();
+                files.set(match[1], lines);
+                const line = Number(match[2]);
+                lines.set(line, (lines.get(line) ?? 0) + Number(match[3]));
+            }
+    const result = [...files].sort(([a], [b]) => a.localeCompare(b)).map(([file, counts]) => ({ file,
+        lines: [...counts].sort(([a], [b]) => a - b).map(([line, count]) => ({ line, count })) }));
+    const executable = result.reduce((sum, file) => sum + file.lines.length, 0);
+    const covered = result.reduce((sum, file) => sum + file.lines.filter(line => line.count > 0).length, 0);
+    const directory = join(root, '.aug-build', 'coverage');
+    mkdirSync(directory, { recursive: true });
+    const report = { kind: 'statement-lines', covered, executable, percent: executable ? covered * 100 / executable : 0, files: result };
+    const path = join(directory, 'coverage.json');
+    writeFileSync(path, JSON.stringify(report, null, 2) + '\n');
+    writeFileSync(join(directory, 'lcov.info'), result.map(file => `TN:AugScript\nSF:${file.file}\n` +
+        file.lines.map(line => `DA:${line.line},${line.count}\n`).join('') + `LF:${file.lines.length}\nLH:${file.lines.filter(line => line.count > 0).length}\nend_of_record\n`).join(''));
+    return { ...report, path: relative(root, path) };
+}
+export function benchmark(output, root, iterations, warmup, args, timeout) {
+    const samples = [];
+    for (let index = -warmup; index < iterations; index++) {
+        const start = performance.now();
+        const run = spawnSync(output, args, { encoding: 'utf8', cwd: root, timeout, killSignal: 'SIGKILL' });
+        if (run.error || run.status !== 0)
+            throw new Error(run.error?.message ?? run.stderr ?? `Benchmark exited ${run.status}`);
+        if (index >= 0)
+            samples.push(performance.now() - start);
+    }
+    const sorted = [...samples].sort((a, b) => a - b);
+    return { iterations, warmup, includesProcessStartup: true, units: 'milliseconds', samples,
+        median: sorted[Math.floor(sorted.length / 2)], p95: sorted[Math.min(sorted.length - 1, Math.ceil(sorted.length * .95) - 1)], minimum: sorted[0] };
+}

package/src/navigation.js

@@ -0,0 +1,162 @@
+import { statSync } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
+import { lex } from "./lexer.js";
+import { libraryChild } from "./libraries.js";
+function definitionTarget(def) {
+    const span = def.node.kind === 'interceptor' ? def.node.nameSpan : def.node.span;
+    return { name: def.name, file: def.file, line: span.line,
+        column: span.column, kind: def.node.kind };
+}
+function parameterTarget(project, param) {
+    const source = project.files.get(param.span.file)?.source ?? '';
+    const token = lex(param.span.file, source).tokens.filter(token => token.value === param.name &&
+        param.span.start <= token.span.start && token.span.end <= param.span.end).at(-1);
+    const span = token?.span ?? param.span;
+    return { name: param.name, file: span.file, line: span.line, column: span.column, kind: 'parameter' };
+}
+function directoryExists(path) {
+    try {
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function exportTarget(project, folder, name, child) {
+    const file = project.files.get(join(folder, 'export.aug'));
+    if (!file)
+        return undefined;
+    const declaration = file.items.find(item => item.kind === 'export' &&
+        item.name === (child ?? name) && item.folder === !!child);
+    return { name, file: file.path, line: declaration?.span.line ?? 1,
+        column: declaration?.span.column ?? 1, kind: 'module' };
+}
+function importPathTarget(project, importer, from, name, segment) {
+    if (!from.length)
+        return undefined;
+    if (from[0] === 'august' && project.stdlibRoot) {
+        let folder = project.stdlibRoot;
+        for (let index = 1; index <= segment; index++)
+            folder = libraryChild(project.libraries, folder, from[index]);
+        return exportTarget(project, folder, name, segment < from.length - 1 ? from[segment + 1] : undefined);
+    }
+    const owner = importer.package ? project.packages.scopes.get(importer.package) : undefined;
+    const dependency = owner ? project.packages.scopes.get(owner.dependencies[from[0]]) : project.packages.roots.get(from[0]);
+    if (dependency) {
+        const folder = join(dependency.sourceRoot, ...from.slice(1, segment + 1));
+        return exportTarget(project, folder, name, segment < from.length - 1 ? from[segment + 1] : undefined);
+    }
+    if (from.length === 1) {
+        const sibling = join(dirname(importer.path), `${from[0]}.aug`);
+        if (project.files.has(sibling) && basename(sibling) !== 'export.aug')
+            return { name: from[0], file: sibling, line: 1, column: 1, kind: 'module' };
+    }
+    const siblingFolder = join(dirname(importer.path), from[0]);
+    let folder = from.length === 1 && directoryExists(siblingFolder) ?
+        siblingFolder : join(owner?.sourceRoot ?? project.sourceRoot, from[0]);
+    if (segment === 0 && from.length > 1)
+        return exportTarget(project, folder, from[0], from[1]);
+    for (let index = 1; index <= segment; index++)
+        folder = join(folder, from[index]);
+    return segment === from.length - 1 ? exportTarget(project, folder, name) :
+        exportTarget(project, folder, from[segment], from[segment + 1]);
+}
+function unfinishedModuleTarget(project, file, token, tokens) {
+    const lineTokens = tokens.filter(entry => entry.span.line === token.span.line &&
+        entry.kind !== 'eof');
+    if (lineTokens[0]?.kind === 'export' && lineTokens[1]?.kind === 'folder' &&
+        lineTokens[2]?.kind === 'identifier' &&
+        (token === lineTokens[1] || token === lineTokens[2]))
+        return exportTarget(project, file.builtin ? libraryChild(project.libraries, dirname(file.path), lineTokens[2].value) : join(dirname(file.path), lineTokens[2].value), lineTokens[2].value);
+    if (!['import', 'export'].includes(lineTokens[0]?.kind ?? '') ||
+        lineTokens[1]?.kind !== 'identifier')
+        return undefined;
+    const fromIndex = lineTokens.findIndex(entry => entry.kind === 'from');
+    if (fromIndex < 0)
+        return undefined;
+    const pathTokens = lineTokens.slice(fromIndex + 1).filter(entry => entry.kind === 'identifier');
+    if (!pathTokens.length)
+        return undefined;
+    const segment = token.kind === 'from' ? pathTokens.length - 1 : pathTokens.indexOf(token);
+    if (segment < 0)
+        return undefined;
+    if (lineTokens[0].kind === 'import')
+        return importPathTarget(project, file, pathTokens.map(entry => entry.value), lineTokens[1].value, segment);
+    const sibling = join(dirname(file.path), `${pathTokens[0].value}.aug`);
+    return project.files.has(sibling) ? { name: pathTokens[0].value, file: sibling,
+        line: 1, column: 1, kind: 'module' } : undefined;
+}
+/** Go to a declaration or the source named by an import/export path. */
+export function definitionAt(project, fileName, offset) {
+    const file = project.files.get(resolve(fileName));
+    if (!file)
+        return undefined;
+    const tokens = lex(file.path, file.source).tokens;
+    const token = tokens.find(entry => entry.kind !== 'eof' &&
+        entry.span.start <= offset && offset < entry.span.end);
+    if (!token)
+        return undefined;
+    for (const node of file.items) {
+        const candidates = node.kind === 'class' || node.kind === 'function' ? [node] : [];
+        if ('methods' in node)
+            candidates.push(...node.methods);
+        for (const target of candidates)
+            for (const tag of target.annotations ?? []) {
+                const mapping = tag.mappings.find(entry => entry.span.start <= token.span.start && token.span.end <= entry.span.end);
+                if (!mapping)
+                    continue;
+                const def = project.scopes.get(file.path)?.get(tag.name);
+                const around = def?.node.kind === 'interceptor' ? def.node.methods.find(method => method.name === 'around') : undefined;
+                const params = target.kind === 'class' ? target.fields : target.params;
+                const param = token.span.start >= mapping.sourceSpan.start ? params.find(param => param.name === mapping.source) :
+                    around?.params.find(param => param.name === mapping.name);
+                if (param)
+                    return parameterTarget(project, param);
+            }
+        if (node.kind === 'interceptor' && token.value === 'next') {
+            const around = node.methods.find(method => method.name === 'around' &&
+                method.span.start <= token.span.start && token.span.end <= method.span.end);
+            if (around)
+                return { name: 'around', file: file.path, line: around.span.line,
+                    column: around.span.column, kind: 'method' };
+        }
+    }
+    const item = file.items.find(entry => entry.span.start <= token.span.start &&
+        token.span.end <= entry.span.end && (entry.kind === 'import' || entry.kind === 'export'));
+    if (item?.kind === 'import' || (item?.kind === 'export' && !item.folder)) {
+        const declarationTokens = tokens.filter(entry => entry.span.start >= item.span.start &&
+            entry.span.end <= item.span.end);
+        const fromIndex = declarationTokens.findIndex(entry => entry.kind === 'from');
+        const sourceTokens = declarationTokens.slice(fromIndex + 1)
+            .filter(entry => entry.kind === 'identifier');
+        const segments = item.kind === 'import' ? item.from : [item.from];
+        const selected = token.kind === 'from' ? segments.length - 1 :
+            sourceTokens.findIndex((entry) => entry === token);
+        if (fromIndex >= 0 && selected >= 0 && selected < segments.length) {
+            if (item.kind === 'import')
+                return importPathTarget(project, file, segments, item.names[0] ?? 'everything', selected);
+            const sibling = join(dirname(file.path), `${item.from}.aug`);
+            return project.files.has(sibling) ? { name: item.from, file: sibling,
+                line: 1, column: 1, kind: 'module' } : undefined;
+        }
+        if (item.kind === 'export' && token.value === item.name) {
+            const sibling = join(dirname(file.path), `${item.from}.aug`);
+            const def = project.scopes.get(sibling)?.get(item.name);
+            return def ? definitionTarget(def) : undefined;
+        }
+    }
+    if (item?.kind === 'export' && item.folder &&
+        (token.kind === 'folder' || token.value === item.name))
+        return exportTarget(project, file.builtin ? libraryChild(project.libraries, dirname(file.path), item.name) : join(dirname(file.path), item.name), item.name);
+    if (!item) {
+        const unfinished = unfinishedModuleTarget(project, file, token, tokens);
+        if (unfinished)
+            return unfinished;
+    }
+    if (token.kind === 'identifier') {
+        const def = project.scopes.get(file.path)?.get(token.value);
+        if (def)
+            return definitionTarget(def);
+    }
+    return undefined;
+}

package/src/openapi.js

@@ -0,0 +1,220 @@
+import { createHash } from 'node:crypto';
+import { schemaType } from "./schemas.js";
+import { callableDocumentation } from "./documentation.js";
+const primitive = (name) => ({ id: 'builtin:' + name, name, kind: 'builtin', args: [], nullable: false });
+const problem = { type: 'object', required: ['type', 'title', 'status'], properties: { type: { type: 'string', format: 'uri-reference' }, title: { type: 'string' }, status: { type: 'integer', minimum: 400, maximum: 599 } } };
+function nodes(value, visit) {
+    if (!value || typeof value !== 'object')
+        return;
+    if (Array.isArray(value)) {
+        value.forEach(child => nodes(child, visit));
+        return;
+    }
+    visit(value);
+    for (const [key, child] of Object.entries(value))
+        if (!['span', 'type'].includes(key))
+            nodes(child, visit);
+}
+/** Build a contract from served declarations and checked returns; untyped wire values fail the enabled build. */
+export function generateOpenApi(checked) {
+    const project = checked.project, config = project.config.openapi;
+    const diagnostics = [], schemas = {}, paths = {};
+    const seenTypes = new Map();
+    const report = (span, message) => diagnostics.push({ ...span, code: 'OPENAPI', message });
+    const schema = (type, span) => {
+        const base = { ...type, optional: false, nullable: false };
+        let result;
+        if (['int', 'c_int'].includes(base.name))
+            result = { type: 'integer', format: base.name === 'int' ? 'int64' : 'int32' };
+        else if (base.name === 'float')
+            result = { type: 'number', format: 'double' };
+        else if (['string', 'bool', 'Html', 'Bytes'].includes(base.name))
+            result = { type: base.name === 'bool' ? 'boolean' : 'string' };
+        else if (['List', 'Set'].includes(base.name))
+            result = { type: 'array', items: schema(base.args[0], span), ...(base.name === 'Set' ? { uniqueItems: true } : {}) };
+        else if (base.name === 'Tuple')
+            result = { type: 'array', prefixItems: base.args.map(item => schema(item, span)), minItems: base.args.length, maxItems: base.args.length };
+        else if (base.name === 'Map' && base.args[0]?.name === 'string')
+            result = { type: 'object', additionalProperties: schema(base.args[1], span) };
+        else if (base.def?.node.kind === 'class' && base.def.node.record) {
+            const identity = (type) => [type.id, type.nullable, !!type.optional, type.args.map(identity)];
+            const key = JSON.stringify(identity(base));
+            let name = seenTypes.get(key);
+            if (!name) {
+                name = base.name + '_' + createHash('sha256').update(key).digest('hex').slice(0, 8);
+                seenTypes.set(key, name);
+                schemas[name] = {};
+                const record = base.def.node, params = new Map(record.typeParams.map((param, index) => [param, base.args[index]]));
+                const properties = {}, required = [];
+                for (const field of record.fields) {
+                    if (field.name.startsWith('_'))
+                        report(field.span, 'Private fields cannot appear in public JSON contracts');
+                    const type = schemaType(project, field.type, base.def.file, params);
+                    properties[field.name] = schema(type, field.span);
+                    if (!type.optional)
+                        required.push(field.name);
+                }
+                schemas[name] = { type: 'object', properties, required, additionalProperties: false };
+            }
+            result = { $ref: '#/components/schemas/' + name };
+        }
+        else {
+            report(span, `${base.name} has no complete OpenAPI schema; expose a concrete data record`);
+            result = {};
+        }
+        if (type.nullable)
+            result = typeof result.type === 'string' ? { ...result, type: [result.type, 'null'] } : { anyOf: [result, { type: 'null' }] };
+        return result;
+    };
+    const variants = (fn, visiting = new Set()) => {
+        if (visiting.has(fn)) {
+            report(fn.span, 'Recursive response helpers need a concrete response contract');
+            return [];
+        }
+        visiting = new Set([...visiting, fn]);
+        const result = [];
+        nodes(fn.body, node => {
+            if (node.kind !== 'return')
+                return;
+            const expr = node.value;
+            if (!expr) {
+                result.push({ status: fn.endpoint?.status ?? 200, type: primitive('void') });
+                return;
+            }
+            const type = checked.expressionTypes.get(expr) ?? schemaType(project, fn.returns, fn.span.file);
+            if (expr.kind === 'call' && expr.callee.kind === 'name' && type.name === 'HttpResponse') {
+                if (expr.callee.name !== 'HttpResponse') {
+                    const def = project.scopes.get(fn.span.file)?.get(expr.callee.name);
+                    if (def?.node.kind === 'function') {
+                        result.push(...variants(def.node, visiting));
+                        return;
+                    }
+                }
+                else {
+                    const plan = checked.callPlans.get(expr), source = plan?.sourceIndices[0], statusIndex = plan?.sourceIndices[1];
+                    let status = 200;
+                    if (statusIndex !== undefined) {
+                        const value = expr.args[statusIndex];
+                        if (value.kind !== 'literal' || typeof value.value !== 'number') {
+                            report(value.span, 'OpenAPI response statuses must be explicit constants');
+                            return;
+                        }
+                        status = value.value;
+                    }
+                    const body = source === undefined ? undefined : expr.args[source];
+                    let bodyType = body ? checked.expressionTypes.get(body) ?? type.args[0] : primitive('void');
+                    if (body?.kind === 'call' && body.callee.kind === 'name' && body.callee.name === 'Json') {
+                        const index = checked.callPlans.get(body)?.sourceIndices[0];
+                        if (index !== undefined)
+                            bodyType = checked.expressionTypes.get(body.args[index]) ?? bodyType;
+                    }
+                    result.push({ status, type: bodyType });
+                    return;
+                }
+            }
+            if (type.name === 'HttpResponse') {
+                report(expr.span, 'A dynamic HttpResponse needs explicit, discoverable response variants');
+                return;
+            }
+            if (type.name === 'Json' && expr.kind === 'call' && expr.callee.kind === 'name' && expr.callee.name === 'Json') {
+                const index = checked.callPlans.get(expr)?.sourceIndices[0];
+                if (index !== undefined) {
+                    result.push({ status: fn.endpoint?.status ?? 200, type: checked.expressionTypes.get(expr.args[index]) ?? type });
+                    return;
+                }
+            }
+            result.push({ status: fn.endpoint?.status ?? 200, type });
+        });
+        if (!result.length && fn.returns.name !== 'HttpResponse')
+            result.push({ status: fn.endpoint?.status ?? 200, type: schemaType(project, fn.returns, fn.span.file) });
+        return result;
+    };
+    const served = new Map();
+    nodes(project.main?.items, node => {
+        if (node.kind === 'serve')
+            for (const name of node.names) {
+                const def = project.scopes.get(project.main.path)?.get(name);
+                if (def?.node.kind === 'function' && def.node.endpoint)
+                    served.set(def.id, def);
+            }
+    });
+    for (const def of served.values()) {
+        const fn = def.node, endpoint = fn.endpoint, doc = callableDocumentation(project, fn);
+        if ([config.path, config.docs, config.docs + '/client.js'].includes(endpoint.path))
+            report(fn.span, 'Endpoint path conflicts with configured OpenAPI routes');
+        const responses = {};
+        const response = (status, media, value) => {
+            const result = responses[status] ??= { description: status < 400 ? 'Successful response' : 'Error response', content: {} };
+            const current = result.content[media];
+            if (!current)
+                result.content[media] = { schema: value };
+            else if (JSON.stringify(current.schema) !== JSON.stringify(value))
+                current.schema = { oneOf: [current.schema, value] };
+        };
+        if (endpoint.streams) {
+            const item = schemaType(project, fn.returns, fn.span.file), sse = item.name === 'ServerEvent';
+            const itemSchema = sse ? { type: 'object', required: ['data'], properties: { data: { type: 'string', contentMediaType: 'application/json', contentSchema: schema(item.args[0], fn.span) }, id: { type: 'string' }, event: { type: 'string' }, retry: { type: 'integer', minimum: 0 } } } : schema(item, fn.span);
+            responses[endpoint.status] = { description: 'Streaming response', content: { [sse ? 'text/event-stream' : item.name === 'Html' ? 'text/html' : 'application/octet-stream']: { itemSchema } } };
+        }
+        for (const variant of endpoint.streams ? [] : variants(fn)) {
+            if (variant.type.name === 'void' || [204, 304].includes(variant.status))
+                responses[variant.status] = { description: 'Response with no body' };
+            else
+                response(variant.status, variant.type.name === 'Html' ? 'text/html' : variant.type.name === 'Bytes' ? 'application/octet-stream' : 'application/json', schema(variant.type, fn.span));
+        }
+        const parameters = [];
+        let requestBody;
+        const bodies = fn.params.filter(param => ['body', 'form'].includes(param.source?.kind ?? ''));
+        for (const param of fn.params) {
+            if (!param.source || ['body', 'form', 'request'].includes(param.source.kind))
+                continue;
+            const type = schemaType(project, param.type, def.file);
+            parameters.push({ name: param.source.name ?? param.name, in: param.source.kind, required: param.source.kind === 'path' || !type.optional,
+                schema: schema(type, param.span), ...(doc?.parameters.get(param.name) ? { description: doc.parameters.get(param.name) } : {}) });
+        }
+        if (bodies.length) {
+            const param = bodies[0], type = schemaType(project, param.type, def.file);
+            requestBody = { required: !type.optional, content: { [param.source.kind === 'form' ? 'application/x-www-form-urlencoded' : 'application/json']: { schema: schema(type, param.span) } } };
+        }
+        else if (fn.params.some(param => param.source?.kind === 'request')) {
+            nodes(fn.body, node => {
+                const call = node;
+                if (call.kind === 'call' && call.callee.kind === 'member' && call.callee.name === 'form' && call.typeArgs[0])
+                    requestBody = { required: true, content: { 'application/x-www-form-urlencoded': { schema: schema(schemaType(project, call.typeArgs[0], def.file), call.span) } } };
+            });
+        }
+        const errors = new Set([500, ...endpoint.errors.map(error => error.status), ...fn.throws.map(error => endpoint.errors.find(mapped => mapped.type.name === error.name)?.status ?? 500)]);
+        const policies = checked.httpPolicies.get(fn) ?? [];
+        for (const policy of policies)
+            for (const status of policy.name === 'RequireLogin' ? [401] : policy.name === 'RequirePermission' ? [401, 403] : policy.name === 'RateLimit' ? [429] : policy.name === 'Timeout' ? [504] : policy.name === 'Cors' ? [400, 403] : [])
+                errors.add(status);
+        if (parameters.length || bodies.length)
+            errors.add(400);
+        if (requestBody) {
+            errors.add(413);
+            errors.add(415);
+            if (bodies.some(param => param.source?.kind === 'body'))
+                errors.add(422);
+        }
+        for (const status of errors)
+            response(status, 'application/problem+json', problem);
+        (paths[endpoint.path] ??= {})[endpoint.method.toLowerCase()] = { operationId: def.name, ...(doc ? { description: doc.markdown } : {}), parameters, ...(requestBody ? { requestBody } : {}), responses,
+            ...(policies.length ? { 'x-august-policies': policies.map(policy => ({ name: policy.name, ...policy.options, dependencies: policy.dependencies.map(index => fn.params[index].name) })) } : {}) };
+    }
+    const document = { openapi: '3.2.1', jsonSchemaDialect: 'https://json-schema.org/draft/2020-12/schema', info: { title: config.title, version: config.version }, paths, components: { schemas } };
+    return { document, diagnostics };
+}
+export function apiExplorer(specPath, clientPath) {
+    const attr = (value) => value.replaceAll('&', '&amp;').replaceAll('"', '&quot;').replaceAll('<', '&lt;');
+    return '<!doctype html><html lang="en"><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>August API</title><body style="font:16px system-ui;max-width:1000px;margin:40px auto;padding:20px"><h1>August API</h1><p>Contracts generated from served August endpoints.</p><main id="api" data-spec="' + attr(specPath) + '">Loading API…</main><script src="' + attr(clientPath) + '" defer></script></body></html>';
+}
+export const apiExplorerScript = `const root=document.getElementById('api');
+const text=(tag,value)=>{const node=document.createElement(tag);node.textContent=value;return node};
+fetch(root.dataset.spec).then(r=>r.json()).then(spec=>{root.textContent='';document.title=spec.info.title;for(const [path,methods] of Object.entries(spec.paths))for(const [method,op] of Object.entries(methods)){
+const block=document.createElement('section');block.style.cssText='border:1px solid #ccd;padding:20px;border-radius:12px;margin:16px 0';block.append(text('h2',method.toUpperCase()+' '+path),text('p',op.description||op.operationId));
+const form=document.createElement('form');const inputs=[];for(const p of op.parameters||[]){const label=text('label',p.in+' '+p.name+' ');const input=document.createElement('input');input.required=p.required;label.append(input);form.append(label);inputs.push([p,input]);}
+let body;if(op.requestBody){body=document.createElement('textarea');body.placeholder='Request body';body.rows=5;body.style.display='block';form.append(body);}
+const button=text('button','Send request');button.type='submit';const output=text('pre','');output.style.whiteSpace='pre-wrap';form.append(button);block.append(form,output);root.append(block);
+form.addEventListener('submit',async event=>{event.preventDefault();let target=path;const query=new URLSearchParams(),headers={};for(const [p,input]of inputs){if(p.in==='path')target=target.replace('{'+p.name+'}',encodeURIComponent(input.value));else if(p.in==='query'&&input.value)query.append(p.name,input.value);else if(p.in==='header'&&input.value)headers[p.name]=input.value;}
+const media=op.requestBody&&Object.keys(op.requestBody.content)[0];if(media)headers['content-type']=media;button.disabled=true;try{const r=await fetch(target+(query.size?'?'+query:''),{method:method.toUpperCase(),headers,body:body?body.value:undefined});output.textContent=r.status+' '+r.statusText+'\\n'+await r.text();}catch(error){output.textContent=String(error);}finally{button.disabled=false;}});
+}}).catch(error=>root.textContent=String(error));`;