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

package/dist/plain/markdown.d.ts

@@ -6,11 +6,14 @@
  * us the first. The second is `renderToMarkdown` below - a serializer for the
  * subset of markdown the plain language uses, matching mistletoe's output
  * (source indentation preserved, links rewritten as `[resource]` spans).
+ *
+ * The reference parses inside the renderer's context, so blank lines are tokens of
+ * their own (BlankLine), one per blank line, and survive in what is rendered; they
+ * are recovered here from the source.
  */
 export declare const RESOURCE_MARKER = "[resource]";
 /** Extra fields the parser hangs off AST nodes, as the Python code hangs them off tokens. */
 export interface PlainAnnotations {
-    acceptance_tests?: AnyNode[];
     linked_resources?: LinkedResource[];
     /** Set when `value` holds the original source slice rather than mdast's decoded text. */
     raw?: boolean;
@@ -20,6 +23,19 @@ export interface PlainAnnotations {
     leader?: string;
     indentation?: number;
     prepend?: number;
+    /**
+     * The blank lines in the source before a block, after the block before it: one run, and one more for each comment
+     * dropped in between - mistletoe's BlankLine tokens, one per blank line.
+     */
+    blankRuns?: number[];
+    /** A thematic break's line, or a setext heading's underline, as its container holds it. */
+    sourceLine?: string;
+    /** A fenced code block's opening: its indentation, its delimiter and its info string, as written. */
+    fence?: {
+        indentation: number;
+        delimiter: string;
+        infoString: string;
+    };
 }
 export interface LinkedResource {
     text: string;
@@ -60,15 +76,28 @@ export interface Section {
  * loses the fact that it was not `*`. mistletoe's MarkdownRenderer round-trips the
  * source instead, so re-serialising a decoded tree drifts from the Python output.
  * Recording the raw slice for leaf nodes and the real delimiters for emphasis and
- * strong keeps the two renderers in agreement.
+ * strong keeps the two renderers in agreement. Tables are GFM's, as mistletoe parses them.
  */
 export declare function parseMarkdown(text: string): Root;
 export declare function lineNumber(node: AnyNode): number;
-/** Port of plain_file.remove_quotes: block quotes are comments and are dropped. */
+/**
+ * Port of plain_file.remove_quotes: block quotes are comments and are dropped. The blank
+ * lines around a dropped one stay, as mistletoe's BlankLine tokens do.
+ */
 export declare function removeQuotes(node: AnyNode): void;
 /** Port of plain_file.get_raw_text. */
 export declare function getRawText(node: AnyNode): string;
 /** Port of mistletoe.utils.traverse restricted to a node type. */
 export declare function traverse(node: AnyNode, type: string): AnyNode[];
+/**
+ * Port of MarkdownRenderer.blocks_to_lines. Blocks are concatenated with no separator;
+ * blank lines are their own tokens in mistletoe, and are recovered here from the source.
+ */
+export declare function blocksToLines(nodes: AnyNode[]): string[];
 /** Port of PlainRenderer.render. */
 export declare function renderToMarkdown(node: AnyNode): string;
+/**
+ * Port of plain_file.render_tokens: blocks rendered as one markdown text, without leading
+ * and trailing blank lines.
+ */
+export declare function renderTokens(nodes: AnyNode[]): string;

package/dist/plain/markdown.js

@@ -1,4 +1,6 @@
 import { fromMarkdown } from "mdast-util-from-markdown";
+import { gfmTableFromMarkdown } from "mdast-util-gfm-table";
+import { gfmTable } from "micromark-extension-gfm-table";
 /**
  * The markdown layer.
  *
@@ -7,6 +9,10 @@ import { fromMarkdown } from "mdast-util-from-markdown";
  * us the first. The second is `renderToMarkdown` below - a serializer for the
  * subset of markdown the plain language uses, matching mistletoe's output
  * (source indentation preserved, links rewritten as `[resource]` spans).
+ *
+ * The reference parses inside the renderer's context, so blank lines are tokens of
+ * their own (BlankLine), one per blank line, and survive in what is rendered; they
+ * are recovered here from the source.
  */
 export const RESOURCE_MARKER = "[resource]";
 /**
@@ -16,17 +22,35 @@ export const RESOURCE_MARKER = "[resource]";
  * loses the fact that it was not `*`. mistletoe's MarkdownRenderer round-trips the
  * source instead, so re-serialising a decoded tree drifts from the Python output.
  * Recording the raw slice for leaf nodes and the real delimiters for emphasis and
- * strong keeps the two renderers in agreement.
+ * strong keeps the two renderers in agreement. Tables are GFM's, as mistletoe parses them.
  */
 export function parseMarkdown(text) {
-    const root = fromMarkdown(text);
-    pinToSource(root, text);
+    const root = fromMarkdown(text, { extensions: [gfmTable()], mdastExtensions: [gfmTableFromMarkdown()] });
+    pinToSource(root, text, 1, text.split("\n"));
     return root;
 }
 const RAW_LEAF_TYPES = new Set(["text", "inlineCode", "html"]);
-function pinToSource(node, source, origin = 1) {
+/** The containers whose children are blocks, with blank lines between them as mistletoe keeps them. */
+const BLOCK_CONTAINERS = new Set(["root", "list", "listItem", "blockquote"]);
+/** The whitespace-only lines strictly between two source lines. */
+function blankLinesWithin(lines, afterLine, beforeLine) {
+    let count = 0;
+    for (let line = afterLine + 1; line < beforeLine; line += 1)
+        if ((lines[line - 1] ?? "").trim() === "")
+            count += 1;
+    return count;
+}
+function pinToSource(node, source, origin, lines) {
     const start = node.position?.start.offset;
     const end = node.position?.end.offset;
+    if (BLOCK_CONTAINERS.has(node.type)) {
+        const children = childrenOf(node);
+        children.forEach((child, index) => {
+            const previousEnd = children[index - 1]?.position?.end.line;
+            const childStart = child.position?.start.line;
+            child.blankRuns = [previousEnd === undefined || childStart === undefined ? 0 : blankLinesWithin(lines, previousEnd, childStart)];
+        });
+    }
     if (start !== undefined && end !== undefined) {
         if (RAW_LEAF_TYPES.has(node.type)) {
             const raw = source.slice(start, end);
@@ -41,6 +65,23 @@ function pinToSource(node, source, origin = 1) {
             node.openDelimiter = source.slice(start, start + width);
             node.closeDelimiter = source.slice(end - width, end);
         }
+        else if (node.type === "thematicBreak") {
+            // mistletoe keeps the line as written, with its indentation in the container.
+            node.sourceLine = (lines[node.position.start.line - 1] ?? "").slice(origin - 1);
+        }
+        else if (node.type === "heading" && source[start] !== "#") {
+            // A setext heading: mistletoe keeps its underline as written.
+            node.sourceLine = (lines[node.position.end.line - 1] ?? "").slice(origin - 1).trimEnd();
+        }
+        else if (node.type === "code") {
+            const opening = /^(`{3,}|~{3,})([^\n]*)/.exec(source.slice(start, end));
+            if (opening !== null)
+                node.fence = { indentation: column(node) - origin, delimiter: opening[1], infoString: opening[2] };
+        }
+        else if (node.type === "definition") {
+            node.value = source.slice(start, end);
+            node.raw = true;
+        }
     }
     let childOrigin = origin;
     if (node.type === "listItem") {
@@ -61,7 +102,7 @@ function pinToSource(node, source, origin = 1) {
         childOrigin = contentColumn;
     }
     for (const child of childrenOf(node))
-        pinToSource(child, source, childOrigin);
+        pinToSource(child, source, childOrigin, lines);
 }
 export function lineNumber(node) {
     return node.position?.start.line ?? 0;
@@ -75,14 +116,24 @@ function isParent(node) {
 function childrenOf(node) {
     return node.children ?? [];
 }
-/** Port of plain_file.remove_quotes: block quotes are comments and are dropped. */
+/**
+ * Port of plain_file.remove_quotes: block quotes are comments and are dropped. The blank
+ * lines around a dropped one stay, as mistletoe's BlankLine tokens do.
+ */
 export function removeQuotes(node) {
     if (!isParent(node))
         return;
     const kept = [];
+    let dropped = [];
     for (const child of node.children) {
-        if (child.type === "blockquote")
+        if (child.type === "blockquote") {
+            dropped = [...dropped, ...(child.blankRuns ?? [0])];
             continue;
+        }
+        if (dropped.length > 0) {
+            child.blankRuns = [...dropped, ...(child.blankRuns ?? [0])];
+            dropped = [];
+        }
         removeQuotes(child);
         kept.push(child);
     }
@@ -98,6 +149,8 @@ export function getRawText(node) {
     const value = node.value;
     if (value !== undefined)
         return value;
+    if (node.type === "thematicBreak")
+        return "";
     throw new Error(`Unknown token type: ${node.type}`);
 }
 /** Port of mistletoe.utils.traverse restricted to a node type. */
@@ -140,13 +193,24 @@ function renderInline(node) {
 function renderInlineChildren(node) {
     return childrenOf(node).map(renderInline).join("");
 }
-/** Blank lines between two sibling blocks, as they appeared in the source. */
-function blankLinesBetween(previous, next) {
-    const previousEnd = previous.position?.end.line;
-    const nextStart = next.position?.start.line;
-    if (previousEnd === undefined || nextStart === undefined)
-        return 0;
-    return Math.max(0, nextStart - previousEnd - 1);
+/** Whether a block ends with a list: a list, or a list item whose last block does. */
+function endsWithList(node) {
+    if (node.type === "list")
+        return true;
+    const last = childrenOf(node).at(-1);
+    return node.type === "listItem" && last !== undefined && endsWithList(last);
+}
+/**
+ * The blank lines mistletoe keeps between two sibling blocks: one per blank line in the
+ * source, comment lines dropped in between counted out. A list item that ends without a
+ * next item gives back only the last of the blank lines after it (`ListItem.read` steps
+ * back one line), so the run right after a list counts once.
+ */
+function blankLinesBefore(previous, node) {
+    const runs = [...(node.blankRuns ?? [0])];
+    if (endsWithList(previous))
+        runs[0] = Math.min(runs[0], 1);
+    return runs.reduce((sum, run) => sum + run, 0);
 }
 /** Port of MarkdownRenderer.prefix_lines. */
 function prefixLines(lines, firstPrefix, followingPrefix) {
@@ -157,14 +221,14 @@ function prefixLines(lines, firstPrefix, followingPrefix) {
 }
 /**
  * Port of MarkdownRenderer.blocks_to_lines. Blocks are concatenated with no separator;
- * blank lines are their own tokens in mistletoe, and are recovered here from the gaps
- * between sibling positions.
+ * blank lines are their own tokens in mistletoe, and are recovered here from the source.
  */
-function blocksToLines(nodes) {
+export function blocksToLines(nodes) {
     const lines = [];
     nodes.forEach((node, index) => {
-        if (index > 0 && blankLinesBetween(nodes[index - 1], node) > 0)
-            lines.push("");
+        if (index > 0)
+            for (let blank = blankLinesBefore(nodes[index - 1], node); blank > 0; blank -= 1)
+                lines.push("");
         lines.push(...renderBlockLines(node));
     });
     return lines;
@@ -180,16 +244,67 @@ function renderListItemLines(item) {
         " ".repeat(Math.max(0, prepend - leader.length - indentation));
     return prefixLines(lines.length > 0 ? lines : [""], firstPrefix, " ".repeat(Math.max(0, prepend)));
 }
+/** mistletoe's alignment of a table column: null for left or none, 0 for centre, 1 for right. */
+function alignOf(align) {
+    return align === "center" ? 0 : align === "right" ? 1 : null;
+}
+/**
+ * Port of MarkdownRenderer.render_table: each cell re-rendered with its pipes escaped,
+ * every column as wide as its widest cell and at least three, padded by its alignment,
+ * and the separator row rebuilt from the alignments.
+ */
+function renderTableLines(node) {
+    const aligns = (node.align ?? []).map(alignOf);
+    const rows = childrenOf(node).map((row) => childrenOf(row).map((cell) => (renderInlineChildren(cell).split("\n")[0] ?? "").replace(/\\\|/g, "|").replace(/\|/g, "\\|")));
+    const [header = [], ...body] = rows;
+    const columns = Math.max(aligns.length, ...rows.map((row) => row.length));
+    const widths = Array.from({ length: columns }, (_, index) => Math.max(3, ...rows.map((row) => (row[index] ?? "").length)));
+    const lineOf = (cells) => "| " +
+        widths
+            .map((width, index) => {
+            const text = cells[index] ?? "";
+            const align = aligns[index] ?? null;
+            if (align === null)
+                return text.padEnd(width);
+            if (align === 1)
+                return text.padStart(width);
+            const left = Math.floor((width - text.length) / 2);
+            return " ".repeat(Math.max(0, left)) + text + " ".repeat(Math.max(0, width - text.length - left));
+        })
+            .join(" | ") +
+        " |";
+    const separator = widths.map((width, index) => {
+        const align = aligns[index] ?? null;
+        return (align === 0 ? ":" : "-") + "-".repeat(width - 2) + (align === 0 || align === 1 ? ":" : "-");
+    });
+    return [lineOf(header), `| ${separator.join(" | ")} |`, ...body.map(lineOf)];
+}
 function renderBlockLines(node) {
     switch (node.type) {
         case "paragraph":
             return renderInlineChildren(node).split("\n");
-        case "heading":
-            return [`${"#".repeat(node.depth)} ${renderInlineChildren(node)}`];
-        case "code":
-            return [`\`\`\`${node.lang ?? ""}`, ...(node.value ?? "").split("\n"), "\`\`\`"];
+        case "heading": {
+            // A setext heading keeps its underline; an ATX one is its hashes and its text.
+            if (node.sourceLine !== undefined)
+                return [...renderInlineChildren(node).split("\n"), node.sourceLine];
+            const text = renderInlineChildren(node);
+            return [`${"#".repeat(node.depth)}${text ? ` ${text}` : ""}`];
+        }
+        case "code": {
+            const content = (node.value ?? "").split("\n");
+            if (node.fence === undefined)
+                return prefixLines(content, "    ", "    ");
+            const indentation = " ".repeat(Math.max(0, node.fence.indentation));
+            return [
+                indentation + node.fence.delimiter + node.fence.infoString,
+                ...prefixLines(content, indentation, indentation),
+                indentation + node.fence.delimiter,
+            ];
+        }
         case "thematicBreak":
-            return ["---"];
+            return [node.sourceLine ?? "---"];
+        case "table":
+            return renderTableLines(node);
         case "blockquote":
             return blocksToLines(childrenOf(node)).map((line) => (line ? `> ${line}` : ">"));
         case "list":
@@ -206,3 +321,10 @@ function renderBlockLines(node) {
 export function renderToMarkdown(node) {
     return renderBlockLines(node).join("\n");
 }
+/**
+ * Port of plain_file.render_tokens: blocks rendered as one markdown text, without leading
+ * and trailing blank lines.
+ */
+export function renderTokens(nodes) {
+    return blocksToLines(nodes).join("\n").replace(/^\n+|\n+$/g, "");
+}

package/dist/plain/module-concepts.js

@@ -3,7 +3,7 @@ import { basename } from "node:path";
 import { resolveTemplateDirs } from "../regenerate/paths.js";
 import { DEFAULT_CONCEPT_DEFINITIONS, definitionText, extractConceptsFromDefinition } from "./concepts.js";
 import { renderToMarkdown } from "./markdown.js";
-import { exportedDefinitionsOf, IMPORT_DIRECTIVE, parsePlainFile, parsePlainSource, PLAIN_SOURCE_FILE_EXTENSION, readPlainSourceMetadata, REQUIRES_DIRECTIVE, restoreStrippedLines, } from "./parser.js";
+import { exportedDefinitionsOf, IMPORT_DIRECTIVE, parsePlainFile, parsePlainSource, PLAIN_SOURCE_FILE_EXTENSION, readPlainSourceMetadata, REQUIRES_DIRECTIVE, restoreStrippedLines, sectionOf, } from "./parser.js";
 import { DEFINITIONS } from "./spec.js";
 /**
  * A module read for what it can name, as the parser builds its definitions: its own, its imports' (`import`), and its
@@ -17,7 +17,7 @@ export function readModule(moduleName, plainFile, templateDirs) {
         for (const node of nodes)
             definitions.push({ node, module: result.importedFrom.get(node) ?? module });
     };
-    const definitionsOf = (result) => result.plainSource[DEFINITIONS]?.children ?? [];
+    const definitionsOf = (result) => sectionOf(result.plainSource, DEFINITIONS)?.children ?? [];
     let requires;
     let parsed = parse(moduleName);
     if (parsed !== undefined) {

package/dist/plain/parser.d.ts

@@ -1,12 +1,28 @@
-import { type AnyNode, type Section } from "./markdown.ts";
-import { type MarshalledPlainSource, type SpecificationItem } from "./spec.ts";
+import { type AnyNode, type LinkedResource, type Section } from "./markdown.ts";
+import { type CodeVariable, type FunctionalSpecItem, type MarshalledPlainSource } from "./spec.ts";
 export declare const IMPORT_DIRECTIVE = "import";
 export declare const REQUIRES_DIRECTIVE = "requires";
+export declare const PREVIOUS_SYNTAX_HINT = "A functionality is a `# <func-id>` heading followed by its body; the previous syntax is not supported.";
 export declare const REQUIRED_CONCEPTS_DIRECTIVE = "required_concepts";
 export declare const EXPORTED_CONCEPTS_DIRECTIVE = "exported_concepts";
 export declare const PLAIN_SOURCE_FILE_EXTENSION = ".plain";
-/** definitions / implementation reqs / test reqs always exist as keys; functional specs does not. */
-export type ParsedPlainSource = Record<string, Section | null | undefined>;
+/** A functional spec as it is read: its func-id and the blocks of its body. */
+export interface Functionality {
+    id: string;
+    lineNumber: number;
+    /** Every block after its heading, up to the next heading or section marker, in source order. */
+    body: AnyNode[];
+    linkedResources: LinkedResource[];
+}
+/**
+ * definitions / implementation reqs / test reqs always exist as keys, each a section of list items; functional specs
+ * does not, and is a list of functional specs when it does.
+ */
+export type ParsedPlainSource = Record<string, Section | Functionality[] | null | undefined>;
+/** A list section of a parsed module. */
+export declare function sectionOf(plainSource: ParsedPlainSource, heading: string): Section | null | undefined;
+/** The functional specs of a parsed module, none when it has no section for them. */
+export declare function functionalitiesOf(plainSource: ParsedPlainSource): Functionality[];
 export interface FrontmatterPost {
     metadata: Record<string, unknown>;
     content: string;
@@ -22,41 +38,37 @@ export interface PlainFileParseResult {
 export declare function getFilenameFromModuleName(moduleName: string): string;
 export declare function getModuleNameFromFilename(filename: string): string;
 export declare function hasScheme(target: string): boolean;
+/**
+ * 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.
+ */
+export declare function resolveLinkedResource(dirs: string[], target: string): string | null;
 /** The links written in an item - what each says and where it points - as the parser reads them, checked or not. */
 export declare function linksIn(section: AnyNode): Array<{
     text: string;
     target: string;
     node: AnyNode;
 }>;
+/**
+ * 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 declare function findLinkedResources(nodes: AnyNode[], dirs?: string[], where?: string): LinkedResource[];
 export declare function checkSectionForLinkedResources(section: AnyNode, dirs?: string[]): void;
 export declare function checkForLinkedResources(plainSource: ParsedPlainSource, dirs?: string[]): void;
-export declare function processSectionCodeVariables(section: SpecificationItem, codeVariables: Record<string, Record<string, string>>): void;
+/** Put `{{ name }}` placeholders back into the section text and record the code variables it uses. */
+export declare function processSectionCodeVariables(section: {
+    code_variables?: CodeVariable[];
+} & Record<string, unknown>, codeVariables: Record<string, Record<string, string>>, textKey?: string): void;
 export declare function processCodeVariables(marshalled: MarshalledPlainSource, codeVariables: Record<string, Record<string, string>>): void;
 /** Whether the module declares a ***functional specs*** section (even if it is empty). */
 export declare function hasFunctionalSpecsSection(plainSource: ParsedPlainSource): boolean;
 /** Number of functionalities under ***functional specs*** (0 if absent or empty). */
 export declare function countFunctionalities(plainSource: ParsedPlainSource): number;
 export declare function validateFunctionalitiesHaveImplementationReqs(plainSource: ParsedPlainSource, moduleName: string, hasRequires?: boolean): void;
-/**
- * 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 declare function isAcceptanceTestHeading(token: AnyNode): [boolean, string | null];
-/** Find an acceptance tests heading anywhere in a subtree. */
-export declare function findAcceptanceTestHeading(token: AnyNode): AnyNode | 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 declare function processSingleAcceptanceTestRequirement(functionalRequirement: AnyNode): void;
-export declare function processAcceptanceTests(plainSource: ParsedPlainSource): void;
+export declare function marshallFunctionality(functionality: Functionality): FunctionalSpecItem;
 export declare function marshallPlainSource(input: ParsedPlainSource): MarshalledPlainSource;
 export declare function normalizeLineEndings(plainSourceText: string): string;
 /**
@@ -65,7 +77,22 @@ export declare function normalizeLineEndings(plainSourceText: string): string;
  */
 export declare function restoreStrippedLines(plainSourceText: string, content: string): string;
 export declare function readPlainSourceMetadata(plainSourceText: string): FrontmatterPost;
-export declare function parsePlainSource(plainSourceText: string, codeVariables: Record<string, Record<string, string>>, templateDirs: string[], importedModules: string[], modulesTrace: string[]): PlainFileParseResult;
+/** `Syntax error at line N in module 'm'`, without the parts that are not known. */
+export declare function syntaxErrorAt(line: number | null | undefined, moduleName: string | null | undefined): string;
+export declare const TEST_PLAIN_FILE_SECTION_HEADINGS: string[];
+/** Throw when a `***conformance tests***` or `***acceptance tests***` marker is anywhere in a spec plain file. */
+export declare function checkNoTestSections(plainSourceFullText: string, moduleName?: string | null): void;
+/** The name in a `***name***` paragraph, or null when the paragraph is not a section marker. */
+export declare function sectionMarker(token: AnyNode): string | null;
+/**
+ * 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 declare function readSections(plainSource: ParsedPlainSource, document: AnyNode, moduleName?: string | null): void;
+export declare function parsePlainSource(plainSourceText: string, codeVariables: Record<string, Record<string, string>>, templateDirs: string[], importedModules: string[], modulesTrace: string[], moduleName?: string): PlainFileParseResult;
 /**
  * The file a module name is read from, as `readModulePlainSource` reads it - a standard library module's in turri's
  * `stdlib/`, any other's in the first template folder that has it - or null when there is none.
@@ -73,8 +100,17 @@ export declare function parsePlainSource(plainSourceText: string, codeVariables:
 export declare function modulePlainFile(moduleName: string, templateDirs: string[]): string | null;
 export declare function readModulePlainSource(moduleName: string, templateDirs: string[]): string;
 export declare function parsePlainFile(moduleName: string, codeVariables: Record<string, Record<string, string>>, templateDirs: string[], importedModules: string[], modulesTrace: string[]): PlainFileParseResult;
-export declare function processRequiredModules(requiredModules: string[], codeVariables: Record<string, Record<string, string>>, templateDirs: string[], allRequiredModules: string[], modulesTrace: string[]): AnyNode[];
-/** The definitions a required module exports: those of its `exported_concepts`, with the definitions they use. */
+/**
+ * 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 declare function processRequiredModules(requiredModules: string[], templateDirs: string[], allRequiredModules: string[], modulesTrace: string[], exports?: Map<string, AnyNode[]>): AnyNode[];
+/**
+ * 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 declare function exportedDefinitionsOf(result: PlainFileParseResult): AnyNode[];
 export declare function processExportedDefinitions(plainSource: ParsedPlainSource, exportedDefinitions: AnyNode[]): void;
 /**
@@ -89,8 +125,27 @@ export interface ParseOptions {
      * product interview has so far given it definitions and reqs.
      */
     allowNoFunctionalities?: boolean;
+    /**
+     * The project's test folder: the module's chain is parsed with its test plain files, `<testDir>/<module>` for each
+     * module of the chain - turri hands the reference one test folder per module - and their scenarios are bound to
+     * the functional specs they name. turri's: the reference takes the test folders themselves.
+     */
+    testDir?: string;
+    /**
+     * With `testDir`: every functional spec of the chain must have a test plain file, which may hold no scenario
+     * (`MissingTestPlainFileError` for the first one that has none) - as the reference asks when the project names a
+     * conformance testing script. turri never asks: a functional spec with no test plain file is not tested, as one
+     * whose file is empty, and no file is the way to say so.
+     */
+    requireTestPlainFiles?: boolean;
 }
 export declare function plainFileParser(plainSourceFileName: string, templateDirs: string[], options?: ParseOptions): [string, MarshalledPlainSource, string[]];
+/**
+ * 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 declare function parseModuleChain(plainSourceFileName: string, templateDirs: string[], options?: ParseOptions): Array<[string, MarshalledPlainSource]>;
 /**
  * One parse per file for the length of `run`, however many times it is asked for.
  *