@stxt-lang/core 0.5.3 → 0.6.1

package/README.md

@@ -115,6 +115,113 @@ for (const error of result.getErrors()) {
 
 Available value types: `INLINE`, `BLOCK`, `TEXT`, `BOOLEAN`, `INTEGER`, `NATURAL`, `NUMBER`, `DATE`, `TIMESTAMP`, `EMAIL`, `URL`, `HEXADECIMAL`, `BASE64`, `GROUP`, `ENUM`.
 
+## Finding the schemas: discovery
+
+`UnifiedSchemaProvider` expects you to hand it the schema text. **Discovery** answers the previous question: *given this document, which schema definitions apply to it?* `DiscoveryResolver` is the reference implementation of the STXT discovery specification, so a command line, an editor and a build step all agree on the answer by construction.
+
+Definitions live in `.stxt/` directories. For a given document the resolution chain is, highest precedence first:
+
+1. every ancestor `.stxt/` directory, nearest first — the ascent does **not** stop at the first one, so in a monorepo both the subproject's and the repo root's participate;
+2. the user level, `$HOME/.stxt` (`%USERPROFILE%\.stxt` on Windows);
+3. the system level, `/etc/stxt` (`%ProgramData%\stxt` on Windows).
+
+Precedence is **per namespace**: the nearest level that defines a namespace wins, and the rest of the chain still contributes the namespaces that level does not define. Defining one namespace twice at the same level is a resolution error, and leaves that namespace without an active definition. When `STXT_PATH` is defined it replaces the whole chain — useful in CI and tests.
+
+The resolver never touches the file system or the environment itself: you inject a `DiscoveryFileSystem` and a `DiscoveryEnvironment`. That is what lets the same logic run over Node's `fs`, over an editor's virtual file system (`vscode.workspace.fs`) or over an in-memory tree in a test. Here are the Node adapters:
+
+```ts
+import * as fs from 'fs/promises';
+import * as os from 'os';
+import * as path from 'path';
+import {
+    DiscoveryEntry,
+    DiscoveryEnvironment,
+    DiscoveryFileSystem,
+    DiscoveryResolver,
+} from '@stxt-lang/core';
+
+class NodeFileSystem implements DiscoveryFileSystem {
+    async isDirectory(p: string): Promise<boolean> {
+        try {
+            return (await fs.stat(p)).isDirectory();
+        } catch {
+            return false; // not existing is the normal case, not an error
+        }
+    }
+    async listDirectory(p: string): Promise<DiscoveryEntry[]> {
+        const entries = await fs.readdir(p, { withFileTypes: true });
+        return entries.map(entry => ({
+            path: path.join(p, entry.name),
+            name: entry.name,
+            isDirectory: entry.isDirectory(),
+        }));
+    }
+    readFile(p: string): Promise<string> {
+        return fs.readFile(p, 'utf-8');
+    }
+    parentOf(p: string): string | null {
+        const parent = path.dirname(p);
+        return parent === p ? null : parent; // null at the file-system root
+    }
+    join(p: string, name: string): string {
+        return path.join(p, name);
+    }
+}
+
+class NodeEnvironment implements DiscoveryEnvironment {
+    getStxtPath(): string[] | null {
+        const value = process.env.STXT_PATH;
+        // null (not defined) and [] (defined but empty) mean different things
+        return value === undefined ? null : value.split(path.delimiter).filter(e => e !== '');
+    }
+    getUserLevelDir(): string | null {
+        return path.join(os.homedir(), '.stxt');
+    }
+    getSystemLevelDir(): string | null {
+        return '/etc/stxt';
+    }
+}
+```
+
+With those in place, resolving a document and validating it is two steps — and note that `DiscoveryResult` implements `SchemaProvider`, so it goes straight into the validator:
+
+```ts
+import { Parser, SchemaValidator, ConditionalValidator } from '@stxt-lang/core';
+
+const resolver = new DiscoveryResolver(new NodeFileSystem(), new NodeEnvironment());
+
+// The chain is per document: pass the directory the document lives in
+// (null for stdin or an unsaved buffer, which starts the chain at the user level).
+const result = await resolver.resolve('/repo/site/posts');
+
+console.log(result.getChain());
+// [ '/repo/site/.stxt', '/repo/.stxt' ]   ← both ancestors, nearest first
+
+// Resolution errors are collected, never thrown: report them and carry on
+for (const error of result.getErrors()) {
+    console.error(`[${error.code}] ${error.message}`);
+}
+
+const parser = new Parser();
+parser.registerValidator(new ConditionalValidator(new SchemaValidator(result)));
+
+const parsed = parser.parseResult(documentText);
+```
+
+`DiscoveryResult` also tells you *where* a schema came from, which is what an editor needs for "go to definition" or a diagnostic that explains itself:
+
+```ts
+const definition = result.getDefinition('blog.post');
+
+console.log(definition?.file);      // '/repo/site/.stxt/blog.stxt'
+console.log(definition?.levelDir);  // '/repo/site/.stxt'  ← the level that won
+
+result.getActiveDefinitions();      // one entry per namespace, precedence applied
+result.getAllSchemas();             // just the schemas of the above
+```
+
+Levels are cached by directory, so resolving many documents that share ancestors reads each `.stxt/` once. Call `resolver.clearCache()` when the definition files may have changed — from a file watcher, for instance.
+
 ## Observing the parse
 
 `Observer` receives streaming callbacks while the document is parsed — useful for syntax highlighting, indexes or any per-line bookkeeping.
@@ -150,7 +257,14 @@ const doc = NodeWriter.toSTXTDocs(result.getNodes(), IndentStyle.SPACES_4);
 
 ## API surface
 
-Everything importable from the package: `Node`, `Parser`, `ParseResult`, `Line`, `Constants`, `parseLine`, `StringUtils`, `ParseException`, `ValidationException`, `Observer`, `Schema`, `SchemaValidator`, `SchemaProvider`, `NodeDefinition`, `ChildDefinition`, `transformNodeToSchema`, `UnifiedSchemaProvider`, `ConditionalValidator`, `NodeWriter`, `IndentStyle`, `transformTemplateNodeToSchema`.
+Everything importable from the package:
+
+- **Parsing** — `Node`, `Parser`, `ParseResult`, `Line`, `Constants`, `parseLine`, `StringUtils`
+- **Exceptions** — `ParseException`, `ValidationException`
+- **Extension points** — `Observer`
+- **Schemas** — `Schema`, `SchemaValidator`, `SchemaProvider`, `NodeDefinition`, `ChildDefinition`, `transformNodeToSchema`, `transformTemplateNodeToSchema`
+- **Runtime** — `UnifiedSchemaProvider`, `ConditionalValidator`, `NodeWriter`, `IndentStyle`
+- **Discovery** — `DiscoveryResolver`, `DiscoveryOptions`, `DiscoveryResult`, `DiscoveryDefinition`, `DiscoveryLevel`, `DiscoveryError`, `DiscoveryFileSystem`, `DiscoveryEntry`, `DiscoveryEnvironment`
 
 ## License
 

package/out/all.d.ts

@@ -17,4 +17,11 @@ export { transformNodeToSchema } from "./schema/SchemaParser";
 export { UnifiedSchemaProvider } from "./runtime/UnifiedSchemaProvider";
 export { ConditionalValidator } from "./runtime/ConditionalValidator";
 export { NodeWriter, IndentStyle } from "./runtime/NodeWriter";
+export { toCanonicalTree, toCanonicalJson } from "./runtime/TreeJson";
+export type { CanonicalDocument, CanonicalNode, CanonicalInlineNode, CanonicalBlockNode } from "./runtime/TreeJson";
 export { transformTemplateNodeToSchema } from "./template/TemplateParser";
+export { DiscoveryResolver, DiscoveryOptions } from "./discovery/DiscoveryResolver";
+export { DiscoveryResult, DiscoveryDefinition, DiscoveryLevel } from "./discovery/DiscoveryResult";
+export { DiscoveryError } from "./discovery/DiscoveryError";
+export { DiscoveryFileSystem, DiscoveryEntry } from "./discovery/DiscoveryFileSystem";
+export { DiscoveryEnvironment } from "./discovery/DiscoveryEnvironment";

package/out/all.js

@@ -3,7 +3,7 @@
 // Anything that should be consumable by third parties (e.g. the VSCode extension)
 // has to be re-exported from here.
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.transformTemplateNodeToSchema = exports.IndentStyle = exports.NodeWriter = exports.ConditionalValidator = exports.UnifiedSchemaProvider = exports.transformNodeToSchema = exports.ChildDefinition = exports.NodeDefinition = exports.SchemaValidator = exports.Schema = exports.ValidationException = exports.ParseException = exports.StringUtils = exports.parseLine = exports.Constants = exports.Line = exports.ParseResult = exports.Parser = exports.Node = void 0;
+exports.DiscoveryError = exports.DiscoveryResult = exports.DiscoveryResolver = exports.transformTemplateNodeToSchema = exports.toCanonicalJson = exports.toCanonicalTree = exports.IndentStyle = exports.NodeWriter = exports.ConditionalValidator = exports.UnifiedSchemaProvider = exports.transformNodeToSchema = exports.ChildDefinition = exports.NodeDefinition = exports.SchemaValidator = exports.Schema = exports.ValidationException = exports.ParseException = exports.StringUtils = exports.parseLine = exports.Constants = exports.Line = exports.ParseResult = exports.Parser = exports.Node = void 0;
 var Node_1 = require("./core/Node");
 Object.defineProperty(exports, "Node", { enumerable: true, get: function () { return Node_1.Node; } });
 var Parser_1 = require("./core/Parser");
@@ -39,6 +39,15 @@ Object.defineProperty(exports, "ConditionalValidator", { enumerable: true, get:
 var NodeWriter_1 = require("./runtime/NodeWriter");
 Object.defineProperty(exports, "NodeWriter", { enumerable: true, get: function () { return NodeWriter_1.NodeWriter; } });
 Object.defineProperty(exports, "IndentStyle", { enumerable: true, get: function () { return NodeWriter_1.IndentStyle; } });
+var TreeJson_1 = require("./runtime/TreeJson");
+Object.defineProperty(exports, "toCanonicalTree", { enumerable: true, get: function () { return TreeJson_1.toCanonicalTree; } });
+Object.defineProperty(exports, "toCanonicalJson", { enumerable: true, get: function () { return TreeJson_1.toCanonicalJson; } });
 var TemplateParser_1 = require("./template/TemplateParser");
 Object.defineProperty(exports, "transformTemplateNodeToSchema", { enumerable: true, get: function () { return TemplateParser_1.transformTemplateNodeToSchema; } });
+var DiscoveryResolver_1 = require("./discovery/DiscoveryResolver");
+Object.defineProperty(exports, "DiscoveryResolver", { enumerable: true, get: function () { return DiscoveryResolver_1.DiscoveryResolver; } });
+var DiscoveryResult_1 = require("./discovery/DiscoveryResult");
+Object.defineProperty(exports, "DiscoveryResult", { enumerable: true, get: function () { return DiscoveryResult_1.DiscoveryResult; } });
+var DiscoveryError_1 = require("./discovery/DiscoveryError");
+Object.defineProperty(exports, "DiscoveryError", { enumerable: true, get: function () { return DiscoveryError_1.DiscoveryError; } });
 //# sourceMappingURL=all.js.map

package/out/discovery/DiscoveryEnvironment.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Environment abstraction used by {@link DiscoveryResolver} (STXT-DISCOVERY-SPEC).
+ *
+ * It answers the three questions that depend on the platform and the process environment:
+ * the `STXT_PATH` override, the user-level directory and the system-level directory.
+ * Injecting it keeps the resolver free of `process`/`os` access, deterministic in tests
+ * and usable from any host (Node, editor extension, browser).
+ */
+export interface DiscoveryEnvironment {
+    /**
+     * The value of the `STXT_PATH` environment variable, already split into entries.
+     *
+     * The distinction between "not defined" and "defined but empty" is normative
+     * (STXT-DISCOVERY-SPEC section 6): when defined, `STXT_PATH` completely replaces the
+     * resolution chain, and an empty value leaves the chain empty.
+     *
+     * @returns the list of directories (highest precedence first), an empty array when the
+     *          variable is defined but empty, or null when it is not defined at all.
+     */
+    getStxtPath(): string[] | null;
+    /**
+     * The user-level resolution directory (`$HOME/.stxt` on Unix, `%USERPROFILE%\.stxt` on
+     * Windows), already resolved to a full path.
+     *
+     * @returns the user-level directory, or null when the host has no notion of a user home.
+     */
+    getUserLevelDir(): string | null;
+    /**
+     * The system-level resolution directory (`/etc/stxt` on Unix, `%ProgramData%\stxt` on
+     * Windows), already resolved to a full path.
+     *
+     * @returns the system-level directory, or null when the host has no system level.
+     */
+    getSystemLevelDir(): string | null;
+}

package/out/discovery/DiscoveryEnvironment.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=DiscoveryEnvironment.js.map

package/out/discovery/DiscoveryError.d.ts

@@ -0,0 +1,30 @@
+/**
+ * A resolution error (STXT-DISCOVERY-SPEC section 8).
+ *
+ * Resolution errors are collected, not thrown: the spec mandates reporting them while
+ * allowing the tool to keep loading the remaining definitions, so a resolve pass returns
+ * every error it found instead of aborting at the first one.
+ */
+export declare class DiscoveryError {
+    readonly code: string;
+    readonly file: string;
+    readonly message: string;
+    readonly namespace?: string | undefined;
+    /** Two definitions for the same target namespace at the same level (spec 8.1). */
+    static readonly DUPLICATE_NAMESPACE = "DISCOVERY_DUPLICATE_NAMESPACE";
+    /** A file under a resolution directory that does not parse as STXT (spec 8.2). */
+    static readonly NOT_PARSEABLE = "DISCOVERY_NOT_PARSEABLE";
+    /** A file whose root node belongs neither to @stxt.schema nor to @stxt.template (spec 8.3). */
+    static readonly NOT_A_DEFINITION = "DISCOVERY_NOT_A_DEFINITION";
+    /** A definition that does not validate against its meta-schema (spec 8.4). */
+    static readonly INVALID_DEFINITION = "DISCOVERY_INVALID_DEFINITION";
+    /**
+     * Creates a resolution error.
+     *
+     * @param code one of the `DISCOVERY_*` constants of this class.
+     * @param file full path of the offending file.
+     * @param message human-readable description of the error.
+     * @param namespace target namespace involved, when the error is about a namespace.
+     */
+    constructor(code: string, file: string, message: string, namespace?: string | undefined);
+}

package/out/discovery/DiscoveryError.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DiscoveryError = void 0;
+/**
+ * A resolution error (STXT-DISCOVERY-SPEC section 8).
+ *
+ * Resolution errors are collected, not thrown: the spec mandates reporting them while
+ * allowing the tool to keep loading the remaining definitions, so a resolve pass returns
+ * every error it found instead of aborting at the first one.
+ */
+class DiscoveryError {
+    /**
+     * Creates a resolution error.
+     *
+     * @param code one of the `DISCOVERY_*` constants of this class.
+     * @param file full path of the offending file.
+     * @param message human-readable description of the error.
+     * @param namespace target namespace involved, when the error is about a namespace.
+     */
+    constructor(code, file, message, namespace) {
+        this.code = code;
+        this.file = file;
+        this.message = message;
+        this.namespace = namespace;
+    }
+}
+exports.DiscoveryError = DiscoveryError;
+/** Two definitions for the same target namespace at the same level (spec 8.1). */
+DiscoveryError.DUPLICATE_NAMESPACE = "DISCOVERY_DUPLICATE_NAMESPACE";
+/** A file under a resolution directory that does not parse as STXT (spec 8.2). */
+DiscoveryError.NOT_PARSEABLE = "DISCOVERY_NOT_PARSEABLE";
+/** A file whose root node belongs neither to @stxt.schema nor to @stxt.template (spec 8.3). */
+DiscoveryError.NOT_A_DEFINITION = "DISCOVERY_NOT_A_DEFINITION";
+/** A definition that does not validate against its meta-schema (spec 8.4). */
+DiscoveryError.INVALID_DEFINITION = "DISCOVERY_INVALID_DEFINITION";
+//# sourceMappingURL=DiscoveryError.js.map

package/out/discovery/DiscoveryFileSystem.d.ts

@@ -0,0 +1,57 @@
+/**
+ * An entry of a directory listing, as returned by {@link DiscoveryFileSystem.listDirectory}.
+ */
+export interface DiscoveryEntry {
+    /** Full path of the entry, in the same form the file system uses for every other path. */
+    path: string;
+    /** Base name of the entry (last path segment). */
+    name: string;
+    /** True if the entry is a directory. */
+    isDirectory: boolean;
+}
+/**
+ * Minimal file-system abstraction used by {@link DiscoveryResolver} (STXT-DISCOVERY-SPEC).
+ *
+ * The resolver treats paths as opaque strings: it never parses or concatenates them itself,
+ * so an implementation may back them with plain OS paths (Node `fs`), editor URIs
+ * (`vscode.workspace.fs`) or an in-memory tree for tests. All paths returned by an
+ * implementation must be canonical enough that string equality means "same directory".
+ */
+export interface DiscoveryFileSystem {
+    /**
+     * Whether a path exists and is a directory.
+     *
+     * @param path path to check.
+     * @returns true if the path is an existing directory; false otherwise (including I/O errors).
+     */
+    isDirectory(path: string): Promise<boolean>;
+    /**
+     * Lists the immediate entries of a directory.
+     *
+     * @param path directory to list.
+     * @returns the entries of the directory, in any order.
+     */
+    listDirectory(path: string): Promise<DiscoveryEntry[]>;
+    /**
+     * Reads a file as UTF-8 text.
+     *
+     * @param path file to read.
+     * @returns the text content of the file.
+     */
+    readFile(path: string): Promise<string>;
+    /**
+     * Returns the parent directory of a path, or null when the path is the file-system root.
+     *
+     * @param path path whose parent is wanted.
+     * @returns the parent path, or null at the root.
+     */
+    parentOf(path: string): string | null;
+    /**
+     * Joins a directory path and a child name.
+     *
+     * @param path base directory.
+     * @param name child segment to append.
+     * @returns the joined path.
+     */
+    join(path: string, name: string): string;
+}

package/out/discovery/DiscoveryFileSystem.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=DiscoveryFileSystem.js.map

package/out/discovery/DiscoveryResolver.d.ts

@@ -0,0 +1,74 @@
+import { DiscoveryEnvironment } from "./DiscoveryEnvironment";
+import { DiscoveryFileSystem } from "./DiscoveryFileSystem";
+import { DiscoveryResult } from "./DiscoveryResult";
+/** Options of a {@link DiscoveryResolver}. */
+export interface DiscoveryOptions {
+    /**
+     * Maximum number of ancestor directories examined during the project-level ascent.
+     * A safeguard against pathological paths (circular links, virtual file systems), as
+     * allowed by STXT-DISCOVERY-SPEC section 4.1. Defaults to 32.
+     */
+    maxAscent?: number;
+}
+/**
+ * Reference implementation of STXT-DISCOVERY-SPEC: builds the resolution chain of a
+ * document (project ascent, user level, system level, or the `STXT_PATH` override), loads
+ * every definition of every level and applies the per-namespace precedence.
+ *
+ * The resolver is host-agnostic: all file-system and environment access goes through the
+ * injected {@link DiscoveryFileSystem} and {@link DiscoveryEnvironment}, so the same logic
+ * serves a command line (Node `fs`), an editor (`vscode.workspace.fs`) or a test (an
+ * in-memory tree).
+ *
+ * Loaded levels are cached by directory: resolving many documents that share levels loads
+ * each directory once, which is the sharing that STXT-DISCOVERY-SPEC section 7 allows —
+ * a level's content does not depend on which document is being resolved. Call
+ * {@link clearCache} when the underlying files may have changed.
+ */
+export declare class DiscoveryResolver {
+    private readonly fs;
+    private readonly env;
+    private readonly maxAscent;
+    private readonly schemaMeta;
+    private readonly templateMeta;
+    private readonly levelCache;
+    /**
+     * Creates a resolver.
+     *
+     * @param fs file-system access.
+     * @param env environment access (`STXT_PATH`, user and system directories).
+     * @param options optional settings.
+     */
+    constructor(fs: DiscoveryFileSystem, env: DiscoveryEnvironment, options?: DiscoveryOptions);
+    /**
+     * Builds the resolution chain of a document (STXT-DISCOVERY-SPEC sections 4 and 6)
+     * without loading any definition.
+     *
+     * @param documentDir directory containing the document, or null for a document with no
+     *        file-system location (standard input, an unsaved buffer), whose chain starts
+     *        at the user level.
+     * @returns the existing resolution directories, highest precedence first.
+     */
+    resolveChain(documentDir: string | null): Promise<string[]>;
+    /**
+     * Resolves the definitions applicable to a document: builds its chain, loads every
+     * level (from the cache when already loaded) and returns the result with the
+     * per-namespace precedence applied.
+     *
+     * @param documentDir directory containing the document, or null for a document with no
+     *        file-system location.
+     * @returns the resolution result, usable directly as a `SchemaProvider`.
+     */
+    resolve(documentDir: string | null): Promise<DiscoveryResult>;
+    /**
+     * Empties the level cache, so that the next resolve re-reads every directory. Call it
+     * when the definition files may have changed (e.g. from a file watcher).
+     */
+    clearCache(): void;
+    private existingUnique;
+    private loadLevel;
+    private collectFiles;
+    private loadFile;
+    private loadRootNode;
+    private compile;
+}

package/out/discovery/DiscoveryResolver.js

@@ -0,0 +1,232 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DiscoveryResolver = void 0;
+const Parser_1 = require("../core/Parser");
+const StringUtils_1 = require("../core/StringUtils");
+const ParseException_1 = require("../exceptions/ParseException");
+const SchemaProviderMeta_1 = require("../schema/SchemaProviderMeta");
+const SchemaValidator_1 = require("../schema/SchemaValidator");
+const SchemaParser_1 = require("../schema/SchemaParser");
+const MetaTemplateSchemaProvider_1 = require("../template/MetaTemplateSchemaProvider");
+const TemplateParser_1 = require("../template/TemplateParser");
+const DiscoveryError_1 = require("./DiscoveryError");
+const DiscoveryResult_1 = require("./DiscoveryResult");
+/** Name of the resolution directories (STXT-DISCOVERY-SPEC section 3). */
+const STXT_DIR = ".stxt";
+/** File extension of STXT documents. */
+const STXT_EXTENSION = ".stxt";
+/** Default value of {@link DiscoveryOptions.maxAscent}. */
+const DEFAULT_MAX_ASCENT = 32;
+/**
+ * Reference implementation of STXT-DISCOVERY-SPEC: builds the resolution chain of a
+ * document (project ascent, user level, system level, or the `STXT_PATH` override), loads
+ * every definition of every level and applies the per-namespace precedence.
+ *
+ * The resolver is host-agnostic: all file-system and environment access goes through the
+ * injected {@link DiscoveryFileSystem} and {@link DiscoveryEnvironment}, so the same logic
+ * serves a command line (Node `fs`), an editor (`vscode.workspace.fs`) or a test (an
+ * in-memory tree).
+ *
+ * Loaded levels are cached by directory: resolving many documents that share levels loads
+ * each directory once, which is the sharing that STXT-DISCOVERY-SPEC section 7 allows —
+ * a level's content does not depend on which document is being resolved. Call
+ * {@link clearCache} when the underlying files may have changed.
+ */
+class DiscoveryResolver {
+    /**
+     * Creates a resolver.
+     *
+     * @param fs file-system access.
+     * @param env environment access (`STXT_PATH`, user and system directories).
+     * @param options optional settings.
+     */
+    constructor(fs, env, options) {
+        this.fs = fs;
+        this.env = env;
+        this.schemaMeta = new SchemaProviderMeta_1.SchemaProviderMeta();
+        this.templateMeta = new MetaTemplateSchemaProvider_1.MetaTemplateSchemaProvider();
+        this.levelCache = new Map();
+        this.maxAscent = options?.maxAscent ?? DEFAULT_MAX_ASCENT;
+    }
+    /**
+     * Builds the resolution chain of a document (STXT-DISCOVERY-SPEC sections 4 and 6)
+     * without loading any definition.
+     *
+     * @param documentDir directory containing the document, or null for a document with no
+     *        file-system location (standard input, an unsaved buffer), whose chain starts
+     *        at the user level.
+     * @returns the existing resolution directories, highest precedence first.
+     */
+    async resolveChain(documentDir) {
+        // STXT_PATH, when defined, completely replaces the chain (spec section 6).
+        const stxtPath = this.env.getStxtPath();
+        if (stxtPath !== null) {
+            return this.existingUnique(stxtPath);
+        }
+        const chain = [];
+        // Project level: every .stxt directory from the document's directory upward.
+        if (documentDir !== null) {
+            let dir = documentDir;
+            for (let level = 0; level < this.maxAscent && dir !== null; level++) {
+                const candidate = this.fs.join(dir, STXT_DIR);
+                if (await this.fs.isDirectory(candidate)) {
+                    chain.push(candidate);
+                }
+                dir = this.fs.parentOf(dir);
+            }
+        }
+        // User and system levels. The ascent may have reached them already (a document
+        // under the user's home finds $HOME/.stxt as a project candidate): deduplicate.
+        const userDir = this.env.getUserLevelDir();
+        const systemDir = this.env.getSystemLevelDir();
+        for (const dir of [userDir, systemDir]) {
+            if (dir !== null && !chain.includes(dir) && await this.fs.isDirectory(dir)) {
+                chain.push(dir);
+            }
+        }
+        return chain;
+    }
+    /**
+     * Resolves the definitions applicable to a document: builds its chain, loads every
+     * level (from the cache when already loaded) and returns the result with the
+     * per-namespace precedence applied.
+     *
+     * @param documentDir directory containing the document, or null for a document with no
+     *        file-system location.
+     * @returns the resolution result, usable directly as a `SchemaProvider`.
+     */
+    async resolve(documentDir) {
+        const chain = await this.resolveChain(documentDir);
+        const levels = [];
+        for (const dir of chain) {
+            levels.push(await this.loadLevel(dir));
+        }
+        return new DiscoveryResult_1.DiscoveryResult(levels, this.schemaMeta, this.templateMeta);
+    }
+    /**
+     * Empties the level cache, so that the next resolve re-reads every directory. Call it
+     * when the definition files may have changed (e.g. from a file watcher).
+     */
+    clearCache() {
+        this.levelCache.clear();
+    }
+    // Filters a list of directories down to the existing ones, removing duplicates.
+    async existingUnique(dirs) {
+        const result = [];
+        for (const dir of dirs) {
+            if (!result.includes(dir) && await this.fs.isDirectory(dir)) {
+                result.push(dir);
+            }
+        }
+        return result;
+    }
+    // Loads a resolution directory (or returns it from the cache): every file under it,
+    // recursively, with the level-local duplicate detection of spec section 5.
+    async loadLevel(dir) {
+        const cached = this.levelCache.get(dir);
+        if (cached) {
+            return cached;
+        }
+        const level = { dir, definitions: new Map(), errors: [] };
+        const conflicted = new Set();
+        for (const file of await this.collectFiles(dir)) {
+            await this.loadFile(file, level, conflicted);
+        }
+        this.levelCache.set(dir, level);
+        return level;
+    }
+    // Collects every file under a directory, recursively, sorted by path so that results
+    // and error messages do not depend on the listing order of the file system.
+    async collectFiles(dir) {
+        const files = [];
+        const entries = [...await this.fs.listDirectory(dir)].sort((a, b) => a.path < b.path ? -1 : 1);
+        for (const entry of entries) {
+            if (entry.isDirectory) {
+                files.push(...await this.collectFiles(entry.path));
+            }
+            else {
+                files.push(entry.path);
+            }
+        }
+        return files;
+    }
+    // Loads one file of a level: parses it and registers every root as a definition,
+    // reporting the errors of spec section 8.
+    async loadFile(file, level, conflicted) {
+        // Spec section 3: every file under a resolution directory must be a definition.
+        if (!file.endsWith(STXT_EXTENSION)) {
+            level.errors.push(new DiscoveryError_1.DiscoveryError(DiscoveryError_1.DiscoveryError.NOT_A_DEFINITION, file, `Not an STXT definition file: ${file}`));
+            return;
+        }
+        let nodes;
+        try {
+            nodes = new Parser_1.Parser().parse(await this.fs.readFile(file));
+        }
+        catch (e) {
+            level.errors.push(new DiscoveryError_1.DiscoveryError(DiscoveryError_1.DiscoveryError.NOT_PARSEABLE, file, `Cannot parse ${file}: ${e instanceof Error ? e.message : String(e)}`));
+            return;
+        }
+        if (nodes.length === 0) {
+            level.errors.push(new DiscoveryError_1.DiscoveryError(DiscoveryError_1.DiscoveryError.NOT_A_DEFINITION, file, `Empty document, not a definition: ${file}`));
+            return;
+        }
+        for (const node of nodes) {
+            this.loadRootNode(node, file, level, conflicted);
+        }
+    }
+    // Validates one root node against its meta-schema, compiles it to a schema and
+    // registers it in the level, detecting same-level duplicates.
+    loadRootNode(node, file, level, conflicted) {
+        const namespace = node.getNamespace();
+        let schema;
+        try {
+            if (namespace === "@stxt.template") {
+                schema = this.compile(node, this.templateMeta, TemplateParser_1.transformTemplateNodeToSchema);
+            }
+            else if (namespace === "@stxt.schema") {
+                schema = this.compile(node, this.schemaMeta, SchemaParser_1.transformNodeToSchema);
+            }
+            else {
+                level.errors.push(new DiscoveryError_1.DiscoveryError(DiscoveryError_1.DiscoveryError.NOT_A_DEFINITION, file, `Root node belongs to '${namespace ?? ""}', not to @stxt.schema or @stxt.template: ${file}`));
+                return;
+            }
+        }
+        catch (e) {
+            const message = e instanceof ParseException_1.ParseException ? `[${e.code}] ${e.message}` : String(e);
+            level.errors.push(new DiscoveryError_1.DiscoveryError(DiscoveryError_1.DiscoveryError.INVALID_DEFINITION, file, `Invalid definition in ${file}: ${message}`));
+            return;
+        }
+        const key = StringUtils_1.StringUtils.lowerCase(schema.getNamespace());
+        const existing = level.definitions.get(key);
+        // Spec section 8: on a same-level duplicate, never silently pick one of the
+        // definitions — the namespace has no active definition while the conflict exists.
+        if (conflicted.has(key) || existing) {
+            if (existing) {
+                level.definitions.delete(key);
+                conflicted.add(key);
+            }
+            const firstFile = existing ? existing.file : "another file of this level";
+            level.errors.push(new DiscoveryError_1.DiscoveryError(DiscoveryError_1.DiscoveryError.DUPLICATE_NAMESPACE, file, `Duplicate definition for namespace '${schema.getNamespace()}' at level ${level.dir}: ` +
+                `already defined in ${firstFile}`, schema.getNamespace()));
+            return;
+        }
+        const definition = {
+            namespace: schema.getNamespace(),
+            schema,
+            file,
+            levelDir: level.dir,
+        };
+        level.definitions.set(key, definition);
+    }
+    // Validates a root node against a meta-schema and transforms it into a Schema,
+    // throwing the first validation error (same policy as UnifiedSchemaProvider).
+    compile(node, meta, transform) {
+        const errors = new SchemaValidator_1.SchemaValidator(meta, true).validate(node);
+        if (errors.length > 0) {
+            throw errors[0];
+        }
+        return transform(node);
+    }
+}
+exports.DiscoveryResolver = DiscoveryResolver;
+//# sourceMappingURL=DiscoveryResolver.js.map

package/out/discovery/DiscoveryResult.d.ts

@@ -0,0 +1,94 @@
+import { Schema } from "../schema/Schema";
+import { SchemaProvider } from "../schema/SchemaProvider";
+import { DiscoveryError } from "./DiscoveryError";
+/**
+ * An active definition: a schema or template that won the per-namespace precedence for a
+ * document's resolution chain, together with where it came from.
+ */
+export interface DiscoveryDefinition {
+    /** Target namespace of the definition, as written in the definition document. */
+    namespace: string;
+    /** The compiled schema (templates are compiled to schemas at load time). */
+    schema: Schema;
+    /** Full path of the file the definition was read from. */
+    file: string;
+    /** Resolution directory (level) the file belongs to. */
+    levelDir: string;
+}
+/**
+ * A loaded resolution directory: its definitions indexed by lowercased target namespace.
+ * Namespaces in conflict inside the level (spec 8.1) are excluded from the map.
+ */
+export interface DiscoveryLevel {
+    /** Full path of the resolution directory. */
+    dir: string;
+    /** Definitions of the level by lowercased target namespace, conflicts excluded. */
+    definitions: Map<string, DiscoveryDefinition>;
+    /** Resolution errors found while loading this level. */
+    errors: DiscoveryError[];
+}
+/**
+ * The outcome of resolving a document's definitions (STXT-DISCOVERY-SPEC): the chain of
+ * levels, the active definition per namespace (nearest level wins) and every resolution
+ * error found along the way.
+ *
+ * It implements {@link SchemaProvider}, so it can be handed directly to a
+ * `SchemaValidator`/`ConditionalValidator` to validate the document it was resolved for.
+ * Like `UnifiedSchemaProvider`, it serves the meta-schemas of the two reserved namespaces
+ * itself, so schema and template documents also validate against it.
+ */
+export declare class DiscoveryResult implements SchemaProvider {
+    private readonly levels;
+    private readonly schemaMeta;
+    private readonly templateMeta;
+    /**
+     * Creates a result. Built by {@link DiscoveryResolver}; not meant to be constructed
+     * directly.
+     *
+     * @param levels loaded levels of the chain, highest precedence first.
+     * @param schemaMeta provider of the @stxt.schema meta-schema.
+     * @param templateMeta provider of the @stxt.template meta-schema.
+     */
+    constructor(levels: ReadonlyArray<DiscoveryLevel>, schemaMeta: SchemaProvider, templateMeta: SchemaProvider);
+    /**
+     * Resolves the schema that applies to a namespace: the meta-schemas for the two
+     * reserved namespaces, and otherwise the active definition of the nearest level.
+     *
+     * @param namespace namespace whose schema is wanted.
+     * @returns the schema of the namespace, or null if the chain has no definition for it.
+     */
+    getSchema(namespace: string): Schema | null | undefined;
+    /**
+     * The active definition of a namespace: the one from the nearest level that defines it
+     * (STXT-DISCOVERY-SPEC section 5), with its provenance.
+     *
+     * @param namespace namespace whose definition is wanted.
+     * @returns the active definition, or undefined if the chain has none for the namespace.
+     */
+    getDefinition(namespace: string): DiscoveryDefinition | undefined;
+    /**
+     * Every active definition of the chain, with per-namespace precedence already applied:
+     * one entry per namespace, from its nearest defining level.
+     *
+     * @returns the active definitions, ordered by level (nearest level's definitions first).
+     */
+    getActiveDefinitions(): ReadonlyArray<DiscoveryDefinition>;
+    /**
+     * Every active schema of the chain (the schemas of {@link getActiveDefinitions}).
+     *
+     * @returns the active schemas, ordered by level (nearest level's schemas first).
+     */
+    getAllSchemas(): ReadonlyArray<Schema>;
+    /**
+     * The resolution chain: the loaded level directories, highest precedence first.
+     *
+     * @returns the directories of the chain, in precedence order.
+     */
+    getChain(): ReadonlyArray<string>;
+    /**
+     * Every resolution error found while loading the chain (STXT-DISCOVERY-SPEC section 8).
+     *
+     * @returns the errors, ordered by level and then by file.
+     */
+    getErrors(): ReadonlyArray<DiscoveryError>;
+}

package/out/discovery/DiscoveryResult.js

@@ -0,0 +1,111 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DiscoveryResult = void 0;
+const StringUtils_1 = require("../core/StringUtils");
+/**
+ * The outcome of resolving a document's definitions (STXT-DISCOVERY-SPEC): the chain of
+ * levels, the active definition per namespace (nearest level wins) and every resolution
+ * error found along the way.
+ *
+ * It implements {@link SchemaProvider}, so it can be handed directly to a
+ * `SchemaValidator`/`ConditionalValidator` to validate the document it was resolved for.
+ * Like `UnifiedSchemaProvider`, it serves the meta-schemas of the two reserved namespaces
+ * itself, so schema and template documents also validate against it.
+ */
+class DiscoveryResult {
+    /**
+     * Creates a result. Built by {@link DiscoveryResolver}; not meant to be constructed
+     * directly.
+     *
+     * @param levels loaded levels of the chain, highest precedence first.
+     * @param schemaMeta provider of the @stxt.schema meta-schema.
+     * @param templateMeta provider of the @stxt.template meta-schema.
+     */
+    constructor(levels, schemaMeta, templateMeta) {
+        this.levels = levels;
+        this.schemaMeta = schemaMeta;
+        this.templateMeta = templateMeta;
+    }
+    /**
+     * Resolves the schema that applies to a namespace: the meta-schemas for the two
+     * reserved namespaces, and otherwise the active definition of the nearest level.
+     *
+     * @param namespace namespace whose schema is wanted.
+     * @returns the schema of the namespace, or null if the chain has no definition for it.
+     */
+    getSchema(namespace) {
+        if (namespace === "@stxt.template") {
+            return this.templateMeta.getSchema(namespace);
+        }
+        else if (namespace === "@stxt.schema") {
+            return this.schemaMeta.getSchema(namespace);
+        }
+        return this.getDefinition(namespace)?.schema ?? null;
+    }
+    /**
+     * The active definition of a namespace: the one from the nearest level that defines it
+     * (STXT-DISCOVERY-SPEC section 5), with its provenance.
+     *
+     * @param namespace namespace whose definition is wanted.
+     * @returns the active definition, or undefined if the chain has none for the namespace.
+     */
+    getDefinition(namespace) {
+        const key = StringUtils_1.StringUtils.lowerCase(namespace);
+        for (const level of this.levels) {
+            const definition = level.definitions.get(key);
+            if (definition) {
+                return definition;
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Every active definition of the chain, with per-namespace precedence already applied:
+     * one entry per namespace, from its nearest defining level.
+     *
+     * @returns the active definitions, ordered by level (nearest level's definitions first).
+     */
+    getActiveDefinitions() {
+        const seen = new Set();
+        const result = [];
+        for (const level of this.levels) {
+            for (const [key, definition] of level.definitions) {
+                if (!seen.has(key)) {
+                    seen.add(key);
+                    result.push(definition);
+                }
+            }
+        }
+        return result;
+    }
+    /**
+     * Every active schema of the chain (the schemas of {@link getActiveDefinitions}).
+     *
+     * @returns the active schemas, ordered by level (nearest level's schemas first).
+     */
+    getAllSchemas() {
+        return this.getActiveDefinitions().map(definition => definition.schema);
+    }
+    /**
+     * The resolution chain: the loaded level directories, highest precedence first.
+     *
+     * @returns the directories of the chain, in precedence order.
+     */
+    getChain() {
+        return this.levels.map(level => level.dir);
+    }
+    /**
+     * Every resolution error found while loading the chain (STXT-DISCOVERY-SPEC section 8).
+     *
+     * @returns the errors, ordered by level and then by file.
+     */
+    getErrors() {
+        const result = [];
+        for (const level of this.levels) {
+            result.push(...level.errors);
+        }
+        return result;
+    }
+}
+exports.DiscoveryResult = DiscoveryResult;
+//# sourceMappingURL=DiscoveryResult.js.map

package/out/runtime/TreeJson.d.ts

@@ -0,0 +1,40 @@
+import { Node } from "../core/Node";
+/** Canonical JSON representation of a parsed STXT document (STXT-TREE-SPEC). */
+export type CanonicalDocument = CanonicalNode[];
+/** A node in the canonical JSON representation of an STXT document. */
+export type CanonicalNode = CanonicalInlineNode | CanonicalBlockNode;
+/** Canonical representation of an INLINE (`:`) node. */
+export interface CanonicalInlineNode {
+    name: string;
+    canonicalName: string;
+    namespace: string;
+    form: "inline";
+    value: string;
+    children: CanonicalNode[];
+}
+/** Canonical representation of a BLOCK (`>>`) node. */
+export interface CanonicalBlockNode {
+    name: string;
+    canonicalName: string;
+    namespace: string;
+    form: "block";
+    lines: string[];
+}
+/**
+ * Converts every root node of a parsed document to the logical tree defined by
+ * STXT-TREE-SPEC. The result deliberately excludes source positions, indentation
+ * style, comments and derived values such as a qualified name.
+ *
+ * @param nodes root nodes of an already parsed STXT document.
+ * @returns the canonical document tree, ready to be serialized as JSON.
+ */
+export declare function toCanonicalTree(nodes: ReadonlyArray<Node>): CanonicalDocument;
+/**
+ * Serializes the canonical tree of a parsed document as human-readable JSON.
+ * JSON whitespace is not part of STXT-TREE-SPEC; two-space indentation is this
+ * implementation's deterministic presentation for command-line use.
+ *
+ * @param nodes root nodes of an already parsed STXT document.
+ * @returns the canonical document tree encoded as JSON, without a final line break.
+ */
+export declare function toCanonicalJson(nodes: ReadonlyArray<Node>): string;

package/out/runtime/TreeJson.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toCanonicalTree = toCanonicalTree;
+exports.toCanonicalJson = toCanonicalJson;
+/**
+ * Converts every root node of a parsed document to the logical tree defined by
+ * STXT-TREE-SPEC. The result deliberately excludes source positions, indentation
+ * style, comments and derived values such as a qualified name.
+ *
+ * @param nodes root nodes of an already parsed STXT document.
+ * @returns the canonical document tree, ready to be serialized as JSON.
+ */
+function toCanonicalTree(nodes) {
+    return nodes.map(node => toCanonicalNode(node));
+}
+/**
+ * Serializes the canonical tree of a parsed document as human-readable JSON.
+ * JSON whitespace is not part of STXT-TREE-SPEC; two-space indentation is this
+ * implementation's deterministic presentation for command-line use.
+ *
+ * @param nodes root nodes of an already parsed STXT document.
+ * @returns the canonical document tree encoded as JSON, without a final line break.
+ */
+function toCanonicalJson(nodes) {
+    return JSON.stringify(toCanonicalTree(nodes), null, 2);
+}
+function toCanonicalNode(node) {
+    if (node.isTextNode()) {
+        return {
+            name: node.getName(),
+            canonicalName: node.getNormalizedName(),
+            namespace: node.getNamespace(),
+            form: "block",
+            lines: [...node.getTextLines()],
+        };
+    }
+    return {
+        name: node.getName(),
+        canonicalName: node.getNormalizedName(),
+        namespace: node.getNamespace(),
+        form: "inline",
+        value: node.getValue(),
+        children: node.getChildren().map(child => toCanonicalNode(child)),
+    };
+}
+//# sourceMappingURL=TreeJson.js.map

package/out/schema/SchemaProviderMemory.js

@@ -52,9 +52,14 @@ class SchemaProviderMemory {
     addSchema(txt) {
         const parser = new Parser_1.Parser();
         const node = parser.parse(txt)[0];
-        const schema = (0, SchemaParser_1.transformNodeToSchema)(node);
+        // A schema that does not validate against its meta-schema must not be
+        // registered (same policy as UnifiedSchemaProvider/DiscoveryResolver)
         const schemaValidator = new SchemaValidator_1.SchemaValidator(new SchemaProviderMeta_1.SchemaProviderMeta(), true);
-        schemaValidator.validate(node);
+        const errors = schemaValidator.validate(node);
+        if (errors.length > 0) {
+            throw errors[0];
+        }
+        const schema = (0, SchemaParser_1.transformNodeToSchema)(node);
         const key = schema.getNamespace();
         this.schemas.set(key, schema);
     }

package/out/template/TemplateSchemaProviderMemory.d.ts

@@ -18,7 +18,8 @@ export declare class TemplateSchemaProviderMemory extends SchemaProviderMemory {
      *
      * @param template text of the `@stxt.template` document.
      * @throws ValidationException with code `INVALID_SCHEMA` if the document does not hold exactly
-     *         one template, or if the resulting schema has no namespace.
+     *         one template or the resulting schema has no namespace, or the first validation error
+     *         if the template does not validate against the template meta-schema.
      */
     addTemplate(template: string): void;
 }

package/out/template/TemplateSchemaProviderMemory.js

@@ -31,7 +31,8 @@ class TemplateSchemaProviderMemory extends SchemaProviderMemory_1.SchemaProvider
      *
      * @param template text of the `@stxt.template` document.
      * @throws ValidationException with code `INVALID_SCHEMA` if the document does not hold exactly
-     *         one template, or if the resulting schema has no namespace.
+     *         one template or the resulting schema has no namespace, or the first validation error
+     *         if the template does not validate against the template meta-schema.
      */
     addTemplate(template) {
         const parser = new Parser_1.Parser();
@@ -39,9 +40,13 @@ class TemplateSchemaProviderMemory extends SchemaProviderMemory_1.SchemaProvider
         if (nodes.length !== 1) {
             throw new ValidationException_1.ValidationException(0, "INVALID_SCHEMA", `There are ${nodes.length}, and expected is 1`);
         }
-        // Validate the template against the template meta-schema
+        // A template that does not validate against the template meta-schema must not
+        // be registered (same policy as UnifiedSchemaProvider/DiscoveryResolver)
         const schemaValidator = new SchemaValidator_1.SchemaValidator(new MetaTemplateSchemaProvider_1.MetaTemplateSchemaProvider(), true);
-        schemaValidator.validate(nodes[0]);
+        const errors = schemaValidator.validate(nodes[0]);
+        if (errors.length > 0) {
+            throw errors[0];
+        }
         // Build the schema out of the template
         const sch = (0, TemplateParser_1.transformTemplateNodeToSchema)(nodes[0]);
         // Minimum safety check (Java checked the expected namespace here too)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stxt-lang/core",
-  "version": "0.5.3",
+  "version": "0.6.1",
   "description": "Parser and schema validator for STXT, an indentation-based structured-text format.",
   "main": "out/all.js",
   "types": "out/all.d.ts",
@@ -11,6 +11,7 @@
     "out/all.js",
     "out/all.d.ts",
     "out/core",
+    "out/discovery",
     "out/exceptions",
     "out/processors",
     "out/runtime",