@turri-dev/cli 0.0.0-stage → 0.1.2-next.48dacfc

package/dist/plain/plain.tmLanguage.json

@@ -0,0 +1,124 @@
+{
+    "$schema": "https://raw.githubusercontent.com/martinring/tmlanguage/master/tmlanguage.json",
+    "name": "***plain",
+    "patterns": [
+        {
+            "include": "#keywords"
+        },
+        {
+            "include": "#strings"
+        },
+        {
+            "include": "#variables"
+        },
+        {
+            "include": "#classes"
+        },
+        {
+            "include": "#comments"
+        },
+        {
+            "include": "#functions"
+        },
+        {
+            "include": "#modules"
+        },
+        {
+            "include": "#punctuation"
+        },
+        {
+            "include": "#strings"
+        }
+    ],
+    "repository": {
+        "keywords": {
+            "patterns": [
+                {
+                    "name": "entity.name.function.plain",
+                    "match": "\\*\\*\\*(definitions|implementation reqs|test reqs|functional specs|acceptance tests)\\*\\*\\*"
+                },
+                {
+                    "name": "meta.frontmatter.plain",
+                    "begin": "^---$",
+                    "end": "^---$",
+                    "patterns": [
+                        {
+                            "name": "keyword.control.import.plain",
+                            "match": "^\\s*(description):"
+                        },
+                        {
+                            "name": "keyword.control.import.plain",
+                            "match": "^\\s*(required_concepts):"
+                        },
+                        {
+                            "name": "keyword.control.import.plain",
+                            "match": "^\\s*(exported_concepts):"
+                        },
+                        {
+                            "name": "keyword.control.import.plain",
+                            "match": "^\\s*(import):"
+                        },
+                        {
+                            "name": "keyword.control.requires.plain",
+                            "match": "^\\s*(requires):"
+                        },
+                        {
+                            "match": "^\\s*-\\s+([a-zA-Z_][a-zA-Z0-9_]*)",
+                            "captures": {
+                                "1": {
+                                    "name": "entity.name.type.class.plain"
+                                }
+                            }
+                        },
+                        {
+                            "name": "variable.parameter.plain",
+                            "match": ":[^\\s]+?:"
+                        }
+                    ]
+                },
+                {
+                    "name": "variable.parameter.plain",
+                    "match": ":[^\\s]+?:"
+                },
+                {
+                    "name": "comment.line.plain",
+                    "match": "^>.*$"
+                },
+                {
+                    "name": "entity.name.function.plain",
+                    "match": "\\\"\\{\\{.*?\\}\\}\\\""
+                },
+                {
+                    "name": "entity.name.module.plain",
+                    "begin": "\\{%\\s*include",
+                    "end": "%\\}"
+                },
+                {
+                    "name": "entity.punctuation.definition.bullet.plain",
+                    "match": "^\\s*-"
+                }
+            ]
+        },
+        "strings": {
+            "patterns": [
+                {
+                    "name": "string.quoted.other.plain",
+                    "match": "\\[[^)]+\\]\\([^\\]]+\\)"
+                },
+                {
+                    "name": "string.quoted.double.plain",
+                    "match": "\"[^\"]*\""
+                },
+                {
+                    "name": "string.quoted.other.backtick.plain",
+                    "match": "`[^`]*`"
+                },
+                {
+                    "name": "string.quoted.other.angle.plain",
+                    "match": "<[^<>]+>"
+                }
+            ]
+        }
+    },
+    "scopeName": "source.plain"
+}

package/dist/plain/spec.js

