@greenpandastudios/aug-cli 0.19.0 → 0.21.0

package/src/editor.js

@@ -1,3 +1,4 @@
+import { callableResult, callableErrors } from "./contracts.js";
 import { dirname, join, relative, resolve, sep } from 'node:path';
 import { fieldsOf, typeName } from "./ast.js";
 import { tyName } from "./checker.js";
@@ -12,6 +13,10 @@ import { interceptorBehavior } from "./interceptors.js";
 import { httpPolicyNames, httpPolicyOptions, httpPolicyOptionHelp } from "./http-policies.js";
 import { builtinTypes } from "./builtins.js";
 import { libraryChild, libraryRelative } from "./libraries.js";
+import { importSource, isGitSource, sourceAlias } from "./git-packages.js";
+import { snippetBody, snippetCatalog } from "./snippets.js";
+import { nativeFact, nativeDependencies, nativeDescription } from "./native-facts.js";
+import { pathToFileURL } from 'node:url';
 const builtins = [
     ...builtinFunctions.map(operation => {
         const parameters = operation.parameters.map(param => `${param.label}=${param.type}`);
@@ -24,6 +29,8 @@ const builtins = [
         .map(([label, help]) => ({ label, kind: 'type', detail: help.detail, documentation: help.documentation })),
 ];
 const keywords = [
+    ...snippetCatalog.map(snippet => ({ label: snippet.prefix + ' template', kind: 'snippet', detail: snippet.description,
+        documentation: snippet.description, insertText: snippet.body })),
     { label: 'initialize block', kind: 'snippet', detail: 'Constructor initialization inside a class or record', documentation: languageHelp.initialize.documentation,
         insertText: 'initialize:\n    $0' },
     ...Object.entries(languageHelp).filter(([label, help]) => help.category === 'keyword' &&
@@ -38,7 +45,7 @@ const keywords = [
         insertText: 'borrow ${1:value} {\n    $0\n}' },
     { label: 'interceptor declaration', kind: 'snippet', detail: 'Generic interceptor wrapping any result type',
         documentation: languageHelp.interceptor.documentation,
-        insertText: 'interceptor ${1:Audit}<T>() {\n    around() returns T {\n        T result to next()\n        $0\n        return result\n    }\n}' },
+        insertText: 'interceptor ${1:Audit}<T>() {\n    around() {\n        result = next()\n        $0\n        return result\n    }\n}' },
     { label: 'test suite', kind: 'snippet', detail: 'Same-file class tests with fresh setup per case',
         documentation: languageHelp.test.documentation,
         insertText: 'test ${1:Worker} ${2:worker} {\n    when ${3:ready} {\n        ${2:worker} = ${1:Worker}()\n        it ${4:works} {\n            assert(${5:true})\n        }\n    }\n}' },
@@ -59,15 +66,18 @@ function parameterText(param) {
         `${typeName(param.type)} ${param.label ?? param.name}${param.label && param.label !== param.name ? ` to ${param.name}` : ''}` +
         (param.source ? ` from ${param.source.kind}${param.source.name ? ' ' + JSON.stringify(param.source.name) : ''}` : '');
 }
-function signature(method, callSite = false, additionalErrors = []) {
+function signature(method, callSite = false, additionalErrors = [], checked) {
     const generic = method.typeParams.length ? `<${method.typeParams.join(', ')}>` : '';
     const params = callSite ? method.params.filter(param => !param.injected)
         .map(param => `${param.label ?? param.name}=${typeName(param.type)}`) : method.params.map(parameterText);
-    const errors = [...new Set([...method.throws.map(typeName), ...additionalErrors])];
+    const errors = checked ? callableErrors(checked, method) : [...new Set([...method.throws.map(typeName), ...additionalErrors])];
+    const contract = checked?.effectContracts.get(method);
+    const changes = contract?.changes ?? method.changes ?? [];
+    const uses = [...(contract?.uses.values() ?? method.uses ?? [])].map(use => `${use.source}.${use.operation}`);
     return (method.endpoint ? `endpoint ${method.endpoint.method} ${JSON.stringify(method.endpoint.path)} as ` : '') + `${method.name}${generic}(${params.join(', ')}) ${method.endpoint?.streams ? 'streams' : 'returns'} ` +
-        `${method.returnOwnership === 'own' ? 'own ' : ''}${typeName(method.returns)}` +
-        (method.changes?.length ? ` changes ${method.changes.join(' and ')}` : '') +
-        (method.uses?.length ? ` uses ${method.uses.map(use => `${use.source}.${use.operation}`).join(' and ')}` : '') +
+        `${method.returnOwnership === 'own' ? 'own ' : ''}${checked ? tyName(callableResult(checked, method)) : typeName(method.returns)}` +
+        (changes.length ? ` changes ${changes.join(' and ')}` : '') +
+        (uses.length ? ` uses ${uses.join(' and ')}` : '') +
         (errors.length ? ` unless ${errors.join(', ')}` : '') +
         (method.endpoint && method.endpoint.status !== 200 ? ` with status ${method.endpoint.status}` : '');
 }
@@ -117,16 +127,17 @@ function methodDocumentation(checked, method, owner) {
 }
 function methodItem(checked, method, kind, owner) {
     const errors = (checked.interceptorPlans.get(method) ?? []).flatMap(layer => layer.errors.map(tyName));
-    const label = signature(method, false, errors);
+    const label = signature(method, false, errors, checked);
     const injected = method.params.filter(param => param.injected);
     const doc = methodDocumentation(checked, method, owner);
     const injectionHelp = injected.length ? `Injected from bindings: ${injected.map(parameterText).join(', ')}.` : '';
     const contract = checked.effectContracts.get(method);
     const effects = contract ? `${contract.inferred ? 'Inferred capabilities; effective' : 'Effective'} contract: changes ${contract.changes.join(', ') || 'nothing'}; capabilities ` +
         `${[...contract.uses.values()].map(effect => `${effect.source}.${effect.operation}`).join(', ') || 'none'}.` : '';
-    return { label: method.name, kind, detail: label, signature: signature(method, true, errors),
+    const native = nativeDependencies(checked, method).map(fact => nativeDescription(fact, '[`native.abi.json`](' + pathToFileURL(checked.native.providerDescriptors.get(fact.provider)).href + ')')).join('\n\n');
+    return { label: method.name, kind, detail: label, signature: signature(method, true, errors, checked),
         documentation: [doc?.markdown, isPrivateName(method.name) ? 'Private to its declaring type.' : '',
-            injectionHelp, effects, interceptorDescription(checked, method), 'Call arguments require labels; their order does not matter.']
+            injectionHelp, effects, native, interceptorDescription(checked, method), 'Call arguments require labels; their order does not matter.']
             .filter(Boolean).join('\n\n'),
         parameters: method.params.filter(param => !param.injected)
             .map(param => `${param.label ?? param.name}=${typeName(param.type)}`),
@@ -135,6 +146,11 @@ function methodItem(checked, method, kind, owner) {
 }
 function definitionItem(checked, def) {
     const node = def.node;
+    if (node.kind === 'resource') {
+        const native = nativeFact(checked, node);
+        return { label: def.name, kind: 'type', detail: 'extern C resource ' + def.name,
+            documentation: native ? nativeDescription(native, '[`native.abi.json`](' + pathToFileURL(checked.native.providerDescriptors.get(native.provider)).href + ')') : 'Opaque native resource. Its package must declare a release identity.' };
+    }
     if (node.kind === 'function')
         return methodItem(checked, node, 'function');
     if (node.kind === 'interface')
@@ -147,7 +163,7 @@ function definitionItem(checked, def) {
         const doc = around && methodDocumentation(checked, around, def);
         return { label: def.name, kind: 'interceptor',
             detail: `interceptor ${node.name}${node.typeParams.length ? `<${node.typeParams.join(', ')}>` : ''}` +
-                `(${node.fields.map(parameterText).join(', ')})` + (around ? `\n${signature(around)}` : ''),
+                `(${node.fields.map(parameterText).join(', ')})` + (around ? `\n${signature(around, false, [], checked)}` : ''),
             signature: `${node.name}(${params.map(param => `${param.name}=targetLabel`).join(', ')})`,
             parameters: params.map(param => `${param.name}=targetLabel`),
             parameterDocumentation: params.map(param => [doc?.parameters.get(param.name),
@@ -167,10 +183,11 @@ function definitionItem(checked, def) {
     const explicit = node.fields.filter(field => !field.injected);
     const callSignature = `${def.name}${node.typeParams.length ? `<${node.typeParams.join(', ')}>` : ''}` +
         `(${explicit.map(field => `${field.label ?? field.name}=${typeName(field.type)}`).join(', ')})`;
-    const errors = [...new Set((checked.interceptorPlans.get(node) ?? []).flatMap(layer => layer.errors.map(tyName)))];
+    const errors = [...new Set([...(checked.constructorContracts.get(node)?.errors.map(tyName) ?? node.validationErrors?.map(typeName) ?? []),
+            ...(checked.interceptorPlans.get(node) ?? []).flatMap(layer => layer.errors.map(tyName))])];
     return { label: def.name, kind: 'class', detail: `${node.record ? 'record ' : ''}${label}` +
-            (node.implements.length ? ` implements ${node.implements.map(typeName).join(' and ')}` : '') +
-            (errors.length ? ` unless ${errors.join(', ')}` : ''),
+            (errors.length ? ` unless ${errors.join(' and ')}` : '') +
+            (node.implements.length ? ` implements ${node.implements.map(typeName).join(', ')}` : ''),
         signature: callSignature + (errors.length ? ` unless ${errors.join(', ')}` : ''), parameters: explicit.map(field => `${field.label ?? field.name}=${typeName(field.type)}`),
         documentation: [doc?.markdown,
             node.fields.some(field => field.injected) ? `Injected from bindings: ${node.fields.filter(field => field.injected).map(parameterText).join(', ')}.` : '',
@@ -181,7 +198,7 @@ function definitionItem(checked, def) {
 function typeFromRef(checked, file, ref) {
     const def = checked.project.scopes.get(file)?.get(ref.name);
     return { id: def?.id ?? `builtin:${ref.name}`, name: ref.name,
-        kind: def?.node.kind === 'class' || def?.node.kind === 'interface' || def?.node.kind === 'interceptor' ? def.node.kind : 'builtin',
+        kind: def?.node.kind === 'class' || def?.node.kind === 'interface' || def?.node.kind === 'interceptor' || def?.node.kind === 'resource' ? def.node.kind : 'builtin',
         args: ref.args.map(arg => typeFromRef(checked, file, arg)), nullable: ref.nullable, def };
 }
 function collectLocals(checked, file, offset) {
@@ -292,7 +309,9 @@ export function importItems(checked, file) {
             if (isPrivateName(item.name))
                 continue;
             items.push({ label: item.name, kind: 'snippet',
-                detail: `import ${item.name} from ${from}`, insertText: `${item.name} from ${from};`,
+                detail: `import ${item.name} from ${from}`, insertText: `${item.name} from ${from}`,
+                signature: definitionItem(checked, project.scopes.get(sibling.path).get(item.name)).signature,
+                parameters: definitionItem(checked, project.scopes.get(sibling.path).get(item.name)).parameters,
                 documentation: item.kind === 'interface' ? documentation(checked, sibling.path, item.span.start)?.markdown :
                     declarationDocumentation(checked, item)?.markdown });
         }
@@ -335,7 +354,8 @@ export function importItems(checked, file) {
             continue;
         for (const prefix of prefixes)
             for (const item of exportFile.items) {
-                const from = [...prefix, ...segments].join('.');
+                const specification = (owner?.specifications ?? project.packages.specifications)[prefix[0]];
+                const from = isGitSource(specification ?? '') && prefix[0] === sourceAlias(specification) ? importSource([specification, ...segments]) : [...prefix, ...segments].join('.');
                 if (!from)
                     continue;
                 if (item.kind !== 'export' || item.folder)
@@ -344,13 +364,15 @@ export function importItems(checked, file) {
                     continue;
                 const exported = project.scopes.get(join(folder, `${item.from}.aug`))?.get(item.name);
                 items.push({ label: item.name, kind: 'snippet',
-                    detail: `import ${item.name} from ${from}`, insertText: `${item.name} from ${from};`,
+                    detail: `import ${item.name} from ${from}`, insertText: `${item.name} from ${from}`,
+                    signature: exported && definitionItem(checked, exported).signature,
+                    parameters: exported && definitionItem(checked, exported).parameters,
                     documentation: exported && definitionItem(checked, exported).documentation });
             }
     }
     return items;
 }
-export function completions(checked, fileName, offset) {
+function rawCompletions(checked, fileName, offset) {
     const file = checked.project.files.get(resolve(fileName));
     if (!file)
         return [];
@@ -364,12 +386,13 @@ export function completions(checked, fileName, offset) {
         const used = new Set(joined[1].split(/\s+and\s+/));
         return unique(imports.filter(item => !used.has(item.label)).map(item => ({ ...item, kind: 'snippet', insertText: item.label })));
     }
-    const from = /^\s*import\s+(.+?)\s+from\s+[A-Za-z_0-9.]*$/.exec(line);
+    const from = /^\s*import\s+(.+?)\s+from\s+([A-Za-z_0-9.]*|"[^"\n]*"?(?:\.[A-Za-z_0-9.]*)?)$/.exec(line);
     if (from)
         return unique(imports.filter(item => from[1] === 'everything' || item.label === from[1].split(/\s+and\s+/)[0]).map(item => {
             const path = item.detail.slice(item.detail.lastIndexOf(' from ') + 6);
             return { label: path, kind: 'snippet', detail: item.detail,
-                insertText: `${path};`, documentation: item.documentation };
+                insertText: path, documentation: item.documentation,
+                replacement: { start: offset - from[2].length, end: offset } };
         }));
     const annotation = /(?<=^|\n)[ \t]*\[\s*([A-Za-z_][A-Za-z0-9_]*|)(?:<[^\[\]()]*>)?(?:\(([^\n()]*))?$/.exec(prefix);
     if (annotation) {
@@ -463,7 +486,48 @@ export function completions(checked, fileName, offset) {
         return all.filter(item => item.kind === 'interface');
     if (/\b(?:returns|unless|catch)\s+[A-Za-z_0-9]*$/.test(prefix))
         return all.filter(item => ['class', 'interface', 'type'].includes(item.kind));
-    return all;
+    const visible = new Set(all.map(item => item.label));
+    const importsEnd = file.items.filter(item => item.kind === 'import').at(-1)?.span.end ?? 0;
+    const insertion = importsEnd ? file.source.indexOf('\n', importsEnd) : 0;
+    return [...all, ...imports.filter(item => !visible.has(item.label)).map(item => ({ ...item,
+            kind: item.signature ? 'function' : 'type',
+            insertText: item.label, sortText: '2-' + item.label,
+            additionalEdits: [{ start: insertion < 0 ? file.source.length : insertion, end: insertion < 0 ? file.source.length : insertion,
+                    text: `${importsEnd ? '\n' : ''}${item.detail}${importsEnd ? '' : '\n'}` }] }))];
+}
+/** Fill labeled calls, keep dependency imports visible, and replace only the token being completed. */
+export function completions(checked, fileName, offset) {
+    const file = checked.project.files.get(resolve(fileName));
+    if (!file)
+        return [];
+    const prefix = file.source.slice(0, offset), line = prefix.slice(prefix.lastIndexOf('\n') + 1);
+    const typeContext = /\b(?:import|export|implement|implements|extends|returns|unless|catch|resolve)\b[^\n]*$/.test(line);
+    const token = /[A-Za-z_][A-Za-z0-9_]*$/.exec(prefix);
+    const start = token ? offset - token[0].length : offset;
+    const end = offset + (/^[A-Za-z0-9_]*/.exec(file.source.slice(offset))?.[0].length ?? 0);
+    const escape = (text) => text.replace(/[\\$}]/g, '\\$&');
+    const argument = (parameter, index) => {
+        const [name, type] = parameter.split('=');
+        const value = type === 'string' ? '""' : type === 'bool' ? 'false' : ['int', 'float', 'c_int'].includes(type) ? '0' : name;
+        return `${name}=\${${index + 1}:${escape(value)}}`;
+    };
+    return rawCompletions(checked, fileName, offset).map(item => {
+        const callable = !typeContext && ['function', 'method', 'class'].includes(item.kind) && item.signature &&
+            !/^\s*\(/.test(file.source.slice(offset));
+        let insertText = callable ? `${item.label}(${(item.parameters ?? []).map(argument).join(', ')})$0` : item.insertText;
+        const template = snippetCatalog.find(snippet => item.label === snippet.prefix + ' template');
+        if (template)
+            insertText = snippetBody(template.body, checked.project.config.block_style, checked.project.config.indentation === 'tabs');
+        if (item.kind === 'snippet' && insertText && checked.project.config.block_style === 'indent' && insertText.includes('{\n'))
+            insertText = insertText.replace(/^(\s*)\} catch /gm, '$1catch ').replace(/ \{\n/g, ':\n').replace(/^[ \t]*\}\n?/gm, '').trimEnd();
+        let additionalEdits = item.additionalEdits;
+        if (additionalEdits?.some(edit => edit.start >= start && edit.start <= end)) {
+            insertText = additionalEdits.map(edit => escape(edit.text)).join('') + (insertText ?? item.label);
+            additionalEdits = undefined;
+        }
+        return { ...item, insertText, additionalEdits, replacement: item.replacement ?? { start, end },
+            sortText: item.sortText ?? (['variable', 'parameter', 'property'].includes(item.kind) ? '0-' : '1-') + item.label };
+    });
 }
 /** Resolve exactly the token under the cursor, including syntax outside completion contexts. */
 export function hoverInfo(checked, fileName, offset) {
@@ -771,7 +835,7 @@ export function semanticTokens(checked, fileName) {
         else {
             const def = scope?.get(token.value);
             if (def)
-                type = def.node.kind === 'interceptor' ? 'decorator' : def.node.kind === 'composition' ? 'function' : def.node.kind;
+                type = def.node.kind === 'resource' ? 'type' : def.node.kind === 'interceptor' ? 'decorator' : def.node.kind === 'composition' ? 'function' : def.node.kind;
         }
         if (type)
             result.push({ line: token.span.line - 1, start: token.span.column - 1,

package/src/fixes.js

@@ -1,5 +1,7 @@
 import { resolve } from 'node:path';
-import { importItems } from "./editor.js";
+import { typeName } from "./ast.js";
+import { completions, hoverInfo, importItems } from "./editor.js";
+import { importSource } from "./git-packages.js";
 import { languageHelp } from "./help.js";
 import { lex } from "./lexer.js";
 import { tyName } from "./types.js";
@@ -74,6 +76,24 @@ function containingStatement(file, offset) {
     }
     return result.at(-1);
 }
+function callsIn(file) {
+    const result = [];
+    const visit = (value) => {
+        if (!value || typeof value !== 'object')
+            return;
+        if (Array.isArray(value)) {
+            value.forEach(visit);
+            return;
+        }
+        if ('kind' in value && value.kind === 'call')
+            result.push(value);
+        for (const [key, child] of Object.entries(value))
+            if (key !== 'span')
+                visit(child);
+    };
+    visit(file.items);
+    return result;
+}
 function wrappedStatement(file, issue, opener, closer = '}') {
     const stmt = containingStatement(file, offsetAt(file.source, issue.line, issue.column));
     // A declaration moved into a new block would become invisible afterward.
@@ -108,7 +128,7 @@ export function suggestedFixes(checked, fileName) {
             if (names.length)
                 fixes.push({ title: 'Expand to named imports', issue: { code: 'IMPORT', line: item.span.line, column: item.span.column,
                         message: 'Make imported dependencies explicit' }, edits: [{ file: file.path, start: item.span.start, end: item.span.end,
-                            text: `import ${names.join(' and ')} from ${item.from.join('.')}` }] });
+                            text: `import ${names.join(' and ')} from ${importSource(item.from)}` }] });
         }
     for (const issue of checked.diagnostics.filter(issue => issue.file === file.path)) {
         const add = (title, edit) => {
@@ -118,6 +138,43 @@ export function suggestedFixes(checked, fileName) {
         const unknown = /^(?:Unknown name|Unknown type|Unknown interceptor) ([A-Za-z_][A-Za-z0-9_]*)$/.exec(issue.message);
         const mistyped = /^Expected ([A-Za-z_]+), found "([A-Za-z_]+)"$/.exec(issue.message);
         const redundant = /^Remove (class|function|fuction); declarations start with their name$/.exec(issue.message);
+        const missing = /^([A-Za-z_][A-Za-z0-9_]*) must implement ([A-Za-z_][A-Za-z0-9_]*)$/.exec(issue.message);
+        if (issue.code === 'INTERFACE' && missing) {
+            const owner = file.items.find(item => item.kind === 'class' && item.name === missing[1]);
+            if (owner?.kind === 'class') {
+                const seen = new Set();
+                const substitute = (ref, types) => types.get(ref.name) ?? { ...ref, args: ref.args.map(arg => substitute(arg, types)) };
+                const find = (ref, source) => {
+                    const def = checked.project.scopes.get(source)?.get(ref.name);
+                    if (!def || def.node.kind !== 'interface' || seen.has(def.id))
+                        return;
+                    seen.add(def.id);
+                    const types = new Map(def.node.typeParams.map((name, index) => [name, ref.args[index]]).filter((entry) => !!entry[1]));
+                    const method = def.node.methods.find(method => method.name === missing[2]);
+                    if (method)
+                        return { method, types };
+                    for (const parent of def.node.extends) {
+                        const found = find(substitute(parent, types), def.file);
+                        if (found)
+                            return found;
+                    }
+                };
+                const contract = owner.implements.map(ref => find(ref, file.path)).find(Boolean);
+                if (contract) {
+                    const params = contract.method.params.map(param => `${param.injected ? 'resolve ' : ''}${param.ownership === 'managed' ? '' : param.ownership + ' '}${typeName(substitute(param.type, contract.types))} ${param.name}`);
+                    const generic = contract.method.typeParams.length ? '<' + contract.method.typeParams.join(', ') + '>' : '';
+                    const header = `${missing[2]}${generic}(${params.join(', ')}) returns ${contract.method.returnOwnership === 'own' ? 'own ' : ''}${typeName(substitute(contract.method.returns, contract.types))}` +
+                        (contract.method.throws.length ? ' unless ' + contract.method.throws.map(ref => typeName(substitute(ref, contract.types))).join(', ') : '');
+                    const unit = checked.project.config.indentation === 'tabs' ? '\t' : '    ';
+                    const start = owner.headerEnd ?? owner.span.start;
+                    const braces = file.source[start] === '{' || file.source.slice(owner.span.start, start + 1).trimEnd().endsWith('{');
+                    const insertion = braces ? file.source.lastIndexOf('}', owner.span.end - 1) : owner.span.end;
+                    if (insertion >= owner.span.start)
+                        add(`Implement ${missing[2]} in ${owner.name}`, { file: file.path, start: insertion, end: insertion,
+                            text: braces ? `\n${unit}${header} {\n${unit}${unit}// TODO: implement ${missing[2]}\n${unit}}\n` : `\n${unit}${header}:\n${unit}${unit}// TODO: implement ${missing[2]}\n${unit}${unit}pass\n` });
+                }
+            }
+        }
         if (issue.code === 'PARSE' && redundant) {
             const start = offsetAt(file.source, issue.line, issue.column);
             if (file.source.slice(start, start + redundant[1].length) === redundant[1])
@@ -140,6 +197,37 @@ export function suggestedFixes(checked, fileName) {
                 seen.add(declaration);
                 add(`Import ${unknown[1]} from ${item.detail.split(' from ')[1]}`, { file: file.path, start: 0, end: 0, text: `${declaration}\n` });
             }
+            const start = offsetAt(file.source, issue.line, issue.column);
+            const candidates = completions(checked, file.path, start + unknown[1].length).filter(item => !item.additionalEdits && ['variable', 'parameter', 'property', 'function', 'class', 'interface', 'type'].includes(item.kind) &&
+                item.label !== unknown[1] && distance(item.label, unknown[1]) <= Math.min(2, Math.floor(unknown[1].length / 3)));
+            for (const candidate of candidates.slice(0, 3))
+                fixes.push({ title: `Replace ${unknown[1]} with ${candidate.label}`, issue,
+                    preferred: candidates.length === 1, edits: [{ file: file.path, start, end: start + unknown[1].length, text: candidate.label }] });
+        }
+        const badMember = / has no (?:member|method) ([A-Za-z_][A-Za-z0-9_]*)$/.exec(issue.message);
+        if (badMember) {
+            const start = offsetAt(file.source, issue.line, issue.column), tokens = lex(file.path, file.source).tokens;
+            const member = tokens.find(token => token.value === badMember[1] && token.span.start >= start && token.span.line === issue.line);
+            if (member) {
+                const candidates = completions(checked, file.path, member.span.end).filter(item => item.label !== member.value && distance(item.label, member.value) <= 2);
+                for (const candidate of candidates.slice(0, 3))
+                    fixes.push({ title: `Replace ${member.value} with ${candidate.label}`, issue,
+                        preferred: candidates.length === 1, edits: [{ file: file.path, start: member.span.start, end: member.span.end, text: candidate.label }] });
+            }
+        }
+        const badLabel = / has no parameter ([A-Za-z_][A-Za-z0-9_]*)$/.exec(issue.message);
+        if (issue.code === 'CALL' && badLabel) {
+            const start = offsetAt(file.source, issue.line, issue.column);
+            const calls = callsIn(file).filter(call => call.span.start <= start && start < call.span.end)
+                .sort((a, b) => a.span.end - a.span.start - (b.span.end - b.span.start));
+            const call = calls[0], entry = call && hoverInfo(checked, file.path, call.callee.span.end - 1);
+            const tokens = call && lex(file.path, file.source).tokens.filter(token => call.span.start < token.span.start && token.span.end <= start);
+            const label = tokens?.findLast(token => token.value === badLabel[1]);
+            const candidates = entry?.parameters?.map(parameter => parameter.split('=')[0]).filter(name => !call.argLabels.includes(name) && distance(name, badLabel[1]) <= 2) ?? [];
+            if (label)
+                for (const name of candidates)
+                    fixes.push({ title: `Use argument label ${name}`, issue, preferred: candidates.length === 1,
+                        edits: [{ file: file.path, start: label.span.start, end: label.span.end, text: name }] });
         }
         if (issue.code === 'INTERCEPTOR' && /constructor parameter .* must be marked resolve/.test(issue.message)) {
             const start = offsetAt(file.source, issue.line, issue.column);

package/src/formatter.js

@@ -1,6 +1,7 @@
 import { typeName } from "./ast.js";
 import { lex } from "./lexer.js";
 import { parse } from "./parser.js";
+import { importSource } from "./git-packages.js";
 /** Canonical syntax comes from the parsed program; comments stay with their lexical owner. */
 export function formatFile(project, file) {
     return printFile(project, file, false);
@@ -43,7 +44,7 @@ function printFile(project, file, migrate) {
         if (!value || typeof value !== 'object')
             return value;
         const node = value;
-        return Object.fromEntries(Object.entries(node).filter(([key, value]) => !['span', 'nameSpan', 'sourceSpan'].includes(key) && value !== undefined)
+        return Object.fromEntries(Object.entries(node).filter(([key, value]) => !['span', 'nameSpan', 'sourceSpan', 'headerEnd'].includes(key) && value !== undefined)
             .sort(([a], [b]) => a.localeCompare(b)).map(([key, value]) => [key, shape(value)]));
     };
     if (JSON.stringify(shape(parsed.file.items)) !== JSON.stringify(shape(verified.file.items)))
@@ -67,7 +68,15 @@ class Printer {
         this.indent = project.config.block_style === 'indent';
         this.assign = project.config.assignment === 'to' ? 'to' : '=';
     }
-    line(text = '') { this.lines.push(text ? this.step.repeat(this.level) + text : ''); }
+    line(text = '') {
+        this.lines.push(...text.split('\n').map(line => line ? this.step.repeat(this.level) + line : ''));
+    }
+    delimited(open, values, close, trailing = '') {
+        const flat = open + values.join(', ') + trailing + close;
+        if (!values.length || (!flat.includes('\n') && flat.length <= 80 - this.level * 4))
+            return flat;
+        return open + '\n' + values.map(value => this.step + value.replaceAll('\n', '\n' + this.step)).join(',\n') + trailing + '\n' + close;
+    }
     before(offset, parentColumn) {
         while (this.comments[0]?.span.start < offset) {
             if (parentColumn !== undefined && this.comments[0].span.column <= parentColumn)
@@ -123,7 +132,7 @@ class Printer {
         this.annotations(method.annotations);
         const header = `${method.endpoint ? `endpoint ${method.endpoint.method} ${JSON.stringify(method.endpoint.path)} as ` : ''}${method.fixture ? 'fixture ' : ''}${method.externC ? 'extern C ' + (method.valueAbi ? 'value ' : '') + (method.nativePure ? 'pure ' : '') : ''}${method.name}${this.generics(method)}` +
             `(${method.params.map(param => this.param(param)).join(', ')})` +
-            (method.returns.name !== 'void' ? ` ${method.endpoint?.streams ? 'streams' : 'returns'} ${method.returnOwnership === 'own' ? 'own ' : ''}${typeName(method.returns)}` : '') +
+            (method.returns.name !== 'void' || method.declared?.returns ? ` ${method.endpoint?.streams ? 'streams' : 'returns'} ${method.returnOwnership === 'own' ? 'own ' : ''}${typeName(method.returns)}` : '') +
             (method.endpoint && method.endpoint.status !== 200 ? ` with status ${method.endpoint.status}` : '') +
             (method.changes?.length ? ` changes ${method.changes.join(' and ')}` : '') +
             (method.uses?.length ? ` uses ${method.uses.map(use => `${use.source}.${use.operation}`).join(' and ')}` : '') +
@@ -159,14 +168,16 @@ class Printer {
             value = `resolve ${expr.name}` + (expr.typeArgs.length ? '<' + expr.typeArgs.map(typeName).join(', ') + '>' : '');
         else if (expr.kind === 'member')
             value = `${this.expression(expr.object, 8)}.${expr.name}`;
-        else if (expr.kind === 'call')
-            value = this.expression(expr.callee, 8) + (expr.typeArgs.length ? '<' + expr.typeArgs.map(typeName).join(', ') + '>' : '') +
-                '(' + expr.args.map((arg, index) => (expr.argLabels[index] ? expr.argLabels[index] + '=' : '') + this.expression(arg)).join(', ') + this.inline(expr.span.end) + ')';
+        else if (expr.kind === 'call') {
+            const open = this.expression(expr.callee, 8) + (expr.typeArgs.length ? '<' + expr.typeArgs.map(typeName).join(', ') + '>' : '') + '(';
+            const values = expr.args.map((arg, index) => (expr.argLabels[index] ? expr.argLabels[index] + '=' : '') + this.expression(arg));
+            value = this.delimited(open, values, ')', this.inline(expr.span.end));
+        }
         else if (expr.kind === 'collection') {
             const open = expr.collection === 'List' ? '[' : expr.collection === 'Tuple' ? '(' : '{';
             const close = open === '[' ? ']' : open === '(' ? ')' : '}';
             const values = expr.collection === 'Map' ? expr.items.filter((_, index) => index % 2 === 0).map((item, index) => `${this.expression(item)}: ${this.expression(expr.items[index * 2 + 1])}`) : expr.items.map(item => this.expression(item));
-            value = open + values.join(', ') + (expr.collection === 'Tuple' && values.length === 1 ? ',' : '') + this.inline(expr.span.end) + close;
+            value = this.delimited(open, values, close, (expr.collection === 'Tuple' && values.length === 1 ? ',' : '') + this.inline(expr.span.end));
         }
         else if (expr.kind === 'unary') {
             const power = expr.op === '!' ? 2.5 : 7;
@@ -232,7 +243,7 @@ class Printer {
     item(item) {
         this.before('annotations' in item ? item.annotations?.[0]?.span.start ?? item.span.start : item.span.start);
         if (item.kind === 'import') {
-            this.line(`import ${item.everything ? 'everything' : item.names.join(' and ')} from ${item.from.join('.')}`);
+            this.line(`import ${item.everything ? 'everything' : item.names.join(' and ')} from ${importSource(item.from)}`);
         }
         else if (item.kind === 'export')
             this.line('export ' + (item.folder ? 'folder ' + item.name : `${item.name} from ${item.from}`));
@@ -243,20 +254,22 @@ class Printer {
                 (item.lifetime ? ' ' + item.lifetime : '') + (item.sharedMutation ? ' mutable' : ''));
         else if (item.kind === 'composition')
             this.block('composition ' + item.name, () => item.bindings.forEach(binding => this.item(binding)), item.span);
+        else if (item.kind === 'resource')
+            this.line('extern C resource ' + item.name);
         else if (item.kind === 'function')
             this.method(item);
         else if (item.kind === 'class') {
             this.annotations(item.annotations);
             const header = `${item.record ? 'record ' : ''}${item.name}${this.generics(item)}(${item.fields.map(field => this.param(field, true)).join(', ')})`;
+            const errors = item.validationErrors?.length ? ` unless ${item.validationErrors.map(typeName).join(' and ')}` : '';
             if (item.record) {
-                const errors = item.validationErrors?.length ? ` unless ${item.validationErrors.map(typeName).join(' and ')}` : '';
                 if (item.constructorBody)
                     this.block(header + errors, () => this.initializer(item), item.span);
                 else
                     this.line(header + errors);
             }
             else {
-                this.block(header + ' implements ' + item.implements.map(typeName).join(', '), () => {
+                this.block(header + errors + ' implements ' + item.implements.map(typeName).join(', '), () => {
                     for (const field of item.stateFields ?? []) {
                         this.before(field.span.start);
                         this.line(`${field.mutable ? 'mutable ' : ''}${typeName(field.type)} ${field.name} = ${this.expression(field.initializer)}`);

package/src/git-http.js

@@ -0,0 +1,137 @@
+import { createHash } from 'node:crypto';
+import { cpSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { homedir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { gitReference, sourceAlias } from "./git-packages.js";
+import { withPackageLockAsync } from "./package-locking.js";
+const selected = (name) => !name.split('/').some(part => part.startsWith('.')) && (name.endsWith('.aug') || ['aug-package.json', 'package.json', 'main.yaml', 'README.md', 'LICENSE', 'native.abi.json', 'THIRD_PARTY_NOTICES.md'].includes(name));
+async function bytes(url, maximum) {
+    const address = new URL(url);
+    if (address.protocol !== 'https:' || !['api.github.com', 'raw.githubusercontent.com'].includes(address.hostname) || address.username || address.password)
+        throw new Error('Invalid source transport URL');
+    const headers = { Accept: 'application/vnd.github+json', 'User-Agent': 'August-source-packages' };
+    // Only the API receives an explicitly supplied token. Raw downloads and
+    // redirects cannot carry it, and it never enters package metadata or logs.
+    if (address.hostname === 'api.github.com' && process.env.AUG_GITHUB_TOKEN)
+        headers.Authorization = 'Bearer ' + process.env.AUG_GITHUB_TOKEN;
+    const response = await fetch(address, { redirect: 'error', signal: AbortSignal.timeout(60000), headers });
+    if (!response.ok || !response.body)
+        throw new Error(`Cannot read public GitHub source (${response.status}). Check the repository/revision. For API rate limits, retry later or supply AUG_GITHUB_TOKEN for authenticated public reads.`);
+    if (Number(response.headers.get('content-length') ?? 0) > maximum)
+        throw new Error('GitHub source response exceeds its size limit');
+    const chunks = [];
+    let length = 0;
+    for await (const chunk of response.body) {
+        length += chunk.length;
+        if (length > maximum)
+            throw new Error('GitHub source response exceeds its size limit');
+        chunks.push(Buffer.from(chunk));
+    }
+    return Buffer.concat(chunks);
+}
+/** Public GitHub snapshots use HTTPS objects, so consumers do not need Git or an SDK. */
+export async function materializeGitHub(request, destination, offline, locked) {
+    const reference = gitReference(request), url = new URL(reference.repository), parts = url.pathname.split('/').filter(Boolean), owner = parts[0], repo = parts[1]?.replace(/\.git$/, '');
+    if (url.hostname !== 'github.com' || parts.length !== 2 || !owner || !repo)
+        throw new Error('GitHub transport requires an owner/repository URL');
+    if (locked && (locked.repository !== reference.repository || locked.folder !== reference.folder || locked.revision !== reference.revision || !/^[0-9a-f]{40}$/.test(locked.commit)))
+        throw new Error('Invalid locked GitHub source identity');
+    const cache = resolve(process.env.AUG_PACKAGE_CACHE ?? join(homedir(), '.cache/augscript/packages'));
+    const base = join(cache, 'https-' + sourceAlias(reference.repository) + '-' + sourceAlias(reference.folder));
+    mkdirSync(base, { recursive: true });
+    return withPackageLockAsync(base + '.lock', async () => {
+        let commit = locked?.commit;
+        const revisionCache = join(base, 'revision-' + sourceAlias(reference.revision) + '.json');
+        if (!commit && offline && existsSync(revisionCache))
+            commit = JSON.parse(readFileSync(revisionCache, 'utf8')).commit;
+        if (!commit) {
+            if (offline)
+                throw new Error('GitHub revision is not cached. Run aug install online once: ' + request);
+            const value = JSON.parse((await bytes(`https://api.github.com/repos/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}/commits/${encodeURIComponent(reference.revision)}`, 4 * 1024 * 1024)).toString());
+            commit = value.sha;
+            if (!/^[0-9a-f]{40}$/.test(commit))
+                throw new Error('GitHub did not resolve an exact commit');
+        }
+        if (!/^[0-9a-f]{40}$/.test(commit))
+            throw new Error('Invalid cached GitHub revision');
+        const snapshot = join(base, commit), metadata = join(base, commit + '.json');
+        if (!existsSync(snapshot) || !existsSync(metadata)) {
+            if (offline)
+                throw new Error('Locked GitHub source is not cached: ' + commit);
+            // An interrupted installation may leave either half of the cache entry.
+            // The exclusive writer discards that incomplete entry before retrying.
+            rmSync(snapshot, { recursive: true, force: true });
+            rmSync(metadata, { force: true });
+            const tree = JSON.parse((await bytes(`https://api.github.com/repos/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}/git/trees/${commit}?recursive=1`, 16 * 1024 * 1024)).toString());
+            if (tree.truncated || !Array.isArray(tree.tree))
+                throw new Error('GitHub source tree coverage is incomplete; installation stopped');
+            const prefix = reference.folder ? reference.folder + '/' : '';
+            const entries = tree.tree.filter((e) => e.type === 'blob' && typeof e.path === 'string' && e.path.startsWith(prefix) && selected(e.path.slice(prefix.length)));
+            if (!entries.length || entries.length > 10000)
+                throw new Error('GitHub package has no source files or exceeds its file limit');
+            const stage = mkdtempSync(join(base, '.snapshot-'));
+            let total = 0;
+            const digests = {};
+            try {
+                // Bounded concurrency avoids one network round trip per source file.
+                for (let i = 0; i < entries.length; i += 8) {
+                    const batch = await Promise.allSettled(entries.slice(i, i + 8).map(async (entry) => {
+                        const name = entry.path.slice(prefix.length);
+                        if (!['100644', '100755'].includes(entry.mode) || name.includes('\\') || name.split('/').some((p) => !p || p === '.' || p === '..' || p.startsWith('.')) || !/^[0-9a-f]{40}$/.test(entry.sha))
+                            throw new Error('GitHub package source must be regular files inside its folder: ' + name);
+                        const content = await bytes(`https://raw.githubusercontent.com/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}/${commit}/${entry.path.split('/').map(encodeURIComponent).join('/')}`, 32 * 1024 * 1024);
+                        total += content.length;
+                        if (total > 32 * 1024 * 1024)
+                            throw new Error('GitHub source package exceeds 32 MiB');
+                        const actual = createHash('sha1').update('blob ' + content.length + '\0').update(content).digest('hex');
+                        if (actual !== entry.sha)
+                            throw new Error('GitHub source blob identity differs from the resolved tree');
+                        digests[name] = createHash('sha256').update(content).digest('hex');
+                        mkdirSync(dirname(join(stage, name)), { recursive: true });
+                        writeFileSync(join(stage, name), content);
+                    }));
+                    const rejected = batch.find(r => r.status === 'rejected');
+                    if (rejected?.status === 'rejected')
+                        throw rejected.reason;
+                }
+                renameSync(stage, snapshot);
+                writeFileSync(metadata, JSON.stringify({ format: 1, commit, files: digests }));
+            }
+            finally {
+                rmSync(stage, { recursive: true, force: true });
+            }
+        }
+        const facts = JSON.parse(readFileSync(metadata, 'utf8'));
+        if (facts.format !== 1 || facts.commit !== commit || !facts.files)
+            throw new Error('Invalid cached GitHub source metadata');
+        const list = (folder, prefix = '') => readdirSync(folder, { withFileTypes: true }).flatMap(entry => {
+            if (entry.isSymbolicLink())
+                throw new Error('Cached GitHub source cannot contain symbolic links');
+            const path = prefix + entry.name;
+            return entry.isDirectory() ? list(join(folder, entry.name), path + '/') : entry.isFile() ? [path] : (() => { throw new Error('Cached GitHub source requires regular files'); })();
+        });
+        if (lstatSync(snapshot).isSymbolicLink() || JSON.stringify(list(snapshot).sort()) !== JSON.stringify(Object.keys(facts.files).sort()))
+            throw new Error('Cached GitHub source file set differs from the resolved snapshot');
+        for (const [name, digest] of Object.entries(facts.files)) {
+            if (name.includes('\\') || name.split('/').some(p => !p || p === '.' || p === '..' || p.startsWith('.')))
+                throw new Error('Cached source path escapes its snapshot');
+            if (createHash('sha256').update(readFileSync(join(snapshot, name))).digest('hex') !== digest)
+                throw new Error('Cached GitHub source changed: ' + name);
+        }
+        cpSync(snapshot, destination, { recursive: true });
+        writeFileSync(revisionCache, JSON.stringify({ commit }));
+        return { ...reference, commit: commit };
+    });
+}
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url) && process.argv[2] === '--materialize') {
+    try {
+        const input = JSON.parse(process.argv[3]);
+        const result = await materializeGitHub(input.request, input.destination, input.offline, input.locked);
+        process.stdout.write(JSON.stringify(result));
+    }
+    catch (error) {
+        process.stderr.write((error instanceof Error ? error.message : String(error)) + '\n');
+        process.exitCode = 1;
+    }
+}