@greenpandastudios/aug-cli 0.20.1 → 0.21.0

package/src/llvm-debug.js

@@ -0,0 +1,101 @@
+import { basename, dirname } from 'node:path';
+const quote = (value) => '"' + [...Buffer.from(value)].map(byte => byte >= 32 && byte < 127 && byte !== 34 && byte !== 92 ? String.fromCharCode(byte) : '\\' + byte.toString(16).padStart(2, '0').toUpperCase()).join('') + '"';
+const typeName = (type) => (type.optional || type.nullable ? 'optional ' : '') + type.name + (type.args.length ? '<' + type.args.map(typeName).join(', ') + '>' : '');
+/** DWARF describes August source and the real boxed storage. Rich collection
+ * views and an August-aware debugger are separate from source-line information. */
+export class DebugMetadata {
+    nodes = [];
+    files = new Map();
+    functions = new Map();
+    retained = new Map();
+    locations = new Map();
+    scopes = new Map();
+    variables = new Map();
+    types = new Map();
+    unit;
+    subroutine;
+    boxed;
+    optimized;
+    constructor(ir, optimized) {
+        this.optimized = optimized;
+        const source = ir.functions.find(fn => fn.name === ir.main);
+        // Use LLDB's C type reader for the concrete tagged C-compatible storage.
+        // An unregistered vendor language prevents older LLDBs from finding locals.
+        // Source paths, names and producer still identify the August program; this
+        // does not enable August expression evaluation in the debugger.
+        this.unit = this.node(`distinct !DICompileUnit(language: DW_LANG_C99, file: ${this.file(source.span.file)}, producer: "August LLVM", isOptimized: ${optimized}, runtimeVersion: 0, emissionKind: FullDebug)`);
+        this.subroutine = this.node(`!DISubroutineType(types: ${this.node('!{}')})`);
+        const tag = this.node('!DIBasicType(name: "tag", size: 32, encoding: DW_ATE_unsigned)');
+        const integer = this.node('!DIBasicType(name: "int64", size: 64, encoding: DW_ATE_signed)');
+        const floating = this.node('!DIBasicType(name: "float64", size: 64, encoding: DW_ATE_float)');
+        const pointer = this.node('!DIDerivedType(tag: DW_TAG_pointer_type, baseType: null, size: 64)');
+        const payload = this.node(`!DICompositeType(tag: DW_TAG_union_type, name: "August payload", size: 64, align: 64, elements: ${this.node('!{' + [
+            this.node(`!DIDerivedType(tag: DW_TAG_member, name: "integer", baseType: ${integer}, size: 64)`),
+            this.node(`!DIDerivedType(tag: DW_TAG_member, name: "floating", baseType: ${floating}, size: 64)`),
+            this.node(`!DIDerivedType(tag: DW_TAG_member, name: "object", baseType: ${pointer}, size: 64)`)
+        ].join(', ') + '}')})`);
+        this.boxed = this.node(`!DICompositeType(tag: DW_TAG_structure_type, name: "August value", size: 128, align: 64, elements: ${this.node('!{' + [
+            this.node(`!DIDerivedType(tag: DW_TAG_member, name: "tag", baseType: ${tag}, size: 32, offset: 0)`),
+            this.node(`!DIDerivedType(tag: DW_TAG_member, name: "payload", baseType: ${payload}, size: 64, offset: 64)`)
+        ].join(', ') + '}')})`);
+    }
+    node(value) { const name = '!' + this.nodes.length; this.nodes.push(name + ' = ' + value); return name; }
+    file(path) { let file = this.files.get(path); if (!file) {
+        file = this.node(`!DIFile(filename: ${quote(basename(path))}, directory: ${quote(dirname(path))})`);
+        this.files.set(path, file);
+    } return file; }
+    function(fn) {
+        let scope = this.functions.get(fn.name);
+        if (!scope) {
+            const retained = this.node('!{}');
+            this.retained.set(fn.name, { node: retained, variables: [] });
+            scope = this.node(`distinct !DISubprogram(name: ${quote(fn.sourceName)}, linkageName: ${quote(fn.name)}, scope: ${this.file(fn.span.file)}, file: ${this.file(fn.span.file)}, line: ${fn.span.line}, type: ${this.subroutine}, scopeLine: ${fn.span.line}, spFlags: DISPFlagDefinition${fn.name === 'main' ? '' : ' | DISPFlagLocalToUnit'}${this.optimized ? ' | DISPFlagOptimized' : ''}, unit: ${this.unit}, retainedNodes: ${retained})`);
+            this.functions.set(fn.name, scope);
+        }
+        return scope;
+    }
+    scope(fn, name) {
+        if (name === undefined)
+            return this.function(fn);
+        const key = fn.name + ':' + name;
+        let result = this.scopes.get(key);
+        if (!result) {
+            const source = fn.scopes.find(scope => scope.name === name);
+            result = this.node(`distinct !DILexicalBlock(scope: ${this.scope(fn, source.parent)}, file: ${this.file(source.span.file)}, line: ${source.span.line}, column: ${source.span.column})`);
+            this.scopes.set(key, result);
+        }
+        return result;
+    }
+    location(fn, span, scopeName) {
+        const key = [fn.name, span.file, span.line, span.column, scopeName].join(':');
+        let location = this.locations.get(key);
+        if (!location) {
+            const base = this.scope(fn, scopeName);
+            const scope = span.file === fn.span.file ? base : this.node(`!DILexicalBlockFile(scope: ${base}, file: ${this.file(span.file)}, discriminator: 0)`);
+            location = this.node(`!DILocation(line: ${Math.max(1, span.line)}, column: ${Math.max(1, span.column)}, scope: ${scope})`);
+            this.locations.set(key, location);
+        }
+        return location;
+    }
+    variable(fn, variable) {
+        const existing = this.variables.get(variable);
+        if (existing)
+            return existing;
+        const key = JSON.stringify(variable.type);
+        let type = this.types.get(key);
+        if (!type) {
+            type = this.node(`!DIDerivedType(tag: DW_TAG_typedef, name: ${quote(typeName(variable.type))}, baseType: ${this.boxed})`);
+            this.types.set(key, type);
+        }
+        const result = this.node(`!DILocalVariable(name: ${quote(variable.name)}, ${variable.argument ? 'arg: ' + variable.argument + ', ' : ''}scope: ${this.scope(fn, variable.scope)}, file: ${this.file(variable.span.file)}, line: ${variable.span.line}, type: ${type})`);
+        this.retained.get(fn.name).variables.push(result);
+        this.variables.set(variable, result);
+        return result;
+    }
+    generate() {
+        for (const entry of this.retained.values())
+            this.nodes[Number(entry.node.slice(1))] = entry.node + ' = !{' + entry.variables.join(', ') + '}';
+        const dwarf = this.node('!{i32 7, !"Dwarf Version", i32 4}'), debug = this.node('!{i32 2, !"Debug Info Version", i32 3}');
+        return [`!llvm.dbg.cu = !{${this.unit}}`, `!llvm.module.flags = !{${dwarf}, ${debug}}`, ...this.nodes].join('\n');
+    }
+}

