@turri-dev/cli 0.1.27 → 0.2.0

package/dist/parse-tool.js

@@ -0,0 +1,33 @@
+import { resolve } from "node:path";
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { checkPlainTargets, formatCheckResults } from "./plain/check.js";
+/** parse, for the conversation and for the skills that write specs alike: it checks the ***plain, never the code. */
+export function checkPlainTool(cwd) {
+    return defineTool({
+        name: "parse",
+        label: "Parse ***plain",
+        description: "Parse one or more .plain modules - their syntax and structure - without regenerating: each with its test plain files, its " +
+            "imports and required modules, reporting every syntax, concept and structure error with the line it is on, " +
+            "and every test plain file outside its module's folder. A module that passes lists each functional spec with its " +
+            "test plain file and its scenarios - one with no test plain file is not tested. Pass a directory to " +
+            "check every .plain module in it; a test plain file or test folder is refused - name its module. Fast, free, and offline. " +
+            "It reads the ***plain alone: it runs no code and no test - whether the code does what the ***plain says is the conformance tests', with conform.",
+        promptSnippet: "parse ***plain - its syntax and structure, never its code or tests - regenerating nothing",
+        promptGuidelines: [
+            "Run parse after editing a .plain file, and before telling the user it is ready. Never shell out to another renderer to check one.",
+        ],
+        parameters: Type.Object({
+            target: Type.String({ description: "A .plain file, or a directory holding .plain files" }),
+            template_dir: Type.Optional(Type.Array(Type.String(), { description: "Extra template directories" })),
+        }),
+        async execute(_id, params) {
+            const results = checkPlainTargets(resolve(cwd, params.target), (params.template_dir ?? []).map((dir) => resolve(cwd, dir)));
+            const failed = results.filter((result) => !result.ok).length;
+            const text = results.length === 0
+                ? `No .plain files found in ${params.target}.`
+                : `${formatCheckResults(results)}\n\n${failed === 0 ? "All specs valid." : `${failed} of ${results.length} failed.`}`;
+            return { content: [{ type: "text", text }], details: { failed, checked: results.length } };
+        },
+    });
+}

package/dist/pi-launch.js

@@ -70,7 +70,7 @@ if (interactive) {
             args.splice(asked, 1);
         restore = saved;
     }
-    driveTerminal(processSession(() => createTurriCore({}, { persist: true })), 
+    driveTerminal(processSession(() => createTurriCore({}, { persist: true, advisor: true })), 
     // With none of the person's chats saved - only the sentinel's - pi starts a fresh one, and every saved chat is opened beside it.
     restore !== undefined ? { restore, skipFirst: restore.chats.some((chat) => chat.role === undefined) } : {});
 }

package/dist/plain/check.d.ts

@@ -1,23 +1,70 @@
 /**
- * Static validation of a .plain file, using this repo's own parser.
+ * Static validation of ***plain, using this repo's own parser - `turri parse`, the chat's `parse`, and the check
+ * `change_plain` and `turri change-plain` run on what a change touched.
  *
- * This is the check that used to mean running the renderer with `--dry-run`: it parses the
- * specification, resolves its imports and required modules, and reports every error the
- * parser can see without generating anything. Nothing is rendered and nothing is spent.
+ * It parses each module with its test plain files, resolves its imports and required modules, and reports every error
+ * the parser can see without generating anything. The parser's errors come one at a time, the first it meets, as the
+ * reference gives them. turri's own checks list everything they find at once: every functional spec without a test
+ * plain file, and every test plain file that is not where it belongs. A module whose functional specs have scenarios
+ * but which has no test reqs, or no conformance testing script for its stack, passes with a warning.
  */
+export interface CheckedFunctionalSpec {
+    funcId: string;
+    /** Its test plain files, from the project's folder. */
+    testPlainFiles: string[];
+    conformance: number;
+    acceptance: number;
+}
 export interface CheckResult {
+    /** The module's file - or, for the test folder's check, the test folder. */
     file: string;
     ok: boolean;
     moduleName?: string;
-    frids?: string[];
+    /** The module's own functional specs, each with its test plain files and how many scenarios they have. */
+    functionalSpecs?: CheckedFunctionalSpec[];
     requiredModules?: string[];
     /** The parser's own message, verbatim - it names the line and the construct. */
     error?: string;
     errorType?: string;
+    /** turri's next step for the error, when it has one: old syntax, say. */
+    nextStep?: string;
+    /** turri's own findings, all of them: what is wrong, and what to do about each. */
+    problems?: string[];
+    /** What does not fail it but leaves something undone: a step of adding tests skipped, and the next step. */
+    warnings?: string[];
 }
