@stxt-lang/core 0.5.2 → 0.6.0

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/exceptions/ParseException.d.ts

@@ -1,6 +1,20 @@
+/**
+ * Syntax error detected while parsing (lexical/structural phase, not schema). Every exception
+ * carries an UPPERCASE code and the line of the document where it was detected.
+ */
 export declare class ParseException extends Error {
+    /** Line number of the document where the error was detected. */
     readonly line: number;
+    /** Error code in UPPERCASE (e.g. `INVALID_LINE`). */
     readonly code: string;
+    /**
+     * Creates a syntax error located at a line of the document.
+     *
+     * @param line line number where the error was detected.
+     * @param code error code in UPPERCASE.
+     * @param message descriptive message.
+     */
     constructor(line: number, code: string, message: string);
+    /** @returns a readable representation of the error, with its line and its code. */
     toString(): string;
 }