@greenpandastudios/aug-cli 0.19.0 → 0.21.0

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'; }