@turri-dev/cli 0.1.27-next.763d091 → 0.1.28-next.d5f2680

package/dist/plain/plain.tmLanguage.json

@@ -35,7 +35,7 @@
             "patterns": [
                 {
                     "name": "entity.name.function.plain",
-                    "match": "\\*\\*\\*(definitions|implementation reqs|test reqs|functional specs|acceptance tests)\\*\\*\\*"
+                    "match": "^\\*\\*\\*(definitions|implementation reqs|test reqs|functional specs|conformance tests|acceptance tests)\\*\\*\\*"
                 },
                 {
                     "name": "meta.frontmatter.plain",
@@ -63,7 +63,29 @@
                             "match": "^\\s*(requires):"
                         },
                         {
-                            "match": "^\\s*-\\s+([a-zA-Z_][a-zA-Z0-9_]*)",
+                            "match": "^\\s*(module:)\\s*([^\\s#][^\\s#]*)?",
+                            "captures": {
+                                "1": {
+                                    "name": "keyword.control.import.plain"
+                                },
+                                "2": {
+                                    "name": "entity.name.type.class.plain"
+                                }
+                            }
+                        },
+                        {
+                            "match": "^\\s*(func_id:)\\s*([a-z0-9]+(?:-[a-z0-9]+)*)?(?=\\s|$)",
+                            "captures": {
+                                "1": {
+                                    "name": "keyword.control.import.plain"
+                                },
+                                "2": {
+                                    "name": "entity.name.tag.id.plain"
+                                }
+                            }
+                        },
+                        {
+                            "match": "^\\s*-\\s+([^\\s#:][^\\s#]*)",
                             "captures": {
                                 "1": {
                                     "name": "entity.name.type.class.plain"
@@ -93,6 +115,10 @@
                     "begin": "\\{%\\s*include",
                     "end": "%\\}"
                 },
+                {
+                    "name": "entity.name.tag.id.plain",
+                    "match": "^#\\s+[a-z0-9]+(?:-[a-z0-9]+)*\\s*$"
+                },
                 {
                     "name": "entity.punctuation.definition.bullet.plain",
                     "match": "^\\s*-"
@@ -121,4 +147,4 @@
         }
     },
     "scopeName": "source.plain"
-}
+}

package/dist/plain/project.d.ts

@@ -0,0 +1,48 @@
+import { type MarshalledPlainSource } from "./spec.ts";
+import { type TestPlainFile } from "./test-plain-file.ts";
+/** Port of project.py: a module with its requires chain and the test plain files bound to its functionalities. */
+export interface BoundTestPlainFile {
+    /** The file on disk. */
+    path: string;
+    /** The path relative to the entry module's folder, with `/` as separator. */
+    name: string;
+    parsed: TestPlainFile;
+}
+export interface ProjectParseResult {
+    /** As `parseModuleChain` gives it, with the scenarios of the test plain files merged into the functionalities. */
+    chain: Array<[string, MarshalledPlainSource]>;
+    testPlainFiles: BoundTestPlainFile[];
+}
+/**
+ * `[path, name]` of every .plain file under the test folders: folder by folder, and within one by path - each
+ * folder's files before its subfolders', as `os.walk` gives them. A test folder that does not exist is skipped.
+ */
+export declare function discoverTestPlainFiles(testDirs: string[], entryDir: string): Array<[string, string]>;
+export declare function readTestPlainFileText(path: string, name: string): string;
+/**
+ * Read every test plain file under the test folders and add its scenarios to the functionality it binds to, in
+ * place in the chain's trees.
+ *
+ * A `.plain` file under a test folder without the `module:` and `func_id:` keys is an error, as is a file that binds
+ * to a module outside the chain or to a func-id the module does not have. The concepts of the scenarios must be
+ * visible to the bound module. Files bound to one functionality are merged in discovery order; a scenario-id is
+ * unique across that merged set.
+ */
+export declare function bindTestPlainFiles(chain: Array<[string, MarshalledPlainSource]>, testDirs: string[], templateDirs: string[], entryDir: string): BoundTestPlainFile[];
+/**
+ * Throw for the first functionality of the chain, in render order, that has no test plain file bound to it.
+ * The sections of the file may be empty; the file itself is what the check asks for.
+ */
+export declare function checkTestPlainFiles(chain: Array<[string, MarshalledPlainSource]>, bound: BoundTestPlainFile[]): void;
+/**
+ * Parse a module with its requires chain and bind the test plain files under `testDirs` to its functionalities.
+ *
+ * `templateDirs[0]` is the entry module's folder; test plain files are named relative to it. With
+ * `requireTestPlainFiles`, every functionality of every module in the chain needs a test plain file.
+ */
+export declare function parseProject(plainFileName: string, templateDirs: string[], testDirs: string[], requireTestPlainFiles: boolean): ProjectParseResult;
+/** Every functionality of the chain, in render order, with no test plain file bound to it. turri's: it lists them all. */
+export declare function missingTestPlainFiles(chain: Array<[string, MarshalledPlainSource]>, bound: BoundTestPlainFile[]): Array<{
+    module: string;
+    funcId: string;
+}>;

