@turri-dev/cli 0.1.14 → 0.1.15-next.5bcaf8b

package/dist/plain/graph.d.ts

@@ -49,6 +49,16 @@ export interface PlainItemNode {
         concept: string;
         definition: string | null;
     }>;
+    /**
+     * The linked resources it names, a functional spec's acceptance tests' too - `[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<{
+        text: string;
+        target: string;
+        file: string | null;
+        line: number;
+    }>;
 }
 /** A concept as defined in one place - or ***plain's own - and every item that names it there. */
 export interface PlainConceptNode {

package/dist/plain/graph.js

@@ -2,10 +2,11 @@ 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 { resourceFile } from "../regenerate/resources.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 { IMPORT_DIRECTIVE, linksIn, 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];
@@ -88,10 +89,18 @@ export function plainGraph(projectDir) {
                     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);
+                    // 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 }) => ({
+                        text,
+                        target,
+                        file: resourceFile(target, dirs),
+                        line: lineOf(link, node.file, lines, { at: lineNumber(link) + line - lineNumber(item), 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: lineOf(item, node.file, lines), text, ...(section === FUNCTIONAL_REQUIREMENTS ? { frid: String(index + 1) } : {}), defines, uses });
+                    items.push({ id, file: node.file, module: node.module, section, line, text, ...(section === FUNCTIONAL_REQUIREMENTS ? { frid: String(index + 1) } : {}), defines, uses, resources });
                     node.items.push(id);
                 });
             }
@@ -116,19 +125,20 @@ function parseError(node, dirs) {
 /**
  * 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.
+ * first line is taken. A link is looked for so too - by its `](target)`, from its item's line on.
  */
-function lineOf(node, file, cache) {
+function lineOf(node, file, cache, look = {}) {
     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))
+    const at = look.at ?? lineNumber(node);
+    const needle = look.needle ?? renderToMarkdown(node).trim().split("\n")[0].replace(/^[-*+]\s+/, "").trim();
+    if (needle === "" || lines[at - 1]?.includes(needle))
         return at;
-    const found = lines.findIndex((line) => line.includes(first));
+    const from = Math.max(0, (look.from ?? 1) - 1);
+    const found = lines.findIndex((line, index) => index >= from && line.includes(needle));
     return found === -1 ? at : found + 1;
 }
 function messageOf(error) {

package/dist/plain/parser.d.ts

@@ -21,6 +21,12 @@ export interface PlainFileParseResult {
 }
 export declare function getFilenameFromModuleName(moduleName: string): string;
 export declare function getModuleNameFromFilename(filename: string): string;
+/** The links written in an item - what each says and where it points - as the parser reads them, checked or not. */
+export declare function linksIn(section: AnyNode): Array<{
+    text: string;
+    target: string;
+    node: AnyNode;
+}>;
 export declare function checkSectionForLinkedResources(section: AnyNode, dirs?: string[]): void;
 export declare function checkForLinkedResources(plainSource: ParsedPlainSource, dirs?: string[]): void;
 export declare function processSectionCodeVariables(section: SpecificationItem, codeVariables: Record<string, Record<string, string>>): void;

package/dist/plain/parser.js

@@ -88,13 +88,15 @@ function parseNoting(run) {
 function stillHolds(kept, fingerprint) {
     return kept !== undefined && fingerprint !== undefined && kept.fingerprint === fingerprint && linkedStamp(kept.linked) === kept.linkedStamp;
 }
+/** The links written in an item - what each says and where it points - as the parser reads them, checked or not. */
+export function linksIn(section) {
+    return [...traverse(section, "link")].map((link) => ({ text: String(link.children?.[0]?.value ?? ""), target: String(link.url ?? ""), node: link }));
+}
 export function checkSectionForLinkedResources(section, dirs = []) {
     const linkedResources = [];
-    for (const link of traverse(section, "link")) {
-        const target = String(link.url ?? "");
+    for (const { text, target, node: link } of linksIn(section)) {
         const children = link.children ?? [];
         if (hasScheme(target) || isAbsolute(target)) {
-            const text = children[0]?.value ?? "";
             throw new PlainSyntaxError(`Plain syntax error: Only relative links are allowed (text: ${text}, target: ${target}).`);
         }
         const file = linkedFile(target, dirs);
@@ -112,7 +114,7 @@ export function checkSectionForLinkedResources(section, dirs = []) {
                 "Referencing .plain files through Linked Resources is not supported. " +
                 "Please use the import section to include definitions or implementation/test requirements from another module.");
         }
-        linkedResources.push({ text: String(children[0].value ?? ""), target });
+        linkedResources.push({ text, target });
     }
     if (linkedResources.length > 0)
         section.linked_resources = linkedResources;

package/dist/regenerate/resources.d.ts

@@ -32,6 +32,8 @@ export declare class LinkedImageError extends Error {
 export declare function loadLinkedResources(tree: MarshalledPlainSource, 
 /** Up to and including this functionality. Null: the whole module. */
 frid: string | null, templateDirs: string[]): LoadedResource[];
+/** The file a linked resource is read from: the first template folder that has it, else the current folder - or null. */
+export declare function resourceFile(target: string, templateDirs: string[]): string | null;
 /**
  * A linked resource that is code - a source file, or a build manifest: the specification points at code that lives
  * elsewhere, a host's module the code plugs into, for the code to build on as it says. It is never copied into the

package/dist/regenerate/resources.js

@@ -42,8 +42,8 @@ frid, templateDirs) {
             loaded.push({ text: resource.text, target: resource.target, content: `[an image: attached to your first message, image ${number}]`, image });
             continue;
         }
-        const source = [...templateDirs.map((dir) => join(dir, resource.target)), resource.target].find((path) => isFileAt(path));
-        if (source === undefined)
+        const source = resourceFile(resource.target, templateDirs);
+        if (source === null)
             continue;
         let content = readFileSync(source, "utf8");
         const whole = content.length;
@@ -52,10 +52,15 @@ frid, templateDirs) {
                 ? `${content.slice(0, MAX_RESOURCE_CHARS)}\n... [cut here: ${whole} characters whole - code that lives outside your codebase: build on it as the specification says, never copy it]`
                 : `${content.slice(0, MAX_RESOURCE_CHARS)}\n... [cut here: ${whole} characters whole - copy_resource puts the whole file at its code-copy path, to read it there]`;
         }
-        loaded.push({ text: resource.text, target: resource.target, content, source: resolve(source), ...(whole > MAX_RESOURCE_CHARS ? { cutFrom: whole } : {}) });
+        loaded.push({ text: resource.text, target: resource.target, content, source, ...(whole > MAX_RESOURCE_CHARS ? { cutFrom: whole } : {}) });
     }
     return loaded;
 }
+/** The file a linked resource is read from: the first template folder that has it, else the current folder - or null. */
+export function resourceFile(target, templateDirs) {
+    const found = [...templateDirs.map((dir) => join(dir, target)), target].find((path) => isFileAt(path));
+    return found === undefined ? null : resolve(found);
+}
 function isFileAt(path) {
     try {
         return statSync(path).isFile();
@@ -145,16 +150,9 @@ export function resourceImages(resources) {
 }
 /** A linked image's bytes, found as a text resource is: the template folders first, then the current directory. */
 function loadImage(templateDirs, target, mimeType) {
-    for (const path of [...templateDirs.map((dir) => join(dir, target)), target]) {
-        let size;
-        try {
-            if (!statSync(path).isFile())
-                continue;
-            size = statSync(path).size;
-        }
-        catch {
-            continue;
-        }
+    const path = resourceFile(target, templateDirs);
+    if (path !== null) {
+        const size = statSync(path).size;
         if (size > MAX_IMAGE_BYTES) {
             throw new LinkedImageError(`The linked image ${target} is ${(size / 1024 / 1024).toFixed(1)} MB - a model takes images up to ${MAX_IMAGE_BYTES / 1024 / 1024} MB. Make it smaller, or link a smaller one.`);
         }

package/docs/hosting.md

@@ -122,12 +122,13 @@ app.requires;      // [{ name: "base", file: "/…/base.plain" }] - and imports,
 app.items;         // ["/…/app.plain:11", "/…/app.plain:15"] - its own items, in order
 items.find((item) => item.id === app.items[1]);
 // { id, file, module: "app", section: "functional specs", line: 15, frid: "1", text: "- :User: can fill :Cart:.",
-//   defines: [], uses: [{ concept: ":User:", definition: "/…/base.plain:8" }, { concept: ":Cart:", definition: "/…/app.plain:11" }] }
+//   defines: [], uses: [{ concept: ":User:", definition: "/…/base.plain:8" }, { concept: ":Cart:", definition: "/…/app.plain:11" }],
+//   resources: [{ text: "the schema", target: "schema.json", file: "/…/schema.json", line: 15 }] }
 concepts.find((concept) => concept.definition === "/…/base.plain:8");
 // { concept: ":User:", definition: "/…/base.plain:8", module: "base", text: "is a person who signs up.", usedBy: [...] }
 ```
 
-- **The graph.** `plainGraph` reads every .plain file in the project's folder and its `template/` folder, and every module they import or require, wherever the parser finds it - the standard library's templates too. A **module** is a file: its imports, resolved as the parser reads an import (a `stdlib/` module from turri's own folder), its required modules, resolved as the requires chain finds them - `file: null` when one is not found - and the reverse of both, `importedBy` and `requiredBy`, so a host goes up and down the requires chain without inverting anything. An **item** is one item of a section - a definition, an implementation req, a test req, a functional spec with its acceptance tests - with its file, the line it starts on, its text, a functional spec's `frid`, the concepts a definition defines, and each concept it names with the item that defines it: its own module's definitions, its imports', and those its required modules export, as the parser sees them from that module. `definition` is null for \*\*\*plain's own concepts, and for one defined nowhere the module can see. A **concept** is one definition of it - or \*\*\*plain's own, `definition: null` - with every item that names it there. An item's id is `<file>:<line>`: the file to open and the line to go to.
+- **The graph.** `plainGraph` reads every .plain file in the project's folder and its `template/` folder, and every module they import or require, wherever the parser finds it - the standard library's templates too. A **module** is a file: its imports, resolved as the parser reads an import (a `stdlib/` module from turri's own folder), its required modules, resolved as the requires chain finds them - `file: null` when one is not found - and the reverse of both, `importedBy` and `requiredBy`, so a host goes up and down the requires chain without inverting anything. An **item** is one item of a section - a definition, an implementation req, a test req, a functional spec with its acceptance tests - with its file, the line it starts on, its text, a functional spec's `frid`, the concepts a definition defines, and each concept it names with the item that defines it: its own module's definitions, its imports', and those its required modules export, as the parser sees them from that module. `definition` is null for \*\*\*plain's own concepts, and for one defined nowhere the module can see. Its `resources` are the linked resources it names - `[text](target)`, a functional spec's acceptance tests' too, as the parser reads them - each with `file`, the file regenerating reads it from (the template folders first, then the current folder), null when it is not there, and `line`, the line the link is on. `resources` is on every item, `[]` when it names none: a turri that gives no resources has no field. A **concept** is one definition of it - or \*\*\*plain's own, `definition: null` - with every item that names it there. An item's id is `<file>:<line>`: the file to open and the line to go to.
 - **What does not parse.** Nothing throws. A file that does not parse has `error`, the parser's message; its links are what its front matter says, and its items what of its own text reads without its imports. A file whose items Liquid moves keeps the lines of its own text.
 - **Concepts.** `conceptsOf(plainFile)` is what one module can name - `{ concept, definition, module }`, `definition` the text after its concepts, `module` null for \*\*\*plain's own - for suggestions as the person types. `findConcepts(text)` is every concept written in a piece of text, `{ concept, start, end }`, and `conceptBeingTyped(text)` the one at its end still open - `{ typed: ":Us", start }`, or undefined - both with the parser's own pattern.
 - **The standard library.** `stdlibTemplates()` is every template in turri's `stdlib/`, sorted: `name` - what a module imports it as - `file`, `kind` (`backend`, `frontend`, `cli`, `library` or `lang`), `description`, `text`, `imports` as the parser reads its front matter, a stack's `conformance` template when it has one, and a conformance template's stack as `tests`. `isStack(template)` says whether it is a stack to import; `STDLIB_KINDS` is the kinds in order, each with its title.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@turri-dev/cli",
-  "version": "0.1.14",
+  "version": "0.1.15-next.5bcaf8b",
   "license": "MIT",
   "type": "module",
   "repository": {