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

package/dist/plain/spec.js

@@ -1,44 +1,55 @@
 import { createHash } from "node:crypto";
 import { InvalidFridArgument } from "./errors.js";
-/** 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 const DEFINITIONS = "definitions";
 export const NON_FUNCTIONAL_REQUIREMENTS = "implementation reqs";
 export const TEST_REQUIREMENTS = "test reqs";
 export const FUNCTIONAL_REQUIREMENTS = "functional specs";
+export const CONFORMANCE_TESTS = "conformance_tests";
 export const ACCEPTANCE_TESTS = "acceptance_tests";
+export const CONFORMANCE_TEST_HEADING = "conformance 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.
+ * 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 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,
-];
+/**
+ * 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 const TEST_PLAIN_FILES = "test plain files";
+/** The sections whose content is a list of `- ` items. */
+export const LIST_SECTION_HEADINGS = [DEFINITIONS, NON_FUNCTIONAL_REQUIREMENTS, TEST_REQUIREMENTS];
+export const ALLOWED_SPECIFICATION_HEADINGS = [...LIST_SECTION_HEADINGS, FUNCTIONAL_REQUIREMENTS];
+export const ALLOWED_IMPORT_SPECIFICATION_HEADINGS = LIST_SECTION_HEADINGS;
+/**
+ * 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 const SEMANTIC_ID_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+export function isSemanticId(text) {
+    return SEMANTIC_ID_PATTERN.test(text);
+}
 /**
  * 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 function getInheritedFunctionalSpecs(tree, replaceCodeVariables = true) {
     const items = tree[REQUIRED_FUNCTIONAL_SPECS] ?? [];
     return items.map((item) => {
         const codeVariables = {};
-        const tests = item[ACCEPTANCE_TESTS];
+        const scenarios = (list) => (list ?? []).map((scenario) => ({ id: scenario.id, text: getSpecificationItemMarkdown(scenario, codeVariables, replaceCodeVariables, "text") }));
         return {
             module: item.module,
-            frid: item.frid,
+            funcId: item.id,
             spec: getSpecificationItemMarkdown(item, codeVariables, replaceCodeVariables),
-            acceptanceTests: tests?.map((test) => getSpecificationItemMarkdown(test, codeVariables, replaceCodeVariables)),
+            conformanceTests: scenarios(item[CONFORMANCE_TESTS]),
+            acceptanceTests: scenarios(item[ACCEPTANCE_TESTS]),
         };
     });
 }
@@ -46,13 +57,14 @@ export function getSpecificationItems(tree, heading) {
     const value = tree[heading];
     return Array.isArray(value) ? value : undefined;
 }
+/** The functional specs of a tree, in file order. */
+export function getFunctionalSpecs(tree) {
+    const value = tree[FUNCTIONAL_REQUIREMENTS];
+    return Array.isArray(value) ? value : [];
+}
+/** True if any functional spec of the tree has acceptance scenarios. */
 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;
+    return getFunctionalSpecs(tree).some((item) => (item[ACCEPTANCE_TESTS] ?? []).length > 0);
 }
 export function collectSpecificationLinkedResources(specification, specificationHeading, linkedResourcesList) {
     for (const resource of specification.linked_resources ?? []) {
@@ -86,59 +98,49 @@ export function collectSpecificationLinkedResources(specification, specification
         }
     }
 }
