@turri-dev/cli 0.1.27 → 0.2.0

package/dist/plain/cycles.js

@@ -0,0 +1,190 @@
+/**
+ * Port of graph.py: the cycle search over a directed graph given as a mapping from a node to its successors.
+ *
+ * Nodes that appear only as successors are treated as having no outgoing edges. The search is Johnson's algorithm,
+ * with the strongly connected components found by Tarjan's. Both keep their own stack of frames instead of
+ * recursing, so the depth of a tangle is not limited by the call stack.
+ *
+ * - D. B. Johnson, "Finding all the elementary circuits of a directed graph", SIAM J. Comput. 4(1):77-84, 1975
+ * - R. Tarjan, "Depth-first search and linear graph algorithms", SIAM J. Comput. 1(2):146-160, 1972
+ */
+function successorsOf(graph) {
+    // A repeated edge would otherwise yield every cycle through it once per repeat.
+    const successors = new Map();
+    for (const [node, targets] of graph)
+        successors.set(node, [...new Set(targets)]);
+    for (const targets of [...successors.values()]) {
+        for (const target of targets)
+            if (!successors.has(target))
+                successors.set(target, []);
+    }
+    return successors;
+}
+/**
+ * Tarjan: one depth-first walk, each node stamped with its visit index and the lowest index it can reach; a node
+ * whose lowest reachable index is its own closes a component.
+ */
+export function stronglyConnectedComponents(graph) {
+    const successors = successorsOf(graph);
+    const index = new Map();
+    const lowlink = new Map();
+    const stack = [];
+    const onStack = new Set();
+    const components = [];
+    const visit = (node) => {
+        index.set(node, index.size);
+        lowlink.set(node, index.get(node));
+        stack.push(node);
+        onStack.add(node);
+        return { node, targets: successors.get(node), next: 0 };
+    };
+    for (const root of successors.keys()) {
+        if (index.has(root))
+            continue;
+        const frames = [visit(root)];
+        while (frames.length > 0) {
+            const frame = frames[frames.length - 1];
+            let descended = false;
+            while (frame.next < frame.targets.length) {
+                const target = frame.targets[frame.next++];
+                if (!index.has(target)) {
+                    frames.push(visit(target));
+                    descended = true;
+                    break;
+                }
+                if (onStack.has(target))
+                    lowlink.set(frame.node, Math.min(lowlink.get(frame.node), index.get(target)));
+            }
+            if (descended)
+                continue;
+            frames.pop();
+            const node = frame.node;
+            if (frames.length > 0) {
+                const parent = frames[frames.length - 1].node;
+                lowlink.set(parent, Math.min(lowlink.get(parent), lowlink.get(node)));
+            }
+            if (lowlink.get(node) === index.get(node)) {
+                const component = new Set();
+                for (;;) {
+                    const member = stack.pop();
+                    onStack.delete(member);
+                    component.add(member);
+                    if (member === node)
+                        break;
+                }
+                components.push(component);
+            }
+        }
+    }
+    return components;
+}
+/**
+ * Johnson's CIRCUIT: every elementary cycle through `s` in one strongly connected component. A node is blocked while
+ * it is on the path, and stays blocked after backtracking until a cycle is found through some node it was waiting on.
+ */
+function* cyclesThrough(adjacency, s) {
+    const blocked = new Set();
+    const blockedMap = new Map();
+    const unblock = (node) => {
+        const pending = [node];
+        while (pending.length > 0) {
+            const current = pending.pop();
+            blocked.delete(current);
+            const waiting = blockedMap.get(current);
+            blockedMap.delete(current);
+            for (const other of waiting ?? [])
+                if (blocked.has(other))
+                    pending.push(other);
+        }
+    };
+    const path = [s];
+    blocked.add(s);
+    const frames = [{ targets: adjacency.get(s), next: 0 }];
+    const foundBelow = [false];
+    while (frames.length > 0) {
+        const node = path[path.length - 1];
+        const frame = frames[frames.length - 1];
+        let descended = false;
+        while (frame.next < frame.targets.length) {
+            const target = frame.targets[frame.next++];
+            if (target === s) {
+                yield [...path];
+                foundBelow[foundBelow.length - 1] = true;
+            }
+            else if (!blocked.has(target)) {
+                path.push(target);
+                blocked.add(target);
+                frames.push({ targets: adjacency.get(target), next: 0 });
+                foundBelow.push(false);
+                descended = true;
+                break;
+            }
+        }
+        if (descended)
+            continue;
+        frames.pop();
+        path.pop();
+        if (foundBelow.pop()) {
+            unblock(node);
+            if (foundBelow.length > 0)
+                foundBelow[foundBelow.length - 1] = true;
+        }
+        else {
+            for (const target of adjacency.get(node)) {
+                if (!blockedMap.has(target))
+                    blockedMap.set(target, new Set());
+                blockedMap.get(target).add(node);
+            }
+        }
+    }
+}
+/**
+ * Johnson's main loop: every cycle lies inside one strongly connected component, and every cycle inside a component
+ * either passes through its least node or survives that node's removal. So search each component from its least
+ * node, drop the node, and split what is left into components again. Components are taken least node first, so a
+ * caller that stops early has seen the cycles through the earliest nodes.
+ */
+function* allCycles(graph) {
+    let successors = successorsOf(graph);
+    for (const [node, targets] of successors)
+        if (targets.includes(node))
+            yield [node];
+    successors = new Map([...successors].map(([node, targets]) => [node, targets.filter((target) => target !== node)]));
+    const position = new Map([...successors.keys()].map((node, i) => [node, i]));
+    const least = (component) => Math.min(...[...component].map((node) => position.get(node)));
+    // A priority queue by least position; components are disjoint, so no two share one.
+    const components = [];
+    const pushComponents = (adjacency) => {
+        for (const component of stronglyConnectedComponents(adjacency)) {
+            if (component.size >= 2)
+                components.push({ least: least(component), component });
+        }
+        components.sort((a, b) => a.least - b.least);
+    };
+    pushComponents(successors);
+    while (components.length > 0) {
+        const { component } = components.shift();
+        const s = [...component].reduce((a, b) => (position.get(a) <= position.get(b) ? a : b));
+        const adjacency = new Map();
+        for (const node of component)
+            adjacency.set(node, successors.get(node).filter((target) => component.has(target)));
+        yield* cyclesThrough(adjacency, s);
+        adjacency.delete(s);
+        for (const [node, targets] of adjacency)
+            adjacency.set(node, targets.filter((target) => target !== s));
+        pushComponents(adjacency);
+    }
+}
+/**
+ * The elementary cycles of `graph`, each as its nodes in edge order, stopping after `limit` cycles when one is given.
+ * Self-loops come first; longer cycles follow in order of their earliest node in the graph's iteration order.
+ */
+export function* simpleCycles(graph, limit) {
+    let found = 0;
+    for (const cycle of allCycles(graph)) {
+        found += 1;
+        if (limit !== undefined && found > limit)
+            return;
+        yield cycle;
+    }
+}

