@turri-dev/cli 0.1.27 → 0.2.0

package/dist/plain/parser.js

@@ -1,19 +1,29 @@
 import { createHash } from "node:crypto";
 import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
-import { extname, isAbsolute, basename, resolve } from "node:path";
+import { extname, isAbsolute, basename, join, resolve } from "node:path";
 import { load as loadYaml } from "js-yaml";
 import { extractConceptsFromDefinition, findConceptDefinitionsInPlainSource, sortDefinitions, validateConcepts, DEFAULT_CONCEPTS, } from "./concepts.js";
 import { ImportedModuleWithFunctionalitiesError, MissingFunctionalitiesError, ModuleDoesNotExistError, PlainSyntaxError, UnsupportedBase64Content, } from "./errors.js";
 import { findIn, findLargeBase64Blob, getLoadedTemplates, openFrom } from "./files.js";
 import { renderPlainSource } from "./liquid.js";
 import { isStdlibModule, readStdlibModule, stdlibModuleFile } from "./stdlib.js";
-import { getRawText, lineNumber, parseMarkdown, removeQuotes, renderToMarkdown, traverse, } from "./markdown.js";
-import { ACCEPTANCE_TESTS, ACCEPTANCE_TEST_HEADING, ALLOWED_IMPORT_SPECIFICATION_HEADINGS, ALLOWED_SPECIFICATION_HEADINGS, DEFINITIONS, FUNCTIONAL_REQUIREMENTS, NON_FUNCTIONAL_REQUIREMENTS, TEST_REQUIREMENTS, getSpecificationItems, REQUIRED_FUNCTIONAL_SPECS, } from "./spec.js";
+import { getRawText, lineNumber, parseMarkdown, removeQuotes, renderToMarkdown, renderTokens, traverse, } from "./markdown.js";
+import { ACCEPTANCE_TESTS, ACCEPTANCE_TEST_HEADING, ALLOWED_IMPORT_SPECIFICATION_HEADINGS, ALLOWED_SPECIFICATION_HEADINGS, CONFORMANCE_TESTS, CONFORMANCE_TEST_HEADING, DEFINITIONS, FUNCTIONAL_REQUIREMENTS, LIST_SECTION_HEADINGS, NON_FUNCTIONAL_REQUIREMENTS, TEST_PLAIN_FILES, TEST_REQUIREMENTS, getFunctionalSpecs, getSpecificationItems, isSemanticId, REQUIRED_FUNCTIONAL_SPECS, } from "./spec.js";
+import { bindTestPlainFiles, checkTestPlainFiles } from "./project.js";
 export const IMPORT_DIRECTIVE = "import";
 export const REQUIRES_DIRECTIVE = "requires";
+export const PREVIOUS_SYNTAX_HINT = "A functionality is a `# <func-id>` heading followed by its body; the previous syntax is not supported.";
 export const REQUIRED_CONCEPTS_DIRECTIVE = "required_concepts";
 export const EXPORTED_CONCEPTS_DIRECTIVE = "exported_concepts";
 export const PLAIN_SOURCE_FILE_EXTENSION = ".plain";