+/** Whether a parser error is one the previous ***plain syntax makes. */
+export declare function isPreviousSyntaxError(message: string): boolean;
+/** turri's next step for a module in the previous ***plain syntax. */
+export declare function previousSyntaxStep(file: string): string;
+/**
+ * The modules of a project whose requires chains a module is in and that nothing requires: the tips its conformance
+ * tests are written in, by name with their files. None when nothing requires it - it is a tip itself.
+ */
+export declare function tipsAbove(moduleName: string, projectDir: string): Array<{
+    name: string;
+    file: string;
+}>;
 export declare function checkPlainFile(file: string, templateDirs?: string[]): CheckResult;
+/** The check of a project's test folder: every test plain file not where it belongs. Undefined when there is none. */
+export declare function checkTestFolder(projectDir: string): CheckResult | undefined;
 /** Every `.plain` file directly in a directory, or the single file given. */
 export declare function resolvePlainTargets(target: string): string[];
+/**
+ * Check a file, or every .plain file directly in a folder - never a test folder, which holds no module - and then the
+ * project's test folder, once, at the end.
+ */
 export declare function checkPlainTargets(target: string, templateDirs?: string[]): CheckResult[];
-/** One line per file, plus the parser's message under any that failed. */
+/**
+ * The check of what a ***plain change touched, shared by `change_plain` and `turri change-plain`: each module it
+ * touched, an import module as the modules that import it read it, and each test plain file as its module - by its
+ * folder - is parsed with its test plain files; a test plain file the change put where it does not belong is refused
+ * as `parse` refuses it. A file the change deleted is checked through the module it belonged to.
+ */
+export declare function checkTouchedPlain(paths: string[]): CheckResult[];
+/**
+ * One line per file, plus the parser's message under any that failed and turri's next step, or every problem turri
+ * found; a module that passed, its functional specs under it, each with its test plain file and its scenarios - and
+ * a WARN line for each warning, a step of adding tests it skipped.
+ */
 export declare function formatCheckResults(results: CheckResult[]): string;

package/dist/plain/check.js

@@ -1,43 +1,166 @@
-import { existsSync, readdirSync, statSync } from "node:fs";
-import { basename, extname, join, resolve } from "node:path";
-import { plainFileParser, PLAIN_SOURCE_FILE_EXTENSION } from "./parser.js";
-import { getFrids } from "./spec.js";
-import { resolveTemplateDirs } from "../regenerate/paths.js";
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { basename, extname, join, relative, resolve, sep } from "node:path";
+import { testDirOf } from "../config.js";
+import { projectDirOf, resolveTemplateDirs } from "../regenerate/paths.js";
+import { importingModules, isImportModule } from "../regenerate/requires.js";
+import { testingGap } from "../regenerate/testing-steps.js";
+import { missingBaseFolder } from "../regenerate/base-folder.js";
+import { conformanceTestsOn } from "../conformance-switch.js";
+import { testedFuncIds } from "../regenerate/records.js";
+import { moduleOfTestPlainFile, projectModules, strayTestPlainFiles, testPlaceOf, testPlainFileRefusal } from "../test-plain-files.js";
+import { plainFileParser, PLAIN_SOURCE_FILE_EXTENSION, PREVIOUS_SYNTAX_HINT, readPlainSourceMetadata, REQUIRES_DIRECTIVE } from "./parser.js";
+import { ACCEPTANCE_TESTS, CONFORMANCE_TESTS, getFunctionalSpecs, TEST_PLAIN_FILES, } from "./spec.js";
+/** Whether a parser error is one the previous ***plain syntax makes. */
+export function isPreviousSyntaxError(message) {
+    return message.includes(PREVIOUS_SYNTAX_HINT) || message.includes("is not allowed in a spec plain file; test scenarios live in test plain files");
+}
+/** turri's next step for a module in the previous ***plain syntax. */
+export function previousSyntaxStep(file) {
+    return (`${basename(file)} is in the old ***plain syntax. Ask turri to convert it: it goes one module at a time, ` +
+        "proposing func-ids and test plain files, and asks you before writing anything.");
+}
+/** A path from the project's folder, as a person reads it. */
+function shown(path, projectDir) {
+    return relative(projectDir, resolve(path)).split(sep).join("/");
+}
+/**
+ * The modules of a project whose requires chains a module is in and that nothing requires: the tips its conformance
+ * tests are written in, by name with their files. None when nothing requires it - it is a tip itself.
+ */
+export function tipsAbove(moduleName, projectDir) {
+    const modules = projectModules(projectDir);
+    const requiredBy = new Map();
+    for (const [name, file] of modules) {
+        let requires = [];
+        try {
+            requires = readPlainSourceMetadata(readFileSync(file, "utf8")).metadata[REQUIRES_DIRECTIVE] ?? [];
+        }
+        catch {
+            continue;
+        }
+        for (const required of requires) {
+            const below = basename(required.replace(/^\.\//, ""), PLAIN_SOURCE_FILE_EXTENSION);
+            requiredBy.set(below, [...(requiredBy.get(below) ?? []), name]);
+        }
+    }
+    const tips = new Set();
+    const seen = new Set();
+    const up = (name) => {
+        if (seen.has(name))
+            return;
+        seen.add(name);
+        const above = requiredBy.get(name) ?? [];
+        if (above.length === 0 && name !== moduleName)
+            tips.add(name);
+        for (const next of above)
+            up(next);
+    };
+    up(moduleName);
+    return [...tips].sort().flatMap((name) => (modules.has(name) ? [{ name, file: modules.get(name) }] : []));
+}
+/**
+ * The steps of adding tests a module skipped, as warnings. A module another requires has its conformance tests
+ * written in the tips above it, from their test reqs and with their script: it is judged by each of them, which says so.
+ */
+function testingGapsOf(moduleName, path, tree, projectDir, templateDirs) {
+    // Conformance tests off: no step of adding them is skipped - and scenarios written are said not to be tested.
+    if (!conformanceTestsOn(path)) {
+        const tested = testedFuncIds(tree);
+        return tested.length > 0
+            ? [`its scenarios are not tested - ${tested.map((funcId) => `${moduleName}:${funcId}`).join(", ")}: conformance tests are off (conformance-tests: false, or unset). Asking for them in the chat turns them on, or conformance-tests: true in config.turri.yaml.`]
+            : [];
+    }
+    const tips = tipsAbove(moduleName, projectDir);
+    if (tips.length === 0) {
+        const gap = testingGap({ moduleName, plainFile: path, tree });
+        return gap !== undefined ? [gap.text] : [];
+    }
+    return tips.flatMap((tip) => {
+        let tipTree;
+        try {
+            [, tipTree] = plainFileParser(basename(tip.file), resolveTemplateDirs(tip.file, templateDirs), {
+                allowNoFunctionalities: true,
+                testDir: testDirOf(tip.file),
+                requireTestPlainFiles: false,
+            });
+        }
+        catch {
+            // A tip that does not parse is reported when it is checked itself.
+            return [];
+        }
+        const gap = testingGap({ moduleName: tip.name, plainFile: tip.file, tree: tipTree });
+        return gap !== undefined ? [`${moduleName}'s conformance tests are written in ${tip.name}, which requires it: ${gap.text}`] : [];
+    });
+}
 export function checkPlainFile(file, templateDirs = []) {
     const path = resolve(file);
     if (extname(path) !== PLAIN_SOURCE_FILE_EXTENSION) {
-        return {
-            file,
-            ok: false,
-            error: `Not a ${PLAIN_SOURCE_FILE_EXTENSION} file.`,
-            errorType: "UsageError",
-        };
+        return { file, ok: false, error: `Not a ${PLAIN_SOURCE_FILE_EXTENSION} file.`, errorType: "UsageError" };
     }
     if (!existsSync(path)) {
         return { file, ok: false, error: "File does not exist.", errorType: "UsageError" };
     }
+    const refusal = testPlainFileRefusal(path);
+    if (refusal !== undefined)
+        return { file, ok: false, error: refusal, errorType: "UsageError" };
+    const projectDir = projectDirOf(path);
+    const testDir = testDirOf(path);
     try {
         const dirs = resolveTemplateDirs(path, templateDirs);
         // A module with no functional specs yet is valid - it is how every module starts, and how
         // an import module always is. It is reported, not failed.
-        const [moduleName, tree, requiredModules] = plainFileParser(basename(path), dirs, { allowNoFunctionalities: true });
+        const [moduleName, tree, requiredModules] = plainFileParser(basename(path), dirs, {
+            allowNoFunctionalities: true,
+            testDir,
+            requireTestPlainFiles: false,
+        });
+        // Scenarios with a step of adding tests skipped - the test reqs, or the conformance testing script: a warning, never a failure.
+        const gaps = testingGapsOf(moduleName, path, tree, projectDir, templateDirs);
+        // A codebase that requires nothing starts from its base folder: one named and not there stops its first pulse.
+        const base = requiredModules.length === 0 && !isImportModule(path) ? missingBaseFolder(path) : undefined;
+        if (base !== undefined)
+            gaps.push(base);
+        const bindings = Object.entries(tree[TEST_PLAIN_FILES] ?? {});
         return {
             file,
             ok: true,
             moduleName,
-            frids: [...getFrids(tree)],
+            ...(gaps.length > 0 ? { warnings: gaps } : {}),
+            functionalSpecs: getFunctionalSpecs(tree).map((item) => ({
+                funcId: item.id,
+                testPlainFiles: bindings
+                    .filter(([, binding]) => binding.module === moduleName && binding.func_id === item.id)
+                    .map(([name]) => shown(join(dirs[0], name), projectDir)),
+                conformance: item[CONFORMANCE_TESTS].length,
+                acceptance: item[ACCEPTANCE_TESTS].length,
+            })),
             requiredModules,
         };
     }
     catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
         return {
             file,
             ok: false,
-            error: error instanceof Error ? error.message : String(error),
+            error: message,
             errorType: error instanceof Error ? error.name : "Error",
+            ...(isPreviousSyntaxError(message) ? { nextStep: previousSyntaxStep(path) } : {}),
         };
     }
 }
+/** The check of a project's test folder: every test plain file not where it belongs. Undefined when there is none. */
+export function checkTestFolder(projectDir) {
+    const strays = strayTestPlainFiles(projectDir);
+    if (strays.length === 0)
+        return undefined;
+    const testDir = testDirOf(join(projectDir, `x${PLAIN_SOURCE_FILE_EXTENSION}`));
+    return {
+        file: `${shown(testDir, projectDir)}/`,
+        ok: false,
+        errorType: `${strays.length} test plain file${strays.length === 1 ? "" : "s"} outside a module's folder`,
+        problems: strays.map((stray) => `${stray.file} - ${stray.problem}`),
+    };
+}
 /** Every `.plain` file directly in a directory, or the single file given. */
 export function resolvePlainTargets(target) {
     const path = resolve(target);
@@ -49,27 +172,97 @@ export function resolvePlainTargets(target) {
     }
     return [path];
 }
+/**
+ * Check a file, or every .plain file directly in a folder - never a test folder, which holds no module - and then the
+ * project's test folder, once, at the end.
+ */
 export function checkPlainTargets(target, templateDirs = []) {
-    return resolvePlainTargets(target).map((file) => checkPlainFile(file, templateDirs));
+    const path = resolve(target);
+    if (existsSync(path) && statSync(path).isDirectory()) {
+        const refusal = testPlainFileRefusal(path);
+        if (refusal !== undefined)
+            return [{ file: target, ok: false, error: refusal, errorType: "UsageError" }];
+    }
+    const results = resolvePlainTargets(target).map((file) => checkPlainFile(file, templateDirs));
+    const projects = [...new Set(resolvePlainTargets(target).map((file) => projectDirOf(file)))];
+    for (const project of projects) {
+        const folder = checkTestFolder(project);
+        if (folder !== undefined)
+            results.push(folder);
+    }
+    return results;
+}
+/**
+ * The check of what a ***plain change touched, shared by `change_plain` and `turri change-plain`: each module it
+ * touched, an import module as the modules that import it read it, and each test plain file as its module - by its
+ * folder - is parsed with its test plain files; a test plain file the change put where it does not belong is refused
+ * as `parse` refuses it. A file the change deleted is checked through the module it belonged to.
+ */
+export function checkTouchedPlain(paths) {
+    const modules = new Set();
+    const results = [];
+    for (const given of paths) {
+        const path = resolve(given);
+        const place = testPlaceOf(path);
+        if (place !== undefined && !place.directory) {
+            const stray = strayTestPlainFiles(place.projectDir).find((found) => resolve(place.projectDir, found.file) === path);
+            if (stray !== undefined) {
+                results.push({ file: path, ok: false, errorType: "a test plain file outside its module's folder", problems: [`${stray.file} - ${stray.problem}`] });
+                continue;
+            }
+            const owner = moduleOfTestPlainFile(path);
+            if (owner?.plainFile !== undefined)
+                modules.add(owner.plainFile);
+            else if (owner !== undefined)
+                results.push({ file: path, ok: false, errorType: "a test plain file outside a module's folder", problems: [`${shown(path, place.projectDir)} - no module ${owner.module}`] });
+            continue;
+        }
+        if (!existsSync(path))
+            continue;
+        const importing = isImportModule(path) ? importingModules(path) : [];
+        for (const module of importing.length > 0 ? importing : [path])
+            modules.add(resolve(module));
+    }
+    for (const module of modules)
+        results.push(checkPlainFile(module));
+    return results;
+}
+/** Columns padded to their widest cell, each line indented under the module's. */
+function columns(rows) {
+    const widths = rows.reduce((acc, row) => row.map((cell, index) => Math.max(acc[index] ?? 0, cell.length)), []);
+    return rows.map((row) => `        ${row.map((cell, index) => (index === row.length - 1 ? cell : cell.padEnd(widths[index]))).join("  ")}`);
+}
+/** How many scenarios a functional spec has, or that it has none and so is not tested. */
+function scenarioCounts(spec) {
+    const counts = [spec.conformance > 0 ? `${spec.conformance} conformance` : "", spec.acceptance > 0 ? `${spec.acceptance} acceptance` : ""].filter(Boolean);
+    return counts.length === 0 ? "no scenarios - not tested" : counts.join(", ");
 }
-/** One line per file, plus the parser's message under any that failed. */
+/**
+ * One line per file, plus the parser's message under any that failed and turri's next step, or every problem turri
+ * found; a module that passed, its functional specs under it, each with its test plain file and its scenarios - and
+ * a WARN line for each warning, a step of adding tests it skipped.
+ */
 export function formatCheckResults(results) {
     const lines = [];
     for (const result of results) {
-        const name = basename(result.file);
+        const name = result.file.endsWith("/") ? result.file : basename(result.file);
         if (result.ok) {
-            const frids = result.frids ?? [];
-            const requires = result.requiredModules && result.requiredModules.length > 0
-                ? `, requires ${result.requiredModules.join(", ")}`
-                : "";
-            lines.push(frids.length === 0
+            const specs = result.functionalSpecs ?? [];
+            const requires = result.requiredModules && result.requiredModules.length > 0 ? `, requires ${result.requiredModules.join(", ")}` : "";
+            lines.push(specs.length === 0
                 ? `PASS  ${name}  no functional specs yet${requires}`
-                : `PASS  ${name}  ${frids.length} functionalit${frids.length === 1 ? "y" : "ies"} (${frids.join(", ")})${requires}`);
+                : `PASS  ${name}  ${specs.length} functional spec${specs.length === 1 ? "" : "s"}${requires}`);
+            // No test plain file is a functional spec not tested - the one way to say so: an empty one is a syntax error.
+            lines.push(...columns(specs.map((spec) => [spec.funcId, spec.testPlainFiles.length > 0 ? spec.testPlainFiles.join(", ") : "no test plain file", scenarioCounts(spec)])));
+            for (const warning of result.warnings ?? [])
+                lines.push(`WARN  ${name}  ${warning}`);
         }
         else {
             lines.push(`FAIL  ${name}  ${result.errorType ?? "Error"}`);
-            for (const line of (result.error ?? "").split("\n"))
+            for (const line of [...(result.error ?? "").split("\n").filter((line, index) => index > 0 || line !== ""), ...(result.problems ?? [])])
                 lines.push(`        ${line}`);
+            if (result.nextStep !== undefined)
+                lines.push(`        ${result.nextStep}`);
         }
     }
     return lines.join("\n");

package/dist/plain/concepts.d.ts

@@ -26,4 +26,12 @@ export declare function extractConceptsFromSpecText(text: string): string[];
 export declare function collectConcepts(plainSource: MarshalledPlainSource): [string[], string[]];
 export declare function validateConcepts(marshalled: MarshalledPlainSource): string[];
 export declare function findConceptDefinitionsInPlainSource(concept: string, definitions: Section | null): AnyNode[];
+export declare const MAX_REPORTED_CYCLES = 10;
+/**
+ * The elementary cycles in the graph, each as a "Cycle N: :A: -> :B: -> :A:" line followed by the definition of
+ * every concept in the cycle. Arrows point from a definition to a concept it mentions, each cycle starts at its
+ * earliest-defined concept, and cycles are ordered by definition position, so the report reads top to bottom like
+ * the file. At most MAX_REPORTED_CYCLES are listed; the search stops once one more than that is found.
+ */
+export declare function formatCyclesError(adjacency: Map<string, string[]>, conceptDefinitions: Map<string, SpecificationItem>): string;
 export declare function sortDefinitions(definitions: SpecificationItem[]): void;

package/dist/plain/concepts.js

@@ -1,6 +1,7 @@
+import { simpleCycles } from "./cycles.js";
 import { PlainSyntaxError } from "./errors.js";
 import { renderToMarkdown } from "./markdown.js";
-import { ACCEPTANCE_TESTS, DEFINITIONS, FUNCTIONAL_REQUIREMENTS, NON_FUNCTIONAL_REQUIREMENTS, TEST_REQUIREMENTS, getSpecificationItems, } from "./spec.js";
+import { DEFINITIONS, FUNCTIONAL_REQUIREMENTS, NON_FUNCTIONAL_REQUIREMENTS, TEST_REQUIREMENTS, getSpecificationItems, } from "./spec.js";
 /** Port of concept_utils.py. */
 /**
  * ***plain's own concepts, each with what it means, in a line: every module can name them, and none may define them.
@@ -123,11 +124,6 @@ export function validateConcepts(marshalled) {
     ]) {
         errors.push(...validateConceptsInSpecGroup(specGroup, marshalled, treeBasedConcepts));
     }
-    for (const funcSpec of getSpecificationItems(marshalled, FUNCTIONAL_REQUIREMENTS) ?? []) {
-        for (const test of funcSpec[ACCEPTANCE_TESTS] ?? []) {
-            errors.push(...validateConceptsInSpec(test, treeBasedConcepts, ACCEPTANCE_TESTS));
-        }
-    }
     return errors;
 }
 export function findConceptDefinitionsInPlainSource(concept, definitions) {
@@ -170,13 +166,13 @@ function buildAdjacencyList(definitions) {
     return [adjacency, conceptDefinitions];
 }
 /**
- * networkx's topological_sort, reproduced.
+ * The order graphlib's `TopologicalSorter.static_order` gives, reproduced.
  *
- * It flattens `topological_generations`, which is Kahn's algorithm processed one
- * generation at a time with nodes visited in graph insertion order. The ordering of
- * independent concepts therefore depends on insertion order, and the Python tests
- * assert that exact order - a generic topological sort would pass the dependency
- * constraints but produce a different sequence.
+ * It hands out every node that is ready at once, in the order the nodes were first
+ * added, then the nodes each one frees, in the order it frees them - Kahn's algorithm
+ * one generation at a time. The ordering of independent concepts therefore depends on
+ * insertion order, and the Python tests assert that exact order - a generic topological
+ * sort would pass the dependency constraints but produce a different sequence.
  */
 function topologicalSort(successors) {
     const inDegree = new Map();
@@ -210,22 +206,69 @@ function topologicalSort(successors) {
         return { order, cycle: [...remaining.keys()] };
     return { order, cycle: null };
 }
+export const MAX_REPORTED_CYCLES = 10;
+/**
+ * The elementary cycles in the graph, each as a "Cycle N: :A: -> :B: -> :A:" line followed by the definition of
+ * every concept in the cycle. Arrows point from a definition to a concept it mentions, each cycle starts at its
+ * earliest-defined concept, and cycles are ordered by definition position, so the report reads top to bottom like
+ * the file. At most MAX_REPORTED_CYCLES are listed; the search stops once one more than that is found.
+ */
+export function formatCyclesError(adjacency, conceptDefinitions) {
+    const position = new Map([...conceptDefinitions.keys()].map((concept, index) => [concept, index]));
+    const at = (concept) => position.get(concept);
+    // Keyed in definition order, so a search cut short by the limit has found the earliest cycles.
+    const byPosition = new Map();
+    for (const concept of [...conceptDefinitions.keys(), ...adjacency.keys()]) {
+        if (!byPosition.has(concept))
+            byPosition.set(concept, adjacency.get(concept));
+    }
+    let cycles = [];
+    for (const found of simpleCycles(byPosition, MAX_REPORTED_CYCLES + 1)) {
+        // Reversed, since the edges point from a used concept to the one defined with it.
+        const cycle = [...found].reverse();
+        let first = 0;
+        cycle.forEach((concept, index) => {
+            if (at(concept) < at(cycle[first]))
+                first = index;
+        });
+        cycles.push([...cycle.slice(first), ...cycle.slice(0, first)]);
+    }
+    cycles.sort((a, b) => {
+        if (at(a[0]) !== at(b[0]))
+            return at(a[0]) - at(b[0]);
+        if (a.length !== b.length)
+            return a.length - b.length;
+        for (let i = 0; i < a.length; i += 1)
+            if (at(a[i]) !== at(b[i]))
+                return at(a[i]) - at(b[i]);
+        return 0;
+    });
+    let lines;
+    if (cycles.length > MAX_REPORTED_CYCLES) {
+        cycles = cycles.slice(0, MAX_REPORTED_CYCLES);
+        lines = [
+            `Plain syntax error: Found more than ${MAX_REPORTED_CYCLES} cycles in concept definitions. Cycles are not allowed.`,
+            `Showing the first ${MAX_REPORTED_CYCLES}.`,
+        ];
+    }
+    else {
+        lines = [`Plain syntax error: Found ${cycles.length} cycle(s) in concept definitions. Cycles are not allowed.`];
+    }
+    cycles.forEach((cycle, index) => {
+        lines.push("");
+        lines.push(`Cycle ${index + 1}: ` + [...cycle, cycle[0]].join(" -> "));
+        // Concepts defined on one line can share a cycle; that line is printed once.
+        lines.push(...new Set(cycle.map((concept) => conceptDefinitions.get(concept).markdown)));
+    });
+    return lines.join("\n");
+}
 export function sortDefinitions(definitions) {
     if (definitions.length <= 1)
         return;
     const [adjacency, conceptDefinitions] = buildAdjacencyList(definitions);
     const { order, cycle } = topologicalSort(adjacency);
-    if (cycle !== null) {
-        let msg = "Found cycles in the concept graph. Cycles are not allowed.";
-        const cyclicDefinitions = cycle
-            .slice(0, 2)
-            .map((concept) => conceptDefinitions.get(concept)?.markdown)
-            .filter((markdown) => markdown !== undefined);
-        msg += "Cyclic definitons:\n";
-        msg += cyclicDefinitions.join("\n");
-        msg += "\n";
-        throw new PlainSyntaxError(`Plain syntax error: ${msg}`);
-    }
+    if (cycle !== null)
+        throw new PlainSyntaxError(formatCyclesError(adjacency, conceptDefinitions));
     if (order.length === 0)
         return;
     const definitionOrder = new Map();

package/dist/plain/cycles.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 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
+ */
+export type Graph<T> = Map<T, Iterable<T>>;
+/**
+ * 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 declare function stronglyConnectedComponents<T>(graph: Graph<T>): Array<Set<T>>;
+/**
+ * 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 declare function simpleCycles<T>(graph: Graph<T>, limit?: number): Generator<T[]>;