@greenpandastudios/aug-cli 0.19.0 → 0.20.1

package/src/project-init.js

@@ -1,18 +1,92 @@
 import { existsSync, mkdirSync, readdirSync, writeFileSync } from 'node:fs';
 import { basename, join, resolve } from 'node:path';
+export const agentInstructions = `# Working on this August project
+
+Start in main.aug. It shows the imports, dependency bindings, and application startup.
+Read the adjacent .aug.md specification before changing a source file. Generate missing
+or stale explanations with aug spec; they describe checked behavior and link dependencies.
+
+Keep tests in the file that declares the behavior. Run aug check, aug test, and aug spec
+after a change, and use aug run to compile and run the application. Run prepares required
+source packages and native libraries. Commit aug.lock.json; do not edit .aug-packages.
+
+Use labeled inputs, narrow export.aug files, and underscore-prefixed private helpers.
+Leave return types, effects, and errors to inference when an executable body provides
+the answer. Bodyless interfaces still declare their contracts. Use borrow for mutation,
+and keep unsafe native calls inside small adapters. Explain intent in Javadoc when it
+is not evident from the code. Follow the existing indentation or brace style.
+
+Language guide: https://greenpandastudios.github.io/augscript/
+`;
+export const weatherSource = `/** The JSON shape returned by the forecast endpoint. Temperatures use whole degrees. */
+record WeatherForecast(string date, int temperatureC, int temperatureF, string summary)
+
+/** Return five simulated forecasts. Fixed data keeps the example and its tests reproducible. */
+endpoint GET "/weatherforecast" as weatherForecast():
+    return [
+        WeatherForecast(
+            date="2026-01-01",
+            temperatureC=0,
+            temperatureF=32,
+            summary="Freezing"
+        ),
+        WeatherForecast(
+            date="2026-01-02",
+            temperatureC=10,
+            temperatureF=50,
+            summary="Cool"
+        ),
+        WeatherForecast(
+            date="2026-01-03",
+            temperatureC=20,
+            temperatureF=68,
+            summary="Mild"
+        ),
+        WeatherForecast(
+            date="2026-01-04",
+            temperatureC=30,
+            temperatureF=86,
+            summary="Warm"
+        ),
+        WeatherForecast(
+            date="2026-01-05",
+            temperatureC=35,
+            temperatureF=95,
+            summary="Hot"
+        )
+    ]
+
+test endpoint weatherForecast client:
+    when forecasts:
+        it returns_json:
+            response = client.request(method="GET", path="/weatherforecast")
+            assert(condition=response.status == 200)
+        it rejects_other_methods:
+            response = client.request(method="POST", path="/weatherforecast")
+            assert(condition=response.status == 405)
+`;
 /** Create a small, runnable application without replacing existing files. */
-export function initProject(destination) {
+export function initProject(destination, template = 'hello') {
     const root = resolve(destination);
     if (existsSync(root) && readdirSync(root).length)
         throw new Error(`Directory is not empty: ${root}`);
     const name = basename(root);
     mkdirSync(root, { recursive: true });
     const files = {
+        'AGENTS.md': agentInstructions,
         'main.aug': `import Greeter and SimpleGreeter from greeting\n\nimplement Greeter with SimpleGreeter\nresolve Greeter to greeter\nprint(value=greeter.greet(name="August"))\n`,
-        'greeting.aug': `/** Build a greeting for a named person. */\ninterface Greeter:\n    /** Return a greeting for the named person. */\n    greet(string name) returns string\n\n/** A plain-language greeting. */\nSimpleGreeter() implements Greeter:\n    greet(string name) returns string:\n        return "Hello, " + name + "!"\n\ntest SimpleGreeter greeter:\n    when greetings:\n        greeter = SimpleGreeter()\n        it greets_a_person:\n            assert(greeter.greet(name="August") == "Hello, August!")\n`,
-        '.gitignore': '.aug-build/\n.aug-spec/\n*.aug.md\n',
-        'README.md': `# ${name}\n\nThis is an August application. Start in \`main.aug\`; its dependencies and startup are visible there.\n\n\`greeting.aug\` contains a public interface, its implementation, and a same-file test.\n\n\`\`\`sh\naug check .\naug test .\naug spec .\naug run .\n\`\`\`\n\nFor the language guide, see https://GreenPandaStudios.github.io/augscript/getting-started.\n`,
+        'greeting.aug': `/** Build a greeting for a named person. */\ninterface Greeter:\n    /** Return a greeting for the named person. */\n    greet(string name) returns string\n\n/** A plain-language greeting. */\nSimpleGreeter() implements Greeter:\n    greet(string name):\n        return "Hello, " + name + "!"\n\ntest SimpleGreeter greeter:\n    when greetings:\n        greeter = SimpleGreeter()\n        it greets_a_person:\n            assert(greeter.greet(name="August") == "Hello, August!")\n`,
+        '.gitignore': '.aug-build/\n.aug-spec/\n.aug-packages/\n.aug-install-*/\n*.aug.md\n',
+        'README.md': `# ${name}\n\nThis is an August application. Start in \`main.aug\`; its dependencies and startup are visible there.\n\n\`greeting.aug\` contains a public interface, its implementation, and a same-file test.\n\n\`\`\`sh\naug run\naug check\naug test\naug spec\n\`\`\`\n\nFor the language guide, see https://GreenPandaStudios.github.io/augscript/getting-started.\n`,
     };
+    if (template === 'weather') {
+        delete files['greeting.aug'];
+        files['main.aug'] = 'import weatherForecast from forecasts\n\nserve weatherForecast on port 8787\n';
+        files['forecasts.aug'] = weatherSource;
+        files['weather.http'] = '### Five simulated forecasts\nGET http://127.0.0.1:8787/weatherforecast\n\n### Generated OpenAPI document\nGET http://127.0.0.1:8787/openapi.json\n';
+        files['main.yaml'] = 'block_style: indent\nopenapi:\n  enabled: true\n  title: "Weather forecast API"\n  version: "0.1.0"\n';
+        files['README.md'] = `# ${name}\n\nA simulated weather API in August. Its endpoint, JSON record, and tests live in forecasts.aug.\n\nRun the server:\n\n\`\`\`sh\naug run\n\`\`\`\n\nOpen http://127.0.0.1:8787/weatherforecast for five forecasts, or http://127.0.0.1:8787/docs for the OpenAPI viewer. These are fixed examples, not live weather observations.\n\n\`\`\`sh\ncurl http://127.0.0.1:8787/weatherforecast\naug test\naug spec\n\`\`\`\n\nGuide: https://greenpandastudios.github.io/augscript/weather-api\n`;
+    }
     for (const [file, contents] of Object.entries(files))
         writeFileSync(join(root, file), contents, { flag: 'wx' });
     return root;

package/src/project.js

@@ -5,7 +5,8 @@ import { loadConfig } from "./config.js";
 import { projectPolicies } from "./policies.js";
 import { builtinFunctions, builtinTypes } from "./builtins.js";
 import { libraryChild, libraryRelative, standardLibraries } from "./libraries.js";
-import { projectPackages, readPackage, sourcePaths } from "./package-manager.js";
+import { packageSpecifications, projectPackages, readPackage, sourcePaths } from "./package-manager.js";
+import { isGitSource, sourceAlias } from "./git-packages.js";
 export function isPrivateName(name) { return name.startsWith('_'); }
 function diagnostic(file, line, column, message, code) {
     return { file, line, column, message, code };
@@ -35,7 +36,7 @@ export function loadProject(projectRoot, overrides = new Map(), cache) {
     const { config, diagnostics } = loadConfig(root);
     let library;
     let sourceRoot = root;
-    if (existsSync(join(root, 'aug-package.json'))) {
+    if (existsSync(join(root, 'aug-package.json')) || !existsSync(join(root, 'main.aug')) && (existsSync(join(root, 'export.aug')) || existsSync(join(root, 'src/export.aug')))) {
         try {
             const loaded = readPackage(root);
             library = loaded.manifest;
@@ -45,7 +46,7 @@ export function loadProject(projectRoot, overrides = new Map(), cache) {
             diagnostics.push(diagnostic(join(root, 'aug-package.json'), 1, 1, error.message, 'PACKAGE'));
         }
     }
-    const packages = projectPackages(root, library?.dependencies ?? config.packages, sourceRoot);
+    const packages = projectPackages(root, packageSpecifications(sourceRoot, library?.dependencies ?? config.packages, overrides), sourceRoot);
     diagnostics.push(...packages.diagnostics);
     const read = (path) => {
         const source = overrides.get(path) ?? readFileSync(path, 'utf8');
@@ -56,7 +57,7 @@ export function loadProject(projectRoot, overrides = new Map(), cache) {
         cache?.set(path, parsed);
         return parsed;
     };
-    for (const path of new Set([...sourceFiles(sourceRoot), ...overrides.keys()].filter(path => path.endsWith('.aug')))) {
+    for (const path of new Set([...sourceFiles(sourceRoot), ...[...overrides.keys()].filter(path => path.startsWith(sourceRoot + '/') || path.startsWith(sourceRoot + '\\'))].filter(path => path.endsWith('.aug')))) {
         const parsed = read(path);
         files.set(path, parsed.file);
         diagnostics.push(...parsed.diagnostics);
@@ -70,7 +71,7 @@ export function loadProject(projectRoot, overrides = new Map(), cache) {
         }
     const libraries = standardLibraries();
     const stdlibRoot = libraries.root;
-    const libraryFiles = new Set([stdlibRoot, ...libraries.modules.values()].flatMap(sourceFiles));
+    const libraryFiles = new Set([join(stdlibRoot, 'export.aug'), ...sourceFiles(join(stdlibRoot, 'io'))]);
     for (const path of libraryFiles) {
         const parsed = read(path);
         parsed.file.builtin = true;
@@ -216,7 +217,7 @@ export function loadProject(projectRoot, overrides = new Map(), cache) {
             }
             return result;
         };
-        const privateModule = item.from.find(isPrivateName);
+        const privateModule = item.from.slice(isGitSource(item.from[0]) ? 1 : 0).find(isPrivateName);
         if (privateModule) {
             diagnostics.push(diagnostic(importer, item.span.line, item.span.column, `Cannot import from private module ${privateModule}`, 'PRIVATE'));
             return result;
@@ -234,7 +235,8 @@ export function loadProject(projectRoot, overrides = new Map(), cache) {
         }
         const owner = files.get(importer)?.package;
         const ownerScope = owner ? packages.scopes.get(owner) : undefined;
-        const dependency = ownerScope ? packages.scopes.get(ownerScope.dependencies[item.from[0]]) : packages.roots.get(item.from[0]);
+        const alias = isGitSource(item.from[0]) ? sourceAlias(item.from[0]) : item.from[0];
+        const dependency = ownerScope ? packages.scopes.get(ownerScope.dependencies[alias]) : packages.roots.get(alias);
         if (dependency) {
             let folder = dependency.sourceRoot;
             for (const child of item.from.slice(1)) {

package/src/semantic.js

@@ -11,6 +11,7 @@ import { javadocBefore } from "./javadoc.js";
 import { checkUnitTests, discoverTests, mergeTestAnalysis, uniqueDiagnostics } from "./testing.js";
 import { formatFile } from "./formatter.js";
 import { interceptorBehavior } from "./interceptors.js";
+import { callableResult, callableErrors } from "./contracts.js";
 const genericFacts = (header) => header.typeParams.map(name => ({ name,
     variance: header.typeVariance?.[name] ?? 'invariant', constraints: (header.typeConstraints?.[name] ?? []).map(typeName) }));
 export function contractFacts(checked) {
@@ -25,11 +26,12 @@ export function contractFacts(checked) {
                 streaming: !!method.endpoint.streams, errors: method.endpoint.errors.map(error => ({ type: typeName(error.type), status: error.status })) } : undefined,
             policies: (checked.httpPolicies.get(method) ?? []).map((policy, index) => ({ name: policy.name, order: index + 1, options: policy.options,
                 dependencies: policy.dependencies.map(index => method.params[index]?.label ?? method.params[index]?.name ?? '') })),
-            result: `${method.returnOwnership === 'own' ? 'own ' : ''}${typeName(method.returns)}`,
+            result: `${method.returnOwnership === 'own' ? 'own ' : ''}${tyName(callableResult(checked, method))}`,
             changes: [...(contract?.changes ?? method.changes ?? [])],
             capabilities: [...(contract?.uses.values() ?? [])].map(effect => `${effect.source}.${effect.operation}`).concat(method.externC ? [`C.${method.name}`] : []),
             inferredEffects: !!contract?.inferred,
-            errors: [...new Set([...method.throws.map(typeName), ...layers.flatMap(layer => layer.errors.map(tyName))])],
+            errors: constructor ? [...new Set([...(checked.constructorContracts.get(constructor)?.errors.map(tyName) ?? constructor.validationErrors?.map(typeName) ?? []),
+                    ...layers.flatMap(layer => layer.errors.map(tyName))])].sort() : callableErrors(checked, method),
             interceptors: layers.map((layer, order) => {
                 const effects = checked.effectContracts.get(layer.around);
                 return { name: layer.definition.name, order: order + 1, location: layer.definition.node.span,
@@ -186,6 +188,48 @@ export class SemanticDocument {
     complete(offset) { return completions(this.checked, this.path, offset); }
     tokens() { return semanticTokens(this.checked, this.path); }
     fixes() { return suggestedFixes(this.checked, this.path); }
+    /** Non-editable declaration hints. Formatting never adds inferred source clauses. */
+    inlayHints(start = 0, end = this.source.length) {
+        const hints = [];
+        for (const [method, contract] of this.checked.callableContracts) {
+            if (method.span.file !== this.path || !method.body || method.headerEnd === undefined)
+                continue;
+            let offset = method.headerEnd;
+            while (offset > method.span.start && /\s/.test(this.source[offset - 1]))
+                offset--;
+            if (offset < start || offset > end)
+                continue;
+            const clauses = [];
+            if (contract.inferredResult && contract.result.kind !== 'error' && contract.result.name !== 'void')
+                clauses.push(contract.result.name === '<target result>' ? 'returns the target result' : `returns ${tyName(contract.result)}`);
+            const effects = this.checked.effectContracts.get(method);
+            if (effects?.inferredChanges && effects.changes.length)
+                clauses.push(`changes ${effects.changes.join(' and ')}`);
+            const uses = [...(effects?.uses.values() ?? [])].map(effect => `${effect.source}.${effect.operation}`).sort();
+            if (effects?.inferred && uses.length)
+                clauses.push(`uses ${[...new Set(uses)].join(' and ')}`);
+            const errors = callableErrors(this.checked, method);
+            if (contract.inferredErrors && errors.length)
+                clauses.push(`unless ${errors.join(' and ')}`);
+            const complete = clauses.join(' ');
+            const compact = complete.length > 120 ? clauses.map(clause => clause.startsWith('uses ') && clause.length > 50 ? `uses ${new Set(uses).size} operations` :
+                clause.startsWith('unless ') && clause.length > 50 ? `unless ${errors.length} errors` : clause).join(' ') : complete;
+            if (clauses.length)
+                hints.push({ offset, label: compact,
+                    tooltip: `\`\`\`augscript\n${complete}\n\`\`\`\n\n` + 'Inferred from the body, implemented interface, and interceptor layers. These hints are not source text. The compiler still checks ownership, interface limits, and escaping errors. See the adjacent .aug.md spec for the full explanation.' });
+        }
+        for (const [record, contract] of this.checked.constructorContracts) {
+            if (record.span.file !== this.path || !contract.inferredErrors || !contract.errors.length || record.headerEnd === undefined)
+                continue;
+            let offset = record.headerEnd;
+            while (offset > record.span.start && /\s/.test(this.source[offset - 1]))
+                offset--;
+            if (offset >= start && offset <= end)
+                hints.push({ offset, label: 'unless ' + contract.errors.map(tyName).sort().join(' and '),
+                    tooltip: 'Checked errors inferred from record validation. Callers must catch or propagate them. These hints are not saved source.' });
+        }
+        return hints.sort((left, right) => left.offset - right.offset);
+    }
     format() { return formatFile(this.checked.project, this.checked.project.files.get(this.path)); }
     describe(options) { return describe(this.checked, this.path, options); }
     definition(offset) {

package/src/snippets.js

@@ -0,0 +1,59 @@
+/** Small starting points for ordinary August declarations and statements. */
+export const snippetCatalog = [
+    { prefix: 'record', description: 'Immutable data with named fields', body: 'record ${1:User}(${2:string name})' },
+    { prefix: 'interface', description: 'A public behavior contract', body: 'interface ${1:Greeter}:\n    ${2:greet}(${3:string name}) returns ${4:string}' },
+    { prefix: 'capability', description: 'An explicit I/O contract', body: 'capability ${1:Logger}:\n    ${2:log}(${3:string message}) uses ${1:Logger}.${2:log}' },
+    { prefix: 'implementation', description: 'A class implementing an interface', body: '${1:SimpleGreeter}(${2:resolve Logger logger}) implements ${3:Greeter}:\n    ${4:greet}(${5:string name}):\n        $0' },
+    { prefix: 'method', description: 'A function or method with an inferred result', body: '${1:calculate}(${2:int value}):\n    $0' },
+    { prefix: 'generic', description: 'A generic identity function', body: '${1:identity}<T>(T value):\n    return value' },
+    { prefix: 'initialize', description: 'Initialize constructor fields or validate a record', body: 'initialize:\n    $0' },
+    { prefix: 'import', description: 'Import a public declaration', body: 'import ${1:Name} from ${2:module}' },
+    { prefix: 'importurl', description: 'Import directly from a public Git repository', body: 'import ${1:Name} from "https://github.com/${2:owner}/${3:library}"' },
+    { prefix: 'export', description: 'Expose one declaration from a sibling file', body: 'export ${1:Name} from ${2:file}' },
+    { prefix: 'exportfolder', description: 'Expose a child module with its own export.aug', body: 'export folder ${1:module}' },
+    { prefix: 'implement', description: 'Select a dependency provider in main.aug', body: 'implement ${1:Contract} with ${2:Provider}' },
+    { prefix: 'resolve', description: 'Resolve a dependency explicitly', body: 'resolve ${1:Contract} to ${2:service}' },
+    { prefix: 'if', description: 'Conditional code', body: 'if ${1:condition}:\n    $0' },
+    { prefix: 'ifelse', description: 'Two alternatives', body: 'if ${1:condition}:\n    $2\nelse:\n    $0' },
+    { prefix: 'for', description: 'Visit collection values', body: 'for ${1:item} in ${2:items}:\n    $0' },
+    { prefix: 'while', description: 'Repeat while a condition holds', body: 'while ${1:condition}:\n    $0' },
+    { prefix: 'matchoptional', description: 'Handle a value or null', body: 'match ${1:value}:\n    when some ${2:item}:\n        $3\n    when null:\n        $0' },
+    { prefix: 'try', description: 'Recover from a checked failure', body: 'try:\n    $1\ncatch ${2:FileError} ${3:error}:\n    $0' },
+    { prefix: 'borrow', description: 'Grant bounded mutable access', body: 'borrow ${1:value}:\n    $0' },
+    { prefix: 'scope', description: 'Start and join a child computation', body: 'scope:\n    ${1:pending} = start ${2:load}(${3:})\n    wait for ${1:pending} as ${4:result}\n    $0' },
+    { prefix: 'waitall', description: 'Join two computations', body: 'wait for ${1:loadingUsers} and ${2:loadingOrders} as ${3:users} and ${4:orders}' },
+    { prefix: 'lock', description: 'Access shared mutable state inside a bounded lock', body: 'lock ${1:shared} as ${2:value}:\n    $0' },
+    { prefix: 'unsafe', description: 'Contain a native C call', body: 'unsafe:\n    $0' },
+    { prefix: 'serve', description: 'Start a native HTTP listener', body: 'serve ${1:endpoint} on port ${2:8787}' },
+    ...['GET', 'POST', 'PATCH', 'DELETE'].map(method => ({ prefix: 'endpoint' + method.toLowerCase(), description: `A typed ${method} endpoint`, body: `endpoint ${method} "\${1:/items}" as \${2:handler}(\${3:}):\n    $0` })),
+    { prefix: 'stream', description: 'An endpoint yielding server-sent events', body: 'endpoint GET "${1:/events}" as ${2:events}() streams ServerEvent<string>:\n    yield ServerEvent(data=${3:"hello"})' },
+    { prefix: 'component', description: 'An embeddable server-rendered HTML component', body: '${1:Heading}(string text) returns Html:\n    return <h1>{text}</h1>' },
+    { prefix: 'test', description: 'A same-file function test', body: 'test ${1:calculate}:\n    when ${2:inputs}:\n        it ${3:works}:\n            assert(condition=${4:true})' },
+    { prefix: 'testclass', description: 'Fresh setup for each class test', body: 'test ${1:Worker} ${2:worker}:\n    when ${3:ready}:\n        ${2:worker} = ${1:Worker}(${4:})\n        it ${5:works}:\n            assert(condition=${6:true})' },
+    { prefix: 'testendpoint', description: 'Exercise the real endpoint pipeline', body: 'test endpoint ${1:handler} client:\n    when requests:\n        it succeeds:\n            response = client.request(method="GET", path="${2:/items}")\n            assert(condition=response.status == 200)' },
+    { prefix: 'it', description: 'A named test case', body: 'it ${1:works}:\n    assert(condition=${2:true})' },
+    { prefix: 'fixture', description: 'A reusable same-file test fixture', body: 'fixture ${1:sample}():\n    return ${2:42}' },
+    { prefix: 'interceptor', description: 'Wrap a call and preserve its result', body: 'interceptor ${1:Audit}<T>():\n    around():\n        result = next()\n        $0\n        return result' },
+    { prefix: 'javadoc', description: 'Document intent and labeled inputs', body: '/**\n * ${1:Explain why this declaration exists.}\n * @param ${2:name} ${3:What the input means.}\n */' },
+];
+export function snippetBody(body, style, tabs = false) {
+    if (style === 'braces') {
+        const result = [];
+        let depth = 0;
+        for (const line of body.split('\n')) {
+            const level = Math.floor((/^ */.exec(line)?.[0].length ?? 0) / 4);
+            while (depth > level)
+                result.push('    '.repeat(--depth) + '}');
+            if (line.endsWith(':')) {
+                result.push(line.slice(0, -1) + ' {');
+                depth = level + 1;
+            }
+            else
+                result.push(line);
+        }
+        while (depth)
+            result.push('    '.repeat(--depth) + '}');
+        body = result.join('\n');
+    }
+    return tabs ? body.replace(/^(?: {4})+/gm, prefix => '\t'.repeat(prefix.length / 4)) : body;
+}

package/src/spec-hints.js

@@ -0,0 +1,56 @@
+import { existsSync, lstatSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { basename, dirname, relative } from 'node:path';
+import { checkProject } from "./checker.js";
+import { loadProject } from "./project.js";
+import { checkUnitTests, discoverTests, mergeTestAnalysis } from "./testing.js";
+const marker = '// aug-spec: ';
+/** One compiler-managed pointer. It gives readers an action and a precise neighboring filename. */
+export function specHint(file) {
+    const newline = file.source.includes('\r\n') ? '\r\n' : '\n';
+    const pointer = marker + JSON.stringify(basename(file.path) + '.md') + ' explains this file. Read it before changes; refresh with aug spec.' + newline;
+    const old = file.source.startsWith(marker) ? (file.source.includes('\n') ? file.source.indexOf('\n') + 1 : file.source.length) : 0;
+    const body = old ? file.source.slice(old) : file.source;
+    return { file, text: pointer + body, lineOffset: old ? 0 : 1 };
+}
+/** Prepare hints before native emission so debugger/source-map lines use the updated sources. */
+export function updateSpecHints(checked) {
+    const hints = [...checked.project.files.values()].filter(file => !file.builtin && !file.package).map(specHint)
+        .filter(hint => hint.text !== hint.file.source);
+    if (!hints.length)
+        return checked;
+    if (checked.diagnostics.some(issue => issue.severity !== 'warning'))
+        throw new Error('Fix compiler errors before adding specification pointers');
+    for (const { file } of hints) {
+        const root = checked.project.root;
+        if (relative(root, file.path).startsWith('..'))
+            throw new Error('Specification pointer escapes the project');
+        let parent = dirname(file.path);
+        while (parent !== root && parent !== dirname(parent)) {
+            if (lstatSync(parent).isSymbolicLink())
+                throw new Error('Specification source directory is a symbolic link');
+            parent = dirname(parent);
+        }
+        if (lstatSync(file.path).isSymbolicLink())
+            throw new Error('Specification source is a symbolic link');
+        if (readFileSync(file.path, 'utf8') !== file.source)
+            throw new Error('Source changed during compilation; retry before generating specifications');
+    }
+    for (const { file, text } of hints) {
+        const temporary = file.path + '.aug-spec-tmp';
+        let created = false;
+        try {
+            writeFileSync(temporary, text, { flag: 'wx', mode: lstatSync(file.path).mode });
+            created = true;
+            renameSync(temporary, file.path);
+        }
+        finally {
+            if (created && existsSync(temporary))
+                rmSync(temporary);
+        }
+    }
+    const project = loadProject(checked.project.root), fresh = checkProject(project), discovery = discoverTests(project);
+    const tests = checkUnitTests(project, discovery.tests);
+    fresh.diagnostics.push(...discovery.diagnostics, ...tests.flatMap(test => test.checked.diagnostics));
+    mergeTestAnalysis(fresh, tests);
+    return fresh;
+}

package/src/spec-tree.js

@@ -0,0 +1,241 @@
+export const step = (text) => ({ kind: 'step', text });
+export const action = (verb, object) => ({ kind: 'action', verb, object });
+export const sequence = (lead, items, infinitive) => ({ kind: 'sequence', lead, items, infinitive });
+export const branch = (condition, then, otherwise = []) => ({ kind: 'branch', condition, then, otherwise });
+export const loop = (lead, children, end) => ({ kind: 'loop', lead, children, end });
+export const choice = (value, cases) => ({ kind: 'choice', value, cases });
+export const attempt = (children, catches, always) => ({ kind: 'attempt', children, catches, always });
+export const scope = (lead, children, end) => ({ kind: 'scope', lead, children, end });
+export const paragraph = (text) => ({ kind: 'paragraph', text });
+export const flow = (steps) => ({ kind: 'flow', steps });
+export const section = (title, level, children, anchor, source) => ({ kind: 'section', title, level, anchor, source, children });
+/** Coordination is grammatical only; callers retain the original evaluation order. */
+export function coordinate(items, conjunction = 'and') {
+    return items.length < 2 ? items[0] ?? '' : items.length === 2 ? items.join(` ${conjunction} `) :
+        items.slice(0, -1).join(', ') + `, ${conjunction} ` + items.at(-1);
+}
+const clause = (text) => text.charAt(0).toLowerCase() + text.slice(1).replace(/\.$/, '');
+const bare = (text) => clause(text).replace(/^it /, '');
+const visible = (text) => text.replace(/\[([^\]]+)\]\([^)]*\)/g, '$1').replace(/[`*_]/g, '');
+const words = (text) => visible(text).split(/\s+/).filter(Boolean).length;
+const sentencesIn = (text) => (text.replace(/(`+)[\s\S]*?\1/g, '').match(/[.!?](?:\s|$)/g) ?? []).length;
+/** Small deterministic microplanner. A clause may join only other clauses in its own scope. */
+export function planFlow(nodes) {
+    const sentence = (text, sources = [], boundary = false) => ({ text, sources, boundary });
+    const plan = (children) => {
+        const result = [];
+        let transition = '';
+        const append = (items) => {
+            if (transition && items.length)
+                items[0].text = transition + ', ' + clause(items[0].text) + '.';
+            transition = '';
+            result.push(...items);
+        };
+        for (let index = 0; index < children.length; index++) {
+            const node = children[index];
+            const setting = node.kind === 'action' && node.verb === 'set' ? node.object.match(/^(`[^`]+`) to (.+)$/) : undefined;
+            if (setting) {
+                const settings = [node];
+                while (index + 1 < children.length) {
+                    const next = children[index + 1], match = next.kind === 'action' && next.verb === 'set' ? next.object.match(/^(`[^`]+`) to (.+)$/) : undefined;
+                    if (!match || match[2] !== setting[2])
+                        break;
+                    settings.push(next);
+                    index++;
+                }
+                if (settings.length > 1) {
+                    append([sentence('It sets ' + coordinate(settings.map(item => item.object.match(/^(`[^`]+`)/)[1])) +
+                            ' separately, each to ' + setting[2] + '.', settings.flatMap(item => item.source ? [item.source] : []))]);
+                    continue;
+                }
+            }
+            // Adjacent validation guards have one outcome. Explain the checks together,
+            // retaining every guard and failure in the evidence ledger.
+            if (node.kind === 'branch' && node.requirement && !node.otherwise.length) {
+                const guards = [node];
+                while (index + 1 < children.length) {
+                    const next = children[index + 1];
+                    if (next.kind !== 'branch' || !next.requirement || next.otherwise.length || next.then[0]?.kind !== 'action' || node.then[0]?.kind !== 'action' ||
+                        next.then[0].object !== node.then[0].object || words(guards.map(guard => guard.requirement).join(' ') + next.requirement) > 65)
+                        break;
+                    guards.push(next);
+                    index++;
+                }
+                const failure = node.then[0];
+                append([sentence('It checks that ' + coordinate(guards.map(guard => guard.requirement)) + '. It raises ' + failure.object.replace(/^with /, '') + ' at the first failed check.', guards.flatMap(guard => [...(guard.source ? [guard.source] : []), ...plan(guard.then).flatMap(item => item.sources)]))]);
+            }
+            else {
+                append(realize(node, index < children.length - 1));
+                if (node.kind === 'loop')
+                    transition = 'After the loop';
+                if (node.kind === 'branch' && (!compact(node.then) && !exits(node.then) || node.otherwise.length && !compact(node.otherwise) && !exits(node.otherwise)))
+                    transition = 'After that conditional work';
+            }
+        }
+        return result;
+    };
+    const compact = (children) => {
+        if (!children.length)
+            return sentence('Do nothing.');
+        if (children.length > 3 || children.some(child => !['step', 'action', 'sequence'].includes(child.kind)))
+            return;
+        const sentences = plan(children);
+        if (sentences.some(item => item.boundary || words(item.text) > 42) || words(sentences.map(item => item.text).join(' ')) > 55)
+            return;
+        return { ...sentence(sentences.map(item => item.text).join(' '), sentences.flatMap(item => item.sources)),
+            infinitive: sentences.every(item => item.infinitive) ? sentences.map(item => item.infinitive).join(', then ') : undefined };
+    };
+    const exits = (children) => {
+        const last = children.at(-1);
+        if (!last)
+            return false;
+        return last.kind === 'action' ? (last.verb === 'return' || last.verb === 'fail') :
+            last.kind === 'branch' ? exits(last.then) && exits(last.otherwise) :
+                last.kind === 'scope' ? exits(last.children) :
+                    last.kind === 'attempt' ? exits(last.children) && last.catches.every(handler => exits(handler.children)) : false;
+    };
+    const under = (lead, children, end) => {
+        const continuation = /(?: and| always| it)$/.test(lead);
+        const join = continuation ? ' ' : ', ';
+        const small = compact(children);
+        if (small) {
+            // One guard governs a coordinated sequence, never an adjacent outer statement.
+            const items = plan(children);
+            return [sentence(`${lead}${join}${items.length ? items.map((item, index) => (index ? 'then ' : '') + (continuation && !index ? bare(item.text) : clause(item.text))).join('; ') : continuation ? 'does nothing' : 'it does nothing'}.`, small.sources)];
+        }
+        const items = plan(children);
+        if (!items.length)
+            return [sentence(`${lead}${join}it does nothing.`)];
+        items[0].text = lead + join + (continuation ? bare(items[0].text) : clause(items[0].text)) + '.';
+        // The paragraph itself expresses the scope. Only loops and resource scopes
+        // need an exit contract; avoid narrating the edges of the syntax tree.
+        return items;
+    };
+    const realize = (node, hasNext) => {
+        let result;
+        switch (node.kind) {
+            case 'step':
+                result = [sentence(node.text)];
+                break;
+            case 'action': {
+                const verbs = { set: 'sets', split: 'splits', call: 'calls', construct: 'creates', evaluate: 'evaluates', return: 'returns', fail: 'raises', send: 'sends', freeze: 'freezes', serve: 'serves', increase: 'increases', decrease: 'decreases', continue: 'continues' };
+                const object = node.object ? ' ' + node.object : '';
+                const realized = node.verb === 'fail' ? `It raises ${node.object.replace(/^with /, '')}.` : `It ${verbs[node.verb]}${object}.`;
+                result = [{ ...sentence(realized), infinitive: node.verb === 'fail' ? 'raise ' + node.object.replace(/^with /, '') : node.verb + object }];
+                break;
+            }
+            case 'sequence':
+                result = [{ ...sentence(`${node.lead}: ${coordinate(node.items)}.`),
+                        infinitive: node.infinitive ? node.infinitive + ': ' + coordinate(node.items) : undefined }];
+                break;
+            case 'branch': {
+                const yes = node.then[0], no = node.otherwise[0];
+                if (node.then.length === 1 && node.otherwise.length === 1 && yes.kind === 'action' && no.kind === 'action' && yes.verb === 'return' && no.verb === 'return')
+                    result = [sentence(`It returns ${yes.object} if ${node.condition}, or ${no.object} otherwise.`, [...(yes.source ? [yes.source] : []), ...(no.source ? [no.source] : [])])];
+                else
+                    result = [...under('If ' + node.condition, node.then, ''), ...(node.otherwise.length ? under('Otherwise', node.otherwise, '') : [])];
+                break;
+            }
+            case 'loop':
+                result = under(node.lead, node.children, node.end);
+                break;
+            case 'choice': {
+                result = node.cases.length > 2 || node.cases.some(item => item.condition.includes(' satisfies ')) ?
+                    [sentence('It handles ' + node.value + ' with the first matching case.')] : [];
+                for (const alternative of node.cases)
+                    result.push(...under(alternative.condition, alternative.children, alternative.end ?? 'This ends that case.'));
+                break;
+            }
+            case 'attempt': {
+                const small = compact(node.children);
+                result = small?.infinitive || !node.children.length ? [sentence(node.children.length ? 'It tries to ' + small.infinitive + '.' : 'This attempt has no operation.', small?.sources ?? [], true)] :
+                    plan(node.children);
+                for (const handler of node.catches) {
+                    const used = plan(handler.children).some(item => visible(item.text).includes(visible(handler.name)));
+                    result.push(...under(`If this work raises ${handler.error}${used ? ' as ' + handler.name : ''}, it`, handler.children, ''));
+                }
+                if (node.always !== undefined)
+                    result.push(...under('Whether it succeeds or fails, it always', node.always, ''));
+                break;
+            }
+            case 'scope':
+                result = [...under(node.lead, node.children, ''), ...(node.end ? [sentence(node.end)] : [])];
+                break;
+        }
+        if (node.source)
+            result[0].sources.unshift(node.source);
+        return result;
+    };
+    const sentences = plan(nodes), paragraphs = [];
+    let current = '';
+    for (const item of sentences) {
+        if (current && (item.boundary || words(current + ' ' + item.text) > 110 || sentencesIn(current + ' ' + item.text) > 4)) {
+            paragraphs.push(current);
+            current = '';
+        }
+        current += (current ? ' ' : '') + item.text;
+    }
+    if (current)
+        paragraphs.push(current);
+    const sources = sentences.flatMap(item => item.sources);
+    const evidence = (node) => {
+        const children = node.kind === 'branch' ? [...node.then, ...node.otherwise] : node.kind === 'choice' ? node.cases.flatMap(item => item.children) :
+            node.kind === 'attempt' ? [...node.children, ...node.catches.flatMap(item => item.children), ...(node.always ?? [])] :
+                node.kind === 'loop' || node.kind === 'scope' ? node.children : [];
+        return [...(node.source ? [node.source] : []), ...children.flatMap(evidence)];
+    };
+    if (JSON.stringify(sources) !== JSON.stringify(nodes.flatMap(evidence)))
+        throw new Error('Specification planning lost or reordered source facts');
+    return { paragraphs, sources };
+}
+function renderChildren(children) {
+    const blocks = [];
+    let current = '';
+    const flush = () => { if (current)
+        blocks.push(current); current = ''; };
+    const add = (text) => {
+        if (!text.trim())
+            return;
+        // Author Markdown keeps its structure; generated contracts and small bodies form connected prose.
+        if (text.includes('\n')) {
+            flush();
+            blocks.push(text.trim());
+            return;
+        }
+        if (current && (words(current + ' ' + text) > 110 || sentencesIn(current + ' ' + text) > 4))
+            flush();
+        current += (current ? ' ' : '') + text.trim();
+    };
+    for (const child of children) {
+        if (child.kind === 'paragraph')
+            add(child.text);
+        else if (child.kind === 'flow') {
+            const paragraphs = planFlow(child.steps).paragraphs;
+            if (paragraphs.length)
+                add(paragraphs[0]);
+            for (const text of paragraphs.slice(1)) {
+                flush();
+                add(text);
+            }
+        }
+        else {
+            flush();
+            blocks.push(renderNode(child));
+        }
+    }
+    flush();
+    return blocks.join('\n\n');
+}
+function renderNode(node) {
+    switch (node.kind) {
+        case 'paragraph': return node.text.trim();
+        case 'flow': return planFlow(node.steps).paragraphs.join('\n\n');
+        case 'section': {
+            const heading = `${node.anchor ? `<a id="${node.anchor}"></a>\n` : ''}${'#'.repeat(node.level)} ${node.title}${node.source ? ' · ' + node.source : ''}`;
+            const body = renderChildren(node.children);
+            return heading + (body ? '\n\n' + body : '');
+        }
+    }
+}
+/** Lay out planned prose with one blank line between paragraphs. */
+export function renderSpecTree(root) { return renderNode(root).trimEnd() + '\n'; }