+/** A list section of a parsed module. */
+export function sectionOf(plainSource, heading) {
+    return plainSource[heading];
+}
+/** The functional specs of a parsed module, none when it has no section for them. */
+export function functionalitiesOf(plainSource) {
+    return plainSource[FUNCTIONAL_REQUIREMENTS] ?? [];
+}
 function newPlainSource() {
     return {
         [DEFINITIONS]: null,
@@ -31,20 +41,19 @@ export function hasScheme(target) {
     return /^[A-Za-z][A-Za-z0-9+.-]*:/.test(target);
 }
 /**
- * A link's file: found where resources are loaded from - the spec's own folder first, then the
- * other template folders - or else from the current directory, as the reference parser has it.
- * Links are relative to the spec, so a spec in a subfolder is checked where it is, wherever
- * turri was started.
+ * Port of loaders.resolve_linked_resource: a link's file, in the first of the folders resources are loaded from - the
+ * spec's own folder first, then the other template folders - where it exists, or null. Existence, not being a file,
+ * decides the match, as in `open_from`'s search. Links are relative to the spec, so a spec in a subfolder is checked
+ * where it is, wherever turri was started.
  */
-function linkedFile(target, dirs) {
+export function resolveLinkedResource(dirs, target) {
     for (const dir of dirs) {
-        const candidate = resolve(dir, target);
-        consulted?.add(candidate);
+        const candidate = join(dir, target);
+        consulted?.add(resolve(candidate));
         if (existsSync(candidate))
             return candidate;
     }
-    consulted?.add(resolve(target));
-    return target;
+    return null;
 }
 /**
  * The linked files a parse looked for, found or not, while one runs: a kept parse holds while each is as it was - a
@@ -92,55 +101,63 @@ function stillHolds(kept, fingerprint) {
 export function linksIn(section) {
     return [...traverse(section, "link")].map((link) => ({ text: String(link.children?.[0]?.value ?? ""), target: String(link.url ?? ""), node: link }));
 }
-export function checkSectionForLinkedResources(section, dirs = []) {
+/**
+ * The links in the blocks, each checked to be a relative path to an existing file that is not a .plain file.
+ * `where` names the place of the links in error messages, e.g. " in test plain file 'tests/m/f.plain', scenario `s`".
+ */
+export function findLinkedResources(nodes, dirs = [], where = "") {
     const linkedResources = [];
-    for (const { text, target, node: link } of linksIn(section)) {
+    for (const { text, target, node: link } of nodes.flatMap((node) => linksIn(node))) {
         const children = link.children ?? [];
         if (hasScheme(target) || isAbsolute(target)) {
-            throw new PlainSyntaxError(`Plain syntax error: Only relative links are allowed (text: ${text}, target: ${target}).`);
+            throw new PlainSyntaxError(`Plain syntax error: Only relative links are allowed${where} (text: ${text}, target: ${target}).`);
         }
-        const file = linkedFile(target, dirs);
-        if (!existsSync(file)) {
-            throw new PlainSyntaxError(`Plain syntax error: Link ${target} does not exist.`);
+        const file = resolveLinkedResource(dirs, target);
+        if (file === null) {
+            const searched = dirs.map((dir, index) => `  ${index + 1}. ${dir}`).join("\n");
+            throw new PlainSyntaxError(`Plain syntax error: Link ${target}${where} does not exist. ` +
+                "Linked resources are looked up relative to the following directories " +
+                `(highest to lowest precedence):\n${searched}`);
         }
         if (!statSync(file).isFile()) {
-            throw new PlainSyntaxError(`Plain syntax error: Link ${target} must be a file.`);
+            throw new PlainSyntaxError(`Plain syntax error: Link ${target}${where} must be a file (resolved to ${file}).`);
         }
         if (children.length !== 1) {
-            throw new PlainSyntaxError(`Plain syntax error: Link must have text specified (link: ${target}).`);
+            throw new PlainSyntaxError(`Plain syntax error: Link${where} must have text specified (link: ${target}).`);
         }
         if (extname(basename(target)) === ".plain") {
-            throw new PlainSyntaxError(`Referenced resource '${target}' is a .plain file. ` +
+            throw new PlainSyntaxError(`Referenced resource '${target}'${where} is a .plain file. ` +
                 "Referencing .plain files through Linked Resources is not supported. " +
                 "Please use the import section to include definitions or implementation/test requirements from another module.");
         }
         linkedResources.push({ text, target });
     }
+    return linkedResources;
+}
+export function checkSectionForLinkedResources(section, dirs = []) {
+    const linkedResources = findLinkedResources([section], dirs);
     if (linkedResources.length > 0)
         section.linked_resources = linkedResources;
 }
 export function checkForLinkedResources(plainSource, dirs = []) {
-    for (const heading of ALLOWED_SPECIFICATION_HEADINGS) {
-        const section = plainSource[heading];
-        if (!section)
-            continue;
-        for (const requirement of section.children) {
+    for (const heading of LIST_SECTION_HEADINGS) {
+        for (const requirement of sectionOf(plainSource, heading)?.children ?? [])
             checkSectionForLinkedResources(requirement, dirs);
-            for (const acceptanceTest of requirement[ACCEPTANCE_TESTS] ?? []) {
-                checkSectionForLinkedResources(acceptanceTest, dirs);
-            }
-        }
+    }
+    for (const functionality of functionalitiesOf(plainSource)) {
+        functionality.linkedResources = findLinkedResources(functionality.body, dirs);
     }
 }
-export function processSectionCodeVariables(section, codeVariables) {
-    if (!("markdown" in section))
+/** Put `{{ name }}` placeholders back into the section text and record the code variables it uses. */
+export function processSectionCodeVariables(section, codeVariables, textKey = "markdown") {
+    if (!(textKey in section))
         return;
     const codeVariablesArray = [];
     for (const [key, value] of Object.entries(codeVariables)) {
-        if (!section.markdown.includes(key))
+        if (!String(section[textKey]).includes(key))
             continue;
         const variableName = Object.keys(value)[0];
-        section.markdown = section.markdown.split(key).join(`{{ ${variableName} }}`);
+        section[textKey] = String(section[textKey]).split(key).join(`{{ ${variableName} }}`);
         codeVariablesArray.push({ name: variableName, value: value[variableName] });
     }
     if (codeVariablesArray.length > 0)
@@ -159,11 +176,10 @@ export function hasFunctionalSpecsSection(plainSource) {
 }
 /** Number of functionalities under ***functional specs*** (0 if absent or empty). */
 export function countFunctionalities(plainSource) {
-    const section = plainSource[FUNCTIONAL_REQUIREMENTS];
-    return section ? section.children.length : 0;
+    return functionalitiesOf(plainSource).length;
 }
 export function validateFunctionalitiesHaveImplementationReqs(plainSource, moduleName, hasRequires = false) {
-    const implementationReqs = plainSource[NON_FUNCTIONAL_REQUIREMENTS];
+    const implementationReqs = sectionOf(plainSource, NON_FUNCTIONAL_REQUIREMENTS);
     const hasImplementationReqs = Boolean(implementationReqs && implementationReqs.children.length > 0);
     if (hasImplementationReqs)
         return;
@@ -176,113 +192,19 @@ export function validateFunctionalitiesHaveImplementationReqs(plainSource, modul
     }
     throw new PlainSyntaxError(message);
 }
-/**
- * Is this token an `acceptance tests` heading?
- *
- * True only for a paragraph holding exactly one emphasis, holding exactly one strong,
- * holding exactly one text node whose content is the heading. Anything that looks like
- * a heading but reads differently comes back as a problem string rather than false, so
- * the caller can reject a near miss instead of silently keeping it.
- */
-export function isAcceptanceTestHeading(token) {
-    if (token.type !== "paragraph")
-        return [false, null];
-    const children = token.children ?? [];
-    if (children.length !== 1 || children[0].type !== "emphasis")
-        return [false, null];
-    const emphasisChildren = children[0].children ?? [];
-    if (emphasisChildren.length !== 1 || emphasisChildren[0].type !== "strong")
-        return [false, null];
-    const strongChildren = emphasisChildren[0].children ?? [];
-    if (strongChildren.length !== 1 || strongChildren[0].type !== "text")
-        return [false, null];
-    const content = String(strongChildren[0].value ?? "").trim();
-    if (content === ACCEPTANCE_TEST_HEADING)
-        return [true, null];
-    return [
-        false,
-        `Syntax error at line ${lineNumber(token)}: Invalid acceptance test heading (\`${content}\`). ` +
-            `Expected: \`${ACCEPTANCE_TEST_HEADING}.\``,
-    ];
-}
-/** Find an acceptance tests heading anywhere in a subtree. */
-export function findAcceptanceTestHeading(token) {
-    const [isHeading] = isAcceptanceTestHeading(token);
-    if (isHeading)
-        return token;
-    for (const child of token.children ?? []) {
-        const found = findAcceptanceTestHeading(child);
-        if (found !== null)
-            return found;
-    }
-    return null;
-}
-/**
- * Pull the acceptance tests out of one functionality.
- *
- * A functionality with acceptance tests has three children: its own text, the
- * `***acceptance tests***` heading, and the list of tests. The heading and list are
- * lifted onto `acceptance_tests` and removed from the children.
- */
-export function processSingleAcceptanceTestRequirement(functionalRequirement) {
-    const newChildren = [];
-    const children = functionalRequirement.children ?? [];
-    let acceptanceTestsFoundAlready = false;
-    for (let index = 0; index < children.length; index += 1) {
-        const child = children[index];
-        const [isHeading, problem] = isAcceptanceTestHeading(child);
-        if (problem) {
-            // A near-miss heading: `acceptance test` instead of `acceptance tests`, or some
-            // other block written where the tests were meant to go.
-            throw new PlainSyntaxError(`Plain syntax error: ${problem}`);
-        }
-        if (!isHeading) {
-            newChildren.push(child);
-            continue;
-        }
-        if (acceptanceTestsFoundAlready) {
-            throw new PlainSyntaxError(`Plain syntax error: Syntax error at line ${lineNumber(child)}: Duplicate 'acceptance tests' ` +
-                "heading found within the same functionality. Only one block of acceptance tests is allowed per functionality.");
-        }
-        const nextToken = children[index + 1];
-        if (nextToken === undefined) {
-            newChildren.push(child);
-            continue;
-        }
-        index += 1;
-        if (nextToken.type === "list") {
-            if (functionalRequirement[ACCEPTANCE_TESTS] === undefined) {
-                functionalRequirement[ACCEPTANCE_TESTS] = [];
-            }
-            for (const listItem of nextToken.children ?? []) {
-                functionalRequirement[ACCEPTANCE_TESTS].push(listItem);
-            }
-            acceptanceTestsFoundAlready = true;
-        }
-        else {
-            // Not followed by a list: keep both tokens.
-            newChildren.push(child);
-            newChildren.push(nextToken);
-        }
-    }
-    functionalRequirement.children = newChildren;
-}
-export function processAcceptanceTests(plainSource) {
-    if (!(FUNCTIONAL_REQUIREMENTS in plainSource))
-        return;
-    const frs = plainSource[FUNCTIONAL_REQUIREMENTS];
-    if (!frs)
-        return;
-    for (const functionalRequirement of frs.children) {
-        if (functionalRequirement.children === undefined)
-            continue;
-        processSingleAcceptanceTestRequirement(functionalRequirement);
-    }
+export function marshallFunctionality(functionality) {
+    return {
+        id: functionality.id,
+        markdown: renderTokens(functionality.body),
+        linked_resources: functionality.linkedResources,
+        [CONFORMANCE_TESTS]: [],
+        [ACCEPTANCE_TESTS]: [],
+    };
 }
 export function marshallPlainSource(input) {
     const plainSource = {};
-    for (const heading of ALLOWED_SPECIFICATION_HEADINGS) {
-        const section = input[heading];
+    for (const heading of LIST_SECTION_HEADINGS) {
+        const section = sectionOf(input, heading);
         if (!section)
             continue;
         const listOfRequirements = [];
@@ -293,19 +215,13 @@ export function marshallPlainSource(input) {
             if (requirement.linked_resources) {
                 requirementSection.linked_resources = requirement.linked_resources;
             }
-            const acceptanceTests = requirement[ACCEPTANCE_TESTS];
-            if (acceptanceTests !== undefined) {
-                requirementSection[ACCEPTANCE_TESTS] = acceptanceTests.map((acceptanceTest) => {
-                    const section = { markdown: renderToMarkdown(acceptanceTest).trim() };
-                    if (acceptanceTest.linked_resources)
-                        section.linked_resources = acceptanceTest.linked_resources;
-                    return section;
-                });
-            }
             listOfRequirements.push(requirementSection);
         }
         plainSource[heading] = listOfRequirements;
     }
+    if (FUNCTIONAL_REQUIREMENTS in input) {
+        plainSource[FUNCTIONAL_REQUIREMENTS] = functionalitiesOf(input).map(marshallFunctionality);
+    }
     return plainSource;
 }
 export function normalizeLineEndings(plainSourceText) {
@@ -326,12 +242,14 @@ export function restoreStrippedLines(plainSourceText, content) {
 export function readPlainSourceMetadata(plainSourceText) {
     let metadata = {};
     let content = plainSourceText;
-    const match = /^---[ \t]*\n([\s\S]*?)\n---[ \t]*(?:\n|$)/.exec(plainSourceText);
+    // python-frontmatter's boundary: a line of three or more dashes, the block between them possibly empty.
+    const match = /^-{3,}[ \t]*\n(?:([\s\S]*?)\n)?-{3,}[ \t]*(?:\n|$)/.exec(plainSourceText);
     if (match) {
         try {
             // python-frontmatter yields {} when the block does not parse to a mapping,
             // so a malformed directive block is ignored rather than fatal.
-            const loaded = loadYaml(match[1]);
+            const block = match[1] ?? "";
+            const loaded = block.trim() === "" ? {} : loadYaml(block);
             metadata =
                 loaded !== null && typeof loaded === "object" && !Array.isArray(loaded)
                     ? loaded
@@ -368,6 +286,141 @@ export function readPlainSourceMetadata(plainSourceText) {
     }
     return { metadata, content };
 }
+/** `Syntax error at line N in module 'm'`, without the parts that are not known. */
+export function syntaxErrorAt(line, moduleName) {
+    let where = "Syntax error";
+    if (line !== null && line !== undefined)
+        where += ` at line ${line}`;
+    if (moduleName)
+        where += ` in module '${moduleName}'`;
+    return where;
+}
+export const TEST_PLAIN_FILE_SECTION_HEADINGS = [CONFORMANCE_TEST_HEADING, ACCEPTANCE_TEST_HEADING];
+/** Throw when a `***conformance tests***` or `***acceptance tests***` marker is anywhere in a spec plain file. */
+export function checkNoTestSections(plainSourceFullText, moduleName) {
+    plainSourceFullText.split("\n").forEach((line, index) => {
+        for (const heading of TEST_PLAIN_FILE_SECTION_HEADINGS) {
+            if (line.trim() === `***${heading}***`) {
+                throw new PlainSyntaxError(`Plain syntax error: ${syntaxErrorAt(index + 1, moduleName)}: The \`${heading}\` section is not ` +
+                    "allowed in a spec plain file; test scenarios live in test plain files.");
+            }
+        }
+    });
+}
+/** The name in a `***name***` paragraph, or null when the paragraph is not a section marker. */
+export function sectionMarker(token) {
+    const paragraphChildren = token.children ?? [];
+    if (paragraphChildren.length !== 1 || paragraphChildren[0].type !== "emphasis")
+        return null;
+    const emphasisChildren = paragraphChildren[0].children ?? [];
+    if (emphasisChildren.length !== 1 || emphasisChildren[0].type !== "strong")
+        return null;
+    return String((emphasisChildren[0].children ?? [])[0]?.value ?? "");
+}
+/** Whether a block is an ATX heading - `# text` - as mistletoe's `Heading`; a setext one is not. */
+function isAtxHeading(token) {
+    return token.type === "heading" && token.sourceLine === undefined;
+}
+/**
+ * Add the sections of the rendered spec plain file to `plainSource`.
+ *
+ * A list section holds a section whose children are its list items; `functional specs` holds a list of
+ * functionalities, one per `# <func-id>` heading, each with every block up to the next heading or section marker.
+ * Throw on the first structural error.
+ */
+export function readSections(plainSource, document, moduleName) {
+    let currentSpecificationHeading = null;
+    let currentFunctionality = null;
+    const processedSpecificationHeadings = new Set();
+    // Func-id to the line of its heading.
+    const functionalityLines = new Map();
+    const closeFunctionality = () => {
+        if (currentFunctionality !== null && currentFunctionality.body.length === 0) {
+            throw new PlainSyntaxError(`Plain syntax error: ${syntaxErrorAt(currentFunctionality.lineNumber, moduleName)}: ` +
+                `Functionality \`${currentFunctionality.id}\` has no body.`);
+        }
+    };
+    for (const token of document.children ?? []) {
+        const tokenText = getRawText(token).trim();
+        const where = syntaxErrorAt(lineNumber(token), moduleName);
+        const inFunctionalSpecs = currentSpecificationHeading === FUNCTIONAL_REQUIREMENTS;
+        if (isAtxHeading(token)) {
+            if (!inFunctionalSpecs) {
+                throw new PlainSyntaxError(`Plain syntax error: ${where}: A \`# <func-id>\` heading is allowed only in the ` +
+                    `${FUNCTIONAL_REQUIREMENTS} section (\`${tokenText}\`).`);
+            }
+            if (token.depth !== 1) {
+                throw new PlainSyntaxError(`Plain syntax error: ${where}: Invalid heading level ${token.depth} (\`${tokenText}\`). ` +
+                    "A functionality heading is `# <func-id>`.");
+            }
+            if (!isSemanticId(tokenText)) {
+                throw new PlainSyntaxError(`Plain syntax error: ${where}: Invalid func-id (\`${tokenText}\`). A func-id is lowercase letters ` +
+                    "and digits, with single hyphens between them.");
+            }
+            if (functionalityLines.has(tokenText)) {
+                throw new PlainSyntaxError(`Plain syntax error: ${where}: Duplicate func-id \`${tokenText}\`; it is first used at line ` +
+                    `${functionalityLines.get(tokenText)}.`);
+            }
+            closeFunctionality();
+            functionalityLines.set(tokenText, lineNumber(token));
+            currentFunctionality = { id: tokenText, lineNumber: lineNumber(token), body: [], linkedResources: [] };
+            functionalitiesOf(plainSource).push(currentFunctionality);
+        }
+        else if (token.type === "paragraph") {
+            const specificationHeading = sectionMarker(token);
+            if (specificationHeading === null) {
+                if (!inFunctionalSpecs) {
+                    throw new PlainSyntaxError(`Plain syntax error: ${where}: Invalid specification (\`${tokenText}\`)`);
+                }
+                if (currentFunctionality === null) {
+                    throw new PlainSyntaxError(`Plain syntax error: ${where}: Content before the first \`# <func-id>\` heading in the ` +
+                        `${FUNCTIONAL_REQUIREMENTS} section (\`${tokenText}\`). ${PREVIOUS_SYNTAX_HINT}`);
+                }
+                currentFunctionality.body.push(token);
+                continue;
+            }
+            if (!ALLOWED_SPECIFICATION_HEADINGS.includes(specificationHeading)) {
+                throw new PlainSyntaxError(`Plain syntax error: ${where}: Invalid specification heading (\`${specificationHeading}\`). ` +
+                    `Allowed headings: ${ALLOWED_SPECIFICATION_HEADINGS.join(", ")}`);
+            }
+            if (processedSpecificationHeadings.has(specificationHeading)) {
+                throw new PlainSyntaxError(`Plain syntax error: ${where}: Duplicate specification heading (\`${specificationHeading}\`)`);
+            }
+            if (specificationHeading === DEFINITIONS && currentSpecificationHeading !== null) {
+                throw new PlainSyntaxError(`Plain syntax error: ${where}: Definitions specification must be the first specification in ` +
+                    `the section (\`${tokenText}\`)`);
+            }
+            closeFunctionality();
+            currentFunctionality = null;
+            currentSpecificationHeading = specificationHeading;
+            if (specificationHeading === FUNCTIONAL_REQUIREMENTS) {
+                plainSource[specificationHeading] = [];
+            }
+            else if (plainSource[specificationHeading] == null) {
+                plainSource[specificationHeading] = { children: [] };
+            }
+            processedSpecificationHeadings.add(specificationHeading);
+        }
+        else if (token.type === "list" && !inFunctionalSpecs) {
+            if (currentSpecificationHeading === null) {
+                throw new PlainSyntaxError(`Plain syntax error: ${where}: Missing specification heading (\`${tokenText}\`)`);
+            }
+            sectionOf(plainSource, currentSpecificationHeading).children.push(...(token.children ?? []));
+        }
+        else if (inFunctionalSpecs) {
+            // The body of a functionality is free text: a list at any indentation, a code block, or any other block.
+            if (currentFunctionality === null) {
+                throw new PlainSyntaxError(`Plain syntax error: ${where}: Content before the first \`# <func-id>\` heading in the ` +
+                    `${FUNCTIONAL_REQUIREMENTS} section (\`${tokenText}\`). ${PREVIOUS_SYNTAX_HINT}`);
+            }
+            currentFunctionality.body.push(token);
+        }
+        else {
+            throw new PlainSyntaxError(`Plain syntax error: ${where}: Invalid source structure (\`${tokenText}\`)`);
+        }
+    }
+    closeFunctionality();
+}
 function processImports(plainSource, imports, codeVariables, templateDirs, importedModules, modulesTrace, importedFrom) {
     const requiredConcepts = [];
     for (const moduleName of imports) {
@@ -382,8 +435,8 @@ function processImports(plainSource, imports, codeVariables, templateDirs, impor
                 "Imported modules may only provide definitions, implementation reqs, and test reqs — " +
                 "use 'requires' instead of 'import' if this module's functionalities should be built on.");
         }
-        for (const section of Object.values(result.plainSource)) {
-            for (const item of section?.children ?? [])
+        for (const heading of LIST_SECTION_HEADINGS) {
+            for (const item of sectionOf(result.plainSource, heading)?.children ?? [])
                 importedFrom.set(item, result.importedFrom.get(item) ?? moduleName);
         }
         for (const heading of Object.keys(result.plainSource)) {
@@ -395,7 +448,7 @@ function processImports(plainSource, imports, codeVariables, templateDirs, impor
                 plainSource[heading] = result.plainSource[heading] ?? null;
             }
             else if (result.plainSource[heading] != null) {
-                plainSource[heading].children.push(...result.plainSource[heading].children);
+                sectionOf(plainSource, heading).children.push(...sectionOf(result.plainSource, heading).children);
             }
         }
         if (REQUIRED_CONCEPTS_DIRECTIVE in result.plainSourceObj.metadata) {
@@ -412,7 +465,7 @@ function processImports(plainSource, imports, codeVariables, templateDirs, impor
     }
     return requiredConcepts;
 }
-export function parsePlainSource(plainSourceText, codeVariables, templateDirs, importedModules, modulesTrace) {
+export function parsePlainSource(plainSourceText, codeVariables, templateDirs, importedModules, modulesTrace, moduleName) {
     plainSourceText = normalizeLineEndings(plainSourceText);
     const plainSourceObj = readPlainSourceMetadata(plainSourceText);
     const plainSource = newPlainSource();
@@ -421,81 +474,53 @@ export function parsePlainSource(plainSourceText, codeVariables, templateDirs, i
     if (IMPORT_DIRECTIVE in plainSourceObj.metadata) {
         requiredConcepts = processImports(plainSource, plainSourceObj.metadata[IMPORT_DIRECTIVE], codeVariables, templateDirs, importedModules, modulesTrace, importedFrom);
     }
-    const [, loadedTemplates] = getLoadedTemplates(templateDirs, plainSourceText);
+    const [, loadedTemplates] = getLoadedTemplates(templateDirs, plainSourceText, moduleName);
     const plainSourceContent = restoreStrippedLines(plainSourceText, plainSourceObj.content);
     const plainSourceFullText = renderPlainSource(plainSourceContent, loadedTemplates, codeVariables);
+    checkNoTestSections(plainSourceFullText, moduleName);
+    // Blank lines are kept as the reference keeps them, parsed inside its renderer: one BlankLine token per blank line.
     const plainFile = parseMarkdown(plainSourceFullText);
     removeQuotes(plainFile);
-    let currentSpecificationHeading = null;
-    const processedSpecificationHeadings = new Set();
-    for (const token of plainFile.children ?? []) {
-        const tokenText = getRawText(token).trim();
-        if (token.type === "paragraph") {
-            const paragraphChildren = token.children ?? [];
-            const emphasisChildren = paragraphChildren.length > 0 && paragraphChildren[0].type === "emphasis"
-                ? (paragraphChildren[0].children ?? [])
-                : [];
-            if (!(paragraphChildren.length === 1 &&
-                paragraphChildren[0].type === "emphasis" &&
-                emphasisChildren.length === 1 &&
-                emphasisChildren[0].type === "strong")) {
-                throw new PlainSyntaxError(`Plain syntax error: Syntax error at line ${lineNumber(token)}: Invalid specification (\`${tokenText}\`)`);
-            }
-            const specificationHeading = String((emphasisChildren[0].children ?? [])[0]?.value ?? "");
-            if (specificationHeading === ACCEPTANCE_TEST_HEADING) {
-                throw new PlainSyntaxError(`Plain syntax error: Syntax error at line ${lineNumber(token)}: ${ACCEPTANCE_TEST_HEADING} heading should be nested under specific functional spec.`);
-            }
-            if (!ALLOWED_SPECIFICATION_HEADINGS.includes(specificationHeading)) {
-                throw new PlainSyntaxError(`Plain syntax error: Syntax error at line ${lineNumber(token)}: Invalid specification heading (\`${specificationHeading}\`). Allowed headings: ${ALLOWED_SPECIFICATION_HEADINGS.join(", ")}`);
-            }
-            if (specificationHeading === FUNCTIONAL_REQUIREMENTS && !(specificationHeading in plainSource)) {
-                plainSource[specificationHeading] = null;
-            }
-            if (processedSpecificationHeadings.has(specificationHeading)) {
-                throw new PlainSyntaxError(`Plain syntax error: Syntax error at line ${lineNumber(token)}: Duplicate specification heading (\`${specificationHeading}\`)`);
-            }
-            if (specificationHeading === DEFINITIONS && currentSpecificationHeading !== null) {
-                throw new PlainSyntaxError(`Plain syntax error: Syntax error at line ${lineNumber(token)}: Definitions specification must be the first specification in the section  (\`${tokenText}\`)`);
-            }
-            currentSpecificationHeading = specificationHeading;
-            if (plainSource[currentSpecificationHeading] == null) {
-                plainSource[currentSpecificationHeading] = { children: [] };
-            }
-            processedSpecificationHeadings.add(currentSpecificationHeading);
-        }
-        else if (token.type === "list") {
-            if (currentSpecificationHeading === null) {
-                throw new PlainSyntaxError(`Plain syntax error: Syntax error at line ${lineNumber(token)}: Missing specification heading (\`${tokenText}\`)`);
-            }
-            plainSource[currentSpecificationHeading].children.push(...(token.children ?? []));
-        }
-        else {
-            throw new PlainSyntaxError(`Plain syntax error: Syntax error at line ${lineNumber(token)}: Invalid source structure  (\`${tokenText}\`)`);
-        }
-    }
-    // Acceptance tests belong under functional specs only.
-    for (const nonFunctionalHeading of [DEFINITIONS, NON_FUNCTIONAL_REQUIREMENTS, TEST_REQUIREMENTS]) {
-        const section = plainSource[nonFunctionalHeading];
-        if (!section)
-            continue;
-        for (const child of section.children) {
-            const nested = findAcceptanceTestHeading(child);
-            if (nested !== null) {
-                throw new PlainSyntaxError(`Plain syntax error: Syntax error at line ${lineNumber(nested)}: ${ACCEPTANCE_TEST_HEADING} heading should be nested under specific functional spec.`);
-            }
-        }
-    }
-    const definitionsSection = plainSource[DEFINITIONS];
+    readSections(plainSource, plainFile, moduleName);
+    const definedConcepts = new Set();
+    const definitionsSection = sectionOf(plainSource, DEFINITIONS);
     if (definitionsSection) {
         for (const token of definitionsSection.children) {
             const [newConcepts] = extractConceptsFromDefinition(renderToMarkdown(token));
             for (const concept of newConcepts) {
+                definedConcepts.add(concept);
                 const index = requiredConcepts.indexOf(concept);
                 if (index !== -1)
                     requiredConcepts.splice(index, 1);
             }
         }
     }
+    if (EXPORTED_CONCEPTS_DIRECTIVE in plainSourceObj.metadata) {
+        const tracedModule = modulesTrace[modulesTrace.length - 1];
+        const subject = tracedModule ? `Module '${tracedModule}'` : "Module";
+        for (const entry of plainSourceObj.metadata[EXPORTED_CONCEPTS_DIRECTIVE]) {
+            const [exportedConcepts, errors] = extractConceptsFromDefinition(entry);
+            if (errors.length > 0) {
+                throw new PlainSyntaxError(`Plain syntax error: ${subject} exports an invalid concept (\`${entry}\`). ` +
+                    "Expected a concept token, e.g. :ConceptName:.");
+            }
+            for (const exportedConcept of exportedConcepts) {
+                if (DEFAULT_CONCEPTS.has(exportedConcept)) {
+                    throw new PlainSyntaxError(`Plain syntax error: ${subject} cannot export default concept ${exportedConcept}. ` +
+                        "Only user-defined concepts can be exported.");
+                }
+                if (!definedConcepts.has(exportedConcept)) {
+                    let message = `Plain syntax error: ${subject} exports undefined concept ${exportedConcept}.`;
+                    if (REQUIRES_DIRECTIVE in plainSourceObj.metadata) {
+                        message +=
+                            " An exported concept must be defined in this module's definitions or in an " +
+                                "imported module; a concept inherited through requires cannot be re-exported.";
+                    }
+                    throw new PlainSyntaxError(message);
+                }
+            }
+        }
+    }
     const requiredModules = plainSourceObj.metadata[REQUIRES_DIRECTIVE] ?? [];
     return { plainSource, plainSourceObj, requiredModules, requiredConcepts, importedFrom };
 }
@@ -515,29 +540,34 @@ export function readModulePlainSource(moduleName, templateDirs) {
     const blob = findLargeBase64Blob(plainSourceText);
     if (blob !== null) {
         throw new UnsupportedBase64Content(`Module '${moduleName}' contains a base64-encoded blob (${blob.length} characters) ` +
-            "inlined in the specification. This is not supported." +
-            "Remove the base64 data from the .plain file or if necessary," +
+            "inlined in the specification. This is not supported. " +
+            "Remove the base64 data from the .plain file or if necessary, " +
             "include the binary file path in the specification.");
     }
     return plainSourceText;
 }
 export function parsePlainFile(moduleName, codeVariables, templateDirs, importedModules, modulesTrace) {
     const plainSourceText = readModulePlainSource(moduleName, templateDirs);
-    return parsePlainSource(plainSourceText, codeVariables, templateDirs, importedModules, [
-        ...modulesTrace,
-        moduleName,
-    ]);
+    return parsePlainSource(plainSourceText, codeVariables, templateDirs, importedModules, [...modulesTrace, moduleName], moduleName);
 }
-export function processRequiredModules(requiredModules, codeVariables, templateDirs, allRequiredModules, modulesTrace) {
+/**
+ * Parse every required module, deepest first, without validating it - each with code variables of its own - and
+ * return the definitions the directly required modules export. A module listed again right after it was walked is
+ * not parsed again, and what it exports is still visible to this module. `exports` records what each module walked
+ * exports, so a repeat can find it.
+ */
+export function processRequiredModules(requiredModules, templateDirs, allRequiredModules, modulesTrace, exports = new Map()) {
     const exportedDefinitions = [];
     for (const moduleName of requiredModules) {
         if (modulesTrace.includes(moduleName)) {
             throw new PlainSyntaxError(`Plain syntax error: Circular required module detected: ${moduleName}.`);
         }
         if (allRequiredModules.length > 0 && moduleName === allRequiredModules[allRequiredModules.length - 1]) {
+            // Already walked as an earlier entry; its exports are still visible to this module.
+            exportedDefinitions.push(...(exports.get(moduleName) ?? []));
             continue;
         }
-        const result = parsePlainFile(moduleName, codeVariables, templateDirs, [], []);
+        const result = parsePlainFile(moduleName, {}, templateDirs, [], []);
         if (result.requiredModules.length === 0) {
             if (allRequiredModules.length > 0) {
                 // Required modules must form one chain; independent modules cannot yet be merged.
@@ -545,40 +575,31 @@ export function processRequiredModules(requiredModules, codeVariables, templateD
             }
         }
         else {
-            processRequiredModules(result.requiredModules, codeVariables, templateDirs, allRequiredModules, [
-                ...modulesTrace,
-                moduleName,
-            ]);
+            processRequiredModules(result.requiredModules, templateDirs, allRequiredModules, [...modulesTrace, moduleName], exports);
         }
-        exportedDefinitions.push(...exportedDefinitionsOf(result));
+        const own = exportedDefinitionsOf(result);
+        exports.set(moduleName, own);
+        exportedDefinitions.push(...own);
         allRequiredModules.push(moduleName);
     }
     return exportedDefinitions;
 }
-/** The definitions a required module exports: those of its `exported_concepts`, with the definitions they use. */
+/**
+ * The definitions a required module exports: those of its `exported_concepts`, with the definitions they use. What
+ * it may export is checked as it is parsed (`parsePlainSource`).
+ */
 export function exportedDefinitionsOf(result) {
     if (!(EXPORTED_CONCEPTS_DIRECTIVE in result.plainSourceObj.metadata))
         return [];
-    const exportedConcepts = [];
-    for (const concept of result.plainSourceObj.metadata[EXPORTED_CONCEPTS_DIRECTIVE]) {
-        if (typeof concept === "string" && DEFAULT_CONCEPTS.has(concept)) {
-            throw new PlainSyntaxError(`Plain syntax error: Default concept cannot be exported: ${concept}. Only user-defined concepts can be exported.`);
-        }
-        if (typeof concept === "string") {
-            exportedConcepts.push(...extractConceptsFromDefinition(concept)[0]);
-        }
-        else {
-            throw new PlainSyntaxError(`Plain syntax error: Invalid exported concept: ${concept}.`);
-        }
-    }
-    return exportedConcepts.flatMap((exportedConcept) => findConceptDefinitionsInPlainSource(exportedConcept, result.plainSource[DEFINITIONS] ?? null));
+    const exportedConcepts = result.plainSourceObj.metadata[EXPORTED_CONCEPTS_DIRECTIVE].flatMap((concept) => extractConceptsFromDefinition(concept)[0]);
+    return exportedConcepts.flatMap((exportedConcept) => findConceptDefinitionsInPlainSource(exportedConcept, sectionOf(result.plainSource, DEFINITIONS) ?? null));
 }
 export function processExportedDefinitions(plainSource, exportedDefinitions) {
     if (exportedDefinitions.length === 0)
         return;
-    const definitions = plainSource[DEFINITIONS];
-    if (!definitions)
-        return;
+    if (!plainSource[DEFINITIONS])
+        plainSource[DEFINITIONS] = { children: [] };
+    const definitions = sectionOf(plainSource, DEFINITIONS);
     for (const exportedDefinition of exportedDefinitions) {
         const exportedRendered = renderToMarkdown(exportedDefinition).trim();
         const alreadyPresent = definitions.children.some((definition) => renderToMarkdown(definition).trim() === exportedRendered);
@@ -587,17 +608,18 @@ export function processExportedDefinitions(plainSource, exportedDefinitions) {
     }
 }
 export function plainFileParser(plainSourceFileName, templateDirs, options = {}) {
-    const key = `${options.allowNoFunctionalities ? "any" : "renderable"}\0${process.cwd()}\0${templateDirs.join("\0")}\0${plainSourceFileName}`;
+    const tests = options.testDir === undefined ? "" : `${resolve(options.testDir)}${options.requireTestPlainFiles === true ? "!" : ""}`;
+    const key = `${options.allowNoFunctionalities ? "any" : "renderable"}\0${process.cwd()}\0${templateDirs.join("\0")}\0${plainSourceFileName}\0${tests}`;
     if (activeCache === undefined) {
         // Between calls: the parse from before, while nothing it could have read has changed since.
-        const fingerprint = filesFingerprint(templateDirs);
+        const fingerprint = filesFingerprint(templateDirs, options.testDir);
         const kept = lastParses.get(key);
         if (stillHolds(kept, fingerprint)) {
             if (kept.error !== undefined)
                 throw kept.error;
             return structuredClone(kept.parsed);
         }
-        const result = parseNoting(() => parseModule(plainSourceFileName, templateDirs, new Map(), options));
+        const result = parseNoting(() => parseWithTestPlainFiles(plainSourceFileName, templateDirs, new Map(), options));
         // A spec that does not parse does not parse again until it, or a file it links, changes: it is not parsed again to say so.
         if (fingerprint !== undefined)
             remember(key, { fingerprint, linked: result.linked, linkedStamp: linkedStamp(result.linked), ...(result.error !== undefined ? { error: result.error } : { parsed: structuredClone(result.parsed) }) });
@@ -608,10 +630,10 @@ export function plainFileParser(plainSourceFileName, templateDirs, options = {})
     let parsed = activeCache.get(key);
     if (parsed === undefined) {
         // Nothing changes while `run` runs: each folder set's fingerprint is taken once.
-        const dirsKey = templateDirs.join("\0");
+        const dirsKey = `${templateDirs.join("\0")}\0${options.testDir ?? ""}`;
         let fingerprint = activeCache.fingerprints.get(dirsKey);
         if (!activeCache.fingerprints.has(dirsKey)) {
-            fingerprint = filesFingerprint(templateDirs);
+            fingerprint = filesFingerprint(templateDirs, options.testDir);
             activeCache.fingerprints.set(dirsKey, fingerprint);
         }
         const kept = lastParses.get(key);
@@ -622,7 +644,7 @@ export function plainFileParser(plainSourceFileName, templateDirs, options = {})
         }
         else {
             const modules = activeCache.modules;
-            const result = parseNoting(() => parseModule(plainSourceFileName, templateDirs, modules, options));
+            const result = parseNoting(() => parseWithTestPlainFiles(plainSourceFileName, templateDirs, modules, options));
             if (fingerprint !== undefined)
                 remember(key, { fingerprint, linked: result.linked, linkedStamp: linkedStamp(result.linked), ...(result.error !== undefined ? { error: result.error } : { parsed: structuredClone(result.parsed) }) });
             if (result.error !== undefined)
@@ -633,6 +655,33 @@ export function plainFileParser(plainSourceFileName, templateDirs, options = {})
     }
     return parsed;
 }
+/**
+ * Port of plain_file.parse_module_chain: a module and every module in its `requires` chain, each as its name and its
+ * tree - every required module first, deepest ancestors first, then the module itself. A module reached through more
+ * than one `requires` path appears once, at its first (deepest) position.
+ */
+export function parseModuleChain(plainSourceFileName, templateDirs, options = {}) {
+    return withParseCache(() => {
+        const [moduleName, tree, requiredModules] = plainFileParser(plainSourceFileName, templateDirs, options);
+        const chain = [];
+        const walked = new Set();
+        const walk = (names) => {
+            for (const name of names) {
+                if (walked.has(name))
+                    continue;
+                const [requiredName, requiredTree, itsRequires] = plainFileParser(`${name}${PLAIN_SOURCE_FILE_EXTENSION}`, templateDirs);
+                walk(itsRequires);
+                if (walked.has(requiredName))
+                    continue;
+                walked.add(requiredName);
+                chain.push([requiredName, requiredTree]);
+            }
+        };
+        walk(requiredModules);
+        chain.push([moduleName, tree]);
+        return chain;
+    });
+}
 /**
  * One parse per file for the length of `run`, however many times it is asked for.
  *
@@ -662,9 +711,13 @@ function remember(key, entry) {
     while (lastParses.size > KEPT_PARSES)
         lastParses.delete(lastParses.keys().next().value);
 }
-function filesFingerprint(templateDirs) {
+function filesFingerprint(templateDirs, testDir) {
     try {
         const parts = [];
+        // Every .plain file under the test folder, by name and text: a scenario written, changed or removed is seen.
+        if (testDir !== undefined)
+            for (const path of plainFilesUnder(resolve(testDir)))
+                parts.push(`${path}:${readFileSync(path, "utf8")}`);
         for (const dir of [process.cwd(), ...templateDirs]) {
             let entries;
             try {
@@ -688,6 +741,74 @@ function filesFingerprint(templateDirs) {
         return undefined;
     }
 }
+/** Every .plain file under a folder, at any depth, sorted; none when it is not there. */
+function plainFilesUnder(dir) {
+    let entries;
+    try {
+        entries = readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const found = [];
+    for (const entry of entries.sort((a, b) => (a.name < b.name ? -1 : 1))) {
+        const path = join(dir, entry.name);
+        if (entry.isDirectory())
+            found.push(...plainFilesUnder(path));
+        else if (entry.name.endsWith(PLAIN_SOURCE_FILE_EXTENSION))
+            found.push(path);
+    }
+    return found;
+}
+/**
+ * A module parsed, and - with `options.testDir` - its chain's test plain files bound to it: the scenarios on its
+ * functional specs and on the ones it inherits, `TEST_PLAIN_FILES` naming each file and what it binds to.
+ */
+function parseWithTestPlainFiles(plainSourceFileName, templateDirs, cache, options) {
+    const [moduleName, tree, requiredModules] = parseModule(plainSourceFileName, templateDirs, cache, options);
+    if (options.testDir === undefined)
+        return [moduleName, tree, requiredModules];
+    // The chain, deepest first, each tree a copy the scenarios are bound into.
+    const chain = [];
+    const walked = new Set();
+    const walk = (names) => {
+        for (const name of names) {
+            if (walked.has(name))
+                continue;
+            let parsed = cache.get(name);
+            if (parsed === undefined) {
+                parsed = parseModule(`${name}${PLAIN_SOURCE_FILE_EXTENSION}`, templateDirs, cache);
+                cache.set(name, parsed);
+            }
+            walk(parsed[2]);
+            if (walked.has(parsed[0]))
+                continue;
+            walked.add(parsed[0]);
+            chain.push([parsed[0], structuredClone(parsed[1])]);
+        }
+    };
+    walk(requiredModules);
+    const own = structuredClone(tree);
+    chain.push([moduleName, own]);
+    const testDirs = chain.map(([name]) => join(options.testDir, name));
+    const bound = bindTestPlainFiles(chain, testDirs, templateDirs, templateDirs[0] ?? ".");
+    if (options.requireTestPlainFiles === true)
+        checkTestPlainFiles(chain, bound);
+    // What the module inherits carries the scenarios bound in the module it is written in.
+    const boundItems = new Map();
+    for (const [name, chainTree] of chain)
+        for (const item of getFunctionalSpecs(chainTree))
+            boundItems.set(`${name}\0${item.id}`, item);
+    const inherited = own[REQUIRED_FUNCTIONAL_SPECS];
+    if (inherited !== undefined) {
+        own[REQUIRED_FUNCTIONAL_SPECS] = inherited.map((item) => {
+            const boundItem = boundItems.get(`${item.module}\0${item.id}`);
+            return boundItem === undefined ? item : { ...item, [CONFORMANCE_TESTS]: boundItem[CONFORMANCE_TESTS], [ACCEPTANCE_TESTS]: boundItem[ACCEPTANCE_TESTS] };
+        });
+    }
+    own[TEST_PLAIN_FILES] = Object.fromEntries(bound.map((file) => [file.name, { module: file.parsed.module, func_id: file.parsed.funcId }]));
+    return [moduleName, own, requiredModules];
+}
 /**
  * The functional specs a module inherits through `requires`, bottom of the chain first.
  *
@@ -701,7 +822,7 @@ function inheritFunctionalSpecs(requires, templateDirs, cache) {
     const inherited = [];
     const seen = new Set();
     const add = (item) => {
-        const key = `${item.module}/${item.frid}`;
+        const key = `${item.module}/${item.id}`;
         if (seen.has(key))
             return;
         seen.add(key);
@@ -716,7 +837,8 @@ function inheritFunctionalSpecs(requires, templateDirs, cache) {
         const [moduleName, tree] = parsed;
         for (const item of tree[REQUIRED_FUNCTIONAL_SPECS] ?? [])
             add(item);
-        (getSpecificationItems(tree, FUNCTIONAL_REQUIREMENTS) ?? []).forEach((item, index) => add({ ...item, module: moduleName, frid: String(index + 1) }));
+        for (const item of getFunctionalSpecs(tree))
+            add({ ...item, module: moduleName });
     }
     return inherited;
 }
@@ -741,13 +863,12 @@ function parseModule(plainSourceFileName, templateDirs, cache, options = {}) {
             "At least one functionality is required for rendering.");
     }
     if (!options.allowNoFunctionalities && countFunctionalities(result.plainSource) === 0) {
-        throw new PlainSyntaxError(`Plain syntax error: Module '${moduleName}' has an empty '${FUNCTIONAL_REQUIREMENTS}' section. ` +
-            "At least one functionality must be specified.");
+        throw new PlainSyntaxError(`Plain syntax error: Module '${moduleName}' has a '${FUNCTIONAL_REQUIREMENTS}' section ` +
+            `without a \`# <func-id>\` heading. ${PREVIOUS_SYNTAX_HINT}`);
     }
     validateFunctionalitiesHaveImplementationReqs(result.plainSource, moduleName, result.requiredModules.length > 0);
-    const exportedDefinitions = processRequiredModules(result.requiredModules, {}, templateDirs, [], []);
+    const exportedDefinitions = processRequiredModules(result.requiredModules, templateDirs, [], []);
     processExportedDefinitions(result.plainSource, exportedDefinitions);
-    processAcceptanceTests(result.plainSource);
     checkForLinkedResources(result.plainSource, templateDirs);
     const marshalled = marshallPlainSource(result.plainSource);
     processCodeVariables(marshalled, codeVariables);