@stxt-lang/core 0.12.0 → 0.14.0

package/README.md

@@ -281,6 +281,33 @@ parser.registerObserver(new LoggingObserver());
 parser.parseResult(text);
 ```
 
+`StreamObserver` watches the results instead of the process: each completed root node and each
+error, in every mode. With `parseStream` the parser retains nothing — no nodes, no errors — so a
+file larger than memory can be processed one root tree at a time:
+
+```ts
+import { Parser, StreamObserver, Node, ParseException } from '@stxt-lang/core';
+
+const parser = new Parser();
+parser.registerStreamObserver({
+    onRootNode(node: Node): void { handle(node); },       // one complete root at a time
+    onError(error: ParseException): void { report(error); },
+} satisfies StreamObserver);
+parser.parseStream(readLinesLazily(file));  // any Iterable<string> of lines
+```
+
+## Parser limits
+
+The parser rejects hostile or runaway inputs by default (STXT-SPEC §11.2): documents nesting
+more than 100 levels, lines longer than 10 000 characters, or inputs over 10 000 000
+characters. A limit error is a `LimitException` (`LIMIT_NESTING_EXCEEDED`,
+`LIMIT_LINE_LENGTH_EXCEEDED`, `LIMIT_INPUT_SIZE_EXCEEDED`) and aborts the parse: it is always
+the last error reported. Each limit is configurable per parser; `-1` disables it:
+
+```ts
+const parser = new Parser({ maxNesting: 500, maxInputSize: -1 });
+```
+
 ## Writing STXT back out
 
 ```ts