package/src/llvm-native.js

@@ -0,0 +1,152 @@
+import { copyFileSync, existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { generateLLVM, runtimeLayout } from "./llvm.js";
+import { lowerToIR } from "./ir.js";
+import { compilerVersion } from "./package-manager.js";
+import { nativePath, nativeHostTarget } from "./native-contracts.js";
+import { runtimeIdentifierSha256 } from "./runtime-abi.js";
+import { generateOpenApi } from "./openapi.js";
+import { llvmPlatform, systemLibc } from "./llvm-platform.js";
+export function readRuntimePack(directory) {
+    if (!existsSync(join(directory, 'runtime.json')))
+        throw new Error('LLVM_RUNTIME: A matching prebuilt August runtime is not available. Contributor builds can run node scripts/build-runtime-pack.mjs.');
+    const pack = JSON.parse(readFileSync(join(directory, 'runtime.json'), 'utf8'));
+    const platform = llvmPlatform();
+    if (pack.identifierSha256 !== runtimeIdentifierSha256)
+        throw new Error('LLVM_RUNTIME: Runtime operation identifiers differ from this compiler');
+    if (!pack || pack.format !== 1 || pack.version !== compilerVersion() || pack.target !== platform.target || pack.minimumOS !== platform.minimumOS || pack.minimumLibc !== platform.minimumLibc || !pack.files || typeof pack.files !== 'object' || Array.isArray(pack.files) || !Array.isArray(pack.libraries) || !pack.libraries.length || !/^([0-9a-f]{64})$/.test(pack.sourceSha256) || JSON.stringify(pack.layout) !== JSON.stringify(runtimeLayout))
+        throw new Error('LLVM_RUNTIME: Runtime pack does not match this compiler, layout and target');
+    const root = realpathSync(directory);
+    for (const [path, expected] of Object.entries(pack.files)) {
+        nativePath(path);
+        const file = join(root, path);
+        if (!/^[0-9a-f]{64}$/.test(expected) || !lstatSync(file).isFile() || !realpathSync(file).startsWith(root + '/'))
+            throw new Error('NATIVE_INTEGRITY: Invalid runtime pack member ' + path);
+        const actual = createHash('sha256').update(readFileSync(file)).digest('hex');
+        if (actual !== expected)
+            throw new Error('NATIVE_INTEGRITY: Runtime pack file changed: ' + path);
+    }
+    for (const path of [...pack.libraries, platform.entry ? 'platform/start.o' : 'platform/libSystem.tbd'])
+        if (!pack.files[nativePath(path)])
+            throw new Error('LLVM_RUNTIME: Runtime manifest does not identify required file ' + path);
+    if (pack.staticCore !== undefined && (typeof pack.staticCore !== 'string' || !pack.staticCore.endsWith('.a') || !pack.files[nativePath(pack.staticCore)]))
+        throw new Error('LLVM_RUNTIME: Runtime manifest does not identify its core archive');
+    if (!pack.components || typeof pack.components !== 'object' || Array.isArray(pack.components))
+        throw new Error('LLVM_RUNTIME: Missing component contracts');
+    for (const [name, component] of Object.entries(pack.components)) {
+        if (!/^[a-z][a-z0-9-]*$/.test(name) || !component || !Array.isArray(component.libraries) || !component.libraries.length || !Array.isArray(component.runtimeFiles) || !Array.isArray(component.metadata))
+            throw new Error('LLVM_RUNTIME: Invalid component ' + name);
+        for (const path of [...component.libraries, ...component.runtimeFiles, ...component.metadata])
+            if (typeof path !== 'string' || !pack.files[nativePath(path)])
+                throw new Error('LLVM_RUNTIME: Missing component file ' + name + ' ' + path);
+    }
+    return pack;
+}
+/** Link target objects with prebuilt runtimes. Application builds never invoke Clang. */
+export function compileLLVM(checked, options = {}) {
+    const root = checked.project.root, target = nativeHostTarget();
+    const config = checked.project.config;
+    const release = options.release ?? config.optimization === 'release';
+    if (config.libraries.length || config.library_paths.length)
+        throw new Error('LLVM_LINK_INPUT: LLVM builds require native libraries to be declared by a locked August package. Remove main.yaml libraries/library_paths or use the C reference backend for this local toolchain build.');
+    const platform = llvmPlatform(target);
+    const compilerRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+    const tools = options.toolchain?.tools ?? process.env.AUG_LLVM_HOME, runtime = resolve(options.toolchain?.runtime ?? process.env.AUG_RUNTIME_PACK ?? join(compilerRoot, '.aug-native/llvm/runtime'));
+    if (!tools)
+        throw new Error('LLVM_TOOLS: Prepare the compiler-owned tool pack before invoking the LLVM compilation API. The CLI installs it automatically.');
+    const llc = join(tools, 'bin/llc'), lld = join(tools, 'bin/lld'), opt = join(tools, 'bin/opt'), dsymutil = join(tools, 'bin/dsymutil');
+    if (platform.tools.some(tool => !existsSync(join(tools, 'bin', tool))))
+        throw new Error('LLVM_TOOLS: The configured tool pack is missing ' + platform.tools.join(', '));
+    const pack = readRuntimePack(runtime), ir = lowerToIR(checked, { coverage: options.coverage }), module = generateLLVM(ir, { layout: pack.layout, release, triple: platform.triple });
+    const directory = resolve(options.bundle ?? join(root, '.aug-build', ...(options.testIndex === undefined ? [] : ['tests'])));
+    mkdirSync(join(directory, 'lib'), { recursive: true });
+    const name = options.testIndex === undefined ? 'program' : 'test-' + options.testIndex;
+    const source = join(directory, name + '.ll'), object = join(directory, name + '.o');
+    const outputName = options.testIndex === undefined ? options.output ?? config.output ?? basename(root) : name;
+    const output = resolve(directory, outputName);
+    const deployment = join(dirname(output), 'lib');
+    mkdirSync(deployment, { recursive: true });
+    writeFileSync(source, module);
+    writeFileSync(join(directory, name + '.aug-ir.json'), JSON.stringify(ir, null, 2) + '\n');
+    if (config.openapi.enabled && options.testIndex === undefined) {
+        const target = resolve(root, config.openapi.output);
+        mkdirSync(dirname(target), { recursive: true });
+        writeFileSync(target, JSON.stringify(generateOpenApi(checked).document, null, 2) + '\n');
+    }
+    const run = (tool, args) => { const result = spawnSync(tool, args, { encoding: 'utf8', cwd: root, env: { ...process.env, SDKROOT: '/nonexistent', DEVELOPER_DIR: '/nonexistent' } }); if (result.status !== 0)
+        throw new Error(`LLVM compilation failed with ${basename(tool)}.\n${result.stderr || result.error?.message || result.stdout}\nLLVM IR: ${source}`); return result; };
+    const optimized = join(directory, name + '.optimized.ll');
+    run(opt, ['-passes=verify', '-disable-output', source]);
+    if (release)
+        run(opt, ['-passes=default<O2>', '-S', source, '-o', optimized]);
+    run(llc, ['-filetype=obj', release ? '-O=2' : '-O=0', '-relocation-model=pic', release ? optimized : source, '-o', object]);
+    const libraries = [], deployed = new Map();
+    const deploy = (origin, path, link) => {
+        nativePath(path);
+        const destination = join(deployment, basename(path));
+        const digest = createHash('sha256').update(readFileSync(join(origin, path))).digest('hex');
+        if (deployed.has(destination) && deployed.get(destination) !== digest)
+            throw new Error('NATIVE_CONFLICT: Different runtime files have the same deployment name ' + basename(path));
+        deployed.set(destination, digest);
+        copyFileSync(join(origin, path), destination);
+        if (link)
+            libraries.push(destination);
+    };
+    const metadata = (origin, namespace, paths) => {
+        for (const path of paths) {
+            nativePath(path);
+            const destination = join(dirname(output), 'share', 'august-native', namespace, path);
+            mkdirSync(dirname(destination), { recursive: true });
+            copyFileSync(join(origin, path), destination);
+        }
+    };
+    const staticCore = !ir.components.length && pack.staticCore !== undefined;
+    if (staticCore)
+        libraries.push(join(runtime, pack.staticCore));
+    else
+        for (const library of pack.libraries)
+            deploy(runtime, library, true);
+    for (const name of ir.components) {
+        const component = pack.components[name];
+        if (!component)
+            throw new Error('LLVM_RUNTIME: Compiler pack is missing the ' + name + ' runtime component. Install a matching complete compiler pack.');
+        for (const path of component.libraries)
+            deploy(runtime, path, true);
+        for (const path of component.runtimeFiles)
+            deploy(runtime, path, false);
+        metadata(runtime, 'runtime-' + pack.sourceSha256, component.metadata);
+    }
+    metadata(runtime, 'runtime-' + pack.sourceSha256, [...Object.keys(pack.files).filter(path => path.startsWith('licenses/')), 'runtime.json']);
+    for (const input of options.native ?? []) {
+        for (const library of input.libraries)
+            deploy(input.directory, library, true);
+        for (const file of input.runtimeFiles)
+            if (!input.libraries.includes(file))
+                deploy(input.directory, file, false);
+        if (input.metadata?.length) {
+            if (!/^[0-9a-f]{64}$/.test(input.artifactSha256 ?? ''))
+                throw new Error('NATIVE_INTEGRITY: Deployment metadata requires an artifact identity');
+            metadata(input.directory, input.artifactSha256, input.metadata);
+        }
+    }
+    if (platform.entry) {
+        const libc = systemLibc(platform), math = join(dirname(libc), 'libm.so.6');
+        if (staticCore && !existsSync(math))
+            throw new Error('LLVM_RUNTIME: The qualified GNU/Linux math runtime is absent. Install the operating system libc runtime; no development headers or compiler are required.');
+        // Only the existing private checkpoint-hook boundary needs dynamic lookup.
+        // August function exports and native runtime entry remain separate profiles.
+        const coreExports = staticCore ? ['--gc-sections', '--export-dynamic-symbol=aug_execution_current', '--export-dynamic-symbol=aug_task_checkpoint_hook'] : [];
+        run(lld, ['-flavor', 'gnu', '-pie', '-z', 'now', '-z', 'noexecstack', '--hash-style=gnu', '--eh-frame-hdr', ...coreExports, '--dynamic-linker', platform.loader, '-e', '_start', '-rpath', '$ORIGIN/lib', join(runtime, 'platform/start.o'), object, ...libraries, libc, ...(staticCore ? [math] : []), '-o', output]);
+    }
+    else
+        run(lld, ['-flavor', 'darwin', ...(staticCore ? ['-dead_strip', '-exported_symbol', '_aug_execution_current', '-exported_symbol', '_aug_task_checkpoint_hook'] : []), '-arch', 'arm64', '-platform_version', 'macos', '14.0', '14.0', '-Z', '-fixup_chains', '-adhoc_codesign', '-e', '_main', '-rpath', '@executable_path/lib', object, ...libraries, join(runtime, 'platform/libSystem.tbd'), '-o', output]);
+    const debugInfo = platform.entry ? output : output + '.dSYM';
+    if (!platform.entry)
+        run(dsymutil, [output, '-o', debugInfo]);
+    const hash = (file) => createHash('sha256').update(readFileSync(file)).digest('hex');
+    writeFileSync(output + '.augmap.json', JSON.stringify({ format: 1, backend: 'llvm', version: compilerVersion(), llvm: '23.1.2', mode: release ? 'release' : 'development', target: pack.target, minimumOS: pack.minimumOS, minimumLibc: pack.minimumLibc, sourceRevision: ir.sourceRevision, llvmIR: source, llvmIRSha256: hash(source), optimizedIRSha256: release ? hash(optimized) : undefined, object, objectSha256: hash(object), executableSha256: hash(output), debugInfo, debugInfoSha256: hash(platform.entry ? output : join(debugInfo, 'Contents/Resources/DWARF', basename(output))), runtime: pack.sourceSha256, compilerArtifact: options.toolchain?.archiveSha256, developmentToolchain: options.toolchain?.developmentOverride ?? true, nativeArtifacts: options.native?.map(input => input.artifactSha256), libraries: [...deployed].map(([file, sha256]) => ({ file: basename(file), sha256 })), symbols: ir.functions.map(f => ({ name: f.name, sourceName: f.sourceName, location: f.span })) }, null, 2) + '\n');
+    return { output, status: 0, error: '', diagnostics: [] };
+}

package/src/llvm-platform.js

@@ -0,0 +1,20 @@
+import { existsSync } from 'node:fs';
+import { nativeHostTarget } from "./native-contracts.js";
+export const llvmPlatforms = [
+    { host: 'darwin-arm64', target: 'aarch64-apple-darwin', triple: 'arm64-apple-macosx14.0.0', artifact: 'macos-arm64', minimumOS: '14.0', tools: ['llc', 'opt', 'lld', 'dsymutil'] },
+    { host: 'linux-x64', target: 'x86_64-unknown-linux-gnu', triple: 'x86_64-unknown-linux-gnu', artifact: 'linux-x64', minimumLibc: '2.36', tools: ['llc', 'opt', 'lld'], entry: 'linux-x64/start.S', loader: '/lib64/ld-linux-x86-64.so.2', libc: ['/lib/x86_64-linux-gnu/libc.so.6', '/usr/lib/x86_64-linux-gnu/libc.so.6'] },
+    { host: 'linux-arm64', target: 'aarch64-unknown-linux-gnu', triple: 'aarch64-unknown-linux-gnu', artifact: 'linux-arm64', minimumLibc: '2.36', tools: ['llc', 'opt', 'lld'], entry: 'linux-arm64/start.S', loader: '/lib/ld-linux-aarch64.so.1', libc: ['/lib/aarch64-linux-gnu/libc.so.6', '/usr/lib/aarch64-linux-gnu/libc.so.6'] }
+];
+const atLeast = (actual, minimum) => !!actual && Number(actual.split('.')[0]) * 1000 + Number(actual.split('.')[1]) >= Number(minimum.split('.')[0]) * 1000 + Number(minimum.split('.')[1]);
+export function llvmPlatform(target = nativeHostTarget()) {
+    const platform = llvmPlatforms.find(platform => platform.target === target.triple && platform.host === process.platform + '-' + process.arch);
+    if (!platform || platform.minimumOS && !atLeast(target.minimumOS, platform.minimumOS) || platform.minimumLibc && !atLeast(target.minimumLibc, platform.minimumLibc))
+        throw new Error('NATIVE_TARGET: LLVM requires macOS 14+ ARM64 or GNU/Linux x86-64/ARM64 with glibc 2.36+. This host is ' + target.triple + ' (' + (target.minimumOS ?? target.minimumLibc ?? target.libc) + '). Cross compilation and musl are not supported.');
+    return platform;
+}
+export function systemLibc(platform) {
+    const libc = platform.libc?.find(path => existsSync(path));
+    if (!libc || !platform.loader || !existsSync(platform.loader))
+        throw new Error('LLVM_RUNTIME: The qualified GNU/Linux libc/loader is absent. Use a glibc 2.36+ Debian/Ubuntu runtime. No development headers or compiler are required.');
+    return libc;
+}