@stxt-lang/core 0.5.2 → 0.6.0

package/README.md

@@ -6,6 +6,7 @@ STXT is a plain-text format for writing structured, semantic documents: no brace
 
 - Website and language reference: <https://stxt.dev>
 - VSCode extension: [STXT - Semantic Text](https://marketplace.visualstudio.com/items?itemName=stxt-lang.stxt)
+- Java implementation: [`dev.stxt:stxt-core`](https://central.sonatype.com/artifact/dev.stxt/stxt-core) on Maven Central
 
 ## What STXT looks like
 
@@ -114,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.
@@ -149,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

@@ -18,3 +18,8 @@ export { UnifiedSchemaProvider } from "./runtime/UnifiedSchemaProvider";
 export { ConditionalValidator } from "./runtime/ConditionalValidator";
 export { NodeWriter, IndentStyle } from "./runtime/NodeWriter";
 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

@@ -1,9 +1,9 @@
 "use strict";
-// Punto de entrada público del paquete (out/all.js / out/all.d.ts).
-// Todo lo que deba ser consumible por terceros (p. ej. la extensión VSCode)
-// debe re-exportarse desde aquí.
+// Public entry point of the package (out/all.js / out/all.d.ts).
+// 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.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");
@@ -41,4 +41,10 @@ Object.defineProperty(exports, "NodeWriter", { enumerable: true, get: function (
 Object.defineProperty(exports, "IndentStyle", { enumerable: true, get: function () { return NodeWriter_1.IndentStyle; } });
 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/core/Constants.d.ts

@@ -1,9 +1,17 @@
+/** Characters and sizes fixed by STXT-SPEC that the parser and the writer share. */
 export declare class Constants {
+    /** Character that opens a comment line. */
     static readonly COMMENT_CHAR: string;
+    /** Number of spaces that make up one indentation level. */
     static readonly TAB_SPACES: number;
+    /** Tab character, the other way of indenting one level. */
     static readonly TAB: string;
+    /** Space character. */
     static readonly SPACE: string;
+    /** Separator between the name and the value of an INLINE node. */
     static readonly SEP_NODE: string;
+    /** Marker that turns a node into a BLOCK text node. */
     static readonly SEP_TEXT_NODE: string;
+    /** Namespace of a node that declares none and inherits none. */
     static readonly EMPTY_NAMESPACE: string;
 }

package/out/core/Constants.js

@@ -1,14 +1,22 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Constants = void 0;
+/** Characters and sizes fixed by STXT-SPEC that the parser and the writer share. */
 class Constants {
 }
 exports.Constants = Constants;
+/** Character that opens a comment line. */
 Constants.COMMENT_CHAR = "#";
+/** Number of spaces that make up one indentation level. */
 Constants.TAB_SPACES = 4;
+/** Tab character, the other way of indenting one level. */
 Constants.TAB = "\t";
+/** Space character. */
 Constants.SPACE = " ";
+/** Separator between the name and the value of an INLINE node. */
 Constants.SEP_NODE = ":";
+/** Marker that turns a node into a BLOCK text node. */
 Constants.SEP_TEXT_NODE = ">>";
+/** Namespace of a node that declares none and inherits none. */
 Constants.EMPTY_NAMESPACE = "";
 //# sourceMappingURL=Constants.js.map

package/out/core/Line.d.ts

@@ -1,9 +1,29 @@
+/**
+ * A source line already split into its indentation and its content, as produced by
+ * {@link parseLine}. It is what tells the {@link Parser} whether the line opens a node, continues
+ * a text block or is just a comment.
+ */
 export declare class Line {
+    /** Indentation level of the line (one level per tab or per {@link Constants.TAB_SPACES} spaces). */
     readonly level: number;
+    /** Content of the line with the indentation already removed. */
     readonly content: string;
+    /** True if the line is a comment (`#`). */
     readonly isComment: boolean;
+    /** True if the line is a text line belonging to an open BLOCK node (`>>`). */
     readonly isBlock: boolean;
+    /** Number of characters the indentation took up. */
     readonly indentLength: number;
+    /**
+     * Creates a line already split into indentation and content.
+     *
+     * @param level indentation level of the line.
+     * @param content content of the line without its indentation.
+     * @param isComment true if the line is a comment.
+     * @param isBlock true if the line belongs to an open text block.
+     * @param indentLength number of characters the indentation took up.
+     */
     constructor(level: number, content: string, isComment: boolean, isBlock: boolean, indentLength: number);
+    /** @returns true if the line has no content beyond whitespace. */
     isEmpty(): boolean;
 }

package/out/core/Line.js

@@ -1,7 +1,21 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Line = void 0;
+/**
+ * A source line already split into its indentation and its content, as produced by
+ * {@link parseLine}. It is what tells the {@link Parser} whether the line opens a node, continues
+ * a text block or is just a comment.
+ */
 class Line {
+    /**
+     * Creates a line already split into indentation and content.
+     *
+     * @param level indentation level of the line.
+     * @param content content of the line without its indentation.
+     * @param isComment true if the line is a comment.
+     * @param isBlock true if the line belongs to an open text block.
+     * @param indentLength number of characters the indentation took up.
+     */
     constructor(level, content, isComment, isBlock, indentLength) {
         this.level = level;
         this.content = content;
@@ -9,6 +23,7 @@ class Line {
         this.isBlock = isBlock;
         this.indentLength = indentLength;
     }
+    /** @returns true if the line has no content beyond whitespace. */
     isEmpty() {
         return this.content.trim() === "";
     }

package/out/core/LineParser.d.ts

@@ -1,2 +1,19 @@
 import { Line } from "./Line";
+/**
+ * Splits a source line into its indentation and its content, and classifies it as a comment, a
+ * text line of an open block or a regular line.
+ *
+ * Indentation is one level per tab or per {@link Constants.TAB_SPACES} spaces; mixing both, using
+ * a number of spaces that is not a multiple of four or going more than one level deeper than the
+ * previous node are errors (spec 8.1 and 8.3).
+ *
+ * @param line source line, with its indentation.
+ * @param lastNodeBlock true if the node currently open is a BLOCK text node.
+ * @param lastLevel indentation level of the node currently open.
+ * @param numLine line number, for the error messages.
+ * @param validate false to split the line without enforcing the indentation rules.
+ * @returns the line already split into indentation and content.
+ * @throws ParseException with code `MIXED_INDENTATION`, `INVALID_NUMBER_SPACES` or
+ *         `INDENTATION_LEVEL_NOT_VALID` if the indentation is not valid.
+ */
 export declare function parseLine(line: string, lastNodeBlock: boolean, lastLevel: number, numLine: number, validate?: boolean): Line;

package/out/core/LineParser.js

@@ -5,6 +5,23 @@ const Constants_1 = require("./Constants");
 const StringUtils_1 = require("./StringUtils");
 const ParseException_1 = require("../exceptions/ParseException");
 const Line_1 = require("./Line");
+/**
+ * Splits a source line into its indentation and its content, and classifies it as a comment, a
+ * text line of an open block or a regular line.
+ *
+ * Indentation is one level per tab or per {@link Constants.TAB_SPACES} spaces; mixing both, using
+ * a number of spaces that is not a multiple of four or going more than one level deeper than the
+ * previous node are errors (spec 8.1 and 8.3).
+ *
+ * @param line source line, with its indentation.
+ * @param lastNodeBlock true if the node currently open is a BLOCK text node.
+ * @param lastLevel indentation level of the node currently open.
+ * @param numLine line number, for the error messages.
+ * @param validate false to split the line without enforcing the indentation rules.
+ * @returns the line already split into indentation and content.
+ * @throws ParseException with code `MIXED_INDENTATION`, `INVALID_NUMBER_SPACES` or
+ *         `INDENTATION_LEVEL_NOT_VALID` if the indentation is not valid.
+ */
 function parseLine(line, lastNodeBlock, lastLevel, numLine, validate = true) {
     let level = 0;
     let spaces = 0;
@@ -30,23 +47,23 @@ function parseLine(line, lastNodeBlock, lastLevel, numLine, validate = true) {
             return new Line_1.Line(level, line.substring(pointer + 1), true, false, pointer);
         }
         else {
-            // Primer carácter no espacio/tab/comentario => fin de indentación
+            // First character that is not space/tab/comment => end of indentation
             break;
         }
-        // Dentro del bloque de texto
+        // Inside the text block
         if (lastNodeBlock && level > lastLevel) {
             const text = StringUtils_1.StringUtils.rightTrim(line.substring(pointer + 1));
-            // El prefijo que cubre el nivel de bloque debe ser homogéneo (spec 10.2, regla 2);
-            // las líneas vacías se preservan siempre y quedan exentas (spec 10.3)
+            // The prefix covering the block level must be homogeneous (spec 10.2, rule 2);
+            // empty lines are always preserved and are exempt from it (spec 10.3)
             if (validate && sawSpace && sawTab && text.length > 0) {
                 throw new ParseException_1.ParseException(numLine, "MIXED_INDENTATION", `Mixed tabs and spaces in indentation`);
             }
             return new Line_1.Line(level, text, false, true, pointer);
         }
-        // Aumentamos pointer
+        // Move the pointer forward
         pointer++;
     }
-    // En este punto ya estamos fuera de bloque de texto (si existía)
+    // From here on we are outside the text block (if there was one)
     // Empty
     if (pointer === line.length) {
         if (lastNodeBlock) {
@@ -54,19 +71,19 @@ function parseLine(line, lastNodeBlock, lastLevel, numLine, validate = true) {
         }
         return new Line_1.Line(level, "", false, false, pointer);
     }
-    // Mezcla de espacios y tabuladores en la indentación (spec 8.1 y 8.3)
+    // Tabs and spaces mixed in the indentation (spec 8.1 and 8.3)
     if (validate && sawSpace && sawTab) {
         throw new ParseException_1.ParseException(numLine, "MIXED_INDENTATION", `Mixed tabs and spaces in indentation`);
     }
-    // Indentación no es múltiplo de 4 con espacios
+    // Indentation with spaces that is not a multiple of 4
     if (validate && spaces > 0) {
         throw new ParseException_1.ParseException(numLine, "INVALID_NUMBER_SPACES", `There are ${spaces} spaces before node`);
     }
-    // Validamos level
+    // Validate the level
     if (validate && level > lastLevel + 1) {
         throw new ParseException_1.ParseException(numLine, "INDENTATION_LEVEL_NOT_VALID", `Level of indent incorrect: ${level}`);
     }
-    // Caso general: devolver la línea sin la indentación consumida
+    // General case: return the line without the indentation already consumed
     return new Line_1.Line(level, line.substring(pointer).trim(), false, false, pointer);
 }
 //# sourceMappingURL=LineParser.js.map

package/out/core/NameNamespace.d.ts

@@ -1,7 +1,16 @@
+/** Result of splitting a raw node name into its resolved name and namespace. */
 export declare class NameNamespace {
     private readonly name;
     private readonly namespace;
+    /**
+     * Creates a resolved name and namespace pair.
+     *
+     * @param name name of the node without the namespace part.
+     * @param namespace resolved namespace (its own or inherited).
+     */
     constructor(name: string, namespace: string);
+    /** @returns the name of the node, without the namespace part. */
     getName(): string;
+    /** @returns the resolved namespace (its own or inherited from the parent), or the empty string if it has none. */
     getNamespace(): string;
 }

package/out/core/NameNamespace.js

@@ -1,14 +1,23 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.NameNamespace = void 0;
+/** Result of splitting a raw node name into its resolved name and namespace. */
 class NameNamespace {
+    /**
+     * Creates a resolved name and namespace pair.
+     *
+     * @param name name of the node without the namespace part.
+     * @param namespace resolved namespace (its own or inherited).
+     */
     constructor(name, namespace) {
         this.name = name;
         this.namespace = namespace;
     }
+    /** @returns the name of the node, without the namespace part. */
     getName() {
         return this.name;
     }
+    /** @returns the resolved namespace (its own or inherited from the parent), or the empty string if it has none. */
     getNamespace() {
         return this.namespace;
     }

package/out/core/NameNamespaceParser.d.ts

@@ -1,5 +1,16 @@
 import { NameNamespace } from "./NameNamespace";
+/** Extracts the name and the namespace `(a.b.c)` from the left-hand side of an STXT line. */
 export declare class NameNamespaceParser {
     private constructor();
+    /**
+     * Splits a raw node name into its name and its namespace.
+     *
+     * @param rawName raw name, with the namespace in parentheses if it carries one.
+     * @param inheritedNs namespace inherited from the parent, used when `rawName` brings none of its own.
+     * @param lineNumber line number, for the error messages.
+     * @param fullLine original full line, for the error messages.
+     * @returns the name and the namespace, already split apart and resolved.
+     * @throws ParseException if the name or the namespace are not well formed.
+     */
     static parse(rawName: string | null | undefined, inheritedNs: string | null | undefined, lineNumber: number, fullLine: string): NameNamespace;
 }

package/out/core/NameNamespaceParser.js

@@ -3,9 +3,20 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.NameNamespaceParser = void 0;
 const ParseException_1 = require("../exceptions/ParseException");
 const NameNamespace_1 = require("./NameNamespace");
+/** Extracts the name and the namespace `(a.b.c)` from the left-hand side of an STXT line. */
 class NameNamespaceParser {
     constructor() {
     }
+    /**
+     * Splits a raw node name into its name and its namespace.
+     *
+     * @param rawName raw name, with the namespace in parentheses if it carries one.
+     * @param inheritedNs namespace inherited from the parent, used when `rawName` brings none of its own.
+     * @param lineNumber line number, for the error messages.
+     * @param fullLine original full line, for the error messages.
+     * @returns the name and the namespace, already split apart and resolved.
+     * @throws ParseException if the name or the namespace are not well formed.
+     */
     static parse(rawName, inheritedNs, lineNumber, fullLine) {
         if (rawName === null || rawName === undefined) {
             throw new ParseException_1.ParseException(lineNumber, "INVALID_LINE", `Line not valid: ${fullLine}`);
@@ -15,27 +26,27 @@ class NameNamespaceParser {
         const endIndex = rawName.indexOf(")");
         let name;
         let namespace = inheritedNs ?? "";
-        // Encontrados los dos
+        // Both of them found
         if (startIndex !== -1 && endIndex !== -1) {
             if (startIndex > endIndex || endIndex !== rawName.length - 1) {
                 throw new ParseException_1.ParseException(lineNumber, "INVALID_NAMESPACE", `Line not valid: ${fullLine}`);
             }
             name = rawName.substring(0, startIndex).trim();
-            // Sin trim: la gramática (STXT-SPEC 7/16) no admite espacios dentro de '( )'
+            // No trim: the grammar (STXT-SPEC 7/16) does not allow spaces inside '( )'
             namespace = rawName.substring(startIndex + 1, endIndex);
             if (namespace.length === 0) {
                 throw new ParseException_1.ParseException(lineNumber, "INVALID_NAMESPACE", `Line not valid: ${fullLine}`);
             }
         }
-        // Ninguno de los dos
+        // Neither of them
         else if (startIndex === -1 && endIndex === -1) {
             name = rawName;
         }
-        // Solo uno de los dos
+        // Only one of the two
         else {
             throw new ParseException_1.ParseException(lineNumber, "INVALID_NAMESPACE", `Line not valid: ${fullLine}`);
         }
-        // Retorno
+        // Return
         return new NameNamespace_1.NameNamespace(name, namespace.toLowerCase());
     }
 }

package/out/core/NamespaceValidator.d.ts

@@ -1,4 +1,22 @@
+/** Validates the format of STXT `(a.b.c)` namespaces. */
 export declare class NamespaceValidator {
+    /**
+     * Format of the logical namespace.
+     *
+     * Rules:
+     * - Lower-case letters, digits and dot only.
+     * - It may optionally start with '@'.
+     * - It must be one or more domain-style labels separated by '.':
+     *   label := [a-z0-9]+
+     * valid examples: "xxx", "xxx.ddd", "zzz.ttt.ooo", "@xxx", "@xxx.ddd".
+     */
     private static readonly NAMESPACE_FORMAT;
+    /**
+     * Validates the format of a namespace.
+     *
+     * @param namespace already normalized namespace to validate; ignored when null or empty.
+     * @param lineNumber line number, for the error message.
+     * @throws ParseException with code `INVALID_NAMESPACE` if it does not match the format.
+     */
     static validateNamespaceFormat(namespace: string | null | undefined, lineNumber: number): void;
 }

package/out/core/NamespaceValidator.js

@@ -2,7 +2,15 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.NamespaceValidator = void 0;
 const ParseException_1 = require("../exceptions/ParseException");
+/** Validates the format of STXT `(a.b.c)` namespaces. */
 class NamespaceValidator {
+    /**
+     * Validates the format of a namespace.
+     *
+     * @param namespace already normalized namespace to validate; ignored when null or empty.
+     * @param lineNumber line number, for the error message.
+     * @throws ParseException with code `INVALID_NAMESPACE` if it does not match the format.
+     */
     static validateNamespaceFormat(namespace, lineNumber) {
         if (!namespace) {
             return;
@@ -13,5 +21,15 @@ class NamespaceValidator {
     }
 }
 exports.NamespaceValidator = NamespaceValidator;
+/**
+ * Format of the logical namespace.
+ *
+ * Rules:
+ * - Lower-case letters, digits and dot only.
+ * - It may optionally start with '@'.
+ * - It must be one or more domain-style labels separated by '.':
+ *   label := [a-z0-9]+
+ * valid examples: "xxx", "xxx.ddd", "zzz.ttt.ooo", "@xxx", "@xxx.ddd".
+ */
 NamespaceValidator.NAMESPACE_FORMAT = /^@?[a-z0-9]+(\.[a-z0-9]+)+$/;
 //# sourceMappingURL=NamespaceValidator.js.map

package/out/core/Node.d.ts

@@ -1,3 +1,9 @@
+/**
+ * Node of the STXT tree. Mutable while parsing ({@link Node.addChild}/{@link Node.addTextLine}
+ * are public); once the document is closed it must be treated as read-only. It represents both
+ * INLINE nodes (with {@link Node.getValue}) and BLOCK text nodes (with {@link Node.getTextLines}),
+ * as told apart by {@link Node.isTextNode}.
+ */
 export declare class Node {
     private static readonly VALID_NAME;
     private readonly name;
@@ -9,21 +15,70 @@ export declare class Node {
     private readonly line;
     private readonly level;
     private children;
+    /**
+     * Creates a node with its full position in the document. This is the constructor the
+     * {@link Parser} uses while parsing.
+     *
+     * @param line line number of the document where the node opens.
+     * @param level indentation level of the node (0 for root nodes).
+     * @param name name of the node.
+     * @param namespace namespace of the node, or null/undefined if it has none.
+     * @param textNode true if it is a text block node (BLOCK); false if it is INLINE.
+     * @param value inline value of the node (INLINE node), ignored when it is BLOCK.
+     * @throws ParseException if the name or the namespace are not valid.
+     */
     constructor(line: number, level: number, name: string, namespace: string | null | undefined, textNode: boolean, value: string | null | undefined);
+    /**
+     * Appends a text line to a BLOCK node.
+     *
+     * @param line text line to append to a BLOCK node ({@link Node.isTextNode}).
+     */
     addTextLine(line: string): void;
+    /** @returns the original name of the node as it appears in the document (with spaces compacted). */
     getName(): string;
+    /** @returns the canonical name of the node, used to compare/look up by structural identity. */
     getNormalizedName(): string;
+    /** @returns the canonical name prefixed by its namespace (`namespace:name`), or just the name when there is no namespace. */
     getQualifiedName(): string;
+    /** @returns the effective namespace of the node (its own or inherited from the parent), lower-cased, or the empty string if it has none. */
     getNamespace(): string;
+    /** @returns the children of the node in order of appearance, as a read-only view. */
     getChildren(): ReadonlyArray<Node>;
+    /**
+     * Appends an already closed child to this node.
+     *
+     * @param node already closed child to append at the end of this node's list of children.
+     */
     addChild(node: Node): void;
+    /** @returns the inline value of the node (INLINE node), or the empty string if it is a BLOCK node. */
     getValue(): string;
+    /** @returns the text lines of a BLOCK node ({@link Node.isTextNode}), in order of appearance. */
     getTextLines(): ReadonlyArray<string>;
+    /** @returns the line number of the document where this node was opened. */
     getLine(): number;
+    /** @returns the indentation level of the node (0 for root nodes). */
     getLevel(): number;
+    /** @returns true if the node is a text block (BLOCK, `>>`); false if it is INLINE. */
     isTextNode(): boolean;
+    /** @returns the textual content of the node: the text lines joined with '\n' if it is BLOCK, or the inline value otherwise. */
     getText(): string;
+    /**
+     * Looks up the only direct child with that name.
+     *
+     * @param cname name of the child to look for.
+     * @param namespace namespace to search in; this node's own namespace when omitted.
+     * @returns the only direct child with that name, or null if there is none.
+     * @throws RuntimeException with code `AMBIGUOUS_CHILD` if there is more than one; use {@link Node.getChildrenByName} then.
+     */
     getChild(cname: string, namespace?: string): Node | null;
+    /**
+     * Looks up every direct child with that name.
+     *
+     * @param cname name of the child to look for.
+     * @param namespace namespace to search in; this node's own namespace when omitted.
+     * @returns every direct child with that name in the given namespace, in order of appearance.
+     */
     getChildrenByName(cname: string, namespace?: string): Node[];
+    /** @returns a readable representation of the node, for debugging and error messages. */
     toString(): string;
 }