@@ -0,0 +1,291 @@
+import { createHash } from "node:crypto";
+import { InvalidFridArgument } from "./errors.js";
+/** Port of plain_spec.py. */
+export const DEFINITIONS = "definitions";
+export const NON_FUNCTIONAL_REQUIREMENTS = "implementation reqs";
+export const TEST_REQUIREMENTS = "test reqs";
+export const FUNCTIONAL_REQUIREMENTS = "functional specs";
+export const ACCEPTANCE_TESTS = "acceptance_tests";
+export const ACCEPTANCE_TEST_HEADING = "acceptance tests";
+/**
+ * Where a module's tree carries the functional specs it inherits through `requires`: every
+ * functional spec of every module it requires, transitively, bottom of the chain first.
+ * Kept apart from its own, which are numbered 1, 2, 3 on their own.
+ */
+export const REQUIRED_FUNCTIONAL_SPECS = "required functional specs";
+export const ALLOWED_SPECIFICATION_HEADINGS = [
+    DEFINITIONS,
+    NON_FUNCTIONAL_REQUIREMENTS,
+    TEST_REQUIREMENTS,
+    FUNCTIONAL_REQUIREMENTS,
+    ACCEPTANCE_TEST_HEADING,
+];
+export const ALLOWED_IMPORT_SPECIFICATION_HEADINGS = [
+    DEFINITIONS,
+    NON_FUNCTIONAL_REQUIREMENTS,
+    TEST_REQUIREMENTS,
+];
+/**
+ * The functional specs a module inherits through `requires`, rendered: each with its
+ * module, its id there, and its acceptance tests.
+ */
+export function getInheritedFunctionalSpecs(tree, replaceCodeVariables = true) {
+    const items = tree[REQUIRED_FUNCTIONAL_SPECS] ?? [];
+    return items.map((item) => {
+        const codeVariables = {};
+        const tests = item[ACCEPTANCE_TESTS];
+        return {
+            module: item.module,
+            frid: item.frid,
+            spec: getSpecificationItemMarkdown(item, codeVariables, replaceCodeVariables),
+            acceptanceTests: tests?.map((test) => getSpecificationItemMarkdown(test, codeVariables, replaceCodeVariables)),
+        };
+    });
+}
+export function getSpecificationItems(tree, heading) {
+    const value = tree[heading];
+    return Array.isArray(value) ? value : undefined;
+}
+export function hasAcceptanceTests(tree) {
+    for (const requirement of getSpecificationItems(tree, FUNCTIONAL_REQUIREMENTS) ?? []) {
+        const tests = requirement[ACCEPTANCE_TESTS];
+        if (tests !== undefined && tests.length > 0)
+            return true;
+    }
+    return false;
+}
+export function collectSpecificationLinkedResources(specification, specificationHeading, linkedResourcesList) {
+    for (const resource of specification.linked_resources ?? []) {
+        let resourceFound = false;
+        for (const resourceMap of linkedResourcesList) {
+            if (resource.text === resourceMap.text) {
+                if (resource.target !== resourceMap.target) {
+                    throw new Error(`The file ${resource.target} is linked to multiple linked resources with the same text: ${resource.text}`);
+                }
+            }
+            else if (resource.target === resourceMap.target) {
+                if (resource.text !== resourceMap.text) {
+                    throw new Error(`The linked resource ${resource.text} is linked to multiple files: ${resourceMap.target}`);
+                }
+            }
+            else {
+                continue;
+            }
+            if (resourceFound) {
+                throw new Error(`Duplicate linked resource found: ${resource.text} (${resource.target})`);
+            }
+            resourceFound = true;
+            resourceMap.sections.push(specificationHeading);
+        }
+        if (!resourceFound) {
+            linkedResourcesList.push({
+                text: resource.text,
+                target: resource.target,
+                sections: [specificationHeading],
+            });
+        }
+    }
+}
+export function collectLinkedResourcesInSection(section, linkedResourcesList, specificationsList, includeAcceptanceTests, frid) {
+    let toCollect = [DEFINITIONS, NON_FUNCTIONAL_REQUIREMENTS, TEST_REQUIREMENTS];
+    if (specificationsList && specificationsList.length > 0) {
+        toCollect = toCollect.filter((heading) => specificationsList.includes(heading));
+    }
+    for (const heading of toCollect) {
+        for (const requirement of getSpecificationItems(section, heading) ?? []) {
+            collectSpecificationLinkedResources(requirement, heading, linkedResourcesList);
+        }
+    }
+    const functionalRequirements = getSpecificationItems(section, FUNCTIONAL_REQUIREMENTS);
+    if (functionalRequirements !== undefined &&
+        (!specificationsList ||
+            specificationsList.length === 0 ||
+            specificationsList.includes(FUNCTIONAL_REQUIREMENTS))) {
+        let count = 0;
+        for (const requirement of functionalRequirements) {
+            collectSpecificationLinkedResources(requirement, FUNCTIONAL_REQUIREMENTS, linkedResourcesList);
+            count += 1;
+            const currentFrid = String(count);
+            const tests = requirement[ACCEPTANCE_TESTS];
+            if (tests !== undefined && includeAcceptanceTests && (frid === null || frid === currentFrid)) {
+                for (const test of tests) {
+                    collectSpecificationLinkedResources(test, FUNCTIONAL_REQUIREMENTS, linkedResourcesList);
+                }
+            }
+            // FRIDs increment, so once the requested one is reached nothing after it counts.
+            if (frid !== null && currentFrid === frid)
+                return true;
+        }
+    }
+    return false;
+}
+export function collectLinkedResources(tree, linkedResourcesList, specificationsList, includeAcceptanceTests, frid = null) {
+    if (tree === null || typeof tree !== "object" || Array.isArray(tree)) {
+        throw new TypeError("[plain_source_tree must be a dictionary.");
+    }
+    if (frid !== null && ![...getFrids(tree)].includes(frid)) {
+        throw new Error(`frid ${frid} does not exist.`);
+    }
+    const result = collectLinkedResourcesInSection(tree, linkedResourcesList, specificationsList, includeAcceptanceTests, frid);
+    linkedResourcesList.sort((a, b) => (a.text < b.text ? -1 : a.text > b.text ? 1 : 0));
+    return result;
+}
+/**
+ * The FRID iterator: one functionality ID per functional spec, 1, 2, 3 in order.
+ * Everything that walks the spec one functionality at a time - rendering, ranges, context
+ * building - is driven by this.
+ */
+export function* getFrids(tree) {
+    const functionalRequirements = getSpecificationItems(tree, FUNCTIONAL_REQUIREMENTS) ?? [];
+    for (let id = 1; id <= functionalRequirements.length; id += 1)
+        yield String(id);
+}
+export function getFirstFrid(tree) {
+    const first = getFrids(tree).next();
+    return first.done ? null : first.value;
+}
+export function getNextFrid(tree, frid) {
+    const iterator = getFrids(tree);
+    for (const candidate of iterator) {
+        if (candidate === frid) {
+            const next = iterator.next();
+            return next.done ? null : next.value;
+        }
+    }
+    throw new Error(`Functionality ${frid} does not exist.`);
+}
+export function getPreviousFrid(tree, frid) {
+    let previous = null;
+    for (const candidate of getFrids(tree)) {
+        if (candidate === frid)
+            return previous;
+        previous = candidate;
+    }
+    throw new Error(`Functionality ${frid} does not exist.`);
+}
+export function getFridsBefore(tree, targetFrid) {
+    const before = [];
+    for (const frid of getFrids(tree)) {
+        if (frid === targetFrid)
+            break;
+        before.push(frid);
+    }
+    return before;
+}
+export function getSpecificationItemMarkdown(specificationItem, codeVariables, replaceCodeVariables) {
+    let markdown = specificationItem.markdown;
+    for (const codeVariable of specificationItem.code_variables ?? []) {
+        if (codeVariable.name in codeVariables) {
+            if (codeVariables[codeVariable.name] !== codeVariable.value) {
+                throw new Error(`Code variable ${codeVariable.name} has multiple values: ${codeVariables[codeVariable.name]} and ${codeVariable.value}`);
+            }
+        }
+        else {
+            codeVariables[codeVariable.name] = codeVariable.value;
+        }
+        if (replaceCodeVariables) {
+            markdown = markdown.split(`{{ ${codeVariable.name} }}`).join(codeVariable.value);
+        }
+    }
+    return markdown;
+}
+function getSpecificationsFromPlainSourceTree(frid, tree, definitions, nonFunctionalRequirements, testRequirements, functionalRequirements, acceptanceTests, codeVariables, replaceCodeVariables) {
+    let returnFrid = null;
+    const requirements = getSpecificationItems(tree, FUNCTIONAL_REQUIREMENTS);
+    if (requirements !== undefined && requirements.length > 0) {
+        let count = 0;
+        for (const requirement of requirements) {
+            count += 1;
+            const currentFrid = String(count);
+            functionalRequirements.push(getSpecificationItemMarkdown(requirement, codeVariables, replaceCodeVariables));
+            if (currentFrid === frid) {
+                for (const test of requirement[ACCEPTANCE_TESTS] ?? []) {
+                    acceptanceTests.push(getSpecificationItemMarkdown(test, codeVariables, replaceCodeVariables));
+                }
+                returnFrid = currentFrid;
+                break;
+            }
+        }
+    }
+    if (returnFrid !== null) {
+        const prepend = (target, heading) => {
+            const source = getSpecificationItems(tree, heading);
+            if (source === undefined)
+                return;
+            target.unshift(...source.map((item) => getSpecificationItemMarkdown(item, codeVariables, replaceCodeVariables)));
+        };
+        prepend(definitions, DEFINITIONS);
+        prepend(nonFunctionalRequirements, NON_FUNCTIONAL_REQUIREMENTS);
+        prepend(testRequirements, TEST_REQUIREMENTS);
+    }
+    return returnFrid;
+}
+/**
+ * Build the rendering context for one functionality: every definition and
+ * implementation/test req in scope, the functionalities up to and including this one,
+ * and this one's acceptance tests.
+ */
+export function getSpecificationsForFrid(tree, frid, replaceCodeVariables = true) {
+    const definitions = [];
+    const nonFunctionalRequirements = [];
+    const testRequirements = [];
+    const functionalRequirements = [];
+    const acceptanceTests = [];
+    const codeVariables = {};
+    const result = getSpecificationsFromPlainSourceTree(frid, tree, definitions, nonFunctionalRequirements, testRequirements, functionalRequirements, acceptanceTests, codeVariables, replaceCodeVariables);
+    if (result === null)
+        throw new Error(`Functionality ${frid} does not exist.`);
+    const specifications = {
+        [DEFINITIONS]: definitions,
+        [NON_FUNCTIONAL_REQUIREMENTS]: nonFunctionalRequirements,
+        [TEST_REQUIREMENTS]: testRequirements,
+        [FUNCTIONAL_REQUIREMENTS]: functionalRequirements,
+    };
+    if (acceptanceTests.length > 0)
+        specifications[ACCEPTANCE_TESTS] = acceptanceTests;
+    return [specifications, Object.keys(codeVariables).length > 0 ? codeVariables : null];
+}
+/** Iterate every functionality with the context that should be rendered for it. */
+export function* iterateFunctionalSpecs(tree, replaceCodeVariables = true) {
+    for (const frid of getFrids(tree)) {
+        const [specifications, codeVariables] = getSpecificationsForFrid(tree, frid, replaceCodeVariables);
+        yield { frid, specifications, codeVariables };
+    }
+}
+export function hashText(text) {
+    return createHash("sha256").update(text, "utf8").digest("hex");
+}
+export function getHashValue(specifications) {
+    return hashText(JSON.stringify(specifications, null, 4));
+}
+function getFridsRange(tree, start, end) {
+    const frids = [...getFrids(tree)];
+    start = String(start);
+    if (!frids.includes(start)) {
+        throw new InvalidFridArgument(`Invalid start functionality ID: ${start}. Valid IDs are: ${JSON.stringify(frids)}.`);
+    }
+    let endIdx;
+    if (end !== undefined) {
+        end = String(end);
+        if (!frids.includes(end)) {
+            throw new InvalidFridArgument(`Invalid end functionality ID: ${end}. Valid IDs are: ${JSON.stringify(frids)}.`);
+        }
+        endIdx = frids.indexOf(end) + 1;
+    }
+    else {
+        endIdx = frids.length;
+    }
+    const startIdx = frids.indexOf(start);
+    if (startIdx >= endIdx) {
+        throw new InvalidFridArgument(`Start functionality ID: ${start} must be before end functionality ID: ${end}.`);
+    }
+    return frids.slice(startIdx, endIdx);
+}
+export function getRenderRange(renderRange, tree) {
+    const parts = renderRange.split(",");
+    const rangeEnd = parts.length === 2 ? parts[1] : parts[0];
+    return getFridsRange(tree, parts[0], rangeEnd);
+}
+export function getRenderRangeFrom(start, tree) {
+    return getFridsRange(tree, start);
+}