package/dist/plain/errors.d.ts

@@ -14,6 +14,10 @@ export declare class MissingFunctionalitiesError extends Error {
 export declare class ImportedModuleWithFunctionalitiesError extends Error {
     constructor(message: string);
 }
+/** A functional spec of the chain has no test plain file bound to it. */
+export declare class MissingTestPlainFileError extends Error {
+    constructor(message: string);
+}
 export declare class InvalidFridArgument extends Error {
     constructor(message: string);
 }

package/dist/plain/errors.js

@@ -29,6 +29,13 @@ export class ImportedModuleWithFunctionalitiesError extends Error {
         this.name = "ImportedModuleWithFunctionalitiesError";
     }
 }
+/** A functional spec of the chain has no test plain file bound to it. */
+export class MissingTestPlainFileError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "MissingTestPlainFileError";
+    }
+}
 export class InvalidFridArgument extends Error {
     constructor(message) {
         super(message);

package/dist/plain/files.d.ts

@@ -2,6 +2,12 @@
 export declare function openFrom(dirs: string[], fileName: string): string | null;
 /** The file `openFrom` reads: the first of the folders that has it. */
 export declare function findIn(dirs: string[], fileName: string): string | null;
+/**
+ * Port of loaders.relative_resource_path: the path of `target` in `resourceDir`, relative to `baseDir`, with `/` as
+ * separator. The folder part is computed lexically and the target is appended as written (`..` kept), so joining
+ * the result onto `baseDir` names the same file as joining `target` onto `resourceDir`.
+ */
+export declare function relativeResourcePath(baseDir: string, resourceDir: string, target: string): string;
 /** First contiguous base64 blob at or above the threshold, or null. */
 export declare function findLargeBase64Blob(text: string): string | null;
 /**
@@ -11,4 +17,15 @@ export declare function findLargeBase64Blob(text: string): string | null;
  * name to raw source, which is what the second (real) render is given so that it does
  * not touch the filesystem again.
  */
-export declare function getLoadedTemplates(templateDirs: string[], plainSource: string): [string, Record<string, string>];
+export declare function getLoadedTemplates(templateDirs: string[], plainSource: string, templateName?: string): [string, Record<string, string>];
+/**
+ * Port of loaders.liquid_error_message: a Liquid syntax error as a ***plain one, naming the template, and the line
+ * and the column (counted from 0) of the token it is at. The message after it is liquidjs's, without the position
+ * liquidjs appends - it phrases its errors differently from liquid2, and places some of them elsewhere.
+ */
+export declare function liquidErrorMessage(error: Error & {
+    token?: {
+        begin?: number;
+        input?: string;
+    };
+}, templateName?: string): string;

package/dist/plain/files.js

@@ -1,5 +1,7 @@
 import { readFileSync, statSync } from "node:fs";
-import { join } from "node:path";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+import { ParseError, TokenizationError } from "liquidjs";
+import { PlainSyntaxError } from "./errors.js";
 import { createEnvironment } from "./liquid.js";
 /** Ports of the Python reference implementation's file helpers this parser needs. */
 export function openFrom(dirs, fileName) {
@@ -20,6 +22,19 @@ export function findIn(dirs, fileName) {
     }
     return null;
 }
+/**
+ * Port of loaders.relative_resource_path: the path of `target` in `resourceDir`, relative to `baseDir`, with `/` as
+ * separator. The folder part is computed lexically and the target is appended as written (`..` kept), so joining
+ * the result onto `baseDir` names the same file as joining `target` onto `resourceDir`.
+ */
+export function relativeResourcePath(baseDir, resourceDir, target) {
+    const relativeDir = relative(resolve(baseDir), resolve(resourceDir));
+    if (relativeDir === "")
+        return target;
+    if (isAbsolute(relativeDir))
+        return join(resourceDir, target).split(sep).join("/");
+    return `${relativeDir.split(sep).join("/")}/${target}`;
+}
 const MAX_BASE64_BLOB_LENGTH = 8192;
 const BASE64_BLOB_PATTERN = new RegExp(`(?:data:[\\w.+-]+/[\\w.+-]+;base64,)?[A-Za-z0-9+/_-]{${MAX_BASE64_BLOB_LENGTH},}={0,2}`);
 /** First contiguous base64 blob at or above the threshold, or null. */
@@ -34,7 +49,7 @@ export function findLargeBase64Blob(text) {
  * name to raw source, which is what the second (real) render is given so that it does
  * not touch the filesystem again.
  */
-export function getLoadedTemplates(templateDirs, plainSource) {
+export function getLoadedTemplates(templateDirs, plainSource, templateName) {
     const loadedTemplates = {};
     const engine = createEnvironment({
         strictVariables: true,
@@ -51,6 +66,9 @@ export function getLoadedTemplates(templateDirs, plainSource) {
         rendered = engine.parseAndRenderSync(plainSource, {});
     }
     catch (error) {
+        if (error instanceof TokenizationError || error instanceof ParseError) {
+            throw new PlainSyntaxError(liquidErrorMessage(error, templateName));
+        }
         const message = error instanceof Error ? error.message : String(error);
         if (/undefined variable/i.test(message)) {
             throw new Error(`Undefined liquid variable: ${message}`);
@@ -59,3 +77,22 @@ export function getLoadedTemplates(templateDirs, plainSource) {
     }
     return [rendered, loadedTemplates];
 }
+/**
+ * Port of loaders.liquid_error_message: a Liquid syntax error as a ***plain one, naming the template, and the line
+ * and the column (counted from 0) of the token it is at. The message after it is liquidjs's, without the position
+ * liquidjs appends - it phrases its errors differently from liquid2, and places some of them elsewhere.
+ */
+export function liquidErrorMessage(error, templateName) {
+    const message = error.message.replace(/, line:\d+, col:\d+$/, "");
+    const token = error.token;
+    let where;
+    if (token?.input === undefined || token.begin === undefined || token.begin < 0) {
+        where = templateName ? ` in ${templateName}` : "";
+    }
+    else {
+        const line = (token.input.slice(0, token.begin).match(/\n/g) ?? []).length + 1;
+        const column = token.begin - (token.input.lastIndexOf("\n", token.begin - 1) + 1);
+        where = templateName ? ` at ${templateName}:${line}:${column}` : ` at ${line}:${column}`;
+    }
+    return `Plain syntax error: Invalid Liquid${where}: ${message}`;
+}

package/dist/plain/graph.d.ts

@@ -8,6 +8,29 @@ export interface PlainGraph {
     modules: PlainModuleNode[];
     items: PlainItemNode[];
     concepts: PlainConceptNode[];
+    /** The test plain files in the project's test folder, each linked to the functional spec it binds to. */
+    testPlainFiles: PlainTestPlainFileNode[];
+}
+/** A scenario of a test plain file: its scenario-id, its text, and the line its `# <scenario-id>` heading is on. */
+export interface PlainScenario {
+    id: string;
+    text: string;
+    line: number;
+}
+/**
+ * A test plain file: the functional spec it binds to - its `module:` and `func_id:`, and that functional spec's item -
+ * and its scenarios. A file that does not parse, is outside its module's folder or binds to no functional spec has
+ * `error`, and `item` null.
+ */
+export interface PlainTestPlainFileNode {
+    file: string;
+    module: string | null;
+    funcId: string | null;
+    /** The functional spec's item id, or null. */
+    item: string | null;
+    conformance: PlainScenario[];
+    acceptance: PlainScenario[];
+    error?: string;
 }
 /** A module one .plain file names, and the file it is - null when it is not found. */
 export interface PlainLink {
@@ -30,7 +53,7 @@ export interface PlainModuleNode {
     error?: string;
 }
 export type PlainSection = typeof DEFINITIONS | typeof NON_FUNCTIONAL_REQUIREMENTS | typeof TEST_REQUIREMENTS | typeof FUNCTIONAL_REQUIREMENTS;
-/** An item of a section, with what is nested under it - a functional spec with its acceptance tests. */
+/** An item of a section: a list item, or a functional spec - its heading's line, its body's text. */
 export interface PlainItemNode {
     /** `<file>:<line>`. */
     id: string;
@@ -40,8 +63,14 @@ export interface PlainItemNode {
     /** The line it starts on, from 1. */
     line: number;
     text: string;
-    /** A functional spec's functionality id: `1`, `2`, ... */
-    frid?: string;
+    /** A functional spec's func-id, its `# <func-id>` heading. */
+    funcId?: string;
+    /** A functional spec's test plain file, and its scenarios - none when it has no file. */
+    testPlainFile?: string | null;
+    scenarios?: {
+        conformance: PlainScenario[];
+        acceptance: PlainScenario[];
+    };
     /** The concepts a definition defines. */
     defines: string[];
     /** The concepts it names, each with the definition it is - an item's id - or null for ***plain's own and one defined nowhere it can see. */
@@ -50,7 +79,7 @@ export interface PlainItemNode {
         definition: string | null;
     }>;
     /**
-     * The linked resources it names, a functional spec's acceptance tests' too - `[text](target)` as the parser reads
+     * The linked resources it names - `[text](target)` as the parser reads
      * them - with the file each is read from when regenerating, null when it is not there, and the line the link is on.
      */
     resources: Array<{

package/dist/plain/graph.js

@@ -4,11 +4,15 @@ import { resolveTemplateDirs } from "../regenerate/paths.js";
 import { locateModule } from "../regenerate/requires.js";
 import { resourceFile } from "../regenerate/resources.js";
 import { DEFAULT_CONCEPT_DEFINITIONS, DEFAULT_CONCEPTS, definitionText, extractConceptsFromDefinition, findConcepts } from "./concepts.js";
-import { lineNumber, renderToMarkdown } from "./markdown.js";
+import { lineNumber, renderToMarkdown, renderTokens } from "./markdown.js";
 import { attempt, namesIn, readModule } from "./module-concepts.js";
-import { IMPORT_DIRECTIVE, linksIn, modulePlainFile, parsePlainFile, PLAIN_SOURCE_FILE_EXTENSION, plainFileParser, readPlainSourceMetadata, REQUIRES_DIRECTIVE, withParseCache, } from "./parser.js";
+import { IMPORT_DIRECTIVE, linksIn, modulePlainFile, parsePlainFile, PLAIN_SOURCE_FILE_EXTENSION, plainFileParser, readPlainSourceMetadata, REQUIRES_DIRECTIVE, functionalitiesOf, sectionOf, withParseCache, } from "./parser.js";
 import { DEFINITIONS, FUNCTIONAL_REQUIREMENTS, NON_FUNCTIONAL_REQUIREMENTS, TEST_REQUIREMENTS } from "./spec.js";
 import { isStdlibModule } from "./stdlib.js";
+import { discoverTestPlainFiles, readTestPlainFileText } from "./project.js";
+import { parseTestPlainFileSource } from "./test-plain-file.js";
+import { testDirOf } from "../config.js";
+import { strayTestPlainFiles } from "../test-plain-files.js";
 const SECTIONS = [DEFINITIONS, NON_FUNCTIONAL_REQUIREMENTS, TEST_REQUIREMENTS, FUNCTIONAL_REQUIREMENTS];
 /**
  * A project's ***plain as a graph: every .plain file in its folder and its `template/` folder, and every module they
@@ -83,29 +87,73 @@ export function plainGraph(projectDir) {
                 }
             }
             for (const section of SECTIONS) {
-                const own = (read.parsed?.plainSource[section]?.children ?? []).filter((item) => !read.parsed.importedFrom.has(item));
-                own.forEach((item, index) => {
-                    const text = renderToMarkdown(item).trim();
+                // An item of a list section is its list item; a functional spec is its `# <func-id>` heading and its body.
+                const own = [];
+                if (read.parsed !== undefined && section === FUNCTIONAL_REQUIREMENTS) {
+                    for (const functionality of functionalitiesOf(read.parsed.plainSource)) {
+                        const at = lineOf({ type: "heading", position: { start: { line: functionality.lineNumber, column: 1 }, end: { line: functionality.lineNumber, column: 1 } } }, node.file, lines, { needle: `# ${functionality.id}` });
+                        own.push({ nodes: functionality.body, line: at, parsedLine: functionality.lineNumber, text: renderTokens(functionality.body), funcId: functionality.id });
+                    }
+                }
+                else {
+                    for (const item of ((read.parsed && sectionOf(read.parsed.plainSource, section)?.children) ?? []).filter((item) => !read.parsed.importedFrom.has(item))) {
+                        own.push({ nodes: [item], line: lineOf(item, node.file, lines), parsedLine: lineNumber(item), text: renderToMarkdown(item).trim() });
+                    }
+                }
+                for (const { nodes, line, parsedLine, text, funcId } of own) {
                     const defines = section === DEFINITIONS ? extractConceptsFromDefinition(text)[0] : [];
                     const named = [...new Set(findConcepts(text).map((found) => found.concept))].filter((concept) => !defines.includes(concept));
-                    const id = idOf(item, node.file);
-                    const line = lineOf(item, node.file, lines);
+                    const id = `${node.file}:${line}`;
                     // A link is on the line the parser has it on, moved as Liquid moved its item.
-                    const resources = linksIn(item).map(({ text, target, node: link }) => ({
+                    const resources = nodes.flatMap((item) => linksIn(item)).map(({ text, target, node: link }) => ({
                         text,
                         target,
                         file: resourceFile(target, dirs),
-                        line: lineOf(link, node.file, lines, { at: lineNumber(link) + line - lineNumber(item), needle: `](${target})`, from: line }),
+                        line: lineOf(link, node.file, lines, { at: lineNumber(link) + line - parsedLine, needle: `](${target})`, from: line }),
                     }));
                     const uses = named.map((concept) => ({ concept, definition: DEFAULT_CONCEPTS.has(concept) ? null : (visible.get(concept) ?? null) }));
                     for (const use of uses)
                         concepts.get(`${use.concept}\0${use.definition ?? ""}`)?.usedBy.push(id);
-                    items.push({ id, file: node.file, module: node.module, section, line, text, ...(section === FUNCTIONAL_REQUIREMENTS ? { frid: String(index + 1) } : {}), defines, uses, resources });
+                    items.push({ id, file: node.file, module: node.module, section, line, text, ...(funcId !== undefined ? { funcId } : {}), defines, uses, resources });
                     node.items.push(id);
-                });
+                }
             }
         }
-        return { modules: [...modules.values()], items, concepts: [...concepts.values()] };
+        const testPlainFiles = testPlainFileNodes(root, dirs, items, lines);
+        return { modules: [...modules.values()], items, concepts: [...concepts.values()], testPlainFiles };
+    });
+}
+/**
+ * The test plain files under the project's test folder, each parsed for its binding and its scenarios, and linked to the
+ * functional spec it binds to - that item given its file and its scenarios. A stray one, one that does not parse, or one
+ * that binds to no functional spec has its error.
+ */
+function testPlainFileNodes(root, dirs, items, lines) {
+    const testDir = testDirOf(join(root, `project${PLAIN_SOURCE_FILE_EXTENSION}`));
+    const strays = new Map((attempt(() => strayTestPlainFiles(root)) ?? []).map((stray) => [resolve(root, stray.file), stray.problem]));
+    for (const item of items)
+        if (item.funcId !== undefined)
+            Object.assign(item, { testPlainFile: null, scenarios: { conformance: [], acceptance: [] } });
+    return (attempt(() => discoverTestPlainFiles([testDir], root)) ?? []).map(([path, name]) => {
+        const node = { file: path, module: null, funcId: null, item: null, conformance: [], acceptance: [] };
+        let parsed;
+        try {
+            parsed = parseTestPlainFileSource(readTestPlainFileText(path, name), name, dirs, {});
+        }
+        catch (error) {
+            return { ...node, error: messageOf(error) };
+        }
+        const scenarios = (list) => list.map((scenario) => ({ id: scenario.id, text: scenario.text, line: lineOf({ type: "heading", position: { start: { line: scenario.lineNumber, column: 1 }, end: { line: scenario.lineNumber, column: 1 } } }, path, lines, { needle: `# ${scenario.id}` }) }));
+        Object.assign(node, { module: parsed.module, funcId: parsed.funcId, conformance: scenarios(parsed.conformanceTests), acceptance: scenarios(parsed.acceptanceTests) });
+        const stray = strays.get(path);
+        if (stray !== undefined)
+            return { ...node, error: stray };
+        const bound = items.find((item) => item.module === parsed.module && item.funcId === parsed.funcId && item.section === FUNCTIONAL_REQUIREMENTS);
+        if (bound === undefined)
+            return { ...node, error: `${name} binds to ${parsed.module}:${parsed.funcId}, and there is no such functional spec` };
+        bound.testPlainFile = path;
+        bound.scenarios = { conformance: node.conformance, acceptance: node.acceptance };
+        return { ...node, item: bound.id };
     });
 }
 /** Why a module does not parse: an import module as an import is parsed, a module of its own as one - functional specs or not yet. */

package/dist/plain/highlight.d.ts

@@ -34,9 +34,10 @@ export declare function highlightLine(line: string, state?: HighlightState): {
 export declare function highlightLines(lines: string[]): Token[][];
 /**
  * What a piece of ***plain is, for its colour: a section's header, a concept, a link, text in quotes or
- * backticks, a front matter key, a module a front matter names, a comment, a list's bullet.
+ * backticks, a front matter key, a module a front matter names, a comment, a list's bullet, the `# <id>` heading of a
+ * functional spec or a scenario.
  */
-export type PlainRole = "section" | "concept" | "link" | "literal" | "keyword" | "module" | "comment" | "bullet";
+export type PlainRole = "section" | "concept" | "link" | "literal" | "keyword" | "module" | "comment" | "bullet" | "id";
 /** A token's role: its innermost scope that has one. */
 export declare function roleOf(scopes: string[]): PlainRole | undefined;
 export {};

package/dist/plain/highlight.js

@@ -7,7 +7,7 @@ function readGrammar(raw) {
     const read = (rules, into, seen) => {
         for (const rule of rules) {
             if (rule.include !== undefined) {
-                // Only the repository's: plyn's grammar includes nothing else, and a rule that includes itself is followed once.
+                // Only the repository's: the grammar includes nothing else, and a rule that includes itself is followed once.
                 if (!rule.include.startsWith("#"))
                     continue;
                 const key = rule.include.slice(1);
@@ -53,7 +53,7 @@ function readGrammar(raw) {
     return root;
 }
 let grammar;
-/** plyn's grammar, read once - or null when it cannot be. */
+/** The grammar, read once - or null when it cannot be. */
 function plainGrammar() {
     if (grammar !== undefined)
         return grammar;
@@ -175,12 +175,13 @@ const ROLES = [
     ["comment", "comment"],
     ["keyword", "keyword"],
     ["entity.name.function", "section"],
+    ["entity.name.tag.id", "id"],
     ["entity.name.type", "module"],
     ["entity.name.module", "module"],
     ["entity.punctuation", "bullet"],
     ["punctuation", "bullet"],
     ["variable", "concept"],
-    // A link is plyn's `string.quoted.other.plain`; its quotes are `string.quoted.double`, `...other.backtick` and the like.
+    // A link is the grammar's `string.quoted.other.plain`; its quotes are `string.quoted.double`, `...other.backtick` and the like.
     ["string.quoted.other.plain", "link"],
     ["string", "literal"],
 ];

package/dist/plain/index.d.ts

@@ -1,15 +1,18 @@
 /**
- * The ***plain*** parser: a TypeScript port of the reference implementation.
+ * The ***plain parser: a TypeScript port of the reference implementation.
  *
- * Mirrors plain_file.py, plain_spec.py, concept_utils.py and the file_utils.py
- * helpers they depend on. The entry points are `plainFileParser` (a .plain file to a
- * marshalled tree) and `iterateFunctionalSpecs` (the tree to one rendering context per
- * functionality).
+ * Mirrors plain_file.py, plain_spec.py, concept_utils.py, graph.py, test_plain_file.py, project.py and the
+ * loaders.py helpers they depend on. The entry points are `plainFileParser` (a .plain file to a marshalled tree,
+ * with its test plain files bound when it is given its project's test folder), `parseProject` (the reference's,
+ * test folders given) and `iterateFunctionalSpecs` (the tree to one rendering context per functional spec).
  */
 export * from "./errors.ts";
 export * from "./markdown.ts";
 export * from "./concepts.ts";
+export * from "./cycles.ts";
 export * from "./files.ts";
 export * from "./liquid.ts";
 export * from "./parser.ts";
+export * from "./project.ts";
 export * from "./spec.ts";
+export * from "./test-plain-file.ts";

package/dist/plain/index.js

@@ -1,15 +1,18 @@
 /**
- * The ***plain*** parser: a TypeScript port of the reference implementation.
+ * The ***plain parser: a TypeScript port of the reference implementation.
  *
- * Mirrors plain_file.py, plain_spec.py, concept_utils.py and the file_utils.py
- * helpers they depend on. The entry points are `plainFileParser` (a .plain file to a
- * marshalled tree) and `iterateFunctionalSpecs` (the tree to one rendering context per
- * functionality).
+ * Mirrors plain_file.py, plain_spec.py, concept_utils.py, graph.py, test_plain_file.py, project.py and the
+ * loaders.py helpers they depend on. The entry points are `plainFileParser` (a .plain file to a marshalled tree,
+ * with its test plain files bound when it is given its project's test folder), `parseProject` (the reference's,
+ * test folders given) and `iterateFunctionalSpecs` (the tree to one rendering context per functional spec).
  */
 export * from "./errors.js";
 export * from "./markdown.js";
 export * from "./concepts.js";
+export * from "./cycles.js";
 export * from "./files.js";
 export * from "./liquid.js";
 export * from "./parser.js";
+export * from "./project.js";
 export * from "./spec.js";
+export * from "./test-plain-file.js";

package/dist/plain/liquid.js

@@ -63,12 +63,7 @@ export function createEnvironment(options) {
             }
             const templateSource = options.loadTemplateSource(name);
             if (templateSource === null) {
-                throw new Error(`Template not found: ${name}\n` +
-                    "The required template could not be found. Templates are searched in the following order " +
-                    "(highest to lowest precedence):\n\n" +
-                    "    1. The directory containing your .plain file\n" +
-                    "    2. The directory specified by --template-dir (if provided)\n" +
-                    "    3. The built-in 'standard_template_library' directory\n");
+                throw new Error(`Template not found: ${name}`);
             }
             // The reference implementation's loader: rstrip, then re-indent every line to match the
             // include site. The rstrip is what stops a block-level include from ending