package/dist/plain/project.js

@@ -0,0 +1,155 @@
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { collectConcepts } from "./concepts.js";
+import { MissingTestPlainFileError, PlainSyntaxError, UnsupportedBase64Content } from "./errors.js";
+import { findLargeBase64Blob, relativeResourcePath } from "./files.js";
+import { parseModuleChain } from "./parser.js";
+import { ACCEPTANCE_TESTS, CONFORMANCE_TESTS, getFunctionalSpecs, } from "./spec.js";
+import { isTestPlainFile, loadFrontmatter, parseTestPlainFileSource, scenarioItem, validateScenarioConcepts, } from "./test-plain-file.js";
+const PLAIN_SOURCE_FILE_EXTENSION = ".plain";
+function isDirectory(path) {
+    try {
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * `[path, name]` of every .plain file under the test folders: folder by folder, and within one by path - each
+ * folder's files before its subfolders', as `os.walk` gives them. A test folder that does not exist is skipped.
+ */
+export function discoverTestPlainFiles(testDirs, entryDir) {
+    const found = [];
+    const walk = (root) => {
+        const entries = readdirSync(root, { withFileTypes: true });
+        const byName = (a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
+        for (const entry of entries.filter((e) => !e.isDirectory()).sort(byName)) {
+            if (entry.name.endsWith(PLAIN_SOURCE_FILE_EXTENSION)) {
+                found.push([join(root, entry.name), relativeResourcePath(entryDir, root, entry.name)]);
+            }
+        }
+        for (const entry of entries.filter((e) => e.isDirectory()).sort(byName))
+            walk(join(root, entry.name));
+    };
+    for (const testDir of testDirs)
+        if (isDirectory(testDir))
+            walk(testDir);
+    return found;
+}
+export function readTestPlainFileText(path, name) {
+    let text;
+    try {
+        text = new TextDecoder("utf-8", { fatal: true }).decode(readFileSync(path));
+    }
+    catch {
+        throw new PlainSyntaxError(`Plain syntax error: File '${name}' under a test folder is not a text file.`);
+    }
+    const blob = findLargeBase64Blob(text);
+    if (blob !== null) {
+        throw new UnsupportedBase64Content(`Test plain file '${name}' contains a base64-encoded blob (${blob.length} characters) inlined in the ` +
+            "scenarios. This is not supported. Remove the base64 data from the file.");
+    }
+    return text;
+}
+/**
+ * Read every test plain file under the test folders and add its scenarios to the functionality it binds to, in
+ * place in the chain's trees.
+ *
+ * A `.plain` file under a test folder without the `module:` and `func_id:` keys is an error, as is a file that binds
+ * to a module outside the chain or to a func-id the module does not have. The concepts of the scenarios must be
+ * visible to the bound module. Files bound to one functionality are merged in discovery order; a scenario-id is
+ * unique across that merged set.
+ */
+export function bindTestPlainFiles(chain, testDirs, templateDirs, entryDir) {
+    const trees = new Map(chain);
+    const bound = [];
+    // (module, func-id) -> scenario-id -> where it is first used.
+    const scenarioPlaces = new Map();
+    for (const [path, name] of discoverTestPlainFiles(testDirs, entryDir)) {
+        const text = readTestPlainFileText(path, name);
+        let metadata;
+        try {
+            metadata = loadFrontmatter(text.split("\r\n").join("\n")).metadata;
+        }
+        catch (e) {
+            throw new PlainSyntaxError(`Plain syntax error: File '${name}' under a test folder has invalid frontmatter: ${e instanceof Error ? e.message : String(e)}`);
+        }
+        if (!isTestPlainFile(metadata)) {
+            throw new PlainSyntaxError(`Plain syntax error: File '${name}' is under a test folder but is not a test plain file: its ` +
+                "frontmatter needs the keys `module:` and `func_id:`.");
+        }
+        const parsed = parseTestPlainFileSource(text, name, templateDirs, {});
+        const tree = trees.get(parsed.module);
+        if (tree === undefined) {
+            throw new PlainSyntaxError(`Plain syntax error: Test plain file '${name}' binds to module '${parsed.module}', which is not the ` +
+                `entry module or one of its required modules (${[...trees.keys()].join(", ")}).`);
+        }
+        const functionality = getFunctionalSpecs(tree).find((item) => item.id === parsed.funcId);
+        if (functionality === undefined) {
+            throw new PlainSyntaxError(`Plain syntax error: Test plain file '${name}' binds to functionality ` +
+                `'${parsed.module}:${parsed.funcId}', which module '${parsed.module}' does not have.`);
+        }
+        const [concepts] = collectConcepts(tree);
+        const errors = validateScenarioConcepts(parsed, new Set(concepts));
+        if (errors.length > 0) {
+            throw new PlainSyntaxError(`Plain syntax error: Found ${errors.length} errors in test plain file '${name}':\n${errors.join("\n")}`);
+        }
+        const key = `${parsed.module}\0${parsed.funcId}`;
+        if (!scenarioPlaces.has(key))
+            scenarioPlaces.set(key, new Map());
+        const places = scenarioPlaces.get(key);
+        for (const [listKey, scenarios] of [
+            [CONFORMANCE_TESTS, parsed.conformanceTests],
+            [ACCEPTANCE_TESTS, parsed.acceptanceTests],
+        ]) {
+            for (const scenario of scenarios) {
+                if (places.has(scenario.id)) {
+                    throw new PlainSyntaxError(`Plain syntax error: Syntax error at line ${scenario.lineNumber} in test plain file ` +
+                        `'${name}': Duplicate scenario-id \`${scenario.id}\` for functionality ` +
+                        `'${parsed.module}:${parsed.funcId}'; it is first used ${places.get(scenario.id)}.`);
+                }
+                places.set(scenario.id, `at line ${scenario.lineNumber} in test plain file '${name}'`);
+                functionality[listKey].push(scenarioItem(scenario));
+            }
+        }
+        bound.push({ path, name, parsed });
+    }
+    return bound;
+}
+/**
+ * Throw for the first functionality of the chain, in render order, that has no test plain file bound to it.
+ * The sections of the file may be empty; the file itself is what the check asks for.
+ */
+export function checkTestPlainFiles(chain, bound) {
+    const missing = missingTestPlainFiles(chain, bound)[0];
+    if (missing !== undefined) {
+        throw new MissingTestPlainFileError(`Functionality ${missing.module}:${missing.funcId} has no test plain file. Add one, by convention ` +
+            `tests/${missing.module}/${missing.funcId}.plain, with the add-test-scenarios skill.`);
+    }
+}
+/**
+ * Parse a module with its requires chain and bind the test plain files under `testDirs` to its functionalities.
+ *
+ * `templateDirs[0]` is the entry module's folder; test plain files are named relative to it. With
+ * `requireTestPlainFiles`, every functionality of every module in the chain needs a test plain file.
+ */
+export function parseProject(plainFileName, templateDirs, testDirs, requireTestPlainFiles) {
+    const chain = parseModuleChain(plainFileName, templateDirs).map(([name, tree]) => [name, structuredClone(tree)]);
+    const bound = bindTestPlainFiles(chain, testDirs, templateDirs, templateDirs[0]);
+    if (requireTestPlainFiles)
+        checkTestPlainFiles(chain, bound);
+    return { chain, testPlainFiles: bound };
+}
+/** Every functionality of the chain, in render order, with no test plain file bound to it. turri's: it lists them all. */
+export function missingTestPlainFiles(chain, bound) {
+    const boundFunctionalities = new Set(bound.map((item) => `${item.parsed.module}\0${item.parsed.funcId}`));
+    const missing = [];
+    for (const [moduleName, tree] of chain) {
+        for (const functionality of getFunctionalSpecs(tree)) {
+            if (!boundFunctionalities.has(`${moduleName}\0${functionality.id}`))
+                missing.push({ module: moduleName, funcId: functionality.id });
+        }
+    }
+    return missing;
+}

package/dist/plain/spec.d.ts

@@ -1,90 +1,152 @@
 import type { LinkedResource } from "./markdown.ts";
-/** Port of plain_spec.py. */
+/**
+ * Port of plain_spec.py. The reference keeps its names for a functional spec's id - `frid`, `get_frids` - and so do
+ * the ports here: a frid is the functional spec's func-id, the `# <func-id>` heading it is written under.
+ */
 export declare const DEFINITIONS = "definitions";
 export declare const NON_FUNCTIONAL_REQUIREMENTS = "implementation reqs";
 export declare const TEST_REQUIREMENTS = "test reqs";
 export declare const FUNCTIONAL_REQUIREMENTS = "functional specs";
+export declare const CONFORMANCE_TESTS = "conformance_tests";
 export declare const ACCEPTANCE_TESTS = "acceptance_tests";
+export declare const CONFORMANCE_TEST_HEADING = "conformance tests";
 export declare 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.
+ * functional spec of every module it requires, transitively, bottom of the chain first, each
+ * with its module. turri's, not the reference parser's.
  */
 export declare const REQUIRED_FUNCTIONAL_SPECS = "required functional specs";
+/**
+ * Where a module's tree carries the test plain files bound to its chain, as the reference's parse output has them
+ * (`test_plain_files`): each file's path, from the module's folder, to the functional spec it binds to. turri's.
+ */
+export declare const TEST_PLAIN_FILES = "test plain files";
+/** The sections whose content is a list of `- ` items. */
+export declare const LIST_SECTION_HEADINGS: string[];
 export declare const ALLOWED_SPECIFICATION_HEADINGS: string[];
 export declare const ALLOWED_IMPORT_SPECIFICATION_HEADINGS: string[];
+/**
+ * A func-id or scenario-id: segments of lowercase letters and digits, with one hyphen between segments. So a hyphen
+ * never starts or ends an id, two hyphens never touch, and an id is never only hyphens.
+ */
+export declare const SEMANTIC_ID_PATTERN: RegExp;
+export declare function isSemanticId(text: string): boolean;
 export interface CodeVariable {
     name: string;
     value: string;
 }
+/** An item of a list section: definitions, implementation reqs, test reqs. */
 export interface SpecificationItem {
     markdown: string;
     linked_resources?: LinkedResource[];
     code_variables?: CodeVariable[];
-    [ACCEPTANCE_TESTS]?: SpecificationItem[];
 }
-/** A functional spec inherited through `requires`, with the module it belongs to and its id there. */
-export interface InheritedSpecificationItem extends SpecificationItem {
+/** A conformance or acceptance scenario, bound to its functional spec from a test plain file. */
+export interface ScenarioItem {
+    id: string;
+    text: string;
+    linked_resources: LinkedResource[];
+    code_variables?: CodeVariable[];
+}
+/** A functional spec: its func-id, its body, its links, and the scenarios of its test plain files. */
+export interface FunctionalSpecItem {
+    id: string;
+    markdown: string;
+    linked_resources: LinkedResource[];
+    [CONFORMANCE_TESTS]: ScenarioItem[];
+    [ACCEPTANCE_TESTS]: ScenarioItem[];
+    code_variables?: CodeVariable[];
+}
+/** A functional spec inherited through `requires`, with the module it belongs to. */
+export interface InheritedSpecificationItem extends FunctionalSpecItem {
     module: string;
-    frid: string;
+}
+/** What `TEST_PLAIN_FILES` holds for each test plain file: the functional spec it binds to. */
+export interface TestPlainFileBinding {
+    module: string;
+    func_id: string;
+}
+/** A scenario as it is regenerated with: its scenario-id and its text, code variables put in place. */
+export interface ScenarioText {
+    id: string;
+    text: string;
 }
 /**
  * The functional specs a module inherits through `requires`, rendered: each with its
- * module, its id there, and its acceptance tests.
+ * module, its func-id, and its scenarios.
  */
 export declare function getInheritedFunctionalSpecs(tree: MarshalledPlainSource, replaceCodeVariables?: boolean): Array<{
     module: string;
-    frid: string;
+    funcId: string;
     spec: string;
-    acceptanceTests?: string[];
+    conformanceTests: ScenarioText[];
+    acceptanceTests: ScenarioText[];
 }>;
-/**
- * The marshalled tree: heading -> list of items. Flat: functionalities are numbered 1, 2, 3
- * in the order they appear. Nested sections with dotted ids ("2.3") are not supported.
- */
+/** The marshalled tree: heading -> list of items. Functional specs are named by their func-ids, in file order. */
 export interface MarshalledPlainSource {
     [heading: string]: unknown;
 }
 export declare function getSpecificationItems(tree: MarshalledPlainSource, heading: string): SpecificationItem[] | undefined;
+/** The functional specs of a tree, in file order. */
+export declare function getFunctionalSpecs(tree: MarshalledPlainSource): FunctionalSpecItem[];
+/** True if any functional spec of the tree has acceptance scenarios. */
 export declare function hasAcceptanceTests(tree: MarshalledPlainSource): boolean;
 export interface CollectedLinkedResource extends LinkedResource {
     sections: string[];
 }
-export declare function collectSpecificationLinkedResources(specification: SpecificationItem, specificationHeading: string, linkedResourcesList: CollectedLinkedResource[]): void;
-export declare function collectLinkedResourcesInSection(section: MarshalledPlainSource, linkedResourcesList: CollectedLinkedResource[], specificationsList: string[] | null, includeAcceptanceTests: boolean, frid: string | null): boolean;
-export declare function collectLinkedResources(tree: MarshalledPlainSource, linkedResourcesList: CollectedLinkedResource[], specificationsList: string[] | null, includeAcceptanceTests: boolean, frid?: string | null): boolean;
+export declare function collectSpecificationLinkedResources(specification: {
+    linked_resources?: LinkedResource[];
+}, specificationHeading: string, linkedResourcesList: CollectedLinkedResource[]): void;
 /**
- * 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
+ * Add the linked resources of the tree to `linkedResourcesList` and sort the list by link text.
+ *
+ * `specificationsList` limits the sections read; null or empty reads every section. The functional specs are read up
+ * to and including `frid`, or all of them when it is null. With `includeTestScenarios` the links of the conformance
+ * and acceptance scenarios are added too, for `frid` alone when one is given. Returns true when `frid` was reached.
+ */
+export declare function collectLinkedResources(tree: MarshalledPlainSource, linkedResourcesList: CollectedLinkedResource[], specificationsList: string[] | null, includeTestScenarios: boolean, frid?: string | null): boolean;
+/**
+ * The FRID iterator: the func-ids of the tree's functional specs, in file order.
+ * Everything that walks the spec one functional spec at a time - rendering, ranges, context
  * building - is driven by this.
  */
 export declare function getFrids(tree: MarshalledPlainSource): Generator<string>;
 export declare function getFirstFrid(tree: MarshalledPlainSource): string | null;
 export declare function getNextFrid(tree: MarshalledPlainSource, frid: string): string | null;
 export declare function getPreviousFrid(tree: MarshalledPlainSource, frid: string): string | null;
+/** The func-ids that come before `targetFrid` in the specification, in order. */
 export declare function getFridsBefore(tree: MarshalledPlainSource, targetFrid: string): string[];
-export declare function getSpecificationItemMarkdown(specificationItem: SpecificationItem, codeVariables: Record<string, string>, replaceCodeVariables: boolean): string;
+/**
+ * The text under `key` of the item, with its code variables recorded in `codeVariables` and, when
+ * `replaceCodeVariables` is set, their values put in place of the `{{ name }}` placeholders.
+ */
+export declare function getSpecificationItemMarkdown(specificationItem: {
+    code_variables?: CodeVariable[];
+}, codeVariables: Record<string, string>, replaceCodeVariables: boolean, key?: string): string;
 export interface Specifications {
     [DEFINITIONS]: string[];
     [NON_FUNCTIONAL_REQUIREMENTS]: string[];
     [TEST_REQUIREMENTS]: string[];
     [FUNCTIONAL_REQUIREMENTS]: string[];
-    [ACCEPTANCE_TESTS]?: string[];
+    [CONFORMANCE_TESTS]: ScenarioText[];
+    [ACCEPTANCE_TESTS]: ScenarioText[];
 }
 /**
- * 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.
+ * The specifications that build `frid`: every list section, the functional specs up to and including `frid`, and
+ * the conformance and acceptance scenarios of `frid` as `{id, text}` entries.
+ *
+ * Returns the specifications and the code variables they use (null when there are none). Throws when `frid` is not
+ * in the tree.
  */
 export declare function getSpecificationsForFrid(tree: MarshalledPlainSource, frid: string, replaceCodeVariables?: boolean): [Specifications, Record<string, string> | null];
-/** Iterate every functionality with the context that should be rendered for it. */
+/** Iterate every functional spec with the context that should be rendered for it. turri's, for a host. */
 export declare function iterateFunctionalSpecs(tree: MarshalledPlainSource, replaceCodeVariables?: boolean): Generator<{
-    frid: string;
+    funcId: string;
     specifications: Specifications;
     codeVariables: Record<string, string> | null;
 }>;
 export declare function hashText(text: string): string;
 export declare function getHashValue(specifications: unknown): string;
-export declare function getRenderRange(renderRange: string, tree: MarshalledPlainSource): string[];
-export declare function getRenderRangeFrom(start: string, tree: MarshalledPlainSource): string[];
+/** The func-ids from `start` through `end` inclusive, or through the last one when `end` is not given. */
+export declare function getFridsRange(tree: MarshalledPlainSource, start: string, end?: string): string[];