package/dist/plain/stdlib.js

@@ -0,0 +1,44 @@
+import { existsSync, realpathSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { ModuleDoesNotExistError, PlainSyntaxError } from "./errors.js";
+import { openFrom } from "./files.js";
+/**
+ * The ***plain standard library's names. `stdlib/` is a reserved prefix: `stdlib/backend/python-fastapi`
+ * is always turri's own template, in its `stdlib/` folder - never a module of the project's. A
+ * project that has a module at such a path gets an error, not a quiet choice between the two: which one
+ * a spec builds on must never depend on what happens to be on disk beside it.
+ *
+ * This is turri's, not the reference parser's: the Python parser has no standard library.
+ */
+export const STDLIB_PREFIX = "stdlib/";
+/** The folder `stdlib/` is in: turri's own. */
+export const STDLIB_ROOT = dirname(dirname(dirname(fileURLToPath(import.meta.url))));
+export function isStdlibModule(moduleName) {
+    return moduleName.replace(/^\.\//, "").startsWith(STDLIB_PREFIX);
+}
+function sameFile(a, b) {
+    try {
+        return realpathSync(a) === realpathSync(b);
+    }
+    catch {
+        return false;
+    }
+}
+/** A standard library module's text - refused when a folder the spec is resolved from has a module of that name too. */
+export function readStdlibModule(moduleName, templateDirs) {
+    const name = moduleName.replace(/^\.\//, "");
+    const file = `${name}.plain`;
+    const own = join(STDLIB_ROOT, file);
+    for (const dir of templateDirs) {
+        const local = join(dir, file);
+        if (existsSync(local) && !sameFile(local, own)) {
+            throw new PlainSyntaxError(`Plain syntax error: '${name}' is a reserved name - modules under ${STDLIB_PREFIX} are turri's standard library - ` +
+                `but ${local} is a module of that name. Rename it, or the folder it is in.`);
+        }
+    }
+    const text = openFrom([STDLIB_ROOT], file);
+    if (text === null)
+        throw new ModuleDoesNotExistError(`Module does not exist (${name}): the standard library has no ${name}.`);
+    return text;
+}

package/dist/question-dialog.js

@@ -0,0 +1,125 @@
+import { Input, matchesKey, truncateToWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
+/** Lines kept for the conversation above the dialog, so it never takes the whole screen. */
+const KEPT_ABOVE = 4;
+/** **bold** and `code`, as the brief's markdown means them. */
+function styled(text, style) {
+    return text.replace(/\*\*([^*]+)\*\*/g, (_all, inner) => style.bold(inner)).replace(/`([^`]+)`/g, (_all, inner) => style.accent(inner));
+}
+export class QuestionDialog {
+    options;
+    input;
+    selected = 0;
+    /** The brief's first line in its window. */
+    scroll = 0;
+    /** How far the brief scrolls, and its window's height - as last drawn. */
+    maxScroll = 0;
+    window = 0;
+    answered = false;
+    focusedNow = false;
+    constructor(options) {
+        this.options = options;
+        if (options.options === undefined || options.options.length === 0) {
+            this.input = new Input({ prompt: "> " });
+            this.input.onSubmit = (value) => this.finish(value.trim() === "" ? undefined : value);
+            this.input.onEscape = () => this.finish(undefined);
+        }
+        else {
+            this.input = undefined;
+        }
+    }
+    get focused() {
+        return this.focusedNow;
+    }
+    set focused(value) {
+        this.focusedNow = value;
+        if (this.input !== undefined)
+            this.input.focused = value;
+    }
+    finish(answer) {
+        if (this.answered)
+            return;
+        this.answered = true;
+        this.options.done(answer);
+    }
+    scrollBy(lines) {
+        const next = Math.max(0, Math.min(this.maxScroll, this.scroll + lines));
+        if (next === this.scroll)
+            return;
+        this.scroll = next;
+        this.options.requestRender();
+    }
+    render(width) {
+        const { style } = this.options;
+        const inner = Math.max(10, width - 2);
+        const pad = (line) => truncateToWidth(`  ${line}`, width);
+        const context = (this.options.context ?? "").trim();
+        const brief = context === "" ? [] : context.split("\n").flatMap((line) => (line.trim() === "" ? [""] : wrapTextWithAnsi(styled(line, style), inner)));
+        const question = wrapTextWithAnsi(style.bold(style.accent(this.options.question)), inner);
+        const choices = this.options.options ?? [];
+        const body = this.input !== undefined
+            ? this.input.render(inner)
+            : choices.map((choice, index) => (index === this.selected ? style.accent(`› ${choice}`) : `  ${choice}`));
+        const hint = this.input !== undefined
+            ? "enter answers · esc dismisses"
+            : "↑↓ choose · enter picks · esc dismisses";
+        // The brief gets what the question, the options and the hints leave of the screen.
+        const fixed = question.length + body.length + 4;
+        const room = Math.max(3, this.options.rows() - KEPT_ABOVE - fixed);
+        const scrolls = brief.length > room;
+        this.window = scrolls ? room - 1 : brief.length;
+        this.maxScroll = scrolls ? brief.length - this.window : 0;
+        this.scroll = Math.min(this.scroll, this.maxScroll);
+        const lines = [];
+        if (brief.length > 0) {
+            lines.push(...brief.slice(this.scroll, this.scroll + this.window).map(pad));
+            if (scrolls) {
+                const last = Math.min(brief.length, this.scroll + this.window);
+                const more = this.scroll === 0 ? " - more below" : last === brief.length ? " - the end" : "";
+                lines.push(pad(style.muted(`── lines ${this.scroll + 1}-${last} of ${brief.length}${more} · PgUp/PgDn or shift+↑↓ scroll ──`)));
+            }
+            lines.push("");
+        }
+        lines.push(...question.map(pad), ...body.map(pad), "", pad(style.muted(hint)));
+        return lines;
+    }
+    handleInput(data) {
+        // The brief scrolls whatever has the keys.
+        if (matchesKey(data, "pageDown"))
+            return this.scrollBy(Math.max(1, this.window - 1));
+        if (matchesKey(data, "pageUp"))
+            return this.scrollBy(-Math.max(1, this.window - 1));
+        if (matchesKey(data, "shift+down"))
+            return this.scrollBy(1);
+        if (matchesKey(data, "shift+up"))
+            return this.scrollBy(-1);
+        if (this.input !== undefined) {
+            this.input.handleInput(data);
+            this.options.requestRender();
+            return;
+        }
+        const choices = this.options.options ?? [];
+        if (matchesKey(data, "up")) {
+            this.selected = (this.selected - 1 + choices.length) % choices.length;
+            this.options.requestRender();
+        }
+        else if (matchesKey(data, "down")) {
+            this.selected = (this.selected + 1) % choices.length;
+            this.options.requestRender();
+        }
+        else if (matchesKey(data, "enter")) {
+            this.finish(choices[this.selected]);
+        }
+        else if (matchesKey(data, "escape")) {
+            this.finish(undefined);
+        }
+    }
+    handleMouse(event) {
+        if (event.type !== "wheel" || event.wheelDelta === undefined || this.maxScroll === 0)
+            return undefined;
+        this.scrollBy(event.wheelDelta);
+        return { handled: true };
+    }
+    invalidate() {
+        this.input?.invalidate();
+    }
+}