@greenpandastudios/aug-cli 0.19.0 → 0.20.1

package/src/cli.js

@@ -11,26 +11,53 @@ import { checkUnitTests, discoverTests, mergeTestAnalysis, uniqueDiagnostics } f
 import { describe, SemanticWorkspace } from "./semantic.js";
 import { formatFile, migrateFile } from "./formatter.js";
 import { updateSpecs } from "./spec.js";
+import { updateSpecHints } from "./spec-hints.js";
 import { runLanguageServer } from "./lsp.js";
 import { benchmark, compileNative, writeCoverage } from "./native.js";
 import { generateOpenApi } from "./openapi.js";
-import { initPackage, installPackages, preparePackage, packPackage } from "./package-manager.js";
+import { addPackage, initPackage, installPackages, preparePackage, packPackage, prepareRunPackages } from "./package-manager.js";
 import { initProject } from "./project-init.js";
+import { prepareNativeDependencies } from '../scripts/native-setup.mjs';
+function failureMessage(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (error instanceof Error && 'code' in error && ['EACCES', 'EPERM', 'EROFS'].includes(String(error.code)))
+        return `${message}\nAugust needs a writable project and native cache. Check the folder permissions, or set AUG_NATIVE_HOME to a directory you own.`;
+    if (error instanceof Error && 'code' in error && error.code === 'ENOSPC')
+        return `${message}\nThere is not enough disk space to compile or prepare dependencies. Free space and retry aug run.`;
+    return message;
+}
 function printDiagnostics(diagnostics, json, root) {
     if (json) {
         process.stdout.write(JSON.stringify(diagnostics.map(issue => ({ ...issue,
             help: diagnosticHelp[issue.code] }))) + '\n');
         return;
     }
+    const sources = new Map();
     for (const issue of diagnostics) {
-        const file = issue.file.startsWith(root) ? issue.file.slice(root.length + 1) : issue.file;
+        const file = relative(root, issue.file) || issue.file;
         process.stderr.write(`${file}:${issue.line}:${issue.column}: ${issue.code}: ${issue.message}\n`);
+        try {
+            if (!sources.has(issue.file))
+                sources.set(issue.file, readFileSync(issue.file, 'utf8').split(/\r?\n/));
+            const line = sources.get(issue.file)?.[issue.line - 1];
+            if (line !== undefined) {
+                const column = Math.max(0, Math.min(line.length, issue.column - 1));
+                const start = Math.max(0, column - 70), end = Math.min(line.length, start + 150);
+                const text = (start ? '…' : '') + line.slice(start, end).replace(/\t/g, '    ') + (end < line.length ? '…' : '');
+                const padding = (start ? 1 : 0) + line.slice(start, column).replace(/\t/g, '    ').length;
+                process.stderr.write(`  ${issue.line} | ${text}\n  ${' '.repeat(String(issue.line).length)} | ${' '.repeat(padding)}^\n`);
+            }
+        }
+        catch { /* Source may have been removed; the location and help remain useful. */ }
+        if (diagnosticHelp[issue.code])
+            process.stderr.write(`  help: ${diagnosticHelp[issue.code]}\n`);
     }
 }
 function usage() {
     process.stdout.write(`AugScript compiler\n\n` +
         `Usage: aug <init|check|build|run|emit-c|test|openapi|format|migrate|spec|bench|explain|context|lsp|symbols|definition|complete|hover|fixes|semantic-tokens> [project directory] [options] [-- args]\n` +
-        `New application: aug init DIRECTORY\n` +
+        `New application: aug init DIRECTORY [--template hello|weather]\n` +
+        `Run: aug run [project directory] [--offline] [-- args] — prepare dependencies, compile, and start\n` +
         `Tests: aug test [project directory] [GROUP_NAME] [--group GROUP_NAME] [--list] [--coverage] [--json] [--timeout milliseconds]\n` +
         `Format: aug format [project directory] [--file path] [--write]\n` +
         `Specifications: aug spec [project directory] [--check] [--json]\n` +
@@ -38,7 +65,7 @@ function usage() {
         `Context: aug context [project directory] [--file path] [--name declaration] [--budget characters]\n` +
         `Benchmark: aug bench [project directory] [--iterations 10] [--warmup 2] [--json] [-- args]\n` +
         `Packages: aug package init DIRECTORY --name @owner/name; aug package pack DIRECTORY\n` +
-        `Dependencies: aug install [project directory] [--frozen] [--offline]\n` +
+        `Dependencies: aug add URL --as NAME [--project DIRECTORY]; aug install [project directory] [--frozen|--update] [--offline]\n` +
         `Entry point: main.aug at the project root.\n`);
 }
 export async function main(argv) {
@@ -53,18 +80,46 @@ export async function main(argv) {
         usage();
         return 0;
     }
+    if (command === 'add') {
+        const aliasIndex = argv.indexOf('--as'), projectIndex = argv.indexOf('--project');
+        if (!argv[1] || argv[1].startsWith('--') || aliasIndex < 0 || !argv[aliasIndex + 1]) {
+            process.stderr.write('Use aug add URL --as NAME [--project DIRECTORY] [--offline]\n');
+            return 2;
+        }
+        for (let index = 2; index < argv.length; index++) {
+            if (['--as', '--project'].includes(argv[index])) {
+                if (!argv[++index] || argv[index].startsWith('--'))
+                    return 2;
+            }
+            else if (argv[index] !== '--offline') {
+                process.stderr.write('Unknown add option: ' + argv[index] + '\n');
+                return 2;
+            }
+        }
+        try {
+            const alias = argv[aliasIndex + 1], root = resolve(projectIndex < 0 ? process.cwd() : argv[projectIndex + 1]);
+            const lock = addPackage(root, argv[1], alias, argv.includes('--offline'));
+            process.stdout.write(`Added ${alias}; installed ${lock.packages.length} source package(s).\nImport public names with: import NAME from ${alias}\n`);
+            return 0;
+        }
+        catch (error) {
+            process.stderr.write(failureMessage(error) + '\n');
+            return 1;
+        }
+    }
     if (command === 'init') {
-        if (argv.length !== 2 || !argv[1] || argv[1].startsWith('--')) {
-            process.stderr.write('Use aug init DIRECTORY\n');
+        const template = argv.length === 2 ? 'hello' : argv[2] === '--template' && argv.length === 4 ? argv[3] : undefined;
+        if (!argv[1] || argv[1].startsWith('--') || !['hello', 'weather'].includes(template ?? '')) {
+            process.stderr.write('Use aug init DIRECTORY [--template hello|weather]\n');
             return 2;
         }
         try {
-            const root = initProject(argv[1]);
-            process.stdout.write(`Created August application in ${root}\nNext: cd ${argv[1]} && aug check . && aug test . && aug run .\n`);
+            const root = initProject(argv[1], template);
+            process.stdout.write(`Created August application in ${root}\nNext: cd ${argv[1]}\n      aug run\n`);
             return 0;
         }
         catch (error) {
-            process.stderr.write(error.message + '\n');
+            process.stderr.write(failureMessage(error) + '\n');
             return 1;
         }
     }
@@ -73,17 +128,18 @@ export async function main(argv) {
             const root = resolve((command === 'install' ? argv[1] : argv[2]) && !(command === 'install' ? argv[1] : argv[2]).startsWith('--')
                 ? (command === 'install' ? argv[1] : argv[2]) : process.cwd());
             if (command === 'install') {
-                const lock = installPackages(root, argv.includes('--frozen'), argv.includes('--offline'));
+                const lock = installPackages(root, argv.includes('--frozen'), argv.includes('--offline'), argv.includes('--update'));
                 process.stdout.write(`Installed ${lock.packages.length} August package(s); aug.lock.json is current.\n`);
             }
             else if (argv[1] === 'init') {
-                const name = argv[argv.indexOf('--name') + 1];
-                if (!argv.includes('--name') || !name)
-                    throw new Error('Use aug package init DIRECTORY --name @owner/name');
-                initPackage(root, name);
+                const name = argv.includes('--name') ? argv[argv.indexOf('--name') + 1] : root.split(/[\\/]/).at(-1);
+                if (!name)
+                    throw new Error('Use aug package init DIRECTORY [--name @owner/name]');
+                initPackage(root, name, argv.includes('--name'));
                 process.stdout.write(`Created August library ${name} in ${root}\n`);
             }
             else if (argv[1] === 'pack') {
+                prepareRunPackages(root);
                 preparePackage(root);
                 const project = loadProject(root), checked = checkProject(project);
                 const tests = checkUnitTests(project, discoverTests(project).tests);
@@ -101,7 +157,7 @@ export async function main(argv) {
             return 0;
         }
         catch (error) {
-            process.stderr.write(error.message + '\n');
+            process.stderr.write(failureMessage(error) + '\n');
             return 1;
         }
     }
@@ -116,6 +172,26 @@ export async function main(argv) {
     const separator = argv.indexOf('--');
     const options = separator >= 0 ? argv.slice(1, separator) : argv.slice(1);
     const programArgs = separator >= 0 ? argv.slice(separator + 1) : [];
+    if (options.includes('--help')) {
+        usage();
+        return 0;
+    }
+    const valueOptions = new Set(['--out', '--stdin-file', '--file', '--name', '--offset', '--budget', '--baseline', '--group', '--case', '--timeout', '--iterations', '--warmup']);
+    const booleanOptions = new Set(['--json', '--coverage', '--list', '--write', '--check', '--offline']);
+    for (let index = 0; index < options.length; index++) {
+        const option = options[index];
+        if (valueOptions.has(option)) {
+            if (!options[index + 1] || options[index + 1].startsWith('--')) {
+                process.stderr.write(`${option} needs a value. See aug ${command} --help.\n`);
+                return 2;
+            }
+            index++;
+        }
+        else if (option.startsWith('-') && !booleanOptions.has(option)) {
+            process.stderr.write(`Unknown option ${option}. See aug ${command} --help. To pass an option to your program, put it after --.\n`);
+            return 2;
+        }
+    }
     const json = options.includes('--json');
     const outIndex = options.indexOf('--out');
     const outputOption = outIndex >= 0 ? options[outIndex + 1] : undefined;
@@ -171,6 +247,10 @@ export async function main(argv) {
             process.stdout.write(JSON.stringify(result) + '\n');
             return 0;
         }
+        if (!existsSync(root) || !statSync(root).isDirectory())
+            throw new Error(`Project directory does not exist: ${root}\nUse aug init DIRECTORY to create a project, or run aug run from the folder containing main.aug.`);
+        if (command === 'run')
+            prepareRunPackages(root, options.includes('--offline'));
         const project = loadProject(root, overrides);
         if (project.library && ['build', 'run', 'bench', 'openapi'].includes(command))
             throw new Error('This is an August library; use check, test, or package pack. Import its exports from an application with main.aug to run it.');
@@ -217,7 +297,9 @@ export async function main(argv) {
             const results = [];
             const coverage = options.includes('--coverage'), reports = [];
             for (const [index, { unit, checked: testChecked }] of checks.entries()) {
-                const native = compileNative(root, generateC(testChecked, { coverage }), { testIndex: index, checked: testChecked });
+                const generated = generateC(testChecked, { coverage });
+                await prepareNativeDependencies(generated, { offline: options.includes('--offline') });
+                const native = compileNative(root, generated, { testIndex: index, checked: testChecked });
                 const report = join(root, '.aug-build', 'tests', `coverage-${index}.tsv`);
                 reports.push(report);
                 if (coverage)
@@ -244,7 +326,7 @@ export async function main(argv) {
                 `${passed} passed, ${failed} failed\n` + (report ? `Coverage: ${report.covered}/${report.executable} statement lines (${report.percent.toFixed(1)}%); ${report.path}\n` : ''));
             return failed ? 1 : 0;
         }
-        const checked = checkProject(project);
+        let checked = checkProject(project);
         const testChecks = checkUnitTests(project, discovered.tests);
         checked.diagnostics = uniqueDiagnostics([...checked.diagnostics, ...discovered.diagnostics,
             ...testChecks.flatMap(entry => entry.checked.diagnostics)]);
@@ -305,6 +387,13 @@ export async function main(argv) {
             process.stdout.write(json ? JSON.stringify(result) + '\n' : result.stale.length ? 'Stale specifications:\n' + result.stale.map(file => '  ' + file).join('\n') + '\n' : `${result.files} specification artifact(s) ${options.includes('--check') ? 'are current' : 'generated'}.\n`);
             return result.stale.length ? 1 : 0;
         }
+        if (['build', 'run', 'bench'].includes(command)) {
+            checked = updateSpecHints(checked);
+            if (checked.diagnostics.some(issue => issue.severity !== 'warning')) {
+                printDiagnostics(checked.diagnostics, json, root);
+                return 1;
+            }
+        }
         const generated = generateC(checked);
         if (command === 'emit-c') {
             process.stdout.write(generated);
@@ -313,6 +402,7 @@ export async function main(argv) {
         if (command === 'bench' && (!Number.isInteger(iterations) || iterations < 1 || iterations > 1000 ||
             !Number.isInteger(warmup) || warmup < 0 || warmup > 100 || !Number.isInteger(timeout) || timeout < 1))
             throw new Error('bench requires iterations 1–1000, warmup 0–100, and a positive timeout');
+        await prepareNativeDependencies(generated, { offline: options.includes('--offline') });
         const native = compileNative(root, generated, { output: outputOption, release: command === 'bench' ? true : undefined, checked });
         const output = native.output;
         if (native.status !== 0) {
@@ -334,11 +424,15 @@ export async function main(argv) {
         }
         const run = spawnSync(output, programArgs, { stdio: 'inherit', cwd: root });
         if (run.error)
-            throw run.error;
+            throw new Error(`Cannot start the compiled program ${output}: ${run.error.message}.\nCheck executable permissions and the native shared-library paths.`);
+        if (run.signal)
+            process.stderr.write(`Program stopped by ${run.signal}. Check the runtime message above; aug run compiled and started ${output}.\n`);
+        else if (run.status !== 0)
+            process.stderr.write(`Program exited with status ${run.status}.\n`);
         return run.status ?? 1;
     }
     catch (error) {
-        process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
-        return 1;
+        process.stderr.write(failureMessage(error) + '\n');
+        return error instanceof Error && 'exitCode' in error && typeof error.exitCode === 'number' ? error.exitCode : 1;
     }
 }

package/src/codegen.js

@@ -154,7 +154,7 @@ class CGenerator {
             `  aug_register_globals(aug_bindings, ${bindingCount});`,
             `  aug_set_cli_args(argc, argv);`,
             ...([...this.activeFiles].some(file => this.checked.project.files.get(file)?.items.some(item => item.kind === 'function' && !!item.endpoint) ||
-                [...this.checked.project.definitions.values()].some(def => def.file === file && def.id.startsWith('august/web/'))) ? [this.httpConfiguration()] : []),
+                this.checked.project.files.get(file)?.items.some(item => item.kind === 'function' && item.externC && item.name.startsWith('_aug_http_'))) ? [this.httpConfiguration()] : []),
             ...[...this.coverage.values()].map(point => `  aug_coverage_register(${cString(point.file)}, ${point.line});`),
             initializeBindings,
             `  AugValue result = aug_main_body(NULL, 0);`,

package/src/config.js

@@ -55,7 +55,7 @@ export function loadConfig(root) {
             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');
+                    report(index + 1, 'Packages map lowercase public aliases to repository URLs, local paths, or npm:name@exact-version');
                 else
                     config.packages[entry[1]] = value;
                 continue;

package/src/contracts.js

@@ -0,0 +1,10 @@
+import { schemaType } from "./schemas.js";
+import { tyName } from "./types.js";
+/** Checked contracts shared by the editor, documentation and wire schemas. */
+export function callableResult(checked, method) {
+    return checked.callableContracts.get(method)?.result ?? schemaType(checked.project, method.returns, method.span.file);
+}
+export function callableErrors(checked, method) {
+    return [...new Set([...(checked.callableContracts.get(method)?.errors.map(tyName) ?? method.throws.map(type => tyName(schemaType(checked.project, type, method.span.file)))),
+            ...(checked.interceptorPlans.get(method) ?? []).flatMap(layer => layer.errors.map(tyName))])].sort();
+}

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,8 @@ 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";
 const builtins = [
     ...builtinFunctions.map(operation => {
         const parameters = operation.parameters.map(param => `${param.label}=${param.type}`);
@@ -24,6 +27,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 +43,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 +64,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,14 +125,14 @@ 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),
+    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.']
             .filter(Boolean).join('\n\n'),
@@ -147,7 +155,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),
@@ -292,7 +300,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 +345,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 +355,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 +377,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 +477,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) {

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);