-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));
+/**
+ * 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 function collectLinkedResources(tree, linkedResourcesList, specificationsList, includeTestScenarios, frid = null) {
+    if (tree === null || typeof tree !== "object" || Array.isArray(tree)) {
+        throw new TypeError("plain_source_tree must be a dictionary.");
     }
-    for (const heading of toCollect) {
-        for (const requirement of getSpecificationItems(section, heading) ?? []) {
-            collectSpecificationLinkedResources(requirement, heading, linkedResourcesList);
-        }
+    if (frid !== null && ![...getFrids(tree)].includes(frid)) {
+        throw new Error(`frid ${frid} does not exist.`);
     }
-    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);
+    const sectionsToCollect = ALLOWED_SPECIFICATION_HEADINGS.filter((heading) => heading in tree && (!specificationsList || specificationsList.length === 0 || specificationsList.includes(heading)));
+    let fridReached = false;
+    for (const heading of sectionsToCollect) {
+        for (const specification of tree[heading] ?? []) {
+            collectSpecificationLinkedResources(specification, heading, linkedResourcesList);
+            if (heading !== FUNCTIONAL_REQUIREMENTS)
+                continue;
+            if (includeTestScenarios && (frid === null || frid === specification.id)) {
+                for (const scenario of [...(specification[CONFORMANCE_TESTS] ?? []), ...(specification[ACCEPTANCE_TESTS] ?? [])]) {
+                    collectSpecificationLinkedResources(scenario, FUNCTIONAL_REQUIREMENTS, linkedResourcesList);
                 }
             }
-            // FRIDs increment, so once the requested one is reached nothing after it counts.
-            if (frid !== null && currentFrid === frid)
-                return true;
+            if (specification.id === frid) {
+                fridReached = true;
+                break;
+            }
         }
     }
-    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;
+    return fridReached;
 }
 /**
- * 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
+ * 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 function* getFrids(tree) {
-    const functionalRequirements = getSpecificationItems(tree, FUNCTIONAL_REQUIREMENTS) ?? [];
-    for (let id = 1; id <= functionalRequirements.length; id += 1)
-        yield String(id);
+    for (const functionality of getFunctionalSpecs(tree))
+        yield functionality.id;
 }
 export function getFirstFrid(tree) {
     const first = getFrids(tree).next();
@@ -163,6 +165,7 @@ export function getPreviousFrid(tree, frid) {
     }
     throw new Error(`Functionality ${frid} does not exist.`);
 }
+/** The func-ids that come before `targetFrid` in the specification, in order. */
 export function getFridsBefore(tree, targetFrid) {
     const before = [];
     for (const frid of getFrids(tree)) {
@@ -172,8 +175,12 @@ export function getFridsBefore(tree, targetFrid) {
     }
     return before;
 }
-export function getSpecificationItemMarkdown(specificationItem, codeVariables, replaceCodeVariables) {
-    let markdown = specificationItem.markdown;
+/**
+ * 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 function getSpecificationItemMarkdown(specificationItem, codeVariables, replaceCodeVariables, key = "markdown") {
+    let markdown = String(specificationItem[key]);
     for (const codeVariable of specificationItem.code_variables ?? []) {
         if (codeVariable.name in codeVariables) {
             if (codeVariables[codeVariable.name] !== codeVariable.value) {
@@ -189,67 +196,41 @@ export function getSpecificationItemMarkdown(specificationItem, codeVariables, r
     }
     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.
+ * 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 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)
+    const functionalities = getFunctionalSpecs(tree);
+    const position = functionalities.findIndex((item) => item.id === frid);
+    if (position === -1)
         throw new Error(`Functionality ${frid} does not exist.`);
+    const codeVariables = {};
+    const texts = (items, key = "markdown") => items.map((item) => getSpecificationItemMarkdown(item, codeVariables, replaceCodeVariables, key));
+    const scenarios = (items) => {
+        const scenarioTexts = texts(items, "text");
+        return items.map((item, index) => ({ id: item.id, text: scenarioTexts[index] }));
+    };
+    const listOf = (heading) => getSpecificationItems(tree, heading) ?? [];
+    const functionality = functionalities[position];
     const specifications = {
-        [DEFINITIONS]: definitions,
-        [NON_FUNCTIONAL_REQUIREMENTS]: nonFunctionalRequirements,
-        [TEST_REQUIREMENTS]: testRequirements,
-        [FUNCTIONAL_REQUIREMENTS]: functionalRequirements,
+        [DEFINITIONS]: texts(listOf(DEFINITIONS)),
+        [NON_FUNCTIONAL_REQUIREMENTS]: texts(listOf(NON_FUNCTIONAL_REQUIREMENTS)),
+        [TEST_REQUIREMENTS]: texts(listOf(TEST_REQUIREMENTS)),
+        [FUNCTIONAL_REQUIREMENTS]: texts(functionalities.slice(0, position + 1)),
+        [CONFORMANCE_TESTS]: scenarios(functionality[CONFORMANCE_TESTS] ?? []),
+        [ACCEPTANCE_TESTS]: scenarios(functionality[ACCEPTANCE_TESTS] ?? []),
     };
-    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. */
+/** Iterate every functional spec with the context that should be rendered for it. turri's, for a host. */
 export function* iterateFunctionalSpecs(tree, replaceCodeVariables = true) {
-    for (const frid of getFrids(tree)) {
-        const [specifications, codeVariables] = getSpecificationsForFrid(tree, frid, replaceCodeVariables);
-        yield { frid, specifications, codeVariables };
+    for (const funcId of getFrids(tree)) {
+        const [specifications, codeVariables] = getSpecificationsForFrid(tree, funcId, replaceCodeVariables);
+        yield { funcId, specifications, codeVariables };
     }
 }
 export function hashText(text) {
@@ -258,17 +239,18 @@ export function hashText(text) {
 export function getHashValue(specifications) {
     return hashText(JSON.stringify(specifications, null, 4));
 }
-function getFridsRange(tree, start, end) {
+/** The func-ids from `start` through `end` inclusive, or through the last one when `end` is not given. */
+export function getFridsRange(tree, start, end) {
     const frids = [...getFrids(tree)];
-    start = String(start);
+    // Python prints the list with repr.
+    const valid = `[${frids.map((frid) => `'${frid}'`).join(", ")}]`;
     if (!frids.includes(start)) {
-        throw new InvalidFridArgument(`Invalid start functionality ID: ${start}. Valid IDs are: ${JSON.stringify(frids)}.`);
+        throw new InvalidFridArgument(`Invalid start functionality ID: ${start}. Valid IDs are: ${valid}.`);
     }
     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)}.`);
+            throw new InvalidFridArgument(`Invalid end functionality ID: ${end}. Valid IDs are: ${valid}.`);
         }
         endIdx = frids.indexOf(end) + 1;
     }
@@ -281,11 +263,3 @@ function getFridsRange(tree, start, 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/test-plain-file.d.ts

@@ -0,0 +1,59 @@
+import { type LinkedResource } from "./markdown.ts";
+import { type CodeVariable, type ScenarioItem } from "./spec.ts";
+/**
+ * Port of test_plain_file.py: test plain files, the conformance and acceptance scenarios of one functionality.
+ *
+ * A test plain file binds to a functionality with the frontmatter keys `module` and `func_id`. It holds a
+ * `***conformance tests***` section, an `***acceptance tests***` section or both, in that order, each with at least one
+ * scenario: a section with none is left out, and a file with none is not written - a functional spec with no scenarios has
+ * no test plain file. Each scenario is a `# <scenario-id>` heading followed by free text, which is kept verbatim.
+ */
+export declare const MODULE_KEY = "module";
+export declare const FUNC_ID_KEY = "func_id";
+export declare const FRONTMATTER_KEYS: string[];
+export declare const SECTION_HEADINGS: readonly ["conformance tests", "acceptance tests"];
+export interface Scenario {
+    id: string;
+    lineNumber: number;
+    /** The body as written, without `>` comment lines and without leading and trailing blank lines. */
+    text: string;
+    linkedResources: LinkedResource[];
+    codeVariables: CodeVariable[];
+}
+/** A scenario as the parse gives it: `{id, text, linked_resources}`, and `code_variables` when it uses any. */
+export declare function scenarioItem(scenario: Scenario): ScenarioItem;
+export interface TestPlainFile {
+    /** The path of the file as shown in messages. */
+    name: string;
+    module: string;
+    funcId: string;
+    conformanceTests: Scenario[];
+    acceptanceTests: Scenario[];
+}
+export declare function scenariosOf(file: TestPlainFile): Scenario[];
+/** Whether a frontmatter binds its file to a functionality, which makes the file a test plain file. */
+export declare function isTestPlainFile(metadata: Record<string, unknown>): boolean;
+/**
+ * The frontmatter and content of a ***plain file, as python-frontmatter reads them: a block between two lines of
+ * three or more dashes, loaded as YAML - a block that is not a mapping is no metadata - and the content after it,
+ * stripped. Raises the YAML error as it is.
+ */
+export declare function loadFrontmatter(text: string): {
+    metadata: Record<string, unknown>;
+    content: string;
+};
+/** The frontmatter and content of a test plain file; raise unless the keys are exactly module and func_id. */
+export declare function readMetadata(text: string, name: string): {
+    metadata: Record<string, unknown>;
+    content: string;
+};
+/** The scenarios of the rendered content, keyed by section heading - a section left out, none; raise on the first structural error. */
+export declare function readScenarios(renderedText: string, name: string): Record<string, Scenario[]>;
+export declare function findScenarioLinkedResources(scenario: Scenario, templateDirs: string[], name: string): LinkedResource[];
+/**
+ * Parse the text of a test plain file. Liquid runs as on a spec plain file, with the same template folders; every
+ * link in a scenario is resolved against them. Concepts are not checked here, see `validateScenarioConcepts`.
+ */
+export declare function parseTestPlainFileSource(plainSourceText: string, name: string, templateDirs: string[], codeVariables: Record<string, Record<string, string>>): TestPlainFile;
+/** One message per concept used in a scenario that is neither in `concepts` nor predefined. */
+export declare function validateScenarioConcepts(file: TestPlainFile, concepts: Set<string>): string[];

package/dist/plain/test-plain-file.js

@@ -0,0 +1,232 @@
+import { load as loadYaml } from "js-yaml";
+import { extractConceptsFromSpecText, DEFAULT_CONCEPTS } from "./concepts.js";
+import { PlainSyntaxError } from "./errors.js";
+import { getLoadedTemplates } from "./files.js";
+import { renderPlainSource } from "./liquid.js";
+import { parseMarkdown } from "./markdown.js";
+import { findLinkedResources, normalizeLineEndings, processSectionCodeVariables, restoreStrippedLines } from "./parser.js";
+import { ACCEPTANCE_TEST_HEADING, CONFORMANCE_TEST_HEADING, isSemanticId } from "./spec.js";
+/**
+ * Port of test_plain_file.py: test plain files, the conformance and acceptance scenarios of one functionality.
+ *
+ * A test plain file binds to a functionality with the frontmatter keys `module` and `func_id`. It holds a
+ * `***conformance tests***` section, an `***acceptance tests***` section or both, in that order, each with at least one
+ * scenario: a section with none is left out, and a file with none is not written - a functional spec with no scenarios has
+ * no test plain file. Each scenario is a `# <scenario-id>` heading followed by free text, which is kept verbatim.
+ */
+export const MODULE_KEY = "module";
+export const FUNC_ID_KEY = "func_id";
+export const FRONTMATTER_KEYS = [MODULE_KEY, FUNC_ID_KEY];
+export const SECTION_HEADINGS = [CONFORMANCE_TEST_HEADING, ACCEPTANCE_TEST_HEADING];
+/** A scenario as the parse gives it: `{id, text, linked_resources}`, and `code_variables` when it uses any. */
+export function scenarioItem(scenario) {
+    const entry = { id: scenario.id, text: scenario.text, linked_resources: scenario.linkedResources };
+    if (scenario.codeVariables.length > 0)
+        entry.code_variables = scenario.codeVariables;
+    return entry;
+}
+export function scenariosOf(file) {
+    return [...file.conformanceTests, ...file.acceptanceTests];
+}
+/** Whether a frontmatter binds its file to a functionality, which makes the file a test plain file. */
+export function isTestPlainFile(metadata) {
+    return FRONTMATTER_KEYS.every((key) => key in metadata);
+}
+const error = (message) => new PlainSyntaxError(`Plain syntax error: ${message}`);
+const at = (lineNumber, name) => `Syntax error at line ${lineNumber} in test plain file '${name}'`;
+/**
+ * The frontmatter and content of a ***plain file, as python-frontmatter reads them: a block between two lines of
+ * three or more dashes, loaded as YAML - a block that is not a mapping is no metadata - and the content after it,
+ * stripped. Raises the YAML error as it is.
+ */
+export function loadFrontmatter(text) {
+    const match = /^-{3,}[ \t]*\n(?:([\s\S]*?)\n)?-{3,}[ \t]*(?:\n|$)/.exec(text);
+    if (match === null)
+        return { metadata: {}, content: text.trim() };
+    const block = match[1] ?? "";
+    const loaded = block.trim() === "" ? {} : loadYaml(block);
+    const metadata = loaded !== null && typeof loaded === "object" && !Array.isArray(loaded) ? loaded : {};
+    return { metadata, content: text.slice(match[0].length).trim() };
+}
+/** The frontmatter and content of a test plain file; raise unless the keys are exactly module and func_id. */
+export function readMetadata(text, name) {
+    let post;
+    try {
+        post = loadFrontmatter(text);
+    }
+    catch (e) {
+        throw error(`Test plain file '${name}' has invalid frontmatter: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    for (const key of FRONTMATTER_KEYS) {
+        if (!(key in post.metadata))
+            throw error(`Test plain file '${name}' has no \`${key}:\` key in its frontmatter.`);
+        const value = post.metadata[key];
+        if (typeof value !== "string" || value.trim() === "") {
+            throw error(`Test plain file '${name}': the frontmatter key \`${key}:\` must be a non-empty string.`);
+        }
+    }
+    for (const key of Object.keys(post.metadata)) {
+        if (!FRONTMATTER_KEYS.includes(key)) {
+            throw error(`Test plain file '${name}' has the frontmatter key \`${key}:\`; only \`module:\` and \`func_id:\` are allowed.`);
+        }
+    }
+    return post;
+}
+function trimBlankLines(lines) {
+    let start = 0;
+    let end = lines.length;
+    while (start < end && lines[start].trim() === "")
+        start += 1;
+    while (end > start && lines[end - 1].trim() === "")
+        end -= 1;
+    return lines.slice(start, end);
+}
+/** The scenarios of the rendered content, keyed by section heading - a section left out, none; raise on the first structural error. */
+export function readScenarios(renderedText, name) {
+    const sections = {};
+    // Each section's heading line, for one left with no scenario.
+    const sectionLines = new Map();
+    let currentSection = null;
+    let current = null;
+    let body = [];
+    // The marker of the open fenced code block (``` or ~~~), null outside one.
+    let fence = null;
+    // Scenario-id to the line of its heading.
+    const headingLines = new Map();
+    const closeScenario = () => {
+        if (current === null)
+            return;
+        if (fence !== null)
+            throw error(`${at(current.lineNumber, name)}: Scenario \`${current.id}\` has a code fence that is not closed.`);
+        const lines = trimBlankLines(body);
+        if (lines.length === 0)
+            throw error(`${at(current.lineNumber, name)}: Scenario \`${current.id}\` has no text.`);
+        current.text = lines.join("\n");
+    };
+    renderedText.split("\n").forEach((line, index) => {
+        const lineNumber = index + 1;
+        const where = at(lineNumber, name);
+        // Inside a fenced code block every line is body text: a `# ` line is not a heading there, a `***` line is not a
+        // section marker, and a `>` line is not a comment.
+        const stripped = line.trimStart();
+        if (stripped.startsWith("```") || stripped.startsWith("~~~")) {
+            const marker = stripped.slice(0, 3);
+            if (fence === null)
+                fence = marker;
+            else if (fence === marker)
+                fence = null;
+            if (current !== null) {
+                body.push(line);
+                return;
+            }
+        }
+        else if (fence !== null && current !== null) {
+            body.push(line);
+            return;
+        }
+        if (line.startsWith("***")) {
+            const trimmed = line.trim();
+            const heading = trimmed.endsWith("***") && trimmed.length > 6 ? trimmed.slice(3, -3) : null;
+            if (heading === null || !SECTION_HEADINGS.includes(heading)) {
+                throw error(`${where}: Invalid section (\`${trimmed}\`). A test plain file has the sections ` +
+                    `\`***${SECTION_HEADINGS[0]}***\` and \`***${SECTION_HEADINGS[1]}***\`, in this order.`);
+            }
+            if (heading in sections)
+                throw error(`${where}: Duplicate section \`***${heading}***\`.`);
+            if (heading === SECTION_HEADINGS[0] && SECTION_HEADINGS[1] in sections) {
+                throw error(`${where}: The \`***${heading}***\` section must come before \`***${SECTION_HEADINGS[1]}***\`.`);
+            }
+            closeScenario();
+            current = null;
+            currentSection = heading;
+            sections[heading] = [];
+            sectionLines.set(heading, lineNumber);
+        }
+        else if (line.startsWith("# ") || line === "#") {
+            const scenarioId = line.slice(1).trim();
+            if (currentSection === null) {
+                throw error(`${where}: Scenario \`${scenarioId}\` comes before the first section; a test plain file starts ` +
+                    `with \`***${SECTION_HEADINGS[0]}***\`.`);
+            }
+            if (!isSemanticId(scenarioId)) {
+                throw error(`${where}: Invalid scenario-id (\`${scenarioId}\`). A scenario-id is lowercase letters and digits, ` +
+                    "with single hyphens between them.");
+            }
+            if (headingLines.has(scenarioId)) {
+                throw error(`${where}: Duplicate scenario-id \`${scenarioId}\`; it is first used at line ${headingLines.get(scenarioId)}.`);
+            }
+            closeScenario();
+            current = { id: scenarioId, lineNumber, text: "", linkedResources: [], codeVariables: [] };
+            body = [];
+            headingLines.set(scenarioId, lineNumber);
+            sections[currentSection].push(current);
+        }
+        else if (line.trimStart().startsWith(">")) {
+            return;
+        }
+        else if (current !== null) {
+            body.push(line);
+        }
+        else if (line.trim() !== "") {
+            if (currentSection === null) {
+                throw error(`${where}: Content before the first section (\`${line.trim()}\`); a test plain file starts with ` +
+                    `\`***${SECTION_HEADINGS[0]}***\`.`);
+            }
+            throw error(`${where}: Content before the first \`# <scenario-id>\` heading in the \`${currentSection}\` section (\`${line.trim()}\`).`);
+        }
+    });
+    closeScenario();
+    for (const heading of SECTION_HEADINGS) {
+        if (sections[heading]?.length === 0) {
+            throw error(`${at(sectionLines.get(heading), name)}: The \`***${heading}***\` section has no scenarios. Leave out a section with none.`);
+        }
+    }
+    if (Object.keys(sections).length === 0) {
+        throw error(`Test plain file '${name}' has no scenarios. A functional spec with none has no test plain file: delete it.`);
+    }
+    for (const heading of SECTION_HEADINGS)
+        sections[heading] ??= [];
+    return sections;
+}
+export function findScenarioLinkedResources(scenario, templateDirs, name) {
+    const document = parseMarkdown(scenario.text);
+    return findLinkedResources(document.children ?? [], templateDirs, ` in test plain file '${name}', scenario \`${scenario.id}\``);
+}
+/**
+ * Parse the text of a test plain file. Liquid runs as on a spec plain file, with the same template folders; every
+ * link in a scenario is resolved against them. Concepts are not checked here, see `validateScenarioConcepts`.
+ */
+export function parseTestPlainFileSource(plainSourceText, name, templateDirs, codeVariables) {
+    plainSourceText = normalizeLineEndings(plainSourceText);
+    const post = readMetadata(plainSourceText, name);
+    const [, loadedTemplates] = getLoadedTemplates(templateDirs, plainSourceText, name);
+    const content = restoreStrippedLines(plainSourceText, post.content);
+    const renderedText = renderPlainSource(content, loadedTemplates, codeVariables);
+    const sections = readScenarios(renderedText, name);
+    for (const scenario of [...sections[SECTION_HEADINGS[0]], ...sections[SECTION_HEADINGS[1]]]) {
+        scenario.linkedResources = findScenarioLinkedResources(scenario, templateDirs, name);
+        const entry = { text: scenario.text };
+        processSectionCodeVariables(entry, codeVariables, "text");
+        scenario.text = entry.text;
+        scenario.codeVariables = entry.code_variables ?? [];
+    }
+    return {
+        name,
+        module: String(post.metadata[MODULE_KEY]),
+        funcId: String(post.metadata[FUNC_ID_KEY]),
+        conformanceTests: sections[SECTION_HEADINGS[0]],
+        acceptanceTests: sections[SECTION_HEADINGS[1]],
+    };
+}
+/** One message per concept used in a scenario that is neither in `concepts` nor predefined. */
+export function validateScenarioConcepts(file, concepts) {
+    const errors = [];
+    for (const scenario of scenariosOf(file)) {
+        for (const concept of new Set(extractConceptsFromSpecText(scenario.text))) {
+            if (!concepts.has(concept) && !DEFAULT_CONCEPTS.has(concept)) {
+                errors.push(`${at(scenario.lineNumber, file.name)}: Concept ${concept} used in scenario \`${scenario.id}\` is not defined in module '${file.module}'.`);
+            }
+        }
+    }
+    return errors;
+}