@turri-dev/cli 0.1.13 → 0.1.14-next.678847f

package/dist/extension.d.ts

@@ -24,7 +24,11 @@ dialogs?: AskUserIO): AskUser;
  * pick from, several at once, "Something else…" to type instead, "Chat about this" to talk it over in
  * the chat first - so a question with a handful of answers is picked, not typed.
  */
-export declare function chatAskUserTool(dialogs?: AskUserIO): ReturnType<typeof createAskUserTool>;
+/**
+ * ask_user, for the conversation. `afterAnswer` may add to what an answer tells the model - a skill the person picked,
+ * to start at once.
+ */
+export declare function chatAskUserTool(dialogs?: AskUserIO, afterAnswer?: (answer: string) => string | undefined): ReturnType<typeof createAskUserTool>;
 /**
  * What a host that runs turri's conversation itself - a desktop app, an editor - is told and asked, where the terminal
  * would draw: the conversation's jobs and its work loop as they are made and as they change, and the dialogs its

package/dist/extension.js

@@ -25,6 +25,7 @@ import { createDeployState, createDeployTools } from "./release-tools.js";
 import { runReleaseAgent } from "./release-agent.js";
 import { createSteeringStore, EVERY_MODULE, moduleNameOf, queueSectionOf, steeringFor } from "./regenerate/steer.js";
 import { askedForCommandLine, refusal, selfInvocation, TOOLS_NOT_CLI } from "./self-invocation.js";
+import { NEW_PROJECT } from "./new-project.js";
 import { describeChoices, describeResolution, modelFor, resolveModel } from "./regenerate/engine.js";
 import { checkPlainFile, checkPlainTargets, formatCheckResults } from "./plain/check.js";
 import { whyFailed } from "./regenerate/diagnose-job.js";
@@ -57,7 +58,7 @@ import { describeStdlib } from "./stdlib.js";
 import { peekKeyListener, runAsk } from "./ask.js";
 import { QuestionDialog } from "./question-dialog.js";
 import { registerStacks } from "./stacks.js";
-import { catalogueLine, createCommandGate, discoverSkills, leftOutNote, startedByCommandOnly } from "./skills.js";
+import { catalogueLine, chosenCommand, createCommandGate, startPicked, discoverSkills, leftOutNote, startedByCommandOnly } from "./skills.js";
 import { supersededByTurri } from "./chat-skills.js";
 import { conversationIdentity } from "./identity.js";
 import { setSurface, surfaceOf } from "./surface.js";
@@ -170,7 +171,11 @@ function hookPeekKey(ctx) {
  * pick from, several at once, "Something else…" to type instead, "Chat about this" to talk it over in
  * the chat first - so a question with a handful of answers is picked, not typed.
  */
-export function chatAskUserTool(dialogs) {
+/**
+ * ask_user, for the conversation. `afterAnswer` may add to what an answer tells the model - a skill the person picked,
+ * to start at once.
+ */
+export function chatAskUserTool(dialogs, afterAnswer) {
     let conversation;
     const tool = createAskUserTool((request) => (conversation !== undefined ? askUserVia(conversation, () => { }, undefined, dialogs)(request) : Promise.resolve("No user is available to answer.")), undefined, undefined, undefined, "reply");
     return {
@@ -181,7 +186,10 @@ export function chatAskUserTool(dialogs) {
         ],
         async execute(...args) {
             conversation = args[4];
-            return tool.execute(...args);
+            const result = await tool.execute(...args);
+            const answer = result.details?.answer;
+            const note = answer !== undefined && answer !== "" ? afterAnswer?.(answer) : undefined;
+            return note !== undefined ? { ...result, content: [...result.content, { type: "text", text: note }] } : result;
         },
     };
 }
@@ -313,7 +321,7 @@ function turriExtension(pi, host) {
             }
         }
         return {
-            systemPrompt: conversationSystemPrompt(event.systemPrompt, host, [TOOLS_NOT_CLI, projectConfigBlock(cwd), machineBlock(cwd, machine.now()), rulesBlock()]),
+            systemPrompt: conversationSystemPrompt(event.systemPrompt, host, [TOOLS_NOT_CLI, NEW_PROJECT, projectConfigBlock(cwd), machineBlock(cwd, machine.now()), rulesBlock()]),
         };
     });
     // The conversation's agent does not run turri again through its shell, unless the person
@@ -433,7 +441,17 @@ function turriExtension(pi, host) {
     registerBranding(pi, discoveredSkills);
     registerInterviewLog(pi);
     registerJobTools(pi, jobs, cwd);
-    registerCheckPlain(pi, cwd, host.dialogs);
+    // The skills the person starts themselves - brood, spawn, bud: each has its command, and cultivate starts it only
+    // once its command is typed, or picked among the options the conversation offers with ask_user.
+    const gate = createCommandGate();
+    // A skill picked is started at once, with what the person asked for: they never type its command after picking it.
+    registerCheckPlain(pi, cwd, host.dialogs, (answer) => {
+        const chosen = chosenCommand(answer, discoveredSkills.skills);
+        if (chosen === undefined)
+            return undefined;
+        gate.typed(chosen);
+        return startPicked(chosen, lastUserMessage);
+    });
     registerRegenerate(pi, cwd, jobs);
     registerDrift(pi, cwd, jobs);
     registerGlimpse(pi, cwd, jobs);
@@ -449,10 +467,8 @@ function turriExtension(pi, host) {
         return;
     const catalogue = skills.map(catalogueLine).join("\n");
     const pendingNote = leftOutNote(discoveredSkills);
-    // The skills the person starts themselves - brood, spawn, bud: each has its command, and cultivate starts it only
-    // once its command is typed. The command puts what was typed in the chat, as the person's message, for the model to
-    // run it with what follows as its context.
-    const gate = createCommandGate();
+    // The command puts what was typed in the chat, as the person's message, for the model to run it with what follows as
+    // its context.
     for (const skill of skills.filter((s) => s.commandOnly)) {
         pi.registerCommand(skill.name, {
             description: `Start ${skill.name}${skill.steps.length > 1 ? ` - ${skill.steps.map((step) => step.name).join(" → ")}` : ""}: /${skill.name} [what you want]`,
@@ -472,7 +488,7 @@ function turriExtension(pi, host) {
         promptSnippet: "cultivate: run a gated skill - its steps and review gates enforced by turri",
         promptGuidelines: [
             "When a request matches a skill listed in cultivate's description, call cultivate instead of doing the work yourself. Doing it by hand skips the review gates.",
-            "A skill marked as started only by the person runs only from its command: a message that is its command - /spawn a small server - is the person starting it, so call cultivate for it at once, with what follows the command as context. Never call cultivate for one otherwise; tell them to type its command.",
+            "A skill marked as started only by the person runs only from its command: a message that is its command - /spawn a small server - is the person starting it, and so is an option starting with it that they picked in your ask_user - /brood - an interview. Call cultivate for it at once, with what they said as context. Never call cultivate for one otherwise; for a new project, offer the choice as <new-project> says.",
             // pi lists .agents/skills among its own skills too: read and followed by hand, a skill's gates would be skipped.
             "A skill cultivate lists may also be among your own skills, from the project's .agents/skills: run it with cultivate all the same, never by reading its SKILL.md and following it.",
             "cultivate returns the reviewed artifact and a trace of every gate decision. Report the artifact to the user; do not rewrite it.",
@@ -2063,9 +2079,9 @@ function jobLines(all) {
  * so it needs no external tool, no API key and no credits - and it is the only honest way
  * to answer "is this spec valid?" without generating anything.
  */
-function registerCheckPlain(pi, cwd, dialogs) {
+function registerCheckPlain(pi, cwd, dialogs, afterAnswer) {
     pi.registerTool(checkPlainTool(cwd));
-    pi.registerTool(chatAskUserTool(dialogs));
+    pi.registerTool(chatAskUserTool(dialogs, afterAnswer));
     // The web, for the conversation too - a library's documentation, an API, an error; curl is its
     // bash. Run here, like the rendering agents' (see render/web.ts).
     for (const tool of createWebTools())

package/dist/host.d.ts

@@ -1,8 +1,8 @@
 /**
  * turri for a host that runs it itself - a desktop app, an editor - imported as `@turri-dev/cli/host`: the
  * conversation as pi's extension, with the host told of its jobs and asking its questions (createTurriExtension), and
- * what a host shows beside it - a spec parsed, checked and coloured, how far each functional spec is built, the work a
- * spec change would plan. It is turri's own code, as the terminal runs it; a 0.x release may change any of it.
+ * what a host shows beside it - a spec parsed, checked and coloured, its concepts and links, the standard library, how
+ * far each functional spec is built, the work a spec change would plan. It is turri's own code, as the terminal runs it; a 0.x release may change any of it.
  */
 export { createTurriExtension, type TurriHost } from "./extension.ts";
 export type { AskUserIO } from "./ask.ts";
@@ -18,6 +18,10 @@ export { checkPlainFile, type CheckResult } from "./plain/check.ts";
 export { plainFileParser } from "./plain/parser.ts";
 export { FUNCTIONAL_REQUIREMENTS, iterateFunctionalSpecs } from "./plain/spec.ts";
 export { highlightLines, roleOf, type PlainRole } from "./plain/highlight.ts";
+export { conceptsOf, type ModuleConcept } from "./plain/module-concepts.ts";
+export { conceptBeingTyped, findConcepts } from "./plain/concepts.ts";
+export { plainGraph, type PlainConceptNode, type PlainGraph, type PlainItemNode, type PlainLink, type PlainModuleNode, type PlainSection } from "./plain/graph.ts";
+export { isStack, STDLIB_KINDS, stdlibTemplates, type StdlibKind, type StdlibTemplate } from "./stdlib.ts";
 export { createWorkLoop, describeModules, functionalityCompletion, promptOf, type DriftReport, type ModuleStatus, type WorkLoop } from "./regenerate/loop.ts";
 export { createJobRegistry, defaultParallelJobs, type Job, type JobRegistry } from "./regenerate/jobs.ts";
 export { describeTurnIncident, onModelEvent, type TranscriptEntry } from "./regenerate/activity.ts";

package/dist/host.js

@@ -1,8 +1,8 @@
 /**
  * turri for a host that runs it itself - a desktop app, an editor - imported as `@turri-dev/cli/host`: the
  * conversation as pi's extension, with the host told of its jobs and asking its questions (createTurriExtension), and
- * what a host shows beside it - a spec parsed, checked and coloured, how far each functional spec is built, the work a
- * spec change would plan. It is turri's own code, as the terminal runs it; a 0.x release may change any of it.
+ * what a host shows beside it - a spec parsed, checked and coloured, its concepts and links, the standard library, how
+ * far each functional spec is built, the work a spec change would plan. It is turri's own code, as the terminal runs it; a 0.x release may change any of it.
  */
 // The conversation.
 export { createTurriExtension } from "./extension.js";
@@ -25,6 +25,14 @@ export { checkPlainFile } from "./plain/check.js";
 export { plainFileParser } from "./plain/parser.js";
 export { FUNCTIONAL_REQUIREMENTS, iterateFunctionalSpecs } from "./plain/spec.js";
 export { highlightLines, roleOf } from "./plain/highlight.js";
+// Its concepts: those a module can name, with what each is and where it is defined, and those written in a piece of text.
+export { conceptsOf } from "./plain/module-concepts.js";
+export { conceptBeingTyped, findConcepts } from "./plain/concepts.js";
+// A project's ***plain as a graph: its modules and their links both ways, each item of their sections, the concepts
+// each names and where each is defined.
+export { plainGraph } from "./plain/graph.js";
+// The standard library: every template, what it is, what it imports, and its conformance template or stack.
+export { isStack, STDLIB_KINDS, stdlibTemplates } from "./stdlib.js";
 // The work: what is built, what is left, and the jobs that build it.
 export { createWorkLoop, describeModules, functionalityCompletion, promptOf } from "./regenerate/loop.js";
 export { createJobRegistry, defaultParallelJobs } from "./regenerate/jobs.js";

package/dist/new-project.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Starting a project from the conversation: the person says what they want built - "create a small server in Java
+ * Spring Boot" - and the chat offers the three ways to start it: brood's interview, spawn's quick start, or writing the
+ * ***plain itself, here, with no skill. An option picked that starts with a skill's command starts that skill, as if
+ * typed (`chosenCommand` in skills.ts).
+ */
+export declare const NEW_PROJECT: string;

package/dist/new-project.js

@@ -0,0 +1,37 @@
+/**
+ * Starting a project from the conversation: the person says what they want built - "create a small server in Java
+ * Spring Boot" - and the chat offers the three ways to start it: brood's interview, spawn's quick start, or writing the
+ * ***plain itself, here, with no skill. An option picked that starts with a skill's command starts that skill, as if
+ * typed (`chosenCommand` in skills.ts).
+ */
+export const NEW_PROJECT = [
+    "<new-project>",
+    "When the person asks for new software / project ",
+    "and there is no ***plain module for it yet, or they ask for a new project, ask them first how to start it, with",
+    "ask_user: one question, these three options, word for word, so they know the skills are there:",
+    `- "${"/brood - an interview: the stack, the testing and every feature settled with you, each answer regenerated"}"`,
+    `- "${"/spawn - something running in minutes: the quick start, asking only what your message leaves open"}"`,
+    `- "${"Just do it - no skill: I write it here and start regenerating"}"`,
+    "Picked /brood or /spawn: the answer starts it - call cultivate for it at once, with what they said as its context,",
+    "never asking them to type its command. Do not ask when their",
+    "message says already - they typed the command, or said to just build it, with no skill, without questions: then",
+    "start it yourself. Started yourself, how soon the first pulse starts, and something they can try, come first:",
+    "1. The stack: the one they named; otherwise one of the standard library's that this machine can build - common,",
+    "   simple - said in a line. A stack named in a language the machine lacks is written all the same: tell them what to",
+    "   install, and that turri doctor checks it. Read the stack's template, its language's and its kind's common first.",
+    "2. One module - a .plain file in the project's root, named after what it is (server.plain) - importing the stack and",
+    "   writing only what the module needs beyond it. Two side by side, each on its stack, only when it needs two stacks.",
+    "3. config.turri.yaml: module: the new file, and conformance-tests: false unless they asked for conformance tests.",
+    "   What a config there already settles - a stack, a script, conformance - is kept, not chosen again.",
+    "4. The unit testing script: keep one turri already finds; otherwise run cultivate with implement-unit-testing-script",
+    "   for the stack's language. Conformance tests asked for: their ***test reqs*** - the stack's conformance template -",
+    "   and cultivate with implement-conformance-testing-script.",
+    "5. The first functional spec: the smallest thing that runs and shows something - the server answers GET / with the",
+    "   app's name, the CLI prints its usage. validate, fix what it finds, and regenerate at once.",
+    "6. While it regenerates: the main thing they described, on its happy path, and at most one more - each a functional",
+    "   spec, with its concepts - then validate and regenerate again. Only what they described: they named only the kind of",
+    "   software, write none, and invite them to say what it does. No validation or edge cases yet.",
+    "Then hand over in a few lines: what you chose, what is regenerating, and the next slices you would write - they say",
+    "go on, or what to change, and every change after is ***plain you write and regenerate.",
+    "</new-project>",
+].join("\n");

package/dist/plain/concepts.d.ts

@@ -1,8 +1,26 @@
 import { type AnyNode, type Section } from "./markdown.ts";
 import { type MarshalledPlainSource, type SpecificationItem } from "./spec.ts";
 /** 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.
+ * turri's, not the reference parser's - it has only the names.
+ */
+export declare const DEFAULT_CONCEPT_DEFINITIONS: Readonly<Record<string, string>>;
 /** Reserved concept names that must not be redefined in the definitions section. */
 export declare const DEFAULT_CONCEPTS: Set<string>;
+/** Every concept written in a piece of text - `:User:` - with where it is, as the parser reads concepts in a spec. */
+export declare function findConcepts(text: string): Array<{
+    concept: string;
+    start: number;
+    end: number;
+}>;
+/** The concept being typed at the end of a piece of text - `:Us` - with where it starts, or undefined when there is none. */
+export declare function conceptBeingTyped(text: string): {
+    typed: string;
+    start: number;
+} | undefined;
+/** A definition's text after the concepts it defines: `is a person who signs up` of `- :User: is a person who signs up`. */
+export declare function definitionText(text: string): string;
 export declare function extractConceptsFromDefinition(text: string): [string[], string[]];
 export declare function extractConceptsFromSpecText(text: string): string[];
 export declare function collectConcepts(plainSource: MarshalledPlainSource): [string[], string[]];

package/dist/plain/concepts.js

@@ -2,23 +2,50 @@ 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";
 /** 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.
+ * turri's, not the reference parser's - it has only the names.
+ */
+export const DEFAULT_CONCEPT_DEFINITIONS = {
+    ":ConformanceTests:": "the tests, written apart from the code, that check it conforms to the functional specs",
+    ":UnitTests:": "the unit tests written with the code of each functional spec",
+    ":AcceptanceTest:": "a test that checks one functional spec does what its acceptance tests say",
+    ":AcceptanceTests:": "the tests that check a functional spec does what its acceptance tests say",
+    ":Implementation:": "the software that implements the module's functional specs",
+    ":plainDefinitions:": "the content of the module's ***definitions*** section",
+    ":plainImplementationReqs:": "the content of the module's ***implementation reqs*** section",
+    ":plainFunctionality:": "the content of the module's ***functional specs*** section",
+    ":plainTestReqs:": "the content of the module's ***test reqs*** section",
+    ":plainImplementationCode:": "the code generated from the module",
+};
 /** Reserved concept names that must not be redefined in the definitions section. */
-export const DEFAULT_CONCEPTS = new Set([
-    ":ConformanceTests:",
-    ":UnitTests:",
-    ":AcceptanceTest:",
-    ":AcceptanceTests:",
-    ":Implementation:",
-    ":plainDefinitions:",
-    ":plainImplementationReqs:",
-    ":plainFunctionality:",
-    ":plainTestReqs:",
-    ":plainImplementationCode:",
-]);
+export const DEFAULT_CONCEPTS = new Set(Object.keys(DEFAULT_CONCEPT_DEFINITIONS));
+/** What a concept's name is made of, between its two colons. */
+const CONCEPT_CHARACTERS = "+\\-.0-9A-Z_a-z";
 const DEFINITION_PATTERN = /-\s(:[^:]+:)(?:,\s*:[^:]+:)*/;
 const CONCEPT_CANDIDATE_PATTERN = /:[^:]+:/g;
-const VALID_CONCEPT_PATTERN = /^:[+\-.0-9A-Z_a-z]+:/;
-const SPEC_CONCEPT_PATTERN = /:[+\-.0-9A-Z_a-z]+:/g;
+const VALID_CONCEPT_PATTERN = new RegExp(`^:[${CONCEPT_CHARACTERS}]+:`);
+const SPEC_CONCEPT_PATTERN = new RegExp(`:[${CONCEPT_CHARACTERS}]+:`, "g");
+const TYPED_CONCEPT_PATTERN = new RegExp(`:[${CONCEPT_CHARACTERS}]*$`);
+/** Every concept written in a piece of text - `:User:` - with where it is, as the parser reads concepts in a spec. */
+export function findConcepts(text) {
+    return [...text.matchAll(SPEC_CONCEPT_PATTERN)].map((match) => ({ concept: match[0], start: match.index, end: match.index + match[0].length }));
+}
+/** The concept being typed at the end of a piece of text - `:Us` - with where it starts, or undefined when there is none. */
+export function conceptBeingTyped(text) {
+    const match = TYPED_CONCEPT_PATTERN.exec(text);
+    if (match === null)
+        return undefined;
+    // A colon that closes a concept is not one that opens the next.
+    if (findConcepts(text).some(({ end }) => end - 1 === match.index))
+        return undefined;
+    return { typed: match[0], start: match.index };
+}
+/** A definition's text after the concepts it defines: `is a person who signs up` of `- :User: is a person who signs up`. */
+export function definitionText(text) {
+    const match = DEFINITION_PATTERN.exec(text);
+    return (match === null ? text : text.slice(match.index + match[0].length)).trim();
+}
 export function extractConceptsFromDefinition(text) {
     const match = DEFINITION_PATTERN.exec(text);
     if (!match) {

package/dist/plain/files.d.ts

@@ -1,5 +1,7 @@
 /** Ports of the Python reference implementation's file helpers this parser needs. */
 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;
 /** First contiguous base64 blob at or above the threshold, or null. */
 export declare function findLargeBase64Blob(text: string): string | null;
 /**

package/dist/plain/files.js

@@ -3,16 +3,20 @@ import { join } from "node:path";
 import { createEnvironment } from "./liquid.js";
 /** Ports of the Python reference implementation's file helpers this parser needs. */
 export function openFrom(dirs, fileName) {
+    const path = findIn(dirs, fileName);
+    return path === null ? null : readFileSync(path, "utf8");
+}
+/** The file `openFrom` reads: the first of the folders that has it. */
+export function findIn(dirs, fileName) {
     for (const dir of dirs) {
         const fullPath = join(dir, fileName);
         try {
-            if (!statSync(fullPath).isFile())
-                continue;
+            if (statSync(fullPath).isFile())
+                return fullPath;
         }
         catch {
             continue;
         }
-        return readFileSync(fullPath, "utf8");
     }
     return null;
 }

package/dist/plain/graph.d.ts

@@ -0,0 +1,68 @@
+import { DEFINITIONS, FUNCTIONAL_REQUIREMENTS, NON_FUNCTIONAL_REQUIREMENTS, TEST_REQUIREMENTS } from "./spec.ts";
+/**
+ * A project's ***plain as a graph, to go from one place in it to another: its modules, each item of their sections,
+ * and the concepts - an item linked to its module, to the concepts it names and to where each is defined, a module to
+ * what it imports and requires and to what imports and requires it.
+ */
+export interface PlainGraph {
+    modules: PlainModuleNode[];
+    items: PlainItemNode[];
+    concepts: PlainConceptNode[];
+}
+/** A module one .plain file names, and the file it is - null when it is not found. */
+export interface PlainLink {
+    name: string;
+    file: string | null;
+}
+/** A .plain file: what it imports and requires, what imports and requires it, its items, and why it does not parse. */
+export interface PlainModuleNode {
+    file: string;
+    module: string;
+    /** Resolved as the parser reads an import: a standard library module from turri's `stdlib/`. */
+    imports: PlainLink[];
+    /** Resolved as the requires chain finds a required module. */
+    requires: PlainLink[];
+    importedBy: PlainLink[];
+    requiredBy: PlainLink[];
+    /** Its own items, in the order they are written: their ids. */
+    items: string[];
+    /** The parser's message, when the file does not parse. Its links are then what its front matter says, its items what of its own text reads. */
+    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. */
+export interface PlainItemNode {
+    /** `<file>:<line>`. */
+    id: string;
+    file: string;
+    module: string;
+    section: PlainSection;
+    /** The line it starts on, from 1. */
+    line: number;
+    text: string;
+    /** A functional spec's functionality id: `1`, `2`, ... */
+    frid?: string;
+    /** 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. */
+    uses: Array<{
+        concept: string;
+        definition: string | null;
+    }>;
+}
+/** A concept as defined in one place - or ***plain's own - and every item that names it there. */
+export interface PlainConceptNode {
+    concept: string;
+    /** The item that defines it; null for ***plain's own. */
+    definition: string | null;
+    module: string | null;
+    /** The definition's text after its concepts. */
+    text: string;
+    usedBy: string[];
+}
+/**
+ * A project's ***plain as a graph: every .plain file in its folder and its `template/` folder, and every module they
+ * import or require, wherever the parser finds it, the standard library's too. Never throws: a file that does not
+ * parse is given with what its front matter says, what of its own text reads, and the error.
+ */
+export declare function plainGraph(projectDir: string): PlainGraph;

package/dist/plain/graph.js

@@ -0,0 +1,136 @@
+import { readdirSync, readFileSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import { resolveTemplateDirs } from "../regenerate/paths.js";
+import { locateModule } from "../regenerate/requires.js";
+import { DEFAULT_CONCEPT_DEFINITIONS, DEFAULT_CONCEPTS, definitionText, extractConceptsFromDefinition, findConcepts } from "./concepts.js";
+import { lineNumber, renderToMarkdown } from "./markdown.js";
+import { attempt, namesIn, readModule } from "./module-concepts.js";
+import { IMPORT_DIRECTIVE, modulePlainFile, parsePlainFile, PLAIN_SOURCE_FILE_EXTENSION, plainFileParser, readPlainSourceMetadata, REQUIRES_DIRECTIVE, withParseCache, } from "./parser.js";
+import { DEFINITIONS, FUNCTIONAL_REQUIREMENTS, NON_FUNCTIONAL_REQUIREMENTS, TEST_REQUIREMENTS } from "./spec.js";
+import { isStdlibModule } from "./stdlib.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
+ * import or require, wherever the parser finds it, the standard library's too. Never throws: a file that does not
+ * parse is given with what its front matter says, what of its own text reads, and the error.
+ */
+export function plainGraph(projectDir) {
+    const root = resolve(projectDir);
+    // The folders a .plain file of the project is read with: its own, its template/ folder, PLAIN_TEMPLATE_DIRS.
+    const dirs = resolveTemplateDirs(join(root, `project${PLAIN_SOURCE_FILE_EXTENSION}`));
+    const modules = new Map();
+    const queue = [];
+    const visit = (file, module) => {
+        if (modules.has(file))
+            return;
+        const node = { file, module, imports: [], requires: [], importedBy: [], requiredBy: [], items: [] };
+        modules.set(file, node);
+        queue.push(node);
+    };
+    for (const dir of [root, join(root, "template")]) {
+        const names = attempt(() => readdirSync(dir).filter((name) => name.endsWith(PLAIN_SOURCE_FILE_EXTENSION)).sort()) ?? [];
+        for (const name of names)
+            visit(join(dir, name), basename(name, PLAIN_SOURCE_FILE_EXTENSION));
+    }
+    for (let node = queue.shift(); node !== undefined; node = queue.shift()) {
+        let metadata = {};
+        try {
+            metadata = readPlainSourceMetadata(readFileSync(node.file, "utf8")).metadata;
+        }
+        catch (error) {
+            node.error = messageOf(error);
+        }
+        node.imports = namesIn(metadata[IMPORT_DIRECTIVE]).map((name) => ({ name, file: modulePlainFile(name, dirs) }));
+        node.requires = namesIn(metadata[REQUIRES_DIRECTIVE]).map((name) => ({ name, file: attempt(() => locateModule(name, dirs)) ?? null }));
+        for (const link of [...node.imports, ...node.requires])
+            if (link.file !== null)
+                visit(link.file, link.name);
+    }
+    for (const node of modules.values()) {
+        for (const link of node.imports)
+            if (link.file !== null)
+                modules.get(link.file).importedBy.push({ name: node.module, file: node.file });
+        for (const link of node.requires)
+            if (link.file !== null)
+                modules.get(link.file).requiredBy.push({ name: node.module, file: node.file });
+    }
+    return withParseCache(() => {
+        const items = [];
+        const concepts = new Map();
+        for (const [concept, text] of Object.entries(DEFAULT_CONCEPT_DEFINITIONS))
+            concepts.set(`${concept}\0`, { concept, definition: null, module: null, text, usedBy: [] });
+        const lines = new Map();
+        const idOf = (node, file) => `${file}:${lineOf(node, file, lines)}`;
+        const fileOf = (module, node) => (module === node.module ? node.file : modulePlainFile(module, dirs));
+        for (const node of modules.values()) {
+            if (node.error === undefined)
+                node.error = parseError(node, dirs);
+            const read = readModule(node.module, node.file, dirs);
+            // Where each concept it can name is defined, the first definition winning, as the parser's checks find one.
+            const visible = new Map();
+            for (const { node: definition, module } of read.definitions) {
+                const file = fileOf(module, node);
+                if (file === null)
+                    continue;
+                const id = idOf(definition, file);
+                const text = renderToMarkdown(definition);
+                for (const concept of extractConceptsFromDefinition(text)[0]) {
+                    if (!visible.has(concept))
+                        visible.set(concept, id);
+                    if (!concepts.has(`${concept}\0${id}`))
+                        concepts.set(`${concept}\0${id}`, { concept, definition: id, module, text: definitionText(text), usedBy: [] });
+                }
+            }
+            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();
+                    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 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: lineOf(item, node.file, lines), text, ...(section === FUNCTIONAL_REQUIREMENTS ? { frid: String(index + 1) } : {}), defines, uses });
+                    node.items.push(id);
+                });
+            }
+        }
+        return { modules: [...modules.values()], items, concepts: [...concepts.values()] };
+    });
+}
+/** 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. */
+function parseError(node, dirs) {
+    const imported = node.importedBy.length > 0 || isStdlibModule(node.module) || basename(dirname(node.file)) === "template";
+    try {
+        if (imported)
+            parsePlainFile(node.module, {}, dirs, [], []);
+        else
+            plainFileParser(`${node.module}${PLAIN_SOURCE_FILE_EXTENSION}`, dirs, { allowNoFunctionalities: true });
+        return undefined;
+    }
+    catch (error) {
+        return messageOf(error);
+    }
+}
+/**
+ * The line an item starts on in its file. The parser's is a line of the text after Liquid has run, which is the file's
+ * own unless an include or a tag changed the lines above it: then the first line of the file that has the item's
+ * first line is taken.
+ */
+function lineOf(node, file, cache) {
+    let lines = cache.get(file);
+    if (lines === undefined) {
+        lines = (attempt(() => readFileSync(file, "utf8")) ?? "").split(/\r?\n/);
+        cache.set(file, lines);
+    }
+    const at = lineNumber(node);
+    const first = renderToMarkdown(node).trim().split("\n")[0].replace(/^[-*+]\s+/, "").trim();
+    if (first === "" || lines[at - 1]?.includes(first))
+        return at;
+    const found = lines.findIndex((line) => line.includes(first));
+    return found === -1 ? at : found + 1;
+}
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/plain/module-concepts.d.ts

@@ -0,0 +1,32 @@
+import { type AnyNode } from "./markdown.ts";
+import { type PlainFileParseResult } from "./parser.ts";
+/** A concept a module can name, what it is, and the module that defines it - null for ***plain's own. */
+export interface ModuleConcept {
+    concept: string;
+    /** The definition's text after its concepts: `is a person who signs up`. */
+    definition: string;
+    module: string | null;
+}
+/** A module as the parser reads it, for what it names: its own parse, and every definition it can name. */
+export interface ReadModule {
+    /** Its parse, its imports merged in - or, when that fails, its own text read without them; undefined when neither reads. */
+    parsed?: PlainFileParseResult;
+    /** Its own definitions, those its imports bring and those its required modules export, each with the module it is written in. */
+    definitions: Array<{
+        node: AnyNode;
+        module: string;
+    }>;
+}
+/**
+ * A module read for what it can name, as the parser builds its definitions: its own, its imports' (`import`), and its
+ * required modules' `exported_concepts` with the definitions they use. Never throws: a module that does not parse
+ * gives its own definitions read without its imports, and what of those it names is there.
+ */
+export declare function readModule(moduleName: string, plainFile: string, templateDirs: string[]): ReadModule;
+/**
+ * Every concept a module can name: its own definitions, those its imports bring, those its required modules export,
+ * and ***plain's own - read as the parser reads them. A module that does not parse gives what can be read of it.
+ */
+export declare function conceptsOf(plainFile: string, templateDirs?: string[]): ModuleConcept[];
+export declare function attempt<T>(run: () => T): T | undefined;
+export declare function namesIn(value: unknown): string[];