@@ -311,14 +338,18 @@ if (errors.length === 0) {
 
 Everything importable from the package:
 
-- **Parsing** — `Node`, `InlineNode`, `TextNode`, `Parser`, `ParseResult`, `Line`, `Constants`, `parseLine`, `StringUtils`
-- **Exceptions** — `ParseException`, `ValidationException`, `RuntimeException`
-- **Extension points** — `Observer`, `Validator`
+- **Parsing** — `Node`, `InlineNode`, `TextNode`, `Parser`, `ParserOptions`, `ParseResult`, `Line`, `Constants`, `parseLine`, `StringUtils`
+- **Exceptions** — `ParseException`, `ValidationException`, `LimitException`, `RuntimeException`
+- **Extension points** — `Observer`, `StreamObserver`, `Validator`
 - **Schemas** — `Schema`, `SchemaValidator`, `SchemaProvider`, `SchemaProviderMemory`, `SchemaProviderMeta`, `NodeDefinition`, `ChildDefinition`, `TypeRegistry`, `Type`, `transformNodeToSchema`
 - **Templates** — `transformTemplateNodeToSchema`, `TEMPLATE_NAMESPACE`, `TemplateSchemaProviderMemory`, `MetaTemplateSchemaProvider`
 - **Runtime** — `UnifiedSchemaProvider`, `NodeWriter`, `IndentStyle`, `Formatter`, `FormatResult`, `toCanonicalTree`, `toCanonicalJson`
 - **Discovery** — `DiscoveryResolver`, `DiscoveryOptions`, `DiscoveryResult`, `DiscoveryDefinition`, `DiscoveryLevel`, `DiscoveryError`, `DiscoveryFileSystem`, `DiscoveryEntry`, `DiscoveryEnvironment`
 
+## Conformance
+
+`@stxt-lang/core` implements the five STXT specifications at `SPEC_VERSION` (exposed by the package; the package version is independent) and passes every case of the official conformance kit, [`stxt-lang/conformance`](https://github.com/stxt-lang/stxt-lang/tree/master/conformance), across all its profiles: `core`, `schema`, `template`, `discovery` and `text`. The kit is the same one any other implementation can run, which is what makes the three ports interchangeable. What the 1.0 line freezes, and what it does not, is stated at <https://stxt.dev/lang-stability>.
+
 ## License
 
 MIT — see [LICENSE](LICENSE).

package/out/all.d.ts

@@ -1,7 +1,7 @@
 export { Node } from "./core/Node";
 export { InlineNode } from "./core/InlineNode";
 export { TextNode } from "./core/TextNode";
-export { Parser } from "./core/Parser";
+export { Parser, ParserOptions } from "./core/Parser";
 export { ParseResult } from "./core/ParseResult";
 export { Line } from "./core/Line";
 export { Constants } from "./core/Constants";
@@ -15,8 +15,10 @@ export { parseLine } from "./core/LineParser";
 export { StringUtils } from "./core/StringUtils";
 export { ParseException } from "./exceptions/ParseException";
 export { ValidationException } from "./exceptions/ValidationException";
+export { LimitException } from "./exceptions/LimitException";
 export { RuntimeException } from "./exceptions/RuntimeException";
 export { Observer } from "./processors/Observer";
+export { StreamObserver } from "./processors/StreamObserver";
 export { Validator } from "./processors/Validator";
 export { Schema } from "./schema/Schema";
 export { SchemaValidator } from "./schema/SchemaValidator";

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.DiscoveryError = exports.DiscoveryResult = exports.DiscoveryResolver = exports.MetaTemplateSchemaProvider = exports.TemplateSchemaProviderMemory = exports.TEMPLATE_NAMESPACE = exports.transformTemplateNodeToSchema = exports.toCanonicalJson = exports.toCanonicalTree = exports.Formatter = exports.IndentStyle = exports.NodeWriter = exports.UnifiedSchemaProvider = exports.transformNodeToSchema = exports.ChildDefinition = exports.NodeDefinition = exports.TypeRegistry = exports.SchemaProviderMeta = exports.SchemaProviderMemory = exports.SchemaValidator = exports.Schema = exports.RuntimeException = exports.ValidationException = exports.ParseException = exports.StringUtils = exports.parseLine = exports.SPEC_VERSION = exports.Constants = exports.Line = exports.ParseResult = exports.Parser = exports.TextNode = exports.InlineNode = exports.Node = void 0;
+exports.DiscoveryError = exports.DiscoveryResult = exports.DiscoveryResolver = exports.MetaTemplateSchemaProvider = exports.TemplateSchemaProviderMemory = exports.TEMPLATE_NAMESPACE = exports.transformTemplateNodeToSchema = exports.toCanonicalJson = exports.toCanonicalTree = exports.Formatter = exports.IndentStyle = exports.NodeWriter = exports.UnifiedSchemaProvider = exports.transformNodeToSchema = exports.ChildDefinition = exports.NodeDefinition = exports.TypeRegistry = exports.SchemaProviderMeta = exports.SchemaProviderMemory = exports.SchemaValidator = exports.Schema = exports.RuntimeException = exports.LimitException = exports.ValidationException = exports.ParseException = exports.StringUtils = exports.parseLine = exports.SPEC_VERSION = exports.Constants = exports.Line = exports.ParseResult = exports.Parser = exports.TextNode = exports.InlineNode = exports.Node = void 0;
 var Node_1 = require("./core/Node");
 Object.defineProperty(exports, "Node", { enumerable: true, get: function () { return Node_1.Node; } });
 var InlineNode_1 = require("./core/InlineNode");
@@ -33,6 +33,8 @@ var ParseException_1 = require("./exceptions/ParseException");
 Object.defineProperty(exports, "ParseException", { enumerable: true, get: function () { return ParseException_1.ParseException; } });
 var ValidationException_1 = require("./exceptions/ValidationException");
 Object.defineProperty(exports, "ValidationException", { enumerable: true, get: function () { return ValidationException_1.ValidationException; } });
+var LimitException_1 = require("./exceptions/LimitException");
+Object.defineProperty(exports, "LimitException", { enumerable: true, get: function () { return LimitException_1.LimitException; } });
 var RuntimeException_1 = require("./exceptions/RuntimeException");
 Object.defineProperty(exports, "RuntimeException", { enumerable: true, get: function () { return RuntimeException_1.RuntimeException; } });
 var Schema_1 = require("./schema/Schema");

package/out/core/Constants.d.ts

@@ -22,4 +22,19 @@ export declare class Constants {
     static readonly SEP_TEXT_NODE: string;
     /** Namespace of a node that declares none and inherits none. */
     static readonly EMPTY_NAMESPACE: string;
+    /**
+     * Default maximum open nesting levels (STXT-SPEC §11.2); level 0 is the first. Configure it
+     * per parser with {@link ParserOptions.maxNesting}; -1 disables the limit.
+     */
+    static readonly DEFAULT_MAX_NESTING: number;
+    /**
+     * Default maximum length of one input line, indentation included (STXT-SPEC §11.2).
+     * Configure it per parser with {@link ParserOptions.maxLineLength}; -1 disables the limit.
+     */
+    static readonly DEFAULT_MAX_LINE_LENGTH: number;
+    /**
+     * Default maximum total input consumed (STXT-SPEC §11.2). Configure it per parser with
+     * {@link ParserOptions.maxInputSize}; -1 disables the limit.
+     */
+    static readonly DEFAULT_MAX_INPUT_SIZE: number;
 }

package/out/core/Constants.js

@@ -27,4 +27,19 @@ Constants.SEP_NODE = ":";
 Constants.SEP_TEXT_NODE = ">>";
 /** Namespace of a node that declares none and inherits none. */
 Constants.EMPTY_NAMESPACE = "";
+/**
+ * Default maximum open nesting levels (STXT-SPEC §11.2); level 0 is the first. Configure it
+ * per parser with {@link ParserOptions.maxNesting}; -1 disables the limit.
+ */
+Constants.DEFAULT_MAX_NESTING = 100;
+/**
+ * Default maximum length of one input line, indentation included (STXT-SPEC §11.2).
+ * Configure it per parser with {@link ParserOptions.maxLineLength}; -1 disables the limit.
+ */
+Constants.DEFAULT_MAX_LINE_LENGTH = 10000;
+/**
+ * Default maximum total input consumed (STXT-SPEC §11.2). Configure it per parser with
+ * {@link ParserOptions.maxInputSize}; -1 disables the limit.
+ */
+Constants.DEFAULT_MAX_INPUT_SIZE = 10000000;
 //# sourceMappingURL=Constants.js.map

package/out/core/Parser.d.ts

@@ -1,21 +1,64 @@
 import { Node } from "./Node";
 import { Observer } from "../processors/Observer";
+import { StreamObserver } from "../processors/StreamObserver";
 import { Validator } from "../processors/Validator";
 import { ParseResult } from "./ParseResult";
+/**
+ * Parser limits (STXT-SPEC §11.2), configurable per {@link Parser}. Every limit defaults to
+ * the `DEFAULT_MAX_*` value of {@link Constants}, and -1 disables it. Lengths are measured in
+ * UTF-16 units (`string.length`); for ASCII content they equal characters.
+ */
+export interface ParserOptions {
+    /** Maximum open nesting levels; level 0 is the first. Default {@link Constants.DEFAULT_MAX_NESTING}; -1 disables. */
+    maxNesting?: number;
+    /** Maximum length of one input line, indentation included. Default {@link Constants.DEFAULT_MAX_LINE_LENGTH}; -1 disables. */
+    maxLineLength?: number;
+    /** Maximum total input consumed. Default {@link Constants.DEFAULT_MAX_INPUT_SIZE}; -1 disables. */
+    maxInputSize?: number;
+}
 /**
  * Line-by-line STXT parsing engine. It knows nothing about schemas: semantic validation is
- * plugged in through {@link Parser.registerValidator} and {@link Parser.registerObserver}.
- * See {@link UnifiedSchemaProvider} for the usual way of building the validators to register.
+ * plugged in through {@link Parser.registerValidator}, process observation through
+ * {@link Parser.registerObserver} and result observation through
+ * {@link Parser.registerStreamObserver}. See {@link UnifiedSchemaProvider} for the usual way
+ * of building the validators to register.
+ *
+ * Three entry points share one traversal: {@link Parser.parse} (fail-fast),
+ * {@link Parser.parseResult} (multi-error) and {@link Parser.parseStream} (line iterator in,
+ * nothing retained). Which callbacks fire never depends on the entry point, only on what is
+ * registered.
+ *
+ * The parser aborts on inputs that exceed its limits (STXT-SPEC §11.2), set to the
+ * `DEFAULT_MAX_*` values of {@link Constants} unless configured through {@link ParserOptions}.
+ * A limit error is a {@link LimitException} and is in every case the last one emitted: the
+ * nodes still open are not closed nor notified.
  */
 export declare class Parser {
     private observers;
+    private streamObservers;
     private validators;
+    private readonly maxNesting;
+    private readonly maxLineLength;
+    private readonly maxInputSize;
+    /**
+     * Creates a parser, optionally with its own limits.
+     *
+     * @param options the {@link ParserOptions} limits; every omitted one takes its default.
+     */
+    constructor(options?: ParserOptions);
     /**
      * Registers an observer, notified when each node is opened and closed.
      *
      * @param observer the {@link Observer} to register, notified while parsing.
      */
     registerObserver(observer: Observer): void;
+    /**
+     * Registers a stream observer, notified with each completed root node and each error, in
+     * every mode.
+     *
+     * @param streamObserver the {@link StreamObserver} to register.
+     */
+    registerStreamObserver(streamObserver: StreamObserver): void;
     /**
      * Registers a validator, invoked when each node is closed.
      *
@@ -34,12 +77,29 @@ export declare class Parser {
     parse(content: string): Node[];
     /**
      * Multi-error mode: parses the whole content collecting every error found (both syntax and
-     * validation) without bailing out on the first one. See {@link ParseResult}.
+     * validation) without bailing out on the first one — except a {@link LimitException}, which
+     * aborts and is in every case the last error collected. See {@link ParseResult}.
      *
      * @param content the whole STXT document to parse.
      * @returns the collected result, with the root nodes obtained and every error found.
      */
     parseResult(content: string): ParseResult;
+    /**
+     * Streaming mode: input from a line iterable (each item one line, without its line break —
+     * e.g. a generator over a file read lazily), and nothing retained: no nodes, no errors.
+     * Results reach the program only through the registered {@link StreamObserver}s (each
+     * completed root by `onRootNode()`, each error by `onError()`), so memory holds one root
+     * tree at a time. This is the entry point for files that do not fit in memory.
+     *
+     * @param lines the input, line by line.
+     */
+    parseStream(lines: Iterable<string>): void;
+    /**
+     * Shared traversal. With a result, roots and errors are collected into it
+     * (parse/parseResult); with null, nothing is retained (parseStream). Either way every
+     * registered callback fires the same.
+     */
+    private parseLines;
     private processLine;
     /**
      * Records an error raised while parsing or validating a line. Typed exceptions travel as they
@@ -47,6 +107,11 @@ export declare class Parser {
      * when it was raised by a validator, so that the subtype still tells the phase apart).
      */
     private handleError;
+    /**
+     * Every error goes through here: collected into the result when there is one, and notified
+     * to the stream observers always, in order of appearance.
+     */
+    private emitError;
     private closeToLevel;
     private removeUTF8BOM;
 }

package/out/core/Parser.js

@@ -4,18 +4,41 @@ exports.Parser = void 0;
 const TextNode_1 = require("./TextNode");
 const LineParser_1 = require("./LineParser");
 const NodeCreator_1 = require("./NodeCreator");
+const Constants_1 = require("./Constants");
 const ParseResult_1 = require("./ParseResult");
 const ParseException_1 = require("../exceptions/ParseException");
 const ValidationException_1 = require("../exceptions/ValidationException");
+const LimitException_1 = require("../exceptions/LimitException");
 /**
  * Line-by-line STXT parsing engine. It knows nothing about schemas: semantic validation is
- * plugged in through {@link Parser.registerValidator} and {@link Parser.registerObserver}.
- * See {@link UnifiedSchemaProvider} for the usual way of building the validators to register.
+ * plugged in through {@link Parser.registerValidator}, process observation through
+ * {@link Parser.registerObserver} and result observation through
+ * {@link Parser.registerStreamObserver}. See {@link UnifiedSchemaProvider} for the usual way
+ * of building the validators to register.
+ *
+ * Three entry points share one traversal: {@link Parser.parse} (fail-fast),
+ * {@link Parser.parseResult} (multi-error) and {@link Parser.parseStream} (line iterator in,
+ * nothing retained). Which callbacks fire never depends on the entry point, only on what is
+ * registered.
+ *
+ * The parser aborts on inputs that exceed its limits (STXT-SPEC §11.2), set to the
+ * `DEFAULT_MAX_*` values of {@link Constants} unless configured through {@link ParserOptions}.
+ * A limit error is a {@link LimitException} and is in every case the last one emitted: the
+ * nodes still open are not closed nor notified.
  */
 class Parser {
-    constructor() {
+    /**
+     * Creates a parser, optionally with its own limits.
+     *
+     * @param options the {@link ParserOptions} limits; every omitted one takes its default.
+     */
+    constructor(options) {
         this.observers = [];
+        this.streamObservers = [];
         this.validators = [];
+        this.maxNesting = options?.maxNesting ?? Constants_1.Constants.DEFAULT_MAX_NESTING;
+        this.maxLineLength = options?.maxLineLength ?? Constants_1.Constants.DEFAULT_MAX_LINE_LENGTH;
+        this.maxInputSize = options?.maxInputSize ?? Constants_1.Constants.DEFAULT_MAX_INPUT_SIZE;
     }
     /**
      * Registers an observer, notified when each node is opened and closed.
@@ -25,6 +48,15 @@ class Parser {
     registerObserver(observer) {
         this.observers.push(observer);
     }
+    /**
+     * Registers a stream observer, notified with each completed root node and each error, in
+     * every mode.
+     *
+     * @param streamObserver the {@link StreamObserver} to register.
+     */
+    registerStreamObserver(streamObserver) {
+        this.streamObservers.push(streamObserver);
+    }
     /**
      * Registers a validator, invoked when each node is closed.
      *
@@ -52,37 +84,76 @@ class Parser {
     }
     /**
      * Multi-error mode: parses the whole content collecting every error found (both syntax and
-     * validation) without bailing out on the first one. See {@link ParseResult}.
+     * validation) without bailing out on the first one — except a {@link LimitException}, which
+     * aborts and is in every case the last error collected. See {@link ParseResult}.
      *
      * @param content the whole STXT document to parse.
      * @returns the collected result, with the root nodes obtained and every error found.
      */
     parseResult(content) {
-        content = this.removeUTF8BOM(content);
         const result = new ParseResult_1.ParseResult();
-        const stack = [];
-        const documents = [];
-        let lineNumber = 0;
         const lines = content.split(/\r?\n/);
         // The final line break terminates the last line, it is not an extra empty line
         // (this avoids adding a spurious line to a >> block at EOF, spec 10.3)
         if (lines.length > 0 && lines[lines.length - 1] === "") {
             lines.pop();
         }
-        for (const line of lines) {
+        this.parseLines(lines, result);
+        return result;
+    }
+    /**
+     * Streaming mode: input from a line iterable (each item one line, without its line break —
+     * e.g. a generator over a file read lazily), and nothing retained: no nodes, no errors.
+     * Results reach the program only through the registered {@link StreamObserver}s (each
+     * completed root by `onRootNode()`, each error by `onError()`), so memory holds one root
+     * tree at a time. This is the entry point for files that do not fit in memory.
+     *
+     * @param lines the input, line by line.
+     */
+    parseStream(lines) {
+        this.parseLines(lines, null);
+    }
+    /**
+     * Shared traversal. With a result, roots and errors are collected into it
+     * (parse/parseResult); with null, nothing is retained (parseStream). Either way every
+     * registered callback fires the same.
+     */
+    parseLines(lines, result) {
+        const stack = [];
+        let lineNumber = 0;
+        let consumed = 0;
+        for (let line of lines) {
             lineNumber++;
-            this.processLine(line, lineNumber, stack, documents, result);
+            // A UTF-8 BOM only means anything at the very start of the input (spec 3)
+            if (lineNumber === 1) {
+                line = this.removeUTF8BOM(line);
+            }
+            // Limits first (spec 11.2): a limit error aborts, leaving the open nodes
+            // unclosed and unnotified.
+            if (this.maxLineLength !== -1 && line.length > this.maxLineLength) {
+                this.emitError(new LimitException_1.LimitException(lineNumber, "LIMIT_LINE_LENGTH_EXCEEDED", `Line longer than ${this.maxLineLength} characters`), result);
+                return;
+            }
+            consumed += line.length + 1; // the line separator counts as one
+            if (this.maxInputSize !== -1 && consumed > this.maxInputSize) {
+                this.emitError(new LimitException_1.LimitException(lineNumber, "LIMIT_INPUT_SIZE_EXCEEDED", `Input larger than ${this.maxInputSize} characters`), result);
+                return;
+            }
+            try {
+                this.processLine(line, lineNumber, stack, result);
+            }
+            catch (e) {
+                if (e instanceof LimitException_1.LimitException) {
+                    this.emitError(e, result);
+                    return;
+                }
+                throw e;
+            }
         }
         // Close every node still open at EOF
         this.closeToLevel(stack, 0, result);
-        // Add the nodes to the result
-        for (const doc of documents) {
-            result.addNode(doc);
-        }
-        // Return the result
-        return result;
     }
-    processLine(lineString, lineNumber, stack, documents, result) {
+    processLine(lineString, lineNumber, stack, result) {
         try {
             const lastNode = stack.length === 0 ? null : stack[stack.length - 1];
             // The stack holds the open nodes, one per level: its size is the level of the next line's parent
@@ -123,18 +194,22 @@ class Parser {
             if (line.isEmpty()) {
                 return;
             }
+            // Nesting limit (spec 11.2): only a node line can open a new level. Comment and
+            // block text lines returned above; with the consecutive-level rule this triggers
+            // exactly when the first node at level maxNesting opens.
+            if (this.maxNesting !== -1 && currentLevel >= this.maxNesting) {
+                throw new LimitException_1.LimitException(lineNumber, "LIMIT_NESTING_EXCEEDED", `Nesting deeper than ${this.maxNesting} levels`);
+            }
             // Close the nodes down to the current level (this "finishes" them: validators and observers run)
             this.closeToLevel(stack, currentLevel, result);
-            // Create the new node, attach it to its parent (or to the documents if it is a root)
-            // and leave it "open" on the stack. Attaching links both ends: the node already knows
-            // its parent, and so its effective namespace and its level, when the observers see it.
-            // The parent is always an InlineNode: a TextNode on top of the stack only takes text lines.
+            // Create the new node, attach it to its parent (or keep it as a root if the stack is
+            // empty) and leave it "open" on the stack. Attaching links both ends: the node already
+            // knows its parent, and so its effective namespace and its level, when the observers
+            // see it. The parent is always an InlineNode: a TextNode on top of the stack only
+            // takes text lines.
             const parent = stack.length === 0 ? null : stack[stack.length - 1];
             const node = (0, NodeCreator_1.createNode)(line, lineNumber);
-            if (parent === null) {
-                documents.push(node);
-            }
-            else {
+            if (parent !== null) {
                 parent.addChild(node);
             }
             // Hand it over to the observers
@@ -145,6 +220,9 @@ class Parser {
             stack.push(node);
         }
         catch (e) {
+            if (e instanceof LimitException_1.LimitException) {
+                throw e;
+            }
             this.handleError(e, lineNumber, result);
         }
     }
@@ -155,15 +233,27 @@ class Parser {
      */
     handleError(e, line, result, validating = false) {
         if (e instanceof ParseException_1.ParseException) {
-            result.addError(e);
+            this.emitError(e, result);
         }
         else {
             const message = e instanceof Error ? e.message : String(e);
-            result.addError(validating
+            this.emitError(validating
                 ? new ValidationException_1.ValidationException(line, "UNEXPECTED_ERROR", message)
-                : new ParseException_1.ParseException(line, "UNEXPECTED_ERROR", message));
+                : new ParseException_1.ParseException(line, "UNEXPECTED_ERROR", message), result);
         }
     }
+    /**
+     * Every error goes through here: collected into the result when there is one, and notified
+     * to the stream observers always, in order of appearance.
+     */
+    emitError(error, result) {
+        if (result !== null) {
+            result.addError(error);
+        }
+        this.streamObservers.forEach(streamObserver => {
+            streamObserver.onError(error);
+        });
+    }
     closeToLevel(stack, targetLevel, result) {
         while (stack.length > targetLevel) {
             const completed = stack.pop();
@@ -172,7 +262,7 @@ class Parser {
                 try {
                     const errors = validator.validate(completed);
                     errors.forEach(error => {
-                        result.addError(error);
+                        this.emitError(error, result);
                     });
                 }
                 catch (e) {
@@ -183,6 +273,15 @@ class Parser {
             this.observers.forEach(observer => {
                 observer.onFinish(completed);
             });
+            // A closed root: the stream observers receive it, the result collects it
+            if (stack.length === 0) {
+                this.streamObservers.forEach(streamObserver => {
+                    streamObserver.onRootNode(completed);
+                });
+                if (result !== null) {
+                    result.addNode(completed);
+                }
+            }
         }
     }
     removeUTF8BOM(content) {

package/out/exceptions/LimitException.d.ts

@@ -0,0 +1,17 @@
+import { ParseException } from "./ParseException";
+/**
+ * A parser limit exceeded (STXT-SPEC §11.2): nesting depth, line length or input size. Unlike
+ * any other parse error it aborts the parse: it is emitted and no further input is processed,
+ * in every mode, so it is always the last error. Exceeding a limit does not make the document
+ * invalid: the same document may parse under higher limits (see {@link ParserOptions}).
+ */
+export declare class LimitException extends ParseException {
+    /**
+     * Creates a limit error located at a line of the document.
+     *
+     * @param line line number where the limit was exceeded.
+     * @param code error code in UPPERCASE (`LIMIT_*`).
+     * @param message descriptive message.
+     */
+    constructor(line: number, code: string, message: string);
+}

package/out/exceptions/LimitException.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LimitException = void 0;
+const ParseException_1 = require("./ParseException");
+/**
+ * A parser limit exceeded (STXT-SPEC §11.2): nesting depth, line length or input size. Unlike
+ * any other parse error it aborts the parse: it is emitted and no further input is processed,
+ * in every mode, so it is always the last error. Exceeding a limit does not make the document
+ * invalid: the same document may parse under higher limits (see {@link ParserOptions}).
+ */
+class LimitException extends ParseException_1.ParseException {
+    /**
+     * Creates a limit error located at a line of the document.
+     *
+     * @param line line number where the limit was exceeded.
+     * @param code error code in UPPERCASE (`LIMIT_*`).
+     * @param message descriptive message.
+     */
+    constructor(line, code, message) {
+        super(line, code, message);
+        this.name = "LimitException";
+        Object.setPrototypeOf(this, LimitException.prototype);
+    }
+}
+exports.LimitException = LimitException;
+//# sourceMappingURL=LimitException.js.map

package/out/processors/StreamObserver.d.ts

@@ -0,0 +1,35 @@
+import { Node } from "../core/Node";
+import { ParseException } from "../exceptions/ParseException";
+/**
+ * Process hook notified by the {@link Parser} with the stream of results a parse emits: each
+ * completed root node, and every error. It complements {@link Observer}, which watches the
+ * process line by line: a StreamObserver only sees finished roots and errors, so a consumer
+ * that processes a document root by root never has to ask a node for its level. Register it
+ * with {@link Parser.registerStreamObserver}; a class may implement {@link Observer},
+ * StreamObserver or both.
+ *
+ * It fires in every entry point — `parse()`, `parseResult()` and `parseStream()` — exactly the
+ * same way; what `parseStream()` adds is that the parser retains nothing, so there these
+ * callbacks are the only way to get the results.
+ */
+export interface StreamObserver {
+    /**
+     * Called when a root (level 0) node is closed, with its whole subtree already complete —
+     * children, values, text lines — and its validators already run. In
+     * {@link Parser.parseStream} the parser releases the node right after this call, so the
+     * memory in use is one root tree at a time.
+     *
+     * @param node the completed root node. Do not modify it.
+     */
+    onRootNode(node: Node): void;
+    /**
+     * Called for every error found (syntax or validation), in order of appearance. Parsing
+     * continues with the next line, except for `LIMIT_*` errors ({@link LimitException},
+     * STXT-SPEC §11.2), which abort the parse right after this call. In fail-fast
+     * {@link Parser.parse} the observer still sees every error before the first one is thrown,
+     * because `parse()` reuses the `parseResult()` traversal.
+     *
+     * @param error the error found.
+     */
+    onError(error: ParseException): void;
+}

package/out/processors/StreamObserver.js

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

package/out/runtime/Formatter.d.ts

@@ -46,8 +46,9 @@ export interface FormatResult {
  *   new style; the remainder only survives in documents with errors, which this conversion
  *   neither repairs nor hides.
  *
- * The result is idempotent, round-trips between the two styles, and produces the same canonical
- * tree (STXT-TREE-SPEC) as the source. The document is parsed without any schema: formatting
+ * These are the rules of STXT-TREE-SPEC 12 (`stxt-impl/core/formatter.txt`). The result is
+ * idempotent, round-trips between the two styles, and produces the same canonical tree as the
+ * source; an initial BOM is removed. The document is parsed without any schema: formatting
  * has nothing to do with validation.
  */
 export declare class Formatter {

package/out/runtime/Formatter.js

@@ -37,8 +37,9 @@ const NodeWriter_1 = require("./NodeWriter");
  *   new style; the remainder only survives in documents with errors, which this conversion
  *   neither repairs nor hides.
  *
- * The result is idempotent, round-trips between the two styles, and produces the same canonical
- * tree (STXT-TREE-SPEC) as the source. The document is parsed without any schema: formatting
+ * These are the rules of STXT-TREE-SPEC 12 (`stxt-impl/core/formatter.txt`). The result is
+ * idempotent, round-trips between the two styles, and produces the same canonical tree as the
+ * source; an initial BOM is removed. The document is parsed without any schema: formatting
  * has nothing to do with validation.
  */
 class Formatter {
@@ -51,6 +52,10 @@ class Formatter {
      * @returns the formatted text and the syntax errors found; see {@link FormatResult}.
      */
     static format(text, style = NodeWriter_1.IndentStyle.TABS) {
+        // STXT-TREE-SPEC 12.1: an initial BOM is not kept
+        if (text.startsWith("\uFEFF")) {
+            text = text.substring(1);
+        }
         const sourceLines = new SourceLines();
         const parser = new Parser_1.Parser();
         parser.registerObserver(sourceLines);

package/out/runtime/NodeWriter.d.ts

@@ -25,6 +25,13 @@ export declare class NodeWriter {
      * @returns the documents serialized to STXT text.
      */
     static toSTXTDocs(docs: ReadonlyArray<Node>, style?: IndentStyle): string;
+    /**
+     * Writes one node and, recursively, its children, in the canonical text form of
+     * STXT-TREE-SPEC 11.1.
+     *
+     * @param parentNs effective namespace of the parent, "" for a root: the namespace is
+     *        written only where it changes (rule 3), regardless of where the source declared it.
+     */
     private static writeNode;
     private static indent;
 }

package/out/runtime/NodeWriter.js

@@ -23,7 +23,7 @@ class NodeWriter {
      */
     static toSTXT(node, style = IndentStyle.TABS) {
         const out = [];
-        NodeWriter.writeNode(out, node, 0, style);
+        NodeWriter.writeNode(out, node, 0, style, "");
         return out.join("");
     }
     /**
@@ -39,17 +39,22 @@ class NodeWriter {
             if (i > 0) {
                 out.push("\n");
             }
-            NodeWriter.writeNode(out, docs[i], 0, style);
+            NodeWriter.writeNode(out, docs[i], 0, style, "");
         }
         return out.join("");
     }
-    static writeNode(out, n, depth, style) {
+    /**
+     * Writes one node and, recursively, its children, in the canonical text form of
+     * STXT-TREE-SPEC 11.1.
+     *
+     * @param parentNs effective namespace of the parent, "" for a root: the namespace is
+     *        written only where it changes (rule 3), regardless of where the source declared it.
+     */
+    static writeNode(out, n, depth, style, parentNs) {
         NodeWriter.indent(out, depth, style);
-        // The namespace is written where the node declares it; inherited ones are implicit,
-        // exactly as in the source (the effective namespace is the same either way)
-        const ns = n.getDeclaredNamespace();
+        const ns = n.getNamespace();
         out.push(n.getName());
-        if (ns.length > 0) {
+        if (ns !== parentNs) {
             out.push(" (", ns, ")");
         }
         if (n instanceof TextNode_1.TextNode) {
@@ -67,7 +72,7 @@ class NodeWriter {
             }
             out.push("\n");
             for (const child of n.getChildren()) {
-                NodeWriter.writeNode(out, child, depth + 1, style);
+                NodeWriter.writeNode(out, child, depth + 1, style, ns);
             }
         }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stxt-lang/core",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "description": "Parser and schema validator for STXT, an indentation-based structured-text format.",
   "main": "out/all.js",
   "types": "out/all.d.ts",
@@ -20,7 +20,8 @@
     "!out/**/*.js.map"
   ],
   "scripts": {
-    "build": "tsc",
+    "clean": "node -e \"require('node:fs').rmSync('out', { recursive: true, force: true })\"",
+    "build": "npm run clean && tsc",
     "watch": "tsc --watch",
     "lint": "eslint src --ext .ts",
     "prepare": "npm run build",

package/out/runtime/ConditionalValidator.d.ts

@@ -1,28 +0,0 @@
-import { Node } from "../core/Node";
-import { Validator } from "../processors/Validator";
-import { SchemaValidator } from "../schema/SchemaValidator";
-import { ValidationException } from "../exceptions/ValidationException";
-/**
- * Wrapper around a {@link SchemaValidator} that only validates namespaced nodes, so that a
- * document mixing schema-bound and free nodes does not report the free ones as unknown.
- *
- * @deprecated since 0.8.0: {@link SchemaValidator} applies this rule itself (STXT-SCHEMA-SPEC 5,
- * the empty namespace is never validated), so the wrapper adds nothing. Register the
- * `SchemaValidator` directly. Kept for compatibility; to be removed in 1.0.
- */
-export declare class ConditionalValidator implements Validator {
-    private readonly schemaValidator;
-    /**
-     * Creates a validator that delegates to a schema validator.
-     *
-     * @param schemaValidator validator the namespaced nodes are handed over to.
-     */
-    constructor(schemaValidator: SchemaValidator);
-    /**
-     * Validates a node when it has a namespace, and lets it through otherwise.
-     *
-     * @param node already closed node to validate.
-     * @returns the validation errors found, or an empty array if the node is valid or has no namespace.
-     */
-    validate(node: Node): ValidationException[];
-}

package/out/runtime/ConditionalValidator.js

@@ -1,36 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.ConditionalValidator = void 0;
-/**
- * Wrapper around a {@link SchemaValidator} that only validates namespaced nodes, so that a
- * document mixing schema-bound and free nodes does not report the free ones as unknown.
- *
- * @deprecated since 0.8.0: {@link SchemaValidator} applies this rule itself (STXT-SCHEMA-SPEC 5,
- * the empty namespace is never validated), so the wrapper adds nothing. Register the
- * `SchemaValidator` directly. Kept for compatibility; to be removed in 1.0.
- */
-class ConditionalValidator {
-    /**
-     * Creates a validator that delegates to a schema validator.
-     *
-     * @param schemaValidator validator the namespaced nodes are handed over to.
-     */
-    constructor(schemaValidator) {
-        this.schemaValidator = schemaValidator;
-    }
-    /**
-     * Validates a node when it has a namespace, and lets it through otherwise.
-     *
-     * @param node already closed node to validate.
-     * @returns the validation errors found, or an empty array if the node is valid or has no namespace.
-     */
-    validate(node) {
-        // Only validate the node when it has a namespace
-        if (node.getNamespace() !== "") {
-            return this.schemaValidator.validate(node);
-        }
-        return [];
-    }
-}
-exports.ConditionalValidator = ConditionalValidator;
-//# sourceMappingURL=ConditionalValidator.js.map