@greenpandastudios/aug-cli 0.19.0

package/src/config.js

@@ -0,0 +1,149 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+export const lintRules = ['wildcard_imports', 'public_helpers', 'public_docs', 'broad_errors', 'discarded_errors', 'architecture'];
+export function loadConfig(root) {
+    const config = { optimization: 'debug', libraries: [], library_paths: [], assignment: 'equals', block_style: 'braces',
+        indentation: 'spaces', lint: [], strict_modules: false, max_public_symbols: 12, max_dependencies: 8, module_dependencies: [], packages: {}, spec: { require_comments: 'none' },
+        web: { host: '127.0.0.1', body_limit: 1048576, response_limit: 4194304, tls: { certificate: '', private_key: '', ca: '' }, http3: false },
+        openapi: { enabled: false, title: 'August API', version: '0.1.0', path: '/openapi.json', docs: '/docs', output: '.aug-build/openapi.json' } };
+    const file = join(root, 'main.yaml');
+    const diagnostics = [];
+    if (!existsSync(file))
+        return { config, diagnostics };
+    const report = (line, message) => diagnostics.push({ file, line, column: 1, code: 'CONFIG', message });
+    const seen = new Set();
+    const sections = [];
+    let list;
+    for (const [index, raw] of readFileSync(file, 'utf8').split(/\r?\n/).entries()) {
+        const line = raw.replace(/\s+#.*$/, '').trim();
+        if (!line || line.startsWith('#'))
+            continue;
+        const item = /^-\s+(.+)$/.exec(line);
+        if (item && list) {
+            const value = item[1].replace(/^(['"])(.*)\1$/, '$2');
+            if (list === 'lint' && !lintRules.includes(value))
+                report(index + 1, `Unknown lint rule ${value}`);
+            else if (list === 'module_dependencies' && !/^[\w./*-]+\s*:\s*[\w./*, -]*$/.test(value))
+                report(index + 1, 'Use module_dependencies entries such as "domain: shared, contracts"');
+            else if (list === 'libraries' && !/^[A-Za-z0-9_.+-]+$/.test(value))
+                report(index + 1, 'Library names contain only letters, numbers, _, ., + and -');
+            else
+                config[list].push(value);
+            continue;
+        }
+        list = undefined;
+        const entry = /^([a-z_][a-z_0-9]*):(?:\s*(.*))?$/.exec(line);
+        const indentation = raw.length - raw.trimStart().length;
+        while (sections.length && sections.at(-1).indentation >= indentation)
+            sections.pop();
+        const path = [...sections.map(section => section.name), entry?.[1]].join('.');
+        if (entry && (path === 'web' || path === 'openapi' || path === 'web.tls' || path === 'packages' || path === 'spec')) {
+            if (entry[2])
+                report(index + 1, `${path} must be a configuration block`);
+            if (seen.has(path))
+                report(index + 1, `Duplicate configuration key ${path}`);
+            seen.add(path);
+            sections.push({ name: entry[1], indentation });
+            continue;
+        }
+        if (entry && sections.length) {
+            const value = (entry[2] ?? '').replace(/^(['"])(.*)\1$/, '$2');
+            if (seen.has(path)) {
+                report(index + 1, `Duplicate configuration key ${path}`);
+                continue;
+            }
+            seen.add(path);
+            if (path.startsWith('packages.')) {
+                if (!/^[a-z][a-z0-9_]*$/.test(entry[1]) || entry[1] === 'august' || !value)
+                    report(index + 1, 'Packages map lowercase public aliases to local paths or npm:name@exact-version');
+                else
+                    config.packages[entry[1]] = value;
+                continue;
+            }
+            if (path === 'spec.require_comments') {
+                if (!['none', 'public', 'all'].includes(value))
+                    report(index + 1, 'spec.require_comments must be none, public, or all');
+                else
+                    config.spec.require_comments = value;
+                continue;
+            }
+            const known = ['web.host', 'web.body_limit', 'web.response_limit', 'web.http3', 'web.tls.certificate', 'web.tls.private_key', 'web.tls.ca',
+                'openapi.enabled', 'openapi.title', 'openapi.version', 'openapi.path', 'openapi.docs', 'openapi.output'];
+            if (!known.includes(path)) {
+                report(index + 1, `Unknown configuration key ${path}`);
+                continue;
+            }
+            if (path === 'web.http3' || path === 'openapi.enabled') {
+                if (!['true', 'false'].includes(value))
+                    report(index + 1, `${path} must be true or false`);
+                else if (path === 'web.http3')
+                    config.web.http3 = value === 'true';
+                else
+                    config.openapi.enabled = value === 'true';
+            }
+            else if (path === 'web.body_limit' || path === 'web.response_limit') {
+                if (!/^[1-9]\d*$/.test(value) || Number(value) > 67108864)
+                    report(index + 1, `${path} must be from 1 to 67108864 bytes`);
+                else
+                    config.web[path.endsWith('body_limit') ? 'body_limit' : 'response_limit'] = Number(value);
+            }
+            else {
+                if (!value || /[\x00-\x1f]/.test(value) || ['openapi.path', 'openapi.docs'].includes(path) && (!value.startsWith('/') || /[?#]/.test(value))) {
+                    report(index + 1, `${path} needs a valid nonempty value`);
+                    continue;
+                }
+                if (path.startsWith('web.tls.'))
+                    Object.assign(config.web.tls, { [entry[1]]: value });
+                else if (path === 'web.host')
+                    config.web.host = value;
+                else
+                    Object.assign(config.openapi, { [entry[1]]: value });
+            }
+            continue;
+        }
+        if (!entry || !(entry[1] in config || entry[1] === 'output')) {
+            report(index + 1, `Unsupported configuration line ${JSON.stringify(raw)}`);
+            continue;
+        }
+        const key = entry[1];
+        const value = (entry[2] ?? '').replace(/^(['"])(.*)\1$/, '$2');
+        if (seen.has(key)) {
+            report(index + 1, `Duplicate configuration key ${key}`);
+            continue;
+        }
+        seen.add(key);
+        if (['libraries', 'library_paths', 'lint', 'module_dependencies'].includes(key)) {
+            if (value)
+                report(index + 1, `${key} must be a YAML list`);
+            else
+                list = key;
+        }
+        else if (key === 'strict_modules') {
+            if (!['true', 'false'].includes(value))
+                report(index + 1, 'strict_modules must be true or false');
+            else
+                config.strict_modules = value === 'true';
+        }
+        else if (key === 'max_dependencies' || key === 'max_public_symbols') {
+            if (!/^[1-9]\d*$/.test(value))
+                report(index + 1, `${key} must be a positive integer`);
+            else
+                config[key] = Number(value);
+        }
+        else {
+            const choices = { optimization: ['debug', 'release'], assignment: ['equals', 'to'],
+                block_style: ['braces', 'indent'], indentation: ['spaces', 'tabs'] };
+            if (!value || choices[key] && !choices[key].includes(value))
+                report(index + 1, `${key} needs ${choices[key]?.join(' or ') ?? 'a value'}`);
+            else
+                Object.assign(config, { [key]: value });
+        }
+    }
+    if (!!config.web.tls.certificate !== !!config.web.tls.private_key)
+        report(1, 'TLS requires both certificate and private_key');
+    if (config.web.http3 && !config.web.tls.certificate)
+        report(1, 'HTTP/3 requires a TLS certificate and private_key');
+    if (config.openapi.path === config.openapi.docs)
+        report(1, 'OpenAPI path and docs must be distinct');
+    return { config, diagnostics };
+}

package/src/continuation.js

@@ -0,0 +1,110 @@
+const add = (left, right) => Math.min(2, left + right);
+const maximum = (...values) => {
+    const present = values.filter((value) => value !== undefined);
+    return present.length ? Math.max(...present) : undefined;
+};
+function calls(expr) {
+    if (expr.kind === 'handle' && expr.call.kind === 'call')
+        return Math.min(2, expr.call.args.reduce((sum, arg) => sum + calls(arg), 0));
+    if (expr.kind === 'markup')
+        return Math.min(2, [...expr.attributes.map(attribute => attribute.value), ...expr.children].reduce((sum, child) => sum + calls(child), 0));
+    if (expr.kind === 'start')
+        return calls(expr.call);
+    if (expr.kind === 'wait')
+        return Math.min(2, expr.tasks.reduce((sum, task) => sum + calls(task), 0));
+    if (expr.kind === 'collection')
+        return Math.min(2, expr.items.reduce((count, item) => count + calls(item), 0));
+    if (expr.kind === 'call')
+        return Math.min(2, (expr.callee.kind === 'name' && expr.callee.name === 'next' ? 1 : calls(expr.callee)) +
+            expr.args.reduce((count, arg) => count + calls(arg), 0));
+    if (expr.kind === 'member')
+        return calls(expr.object);
+    if (expr.kind === 'binary') {
+        if (expr.left.kind === 'literal' && ((expr.op === '&&' && expr.left.value === false) ||
+            (expr.op === '||' && expr.left.value === true)))
+            return calls(expr.left);
+        return add(calls(expr.left), calls(expr.right));
+    }
+    if (expr.kind === 'unary')
+        return calls(expr.value);
+    return 0;
+}
+function block(body, initial = 0) {
+    let flow = { normal: initial, exited: 0, thrown: undefined };
+    for (const stmt of body) {
+        if (flow.normal === undefined)
+            break;
+        const inside = statement(stmt, flow.normal);
+        flow = { normal: inside.normal, exited: Math.max(flow.exited, inside.exited),
+            thrown: maximum(flow.thrown, inside.thrown) };
+    }
+    return flow;
+}
+function statement(stmt, initial) {
+    if (stmt.kind === 'serve')
+        return { normal: add(initial, calls(stmt.port)), exited: 0, thrown: initial };
+    if (stmt.kind === 'unsafe' || stmt.kind === 'borrow' || stmt.kind === 'scope' || stmt.kind === 'lock')
+        return block(stmt.body, initial);
+    if (stmt.kind === 'for') {
+        const count = add(initial, calls(stmt.iterable));
+        const body = block(stmt.body, count);
+        const repeated = body.normal !== undefined && body.normal > count;
+        return { normal: maximum(count, repeated ? 2 : body.normal), exited: body.exited,
+            thrown: maximum(count, body.thrown, repeated ? 2 : undefined) };
+    }
+    if (stmt.kind === 'match') {
+        const count = add(initial, calls(stmt.value));
+        const cases = stmt.cases.map(clause => block(clause.body, count));
+        return { normal: maximum(...cases.map(flow => flow.normal)), exited: Math.max(0, ...cases.map(flow => flow.exited)),
+            thrown: maximum(count, ...cases.map(flow => flow.thrown)) };
+    }
+    if (stmt.kind === 'if') {
+        const count = add(initial, calls(stmt.test));
+        if (stmt.test.kind === 'literal' && typeof stmt.test.value === 'boolean')
+            return block(stmt.test.value ? stmt.then : stmt.otherwise, count);
+        const left = block(stmt.then, count);
+        const right = block(stmt.otherwise, count);
+        return { normal: maximum(left.normal, right.normal), exited: Math.max(left.exited, right.exited),
+            thrown: maximum(count, left.thrown, right.thrown) };
+    }
+    if (stmt.kind === 'while') {
+        const test = calls(stmt.test);
+        const count = add(initial, test);
+        if (stmt.test.kind === 'literal' && stmt.test.value === false)
+            return { normal: count, exited: 0, thrown: undefined };
+        const body = block(stmt.body, count);
+        // A fallthrough edge feeds the condition again. If either the condition or
+        // body invokes next, an arbitrary second iteration can repeat the call.
+        const repeated = body.normal !== undefined && (test > 0 || body.normal > initial);
+        return { normal: stmt.test.kind === 'literal' && stmt.test.value === true ? undefined : maximum(count, repeated ? 2 : body.normal),
+            exited: body.exited, thrown: maximum(count, body.thrown, repeated ? 2 : undefined) };
+    }
+    if (stmt.kind === 'try') {
+        const inside = block(stmt.body, initial);
+        const catches = inside.thrown === undefined ? [] :
+            stmt.catches.map(clause => block(clause.body, inside.thrown));
+        const flow = { normal: maximum(inside.normal, ...catches.map(flow => flow.normal)),
+            exited: Math.max(inside.exited, ...catches.map(flow => flow.exited)),
+            thrown: maximum(inside.thrown, ...catches.map(flow => flow.thrown)) };
+        if (!stmt.always)
+            return flow;
+        const normal = flow.normal === undefined ? undefined : block(stmt.always, flow.normal);
+        const exited = block(stmt.always, flow.exited);
+        const thrown = flow.thrown === undefined ? undefined : block(stmt.always, flow.thrown);
+        return { normal: normal?.normal, exited: Math.max(normal?.exited ?? 0, exited.normal ?? 0, exited.exited),
+            thrown: maximum(normal?.thrown, exited.thrown, thrown?.normal, thrown?.thrown) };
+    }
+    const count = add(initial, stmt.kind === 'assign' ? add(calls(stmt.value), calls(stmt.target)) :
+        stmt.kind === 'return' ? stmt.value ? calls(stmt.value) : 0 :
+            calls(stmt.kind === 'expr' ? stmt.expr : stmt.value));
+    return { normal: stmt.kind === 'return' || stmt.kind === 'throw' ? undefined : count,
+        exited: stmt.kind === 'return' ? count : 0,
+        // Calls can fail after next has run. Catch paths therefore inherit the
+        // consumed continuation, including failures during a return expression.
+        thrown: count };
+}
+export function canRepeatNext(body) {
+    const flow = block(body);
+    return maximum(flow.normal, flow.exited, flow.thrown) === 2;
+}
+export function canFallThrough(body) { return block(body).normal !== undefined; }

package/src/di.js

@@ -0,0 +1,24 @@
+/** The same bounded graph traversal serves composition and module checking. */
+export function orderGraph(nodes, cycle) {
+    const byKey = new Map(nodes.map(node => [node.key, node]));
+    const state = new Map();
+    const ordered = [];
+    const visit = (node, path) => {
+        if (state.get(node.key) === 2)
+            return;
+        if (state.get(node.key) === 1) {
+            cycle(node, [...path.slice(path.indexOf(node.key)), node.key]);
+            return;
+        }
+        state.set(node.key, 1);
+        for (const key of node.dependencies) {
+            const dependency = byKey.get(key);
+            if (dependency)
+                visit(dependency, [...path, node.key]);
+        }
+        state.set(node.key, 2);
+        ordered.push(node);
+    };
+    nodes.forEach(node => visit(node, []));
+    return ordered;
+}

package/src/documentation.js

@@ -0,0 +1,27 @@
+import { javadocBefore } from "./javadoc.js";
+/** One documentation resolution path for checking, editor help, and context. */
+export function callableDocumentation(project, method, owner) {
+    const read = (method) => javadocBefore(project.files.get(method.span.file)?.source ?? '', method.annotations?.[0]?.span.start ?? method.span.start);
+    const direct = read(method);
+    if (direct && !direct.markdown.includes('{@inheritDoc}'))
+        return direct;
+    const seen = new Set();
+    const inherited = (file, refs) => {
+        for (const ref of refs) {
+            const def = project.scopes.get(file)?.get(ref.name);
+            if (!def || def.node.kind !== 'interface' || seen.has(def.id))
+                continue;
+            seen.add(def.id);
+            const target = def.node.methods.find(target => target.name === method.name);
+            const doc = target && read(target) || inherited(def.file, def.node.extends);
+            if (doc)
+                return doc;
+        }
+    };
+    const doc = owner && inherited(owner.file, owner.node.kind === 'class' ? owner.node.implements :
+        owner.node.kind === 'interface' ? owner.node.extends : []);
+    if (!direct)
+        return doc || undefined;
+    return doc ? { ...direct, markdown: direct.markdown.replaceAll('{@inheritDoc}', doc.markdown),
+        parameters: new Map([...doc.parameters, ...direct.parameters]) } : direct;
+}