@rse/specbook 1.5.2 → 1.6.1

package/dst/specbook-ignore.js

@@ -155,8 +155,8 @@ export const excluder = (dir) => {
         return rules;
     };
     return (file) => {
-        const rel = path.relative(root, path.resolve(file)).replace(/\\/g, "/");
-        if (rel === "" || rel.startsWith("../"))
+        const rel = path.relative(root, path.resolve(file)).split(path.sep).join("/");
+        if (rel === "" || rel === ".." || rel.startsWith("../") || path.isAbsolute(rel))
             return false;
         const segments = rel.split("/");
         /*  walk the directory chain from the working tree root down to

package/dst/specbook-link.d.ts

@@ -1,6 +1,8 @@
 import type { Spec, SpecObject } from "./specbook-format-spec.js";
 export declare const referenceRegex: RegExp;
+export declare const outsideCode: (text: string, apply: (part: string) => string) => string;
 export declare const plainText: (text: string) => string;
+export declare const referenceText: (text: string) => string;
 interface LinkNode {
     object: SpecObject;
     parent?: LinkNode;
@@ -17,6 +19,8 @@ export interface LinkTarget {
 export declare const buildLinkIndex: (specification: Spec) => LinkIndex;
 export declare const resolveSet: (index: LinkIndex, reference: string) => SpecObject[];
 export declare const resolveUnique: (index: LinkIndex, reference: string, from?: SpecObject) => LinkTarget;
+export declare const referenceTo: (index: LinkIndex, target: SpecObject, from: SpecObject) => string;
+export declare const referenceTargets: (index: LinkIndex, object: SpecObject) => SpecObject[];
 export declare const anchorPaths: (index: LinkIndex) => Map<SpecObject, string>;
 export declare const expandReferences: (text: string, replace: (reference: string) => string) => string;
 export {};

package/dst/specbook-link.js

@@ -8,21 +8,38 @@ export const referenceRegex = /\[\[([^[\]]+)\]\]/g;
 /*  the fenced code blocks of a Markdown text (from the opening fence line
     up to the closing fence line, or to the end of an unclosed one)  */
 const fenceRegex = /^[ \t]*(`{3,}|~{3,})[^\n]*(?:\n[\s\S]*?(?:\n[ \t]*\1[`~]*[ \t]*(?=\n|$)|(?![\s\S]))|(?![\s\S]))/gm;
+/*  the inline code spans of a Markdown text (a backtick run up to the
+    next backtick run of the same length)  */
+const spanRegex = /(?<!`)(`+)(?!`)[\s\S]*?(?<!`)\1(?!`)/g;
 /*  apply a transformation to the parts of a text outside of its fenced
-    code blocks, which stay verbatim, as code carries no references  */
-const outsideFences = (text, apply) => {
+    code blocks and inline code spans, which stay verbatim, as code
+    carries no references  */
+export const outsideCode = (text, apply) => {
+    const outsideSpans = (part) => {
+        let result = "";
+        let last = 0;
+        for (const m of part.matchAll(spanRegex)) {
+            result += apply(part.slice(last, m.index)) + m[0];
+            last = m.index + m[0].length;
+        }
+        return result + apply(part.slice(last));
+    };
     let result = "";
     let last = 0;
     for (const m of text.matchAll(fenceRegex)) {
-        result += apply(text.slice(last, m.index)) + m[0];
+        result += outsideSpans(text.slice(last, m.index)) + m[0];
         last = m.index + m[0].length;
     }
-    return result + apply(text.slice(last));
+    return result + outsideSpans(text.slice(last));
 };
 /*  strip the fenced code blocks of a description and the inline code
     markup of a name, property value, or description (preserved in the
     AST for rendering) for matching and labeling  */
 export const plainText = (text) => text.replace(fenceRegex, "").replace(/`/g, "");
+/*  strip the fenced code blocks and the inline code spans (with their
+    contents) of a text for scanning its references, as code carries no
+    references  */
+export const referenceText = (text) => text.replace(fenceRegex, "").replace(spanRegex, "");
 /*  provide the lookup structures of an index, built once on first use  */
 const lookups = new WeakMap();
 const lookup = (index) => {
@@ -186,6 +203,44 @@ export const resolveUnique = (index, reference, from) => {
         matches = nearest(index, matches, from);
     return { target: matches.length === 1 ? matches[0] : undefined, ambiguous: matches.length > 1 };
 };
+/*  the shortest reference uniquely resolving onto a target from a
+    referencing object: the kind-qualified name of the target, prefixed
+    by as many of its ancestors (their parenthesized id, else their
+    kind-qualified name) as the resolution needs, and as a last resort
+    the kind-qualified id of the target (unique among its siblings),
+    should its name be shared by a sibling of its kind  */
+export const referenceTo = (index, target, from) => {
+    const chain = chainOf(index, target);
+    const quote = (text) => /[.:]/.test(text) ? `"${text}"` : text;
+    const parents = chain.slice(0, -1).map((object) => object.paren !== undefined ? object.paren : `${object.kind}:${quote(object.name)}`);
+    const lasts = [`${target.kind}:${quote(target.name)}`, `${target.kind}:${quote(target.id)}`];
+    for (const last of lasts) {
+        const segments = [...parents, last];
+        for (let i = segments.length - 1; i >= 0; i--) {
+            const reference = segments.slice(i).join(".");
+            if (resolveUnique(index, reference, from).target === target)
+                return reference;
+        }
+    }
+    return [...parents, lasts[0]].join(".");
+};
+/*  resolve the references of the own texts of an object (its name,
+    property values, description, rationale, and elaboration) into
+    their distinct targets, in order of occurrence, leniently skipping
+    the unresolvable ones, as the reference pass reports those  */
+export const referenceTargets = (index, object) => {
+    const texts = [object.name, ...object.properties.map((property) => property.value)];
+    if (object.description !== undefined)
+        texts.push(object.description.description, object.description.rationale ?? "", object.description.elaboration ?? "");
+    const targets = new Set();
+    for (const text of texts)
+        for (const m of referenceText(text).matchAll(referenceRegex)) {
+            const target = resolveUnique(index, m[1].trim(), object).target;
+            if (target !== undefined && target !== object)
+                targets.add(target);
+        }
+    return Array.from(targets);
+};
 /*  derive the fully-qualified anchor path of every object: the
     "<kind>-<id>" segments (whitespace in kinds dashed) of the ancestor
     chain joined with "." (the index lists parents before children)  */
@@ -200,5 +255,5 @@ export const anchorPaths = (index) => {
     return paths;
 };
 /*  expand all references of a text via a per-reference replacer
-    (except inside its fenced code blocks)  */
-export const expandReferences = (text, replace) => outsideFences(text, (part) => part.replace(referenceRegex, (_, reference) => replace(reference.trim())));
+    (except inside its fenced code blocks and inline code spans)  */
+export const expandReferences = (text, replace) => outsideCode(text, (part) => part.replace(referenceRegex, (_, reference) => replace(reference.trim())));

package/dst/specbook-mcp.js

@@ -8,7 +8,7 @@ import * as path from "node:path";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
-import { SpecBook, renderDiagnostic, renderVerbose, formats, parseOutputSpec, describeFormats, describeParts, compressLevels, projectFile, omitAspects, version } from "./specbook-api.js";
+import { SpecBook, renderDiagnostic, renderVerbose, formats, parseOutputSpec, describeFormats, describeParts, compressLevels, projectFile, omitAspects, fetchModes, version, renderNodes, queryFormats, parseQueryOutput } from "./specbook-api.js";
 /*  render an error with its cause chain into a tool error result  */
 const errorResult = (err) => {
     let msg = err instanceof Error ? err.message : String(err);
@@ -24,17 +24,26 @@ export const serveMcp = async (verbose) => {
     const server = new McpServer({ name: "specbook", version });
     const specbook = new SpecBook({ verbose });
     /*  the input schema fields shared by the specification processing tools  */
-    const config = z.array(z.string()).optional().describe("YAML schema configuration files or glob " +
-        "patterns, merged in order (\"std\" for the bundled standard schema configuration; " +
+    const remote = "\"npm:<pkg>[@<range>][/<path>]\" or \"github:<user>/<repo>[/<path>][#<ref>]\"";
+    const config = z.array(z.string()).optional().describe("YAML schema configuration files, glob " +
+        `patterns, or remote references (${remote}, or an "http[s]://..." URL), merged in order ` +
+        "(\"std\" for the bundled standard schema configuration, \"meta\" for the bundled meta one, " +
+        "\"pm\" for the bundled project management one; " +
         "default: the SPECBOOK_CONFIG environment variable, else the \"config\" entry " +
         "of the project configuration file, else the bundled standard " +
         "schema configuration)");
     const basedir = z.string().optional().describe("base directory of the specification Markdown files " +
         "(default: the SPECBOOK_BASEDIR environment variable, else the \"basedir\" entry " +
         "of the project configuration file, else \".\")");
+    const fetch = z.enum(fetchModes).optional().describe("when to fetch the remote references through " +
+        "the network (\"never\": the download cache only, \"auto\": whenever the download cache lacks them " +
+        "or is no longer fresh, \"always\": ignoring the download cache; default: \"auto\")");
     const gitignore = z.boolean().optional().describe("skip the artifact files excluded by the Git " +
         "exclude rules (the \".gitignore\" files, \"info/exclude\", and the global excludes " +
         "file), treating such a file exactly like an absent one (default: false)");
+    const sample = z.boolean().optional().describe("scaffold a sample object per allowed object kind " +
+        "into the artifact files, with placeholder values satisfying the schema configuration " +
+        "(default: false)");
     /*  the working directory of the client, which this server does not
         necessarily share: it anchors the relative paths and starts the
         upward search for the project configuration file  */
@@ -46,10 +55,11 @@ export const serveMcp = async (verbose) => {
     server.registerTool("specbook_init", {
         title: "Initialize Specification",
         description: "Initialize the configured specification artifact files below the base directory " +
-            "with their frontmatter and artifact heading, skipping already existing files, and " +
+            "with their frontmatter and artifact heading (or, with \"sample\", with a sample object per " +
+            "allowed object kind), skipping already existing files, and " +
             `create the project configuration file "${projectFile}" in the working directory, ` +
             "persisting the effective schema configuration and base directory, unless one already applies.",
-        inputSchema: { config, basedir, cwd }
+        inputSchema: { config, basedir, fetch, sample, cwd }
     }, async (args) => {
         try {
             const result = await specbook.init(args);
@@ -65,9 +75,9 @@ export const serveMcp = async (verbose) => {
     });
     server.registerTool("specbook_lint", {
         title: "Lint Specification",
-        description: "Lint the specification Markdown files the YAML schema configuration references " +
-            "below the base directory against this configuration and return all diagnostics.",
-        inputSchema: { config, basedir, gitignore, cwd }
+        description: "Lint all specification Markdown files below the base directory against the " +
+            "YAML schema configuration and return all diagnostics.",
+        inputSchema: { config, basedir, fetch, gitignore, cwd }
     }, async (args) => {
         try {
             const result = await specbook.lint(args);
@@ -82,20 +92,25 @@ export const serveMcp = async (verbose) => {
     });
     server.registerTool("specbook_export", {
         title: "Export Specification",
-        description: "Export the specification Markdown files the YAML schema configuration references " +
-            "below the base directory as JSON, JSON5, " +
+        description: "Export all specification Markdown files below the base directory (or, with " +
+            "\"schema\", the effective YAML schema configuration " +
+            "itself, described as a SpecBook document through the bundled meta schema configuration) " +
+            "as JSON, JSON5, " +
             "YAML, TOON, HTML, PDF, or normalized Markdown. The result is written to the output file " +
             "if an output path is given, else it is returned directly (PDF as a base64-encoded resource). " +
             "The normalized Markdown embeds its images as \"data:\" URL definitions (so it is large), and " +
             "its remaining image references are re-based onto the directory of the " +
             "output file, while a directly returned result keeps them unchanged.",
-        inputSchema: { config, basedir, gitignore, cwd,
+        inputSchema: { config, basedir, fetch, gitignore, cwd,
             format: z.enum(formats).optional().describe("output format (default: inferred from the " +
                 "output file extension, else json)"),
             output: z.string().optional().describe("output file path (\"-\" or omitted returns the result directly)"),
             omit: z.array(z.string()).optional().describe("content aspects to omit from the HTML, " +
                 "the PDF, and (the diagrams) the AST output, instead of leaving them foldable: \"diagram\" " +
-                `(all diagrams) or "${omitAspects.join("\", \"")}" (default: none)`)
+                `(all diagrams) or "${omitAspects.join("\", \"")}" (default: none)`),
+            schema: z.boolean().optional().describe("export the effective YAML schema configuration " +
+                "itself as a SpecBook document instead of the specification (the base directory is not " +
+                "applicable then; default: false)")
         }
     }, async (args) => {
         try {
@@ -110,8 +125,8 @@ export const serveMcp = async (verbose) => {
             const rebase = spec.format === "md" && spec.output !== undefined && spec.output !== "-" ?
                 path.dirname(spec.output) : undefined;
             const [data] = await specbook.export({ config: args.config, basedir: args.basedir,
-                cwd: args.cwd, formats: [spec.format], rebase: [rebase], omit: args.omit,
-                gitignore: args.gitignore });
+                cwd: args.cwd, fetch: args.fetch, formats: [spec.format], rebase: [rebase],
+                omit: args.omit, gitignore: args.gitignore, schema: args.schema });
             if (spec.output !== undefined && spec.output !== "-") {
                 await fs.promises.writeFile(outputOf(args, spec.output), data);
                 return { content: [{ type: "text", text: `exported specification into "${spec.output}" (${data.length} bytes)` }] };
@@ -128,6 +143,47 @@ export const serveMcp = async (verbose) => {
             return errorResult(err);
         }
     });
+    server.registerTool("specbook_query", {
+        title: "Query Specification",
+        description: "Load all specification Markdown files below the base directory (or, with " +
+            "\"schema\", the effective YAML schema configuration itself, described as a SpecBook document " +
+            "through the bundled meta schema configuration), strictly validated, and query its Abstract " +
+            "Syntax Tree (AST) with an XPath-like ASTq selector (like \"// USE-CASE [ @STATUS == 'Done' ]\"). " +
+            "The root node is of type \"specification\", its children are of type \"artifact\" (attributes " +
+            "\"created\", \"modified\", and \"file\"), and the objects below are typed by their kind (attributes " +
+            "\"kind\", \"id\", \"anchor\", \"paren\", \"name\", \"primary\", \"description\", \"rationale\", " +
+            "\"elaboration\", and one per property key), where the query function \"refs()\" yields the objects " +
+            "the references of an object resolve to. The matched nodes are rendered as a JSON (or JSON5, " +
+            "YAML, or TOON) array (their subtrees included, the embedded file contents dropped), written to " +
+            "the output file if an output path is given, else returned directly.",
+        inputSchema: { config, basedir, fetch, gitignore, cwd,
+            schema: z.boolean().optional().describe("query the effective YAML schema configuration " +
+                "itself as a SpecBook document instead of the specification (the base directory is not " +
+                "applicable then; default: false)"),
+            selector: z.string().describe("the ASTq selector of the nodes to return"),
+            params: z.record(z.string(), z.string()).optional().describe("the values of the \"{name}\" " +
+                "parameters of the selector (default: none)"),
+            format: z.enum(queryFormats).optional().describe("output format (default: inferred from the " +
+                "output file like for the export, else json)"),
+            output: z.string().optional().describe("output file path (\"-\" or omitted returns the result directly)")
+        }
+    }, async (args) => {
+        try {
+            const { selector, params, format, output, ...options } = args;
+            const spec = parseQueryOutput(output ?? "-", format);
+            const document = await specbook.load(options);
+            const text = renderNodes(document.query(selector, params), spec.format);
+            if (spec.output !== "-") {
+                await fs.promises.writeFile(outputOf(args, spec.output), text);
+                return { content: [{ type: "text", text: `queried specification into "${spec.output}" ` +
+                                `(${Buffer.byteLength(text)} bytes)` }] };
+            }
+            return { content: [{ type: "text", text }] };
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
     server.registerTool("specbook_describe", {
         title: "Describe Specification Format",
         description: "Describe the SpecBook models and formats as a Markdown document, which embeds the " +
@@ -136,20 +192,24 @@ export const serveMcp = async (verbose) => {
             "points to the artifacts of that particular project. The description can be reduced to a " +
             "single part and emitted as the raw original file content instead of Markdown.",
         inputSchema: {
-            config: z.array(z.string()).optional().describe("YAML schema configuration files or glob " +
-                "patterns, merged in order (\"std\" for the bundled standard schema configuration; " +
+            config: z.array(z.string()).optional().describe("YAML schema configuration files, glob " +
+                `patterns, or remote references (${remote}, or an "http[s]://..." URL), merged in order ` +
+                "(\"std\" for the bundled standard schema configuration; " +
                 "default: the SPECBOOK_CONFIG environment variable, else the \"config\" entry " +
                 "of the project configuration file, else the bundled standard " +
                 "schema configuration, embedded)"),
             basedir: z.string().optional().describe("base directory of the specification Markdown files " +
                 "(default: the SPECBOOK_BASEDIR environment variable, else the \"basedir\" entry " +
                 "of the project configuration file)"),
+            fetch,
             embed: z.boolean().optional().describe("embed the given YAML schema configuration instead " +
-                "of just referencing it (default: false; the bundled standard one is always embedded)"),
+                "of just referencing it (default: false; the bundled standard one and a remote one are " +
+                "always embedded)"),
             compress: z.literal(compressLevels).optional().describe("compression level of the emitted " +
                 "YAML schema configuration (embedded or raw): 0 for verbatim, 1 for re-emitted with 2-space " +
-                "indentation and without comments, 2 for additionally without its \"refs\", \"diagram\", and " +
-                "\"format\" fields, or 3 for additionally without its \"desc\" fields (default: 2)"),
+                "indentation and without comments, 2 for additionally without its \"refs\", \"badge\", " +
+                "\"multiple\", \"diagram\", and \"format\" fields, or 3 for additionally without its " +
+                "\"desc\" fields (default: 2)"),
             format: z.enum(describeFormats).optional().describe("output format: \"md\" for Markdown or " +
                 "\"raw\" for the raw original file content of the part (default: \"md\")"),
             part: z.enum(describeParts).optional().describe("document part: \"all\" for the entire " +
@@ -173,5 +233,29 @@ export const serveMcp = async (verbose) => {
             return errorResult(err);
         }
     });
+    server.registerTool("specbook_search", {
+        title: "Search Schema Configurations",
+        description: "Search the bundled standard, meta, and project management schema configurations " +
+            "(references \"std\", \"meta\", and \"pm\"), the npm " +
+            "registry (the packages carrying the keyword \"specbook-schema\"), and GitHub (the repositories " +
+            "carrying the same topic) for the shareable schema configurations (reusable building blocks for " +
+            "the \"config\" option) matching a term, and return the hits as a JSON array of objects with the " +
+            "fields \"ref\" (the remote reference to use), \"name\", \"version\", \"description\", and " +
+            "\"source\" (\"builtin\", \"npm\", or \"github\").",
+        inputSchema: {
+            term: z.string().optional().describe("the words a matching schema configuration has to carry " +
+                "(default: none, matching all of them)"),
+            fetch,
+            cwd
+        }
+    }, async (args) => {
+        try {
+            const hits = await specbook.search(args);
+            return { content: [{ type: "text", text: JSON.stringify(hits, null, 4) }] };
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
     await server.connect(new StdioServerTransport());
 };

package/dst/specbook-parse-semantic.d.ts

@@ -2,6 +2,7 @@ import { type Spec, type SpecObject, type SpecProperty } from "./specbook-format
 import { type Schema, type SchemaObject } from "./specbook-format-schema.js";
 import { type ParseContext } from "./specbook-parse-common.js";
 export declare const resolveArtifact: (config: Schema, object: SpecObject) => SchemaObject | undefined;
+export declare const isRecurring: (schema: SchemaObject) => boolean;
 export declare const collectSchemas: (specification: Spec, config: Schema) => Map<SpecObject, SchemaObject>;
 export declare const collectParenProps: (schemas: Map<SpecObject, SchemaObject>) => Map<SpecObject, SpecProperty>;
 export declare const validate: (ctx: ParseContext, specification: Spec, config: Schema) => void;

package/dst/specbook-parse-semantic.js

@@ -3,7 +3,7 @@
 **  Copyright (c) 2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
 **  Licensed under Apache 2.0 <https://spdx.org/licenses/Apache-2.0>
 */
-import { referenceRegex, resolveUnique, resolveSet, chainOf, plainText, assignId } from "./specbook-link.js";
+import { referenceRegex, resolveUnique, resolveSet, chainOf, plainText, referenceText, assignId } from "./specbook-link.js";
 import { compileValueExpr, splitItems, anchored } from "./specbook-parse-value.js";
 import { referencedCoverage } from "./specbook-coverage.js";
 /*  the syntax of a value consisting of exactly one Wiki-style reference  */
@@ -233,10 +233,17 @@ const validateObject = (ctx, object, schema, level) => {
 };
 /*  resolve a level 1 object onto its configured artifact, deliberately
     leniently by kind and id first and by case-insensitive name second,
-    so deviations of the heading can still be precisely reported  */
+    so deviations of the heading can still be precisely reported, and
+    by kind alone third onto a recurring artifact (one configured with
+    neither name nor id), which every level 1 object of its kind matches  */
 export const resolveArtifact = (config, object) => config.find((s) => (s.kind === object.kind && s.id === object.id) || (s.id !== undefined && `${s.kind}-${s.id}` === object.id)) ??
     config.find((s) => s.name !== undefined
-        && s.name.toUpperCase() === plainText(object.name).toUpperCase());
+        && s.name.toUpperCase() === plainText(object.name).toUpperCase()) ??
+    config.find((s) => isRecurring(s) && s.kind === object.kind);
+/*  whether a configured artifact is a recurring one: configured with
+    neither name nor id, so any number of level 1 objects of its kind
+    match it (and none at all, as it is optional by definition)  */
+export const isRecurring = (schema) => schema.name === undefined && schema.id === undefined;
 /*  map the specification objects onto their schema configuration
     nodes (the artifact resolution is shared with the validation)  */
 export const collectSchemas = (specification, config) => {
@@ -498,7 +505,7 @@ export const validate = (ctx, specification, config) => {
     its carrying object), independent of any configuration  */
 export const validateReferences = (ctx, specification) => {
     const check = (object, text, file, line) => {
-        for (const m of plainText(text).matchAll(referenceRegex)) {
+        for (const m of referenceText(text).matchAll(referenceRegex)) {
             const ref = m[1].trim();
             const resolution = resolveUnique(ctx.linkIndex, ref, object);
             if (resolution.ambiguous)

package/dst/specbook-parse-syntax.d.ts

@@ -1,3 +1,4 @@
 import { type SpecArtifact } from "./specbook-format-spec.js";
 import { type ParseContext, type SourceFile } from "./specbook-parse-common.js";
+export declare const slugify: (text: string) => string;
 export declare const parseFile: (ctx: ParseContext, source: SourceFile) => SpecArtifact[];

package/dst/specbook-parse-syntax.js

@@ -87,7 +87,7 @@ const parseHeadingText = (raw) => {
     };
 };
 /*  derive a stable slug identifier from an object name  */
-const slugify = (text) => text.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+export const slugify = (text) => text.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
 /*  extract the plain text lines of a Markdown list item (excluding any
     nested lists), whose body is a "text" token in a tight list, but a
     "paragraph" token in a loose list (and never "item.text", as this

package/dst/specbook-parse.d.ts

@@ -2,7 +2,7 @@ import { Spec } from "./specbook-format-spec.js";
 import { type Schema } from "./specbook-format-schema.js";
 import { type SourceFile, type ParseResult } from "./specbook-parse-common.js";
 export { type SourceFile, type ParseResult } from "./specbook-parse-common.js";
-export { resolveArtifact, collectSchemas } from "./specbook-parse-semantic.js";
+export { resolveArtifact, isRecurring, collectSchemas } from "./specbook-parse-semantic.js";
 export declare const parseSpecification: (sources: SourceFile[], config?: Schema) => ParseResult;
 export declare const specStatistics: (specification: Spec) => {
     objects: number;

package/dst/specbook-parse.js

@@ -5,12 +5,12 @@
 */
 import * as v from "valibot";
 import { Spec } from "./specbook-format-spec.js";
-import { buildLinkIndex, referenceRegex, plainText } from "./specbook-link.js";
+import { buildLinkIndex, referenceRegex, referenceText } from "./specbook-link.js";
 import { ParseContext } from "./specbook-parse-common.js";
 import { parseFile } from "./specbook-parse-syntax.js";
 import { validate, validateReferences } from "./specbook-parse-semantic.js";
 import { validateDiagrams } from "./specbook-diagram.js";
-export { resolveArtifact, collectSchemas } from "./specbook-parse-semantic.js";
+export { resolveArtifact, isRecurring, collectSchemas } from "./specbook-parse-semantic.js";
 /*  parse a set of specification Markdown files into the specification
     AST and optionally validate the result against a configuration  */
 export const parseSpecification = (sources, config) => {
@@ -54,7 +54,7 @@ export const specStatistics = (specification) => {
         if (object.description !== undefined)
             texts.push(object.description.description, object.description.rationale ?? "", object.description.elaboration ?? "");
         for (const text of texts)
-            links += (plainText(text).match(referenceRegex) ?? []).length;
+            links += (referenceText(text).match(referenceRegex) ?? []).length;
         object.children.forEach(walk);
     };
     for (const artifact of specification.artifacts)

package/dst/specbook-project.d.ts

@@ -1,8 +1,10 @@
 export declare const projectFile = ".specbook.yaml";
+export declare const isRemote: (value: string) => boolean;
 export interface Project {
     file: string;
     config?: string[];
     basedir?: string;
 }
 export declare const loadProject: (dir: string) => Project | undefined;
+export declare const loadProjectFile: (file: string) => Project;
 export declare const writeProject: (dir: string, config: string[], basedir: string) => string;

package/dst/specbook-project.js

@@ -11,6 +11,12 @@ import { lineColOfPath } from "./specbook-config.js";
 import { renderDiagnostic } from "./specbook-diagnostic.js";
 /*  the name of the YAML project configuration file  */
 export const projectFile = ".specbook.yaml";
+/*  whether a schema configuration pattern is a remote reference
+    (resolved by the remote module) instead of a local path: the literals
+    "std", "meta", and "pm" (the bundled standard, meta, and project
+    management schema configurations), an "npm:" or "github:" reference,
+    or an "http:" or "https:" URL  */
+export const isRemote = (value) => value === "std" || value === "meta" || value === "pm" || (/^(?:npm|github):|^https?:\/\//).test(value);
 /*  the schema of the YAML project configuration: the files or glob
     patterns of the YAML schema configuration and the base directory
     of the specification Markdown files  */
@@ -62,12 +68,16 @@ const readProject = (file) => {
 /*  find, load, and validate the project configuration, failing on any
     problem, where its relative paths resolve against the directory of
     the file itself (and not against the perhaps deeper directory the
-    search started at) and the literal "std" still names the bundled
-    standard schema configuration  */
+    search started at)  */
 export const loadProject = (dir) => {
     const file = findProject(dir);
-    if (file === undefined)
-        return undefined;
+    return file !== undefined ? loadProjectFile(file) : undefined;
+};
+/*  load and validate a particular project configuration file, failing
+    on any problem, where its relative paths resolve against the
+    directory of the file and the remote references (the literal "std"
+    included) stay as they are  */
+export const loadProjectFile = (file) => {
     /*  parse the YAML, reporting its syntax errors as positioned diagnostics  */
     const diagnostics = new Array();
     const lines = new LineCounter();
@@ -100,7 +110,7 @@ export const loadProject = (dir) => {
     const patterns = typeof config === "string" ? [config] : config;
     return {
         file,
-        config: patterns?.map((pattern) => pattern === "std" ? pattern : path.resolve(base, pattern)),
+        config: patterns?.map((pattern) => isRemote(pattern) ? pattern : path.resolve(base, pattern)),
         basedir: basedir !== undefined ? path.resolve(base, basedir) : undefined
     };
 };

package/dst/specbook-remote.d.ts

@@ -0,0 +1,28 @@
+import { type ConfigOverlap } from "./specbook-config.js";
+import { type Verbose } from "./specbook-verbose.js";
+export declare const version: string;
+export declare const standardConfig: string;
+export declare const metaConfig: string;
+export declare const pmConfig: string;
+export declare const isBundled: (file: string) => boolean;
+export declare const cacheDir: string;
+export declare const isCached: (file: string) => boolean;
+export declare const reportOverlaps: (overlaps: ConfigOverlap[], verbose: Verbose) => void;
+export declare const fetchModes: readonly ["never", "auto", "always"];
+export type FetchMode = typeof fetchModes[number];
+export declare const parseFetchMode: (value: string) => FetchMode;
+export interface RemoteOptions {
+    fetch: FetchMode;
+    cwd: string;
+    verbose: Verbose;
+}
+export declare const expandPattern: (pattern: string) => Promise<string[]>;
+export declare const resolveConfig: (ref: string, options: RemoteOptions, chain?: string[]) => Promise<string[]>;
+export interface SearchHit {
+    ref: string;
+    name: string;
+    version?: string;
+    description?: string;
+    source: "builtin" | "npm" | "github";
+}
+export declare const search: (term: string, options: RemoteOptions) => Promise<SearchHit[]>;