@stxt-lang/core 0.10.0 → 0.11.1

package/README.md

@@ -117,7 +117,6 @@ import {
     Parser,
     UnifiedSchemaProvider,
     SchemaValidator,
-    ConditionalValidator,
     ValidationException,
 } from '@stxt-lang/core';
 
@@ -138,8 +137,8 @@ const provider = new UnifiedSchemaProvider();
 provider.addFile(schemaText);
 
 const parser = new Parser();
-// ConditionalValidator only validates nodes that carry a namespace
-parser.registerValidator(new ConditionalValidator(new SchemaValidator(provider)));
+// Only nodes that carry a namespace are validated; free nodes pass through
+parser.registerValidator(new SchemaValidator(provider));
 
 const result = parser.parseResult(documentText);
 
@@ -223,7 +222,7 @@ class NodeEnvironment implements DiscoveryEnvironment {
 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';
+import { Parser, SchemaValidator } from '@stxt-lang/core';
 
 const resolver = new DiscoveryResolver(new NodeFileSystem(), new NodeEnvironment());
 
@@ -240,7 +239,7 @@ for (const error of result.getErrors()) {
 }
 
 const parser = new Parser();
-parser.registerValidator(new ConditionalValidator(new SchemaValidator(result)));
+parser.registerValidator(new SchemaValidator(result));
 
 const parsed = parser.parseResult(documentText);
 ```
@@ -292,15 +291,32 @@ const text = NodeWriter.toSTXT(node, IndentStyle.TABS);
 const doc = NodeWriter.toSTXTDocs(result.getNodes(), IndentStyle.SPACES_4);
 ```
 
+`NodeWriter` re-serializes the tree, so comments and blank lines are gone. To reformat a document
+**keeping everything the author wrote**, use `Formatter`: it rewrites the original text line by
+line — node lines in canonical form, block lines re-indented to their block, comments and blank
+lines kept with their indentation units converted — and reports the syntax errors it met, so the
+caller decides what to do with a document that does not parse. It is the formatter behind
+`stxt format`, the VS Code extension and the playground.
+
+```ts
+import { Formatter, IndentStyle } from '@stxt-lang/core';
+
+const { text, errors } = Formatter.format(source, IndentStyle.TABS);
+if (errors.length === 0) {
+  fs.writeFileSync(file, text);
+}
+```
+
 ## API surface
 
 Everything importable from the package:
 
 - **Parsing** — `Node`, `InlineNode`, `TextNode`, `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`
+- **Exceptions** — `ParseException`, `ValidationException`, `RuntimeException`
+- **Extension points** — `Observer`, `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`
 
 ## License

package/out/all.d.ts

@@ -6,28 +6,37 @@ export { ParseResult } from "./core/ParseResult";
 export { Line } from "./core/Line";
 export { Constants } from "./core/Constants";
 /**
- * Version of the STXT specifications (STXT-SPEC, STXT-TREE-SPEC, STXT-SCHEMA-SPEC,
- * STXT-TEMPLATE-SPEC, STXT-DISCOVERY-SPEC) this library implements, distinct from the version of
- * the package. Same value as `Constants.SPEC_VERSION`.
+ * Version of STXT-SPEC (the base syntax) this library implements, distinct from the version of
+ * the package; each specification is versioned independently (STXT-SPEC §1.1). Same value as
+ * `Constants.SPEC_VERSION`.
  */
 export declare const SPEC_VERSION: string;
 export { parseLine } from "./core/LineParser";
 export { StringUtils } from "./core/StringUtils";
 export { ParseException } from "./exceptions/ParseException";
 export { ValidationException } from "./exceptions/ValidationException";
+export { RuntimeException } from "./exceptions/RuntimeException";
 export { Observer } from "./processors/Observer";
+export { Validator } from "./processors/Validator";
 export { Schema } from "./schema/Schema";
 export { SchemaValidator } from "./schema/SchemaValidator";
 export { SchemaProvider } from "./schema/SchemaProvider";
+export { SchemaProviderMemory } from "./schema/SchemaProviderMemory";
+export { SchemaProviderMeta } from "./schema/SchemaProviderMeta";
+export { TypeRegistry } from "./schema/TypeRegistry";
+export type { Type } from "./schema/Type";
 export { NodeDefinition } from "./schema/NodeDefinition";
 export { ChildDefinition } from "./schema/ChildDefinition";
 export { transformNodeToSchema } from "./schema/SchemaParser";
 export { UnifiedSchemaProvider } from "./runtime/UnifiedSchemaProvider";
-export { ConditionalValidator } from "./runtime/ConditionalValidator";
 export { NodeWriter, IndentStyle } from "./runtime/NodeWriter";
+export { Formatter } from "./runtime/Formatter";
+export type { FormatResult } from "./runtime/Formatter";
 export { toCanonicalTree, toCanonicalJson } from "./runtime/TreeJson";
 export type { CanonicalDocument, CanonicalNode, CanonicalInlineNode, CanonicalBlockNode } from "./runtime/TreeJson";
-export { transformTemplateNodeToSchema } from "./template/TemplateParser";
+export { transformTemplateNodeToSchema, TEMPLATE_NAMESPACE } from "./template/TemplateParser";
+export { TemplateSchemaProviderMemory } from "./template/TemplateSchemaProviderMemory";
+export { MetaTemplateSchemaProvider } from "./template/MetaTemplateSchemaProvider";
 export { DiscoveryResolver, DiscoveryOptions } from "./discovery/DiscoveryResolver";
 export { DiscoveryResult, DiscoveryDefinition, DiscoveryLevel } from "./discovery/DiscoveryResult";
 export { DiscoveryError } from "./discovery/DiscoveryError";

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.transformTemplateNodeToSchema = exports.toCanonicalJson = exports.toCanonicalTree = exports.IndentStyle = exports.NodeWriter = exports.ConditionalValidator = exports.UnifiedSchemaProvider = exports.transformNodeToSchema = exports.ChildDefinition = exports.NodeDefinition = exports.SchemaValidator = exports.Schema = exports.ValidationException = exports.ParseException = exports.StringUtils = exports.parseLine = exports.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.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");
@@ -20,9 +20,9 @@ var Constants_1 = require("./core/Constants");
 Object.defineProperty(exports, "Constants", { enumerable: true, get: function () { return Constants_1.Constants; } });
 const Constants_2 = require("./core/Constants");
 /**
- * Version of the STXT specifications (STXT-SPEC, STXT-TREE-SPEC, STXT-SCHEMA-SPEC,
- * STXT-TEMPLATE-SPEC, STXT-DISCOVERY-SPEC) this library implements, distinct from the version of
- * the package. Same value as `Constants.SPEC_VERSION`.
+ * Version of STXT-SPEC (the base syntax) this library implements, distinct from the version of
+ * the package; each specification is versioned independently (STXT-SPEC §1.1). Same value as
+ * `Constants.SPEC_VERSION`.
  */
 exports.SPEC_VERSION = Constants_2.Constants.SPEC_VERSION;
 var LineParser_1 = require("./core/LineParser");
@@ -33,10 +33,18 @@ 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 RuntimeException_1 = require("./exceptions/RuntimeException");
+Object.defineProperty(exports, "RuntimeException", { enumerable: true, get: function () { return RuntimeException_1.RuntimeException; } });
 var Schema_1 = require("./schema/Schema");
 Object.defineProperty(exports, "Schema", { enumerable: true, get: function () { return Schema_1.Schema; } });
 var SchemaValidator_1 = require("./schema/SchemaValidator");
 Object.defineProperty(exports, "SchemaValidator", { enumerable: true, get: function () { return SchemaValidator_1.SchemaValidator; } });
+var SchemaProviderMemory_1 = require("./schema/SchemaProviderMemory");
+Object.defineProperty(exports, "SchemaProviderMemory", { enumerable: true, get: function () { return SchemaProviderMemory_1.SchemaProviderMemory; } });
+var SchemaProviderMeta_1 = require("./schema/SchemaProviderMeta");
+Object.defineProperty(exports, "SchemaProviderMeta", { enumerable: true, get: function () { return SchemaProviderMeta_1.SchemaProviderMeta; } });
+var TypeRegistry_1 = require("./schema/TypeRegistry");
+Object.defineProperty(exports, "TypeRegistry", { enumerable: true, get: function () { return TypeRegistry_1.TypeRegistry; } });
 var NodeDefinition_1 = require("./schema/NodeDefinition");
 Object.defineProperty(exports, "NodeDefinition", { enumerable: true, get: function () { return NodeDefinition_1.NodeDefinition; } });
 var ChildDefinition_1 = require("./schema/ChildDefinition");
@@ -45,16 +53,21 @@ var SchemaParser_1 = require("./schema/SchemaParser");
 Object.defineProperty(exports, "transformNodeToSchema", { enumerable: true, get: function () { return SchemaParser_1.transformNodeToSchema; } });
 var UnifiedSchemaProvider_1 = require("./runtime/UnifiedSchemaProvider");
 Object.defineProperty(exports, "UnifiedSchemaProvider", { enumerable: true, get: function () { return UnifiedSchemaProvider_1.UnifiedSchemaProvider; } });
-var ConditionalValidator_1 = require("./runtime/ConditionalValidator");
-Object.defineProperty(exports, "ConditionalValidator", { enumerable: true, get: function () { return ConditionalValidator_1.ConditionalValidator; } });
 var NodeWriter_1 = require("./runtime/NodeWriter");
 Object.defineProperty(exports, "NodeWriter", { enumerable: true, get: function () { return NodeWriter_1.NodeWriter; } });
 Object.defineProperty(exports, "IndentStyle", { enumerable: true, get: function () { return NodeWriter_1.IndentStyle; } });
+var Formatter_1 = require("./runtime/Formatter");
+Object.defineProperty(exports, "Formatter", { enumerable: true, get: function () { return Formatter_1.Formatter; } });
 var TreeJson_1 = require("./runtime/TreeJson");
 Object.defineProperty(exports, "toCanonicalTree", { enumerable: true, get: function () { return TreeJson_1.toCanonicalTree; } });
 Object.defineProperty(exports, "toCanonicalJson", { enumerable: true, get: function () { return TreeJson_1.toCanonicalJson; } });
 var TemplateParser_1 = require("./template/TemplateParser");
 Object.defineProperty(exports, "transformTemplateNodeToSchema", { enumerable: true, get: function () { return TemplateParser_1.transformTemplateNodeToSchema; } });
+Object.defineProperty(exports, "TEMPLATE_NAMESPACE", { enumerable: true, get: function () { return TemplateParser_1.TEMPLATE_NAMESPACE; } });
+var TemplateSchemaProviderMemory_1 = require("./template/TemplateSchemaProviderMemory");
+Object.defineProperty(exports, "TemplateSchemaProviderMemory", { enumerable: true, get: function () { return TemplateSchemaProviderMemory_1.TemplateSchemaProviderMemory; } });
+var MetaTemplateSchemaProvider_1 = require("./template/MetaTemplateSchemaProvider");
+Object.defineProperty(exports, "MetaTemplateSchemaProvider", { enumerable: true, get: function () { return MetaTemplateSchemaProvider_1.MetaTemplateSchemaProvider; } });
 var DiscoveryResolver_1 = require("./discovery/DiscoveryResolver");
 Object.defineProperty(exports, "DiscoveryResolver", { enumerable: true, get: function () { return DiscoveryResolver_1.DiscoveryResolver; } });
 var DiscoveryResult_1 = require("./discovery/DiscoveryResult");

package/out/core/Constants.d.ts

@@ -1,10 +1,11 @@
 /** Characters and sizes fixed by STXT-SPEC that the parser and the writer share. */
 export declare class Constants {
     /**
-     * Version of the STXT specifications (STXT-SPEC, STXT-TREE-SPEC, STXT-SCHEMA-SPEC,
-     * STXT-TEMPLATE-SPEC, STXT-DISCOVERY-SPEC) this library implements. It is distinct from the
-     * version of the package: the package may be released many times against the same
-     * specification version.
+     * Version of STXT-SPEC (the base syntax) this library implements; "STXT 1.0" on its own means
+     * this number (STXT-SPEC §1.1). Each specification is versioned independently, so the schema,
+     * template, tree and discovery specs may carry other numbers. It is distinct from the version
+     * of the package: the package may be released many times against the same specification
+     * version.
      */
     static readonly SPEC_VERSION: string;
     /** Character that opens a comment line. */

package/out/core/Constants.js

@@ -6,10 +6,11 @@ class Constants {
 }
 exports.Constants = Constants;
 /**
- * Version of the STXT specifications (STXT-SPEC, STXT-TREE-SPEC, STXT-SCHEMA-SPEC,
- * STXT-TEMPLATE-SPEC, STXT-DISCOVERY-SPEC) this library implements. It is distinct from the
- * version of the package: the package may be released many times against the same
- * specification version.
+ * Version of STXT-SPEC (the base syntax) this library implements; "STXT 1.0" on its own means
+ * this number (STXT-SPEC §1.1). Each specification is versioned independently, so the schema,
+ * template, tree and discovery specs may carry other numbers. It is distinct from the version
+ * of the package: the package may be released many times against the same specification
+ * version.
  */
 Constants.SPEC_VERSION = "1.0";
 /** Character that opens a comment line. */

package/out/core/Line.d.ts

@@ -15,8 +15,8 @@ export declare class Line {
     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;
+    /** Index of the first character of the content (the number of characters the indentation took up). */
+    readonly contentStart: number;
     /**
      * Creates a line already split into indentation and content.
      *
@@ -24,9 +24,9 @@ export declare class 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.
+     * @param contentStart index of the first character of the content, i.e. the number of characters the indentation took up.
      */
-    constructor(level: number, content: string, isComment: boolean, isBlock: boolean, indentLength: number);
+    constructor(level: number, content: string, isComment: boolean, isBlock: boolean, contentStart: number);
     /** @returns true if the line has no content beyond blanks (space/tab only, spec 4). */
     isEmpty(): boolean;
 }

package/out/core/Line.js

@@ -15,14 +15,14 @@ class 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.
+     * @param contentStart index of the first character of the content, i.e. the number of characters the indentation took up.
      */
-    constructor(level, content, isComment, isBlock, indentLength) {
+    constructor(level, content, isComment, isBlock, contentStart) {
         this.level = level;
         this.content = content;
         this.isComment = isComment;
         this.isBlock = isBlock;
-        this.indentLength = indentLength;
+        this.contentStart = contentStart;
     }
     /** @returns true if the line has no content beyond blanks (space/tab only, spec 4). */
     isEmpty() {

package/out/core/LineParser.js

@@ -68,7 +68,9 @@ function parseLine(line, lastNodeBlock, lastLevel, numLine, validate = true) {
             if (validate && sawSpace && sawTab && text.length > 0) {
                 throw new ParseException_1.ParseException(numLine, "INDENTATION_MIXED", `Mixed tabs and spaces in indentation`);
             }
-            return new Line_1.Line(level, text, false, true, pointer);
+            // pointer is the index of the indentation character that crossed the block level;
+            // the indentation took pointer + 1 characters
+            return new Line_1.Line(level, text, false, true, pointer + 1);
         }
         // Move the pointer forward
         pointer++;

package/out/core/Node.d.ts

@@ -51,12 +51,6 @@ export declare abstract class Node {
     setName(name: string): void;
     /** @returns the canonical name of the node (STXT-SPEC §4.3), used to compare/look up by structural identity. */
     getCanonicalName(): string;
-    /**
-     * @returns the canonical name of the node.
-     * @deprecated since 0.7.0, use {@link Node.getCanonicalName}; "canonical name" is the term of
-     *             the specifications. To be removed in a later version.
-     */
-    getNormalizedName(): string;
     /** @returns the canonical name prefixed by the effective namespace (`namespace:name`), or just the canonical name when there is no namespace. */
     getQualifiedName(): string;
     /** @returns the namespace this node declares itself, lower-cased, or the empty string if it declares none (and so inherits the parent's). */

package/out/core/Node.js

@@ -68,14 +68,6 @@ class Node {
     getCanonicalName() {
         return this.canonicalName;
     }
-    /**
-     * @returns the canonical name of the node.
-     * @deprecated since 0.7.0, use {@link Node.getCanonicalName}; "canonical name" is the term of
-     *             the specifications. To be removed in a later version.
-     */
-    getNormalizedName() {
-        return this.canonicalName;
-    }
     /** @returns the canonical name prefixed by the effective namespace (`namespace:name`), or just the canonical name when there is no namespace. */
     getQualifiedName() {
         const namespace = this.getNamespace();

package/out/discovery/DiscoveryResult.d.ts

@@ -35,7 +35,7 @@ export interface DiscoveryLevel {
  * 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.
+ * `SchemaValidator` 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.
  */

package/out/discovery/DiscoveryResult.js

@@ -8,7 +8,7 @@ const StringUtils_1 = require("../core/StringUtils");
  * 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.
+ * `SchemaValidator` 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.
  */

package/out/runtime/Formatter.d.ts

@@ -0,0 +1,104 @@
+import { ParseException } from "../exceptions/ParseException";
+import { IndentStyle } from "./NodeWriter";
+/** The outcome of {@link Formatter.format}. */
+export interface FormatResult {
+    /**
+     * The formatted document: the same lines as the source, in the same order, with the same
+     * line ending (CRLF is kept) and with a final newline only where the source had one.
+     */
+    text: string;
+    /**
+     * Syntax errors found while parsing, in line order; empty when the document parses. A line
+     * the parse tree does not describe because of an error is only converted by indentation
+     * units and right-trimmed (see {@link Formatter}): formatting never repairs a document, and
+     * whether a document with errors should be reformatted at all is the caller's decision.
+     */
+    errors: ParseException[];
+}
+/**
+ * Reformats an STXT document **line by line, over the original text**, so that nothing the
+ * parse tree does not hold — comments, blank lines, the exact content of text blocks — is lost.
+ * This is what distinguishes it from {@link NodeWriter}, which re-serializes the tree and
+ * therefore drops comments and blank lines.
+ *
+ * The rules, the same for every tool of the ecosystem (the CLI's `stxt format`, the VS Code
+ * extension's formatter and the playground's re-indentation all delegate here):
+ *
+ * - A line that **opens a node** is rendered in canonical form: the indentation of its level in
+ *   the requested style, the name as parsed, the namespace only where the source wrote it (a
+ *   child repeating its parent's namespace is redundant but legal, and dropping it would be an
+ *   edit, not a reformat), `: value` with exactly one space — or a bare `:` when there is no
+ *   value, so container nodes do not end in a stray space — or ` >>` for a block.
+ * - A **text line of a block** gets the indentation of the block (its level plus one) in the
+ *   requested style, followed by its content; any indentation the line had beyond the block's
+ *   is content (STXT-SPEC §10.2, relative indentation is preserved) and is kept exactly. A
+ *   blank line of the block is `""` in the content whatever it looks like in the source
+ *   (STXT-SPEC §10.3), so it is written with the indentation of the block too: the block reads
+ *   as one piece and, at the end of the file, the line is not lost — an empty last line would
+ *   be indistinguishable from the final line ending.
+ * - Every **other line** — a comment, a blank line outside a block, or a line the parse tree
+ *   does not describe because of a syntax error — is kept as the author wrote it, except that
+ *   its trailing blanks are removed and the whole indentation units at its start are converted
+ *   one for one to the requested style (a tab or four spaces in either style count as a unit;
+ *   whatever follows the last whole unit, including a remainder that is not a whole unit, is
+ *   kept as it is). STXT-SPEC §9 validates the indentation of a comment like a node's, so in a
+ *   document that parses every comment has a whole number of units and comes out fully in the
+ *   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
+ * has nothing to do with validation.
+ */
+export declare class Formatter {
+    private constructor();
+    /**
+     * Formats a document.
+     *
+     * @param text the document.
+     * @param style indentation style to format with; tabs by default.
+     * @returns the formatted text and the syntax errors found; see {@link FormatResult}.
+     */
+    static format(text: string, style?: IndentStyle): FormatResult;
+    /**
+     * Formats one source line.
+     *
+     * @param line the line, without its line ending.
+     * @param lineNumber its line number, 1-indexed as the parser counts them.
+     * @param style indentation style to format with.
+     * @param sourceLines the parse of the document seen as source lines.
+     * @returns the formatted line.
+     */
+    private static formatLine;
+    /**
+     * Renders the line that opens a node in its canonical form.
+     *
+     * @param node the node the line opens.
+     * @param line the source line, used only to tell whether it spelled the namespace out.
+     * @param style indentation style to format with.
+     * @returns the formatted line.
+     */
+    private static renderNode;
+    /**
+     * Converts the whole indentation units at the start of a line to the requested style and
+     * keeps the rest of the line, remainder included.
+     *
+     * @param line the line, without trailing blanks.
+     * @param style indentation style to convert to.
+     * @returns the line with its indentation units converted.
+     */
+    private static convertUnits;
+    /**
+     * @param line a line.
+     * @param position a position in it.
+     * @returns the length of the whole indentation unit — a tab or four spaces — that starts at
+     *          `position`, or 0 if none does.
+     */
+    private static unitAt;
+    /**
+     * @param level indentation level to produce.
+     * @param style indentation style to produce it in.
+     * @returns the indentation of that level.
+     */
+    private static indent;
+}

package/out/runtime/Formatter.js

@@ -0,0 +1,184 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Formatter = void 0;
+const InlineNode_1 = require("../core/InlineNode");
+const Parser_1 = require("../core/Parser");
+const StringUtils_1 = require("../core/StringUtils");
+const TextNode_1 = require("../core/TextNode");
+const NodeWriter_1 = require("./NodeWriter");
+/**
+ * Reformats an STXT document **line by line, over the original text**, so that nothing the
+ * parse tree does not hold — comments, blank lines, the exact content of text blocks — is lost.
+ * This is what distinguishes it from {@link NodeWriter}, which re-serializes the tree and
+ * therefore drops comments and blank lines.
+ *
+ * The rules, the same for every tool of the ecosystem (the CLI's `stxt format`, the VS Code
+ * extension's formatter and the playground's re-indentation all delegate here):
+ *
+ * - A line that **opens a node** is rendered in canonical form: the indentation of its level in
+ *   the requested style, the name as parsed, the namespace only where the source wrote it (a
+ *   child repeating its parent's namespace is redundant but legal, and dropping it would be an
+ *   edit, not a reformat), `: value` with exactly one space — or a bare `:` when there is no
+ *   value, so container nodes do not end in a stray space — or ` >>` for a block.
+ * - A **text line of a block** gets the indentation of the block (its level plus one) in the
+ *   requested style, followed by its content; any indentation the line had beyond the block's
+ *   is content (STXT-SPEC §10.2, relative indentation is preserved) and is kept exactly. A
+ *   blank line of the block is `""` in the content whatever it looks like in the source
+ *   (STXT-SPEC §10.3), so it is written with the indentation of the block too: the block reads
+ *   as one piece and, at the end of the file, the line is not lost — an empty last line would
+ *   be indistinguishable from the final line ending.
+ * - Every **other line** — a comment, a blank line outside a block, or a line the parse tree
+ *   does not describe because of a syntax error — is kept as the author wrote it, except that
+ *   its trailing blanks are removed and the whole indentation units at its start are converted
+ *   one for one to the requested style (a tab or four spaces in either style count as a unit;
+ *   whatever follows the last whole unit, including a remainder that is not a whole unit, is
+ *   kept as it is). STXT-SPEC §9 validates the indentation of a comment like a node's, so in a
+ *   document that parses every comment has a whole number of units and comes out fully in the
+ *   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
+ * has nothing to do with validation.
+ */
+class Formatter {
+    constructor() { }
+    /**
+     * Formats a document.
+     *
+     * @param text the document.
+     * @param style indentation style to format with; tabs by default.
+     * @returns the formatted text and the syntax errors found; see {@link FormatResult}.
+     */
+    static format(text, style = NodeWriter_1.IndentStyle.TABS) {
+        const sourceLines = new SourceLines();
+        const parser = new Parser_1.Parser();
+        parser.registerObserver(sourceLines);
+        const result = parser.parseResult(text);
+        const eol = text.includes("\r\n") ? "\r\n" : "\n";
+        const formatted = text
+            .split(/\r?\n/)
+            .map((line, index) => Formatter.formatLine(line, index + 1, style, sourceLines))
+            .join(eol);
+        return { text: formatted, errors: result.getErrors() };
+    }
+    /**
+     * Formats one source line.
+     *
+     * @param line the line, without its line ending.
+     * @param lineNumber its line number, 1-indexed as the parser counts them.
+     * @param style indentation style to format with.
+     * @param sourceLines the parse of the document seen as source lines.
+     * @returns the formatted line.
+     */
+    static formatLine(line, lineNumber, style, sourceLines) {
+        const node = sourceLines.nodeAt(lineNumber);
+        if (node) {
+            return Formatter.renderNode(node, line, style);
+        }
+        const text = sourceLines.textAt(lineNumber);
+        if (text) {
+            return Formatter.indent(text.node.getLevel() + 1, style) + text.line.content;
+        }
+        return Formatter.convertUnits(StringUtils_1.StringUtils.rightTrim(line), style);
+    }
+    /**
+     * Renders the line that opens a node in its canonical form.
+     *
+     * @param node the node the line opens.
+     * @param line the source line, used only to tell whether it spelled the namespace out.
+     * @param style indentation style to format with.
+     * @returns the formatted line.
+     */
+    static renderNode(node, line, style) {
+        const indent = Formatter.indent(node.getLevel(), style);
+        const head = node instanceof InlineNode_1.InlineNode ? line.substring(0, line.indexOf(":")) : line;
+        const name = head.includes("(")
+            ? `${node.getName()} (${node.getNamespace()})`
+            : node.getName();
+        if (node instanceof TextNode_1.TextNode) {
+            return `${indent}${name} >>`;
+        }
+        const value = node.getValue();
+        return value.length > 0 ? `${indent}${name}: ${value}` : `${indent}${name}:`;
+    }
+    /**
+     * Converts the whole indentation units at the start of a line to the requested style and
+     * keeps the rest of the line, remainder included.
+     *
+     * @param line the line, without trailing blanks.
+     * @param style indentation style to convert to.
+     * @returns the line with its indentation units converted.
+     */
+    static convertUnits(line, style) {
+        let consumed = 0;
+        let units = 0;
+        let unit = Formatter.unitAt(line, consumed);
+        while (unit > 0) {
+            consumed += unit;
+            units++;
+            unit = Formatter.unitAt(line, consumed);
+        }
+        return units === 0 ? line : Formatter.indent(units, style) + line.substring(consumed);
+    }
+    /**
+     * @param line a line.
+     * @param position a position in it.
+     * @returns the length of the whole indentation unit — a tab or four spaces — that starts at
+     *          `position`, or 0 if none does.
+     */
+    static unitAt(line, position) {
+        if (line.startsWith("\t", position)) {
+            return 1;
+        }
+        return line.startsWith("    ", position) ? 4 : 0;
+    }
+    /**
+     * @param level indentation level to produce.
+     * @param style indentation style to produce it in.
+     * @returns the indentation of that level.
+     */
+    static indent(level, style) {
+        return (style === NodeWriter_1.IndentStyle.SPACES_4 ? "    " : "\t").repeat(level);
+    }
+}
+exports.Formatter = Formatter;
+/**
+ * The parse of a document seen as source lines: which line opened which node, and which line is
+ * a text line of which block. It is what lets the formatter rewrite the lines the parse tree
+ * describes and leave every other line as the author wrote it.
+ */
+class SourceLines {
+    constructor() {
+        this.nodeByLine = new Map();
+        this.textByLine = new Map();
+    }
+    onCreate(node) {
+        this.nodeByLine.set(node.getLine(), node);
+    }
+    onFinish() {
+        // Formatting only needs to know where each node started.
+    }
+    onComment() {
+        // Comment lines need no bookkeeping: every line that opens no node is treated alike.
+    }
+    onTextLine(node, lineNumber, lineString, line) {
+        this.textByLine.set(lineNumber, { node, line });
+    }
+    /**
+     * @param lineNumber line number, 1-indexed.
+     * @returns the node this line opened, or undefined if it opened none.
+     */
+    nodeAt(lineNumber) {
+        return this.nodeByLine.get(lineNumber);
+    }
+    /**
+     * @param lineNumber line number, 1-indexed.
+     * @returns the block node this line is text of and the line already split into indentation
+     *          and content, or undefined if the line is not text of a block.
+     */
+    textAt(lineNumber) {
+        return this.textByLine.get(lineNumber);
+    }
+}
+//# sourceMappingURL=Formatter.js.map

package/out/schema/ChildDefinition.d.ts

@@ -1,6 +1,6 @@
 /** Definition of an expected child inside a {@link NodeDefinition}: name, namespace and min/max cardinality. */
 export declare class ChildDefinition {
-    private readonly normalizedName;
+    private readonly canonicalName;
     private readonly name;
     private readonly namespace;
     private readonly min;
@@ -20,11 +20,6 @@ export declare class ChildDefinition {
     getName(): string;
     /** @returns the canonical name of the expected child. */
     getCanonicalName(): string;
-    /**
-     * @returns the canonical name of the expected child.
-     * @deprecated since 0.7.0, use getCanonicalName().
-     */
-    getNormalizedName(): string;
     /** @returns the namespace of the expected child, or the empty string if it has none. */
     getNamespace(): string;
     /** @returns the minimum cardinality, or null if there is no minimum. */
@@ -36,7 +31,7 @@ export declare class ChildDefinition {
     /** @returns a plain object with the definition, so that JSON.stringify serializes it. */
     toJSON(): {
         name: string;
-        normalizedName: string;
+        canonicalName: string;
         namespace: string;
         min: number | null;
         max: number | null;

package/out/schema/ChildDefinition.js

@@ -18,7 +18,7 @@ class ChildDefinition {
      */
     constructor(name, namespace, min, max, numLine) {
         this.name = StringUtils_1.StringUtils.compactSpaces(name);
-        this.normalizedName = StringUtils_1.StringUtils.normalize(name);
+        this.canonicalName = StringUtils_1.StringUtils.normalize(name);
         this.namespace = StringUtils_1.StringUtils.lowerCase(namespace);
         this.min = min;
         this.max = max;
@@ -33,14 +33,7 @@ class ChildDefinition {
     }
     /** @returns the canonical name of the expected child. */
     getCanonicalName() {
-        return this.normalizedName;
-    }
-    /**
-     * @returns the canonical name of the expected child.
-     * @deprecated since 0.7.0, use getCanonicalName().
-     */
-    getNormalizedName() {
-        return this.normalizedName;
+        return this.canonicalName;
     }
     /** @returns the namespace of the expected child, or the empty string if it has none. */
     getNamespace() {
@@ -57,14 +50,14 @@ class ChildDefinition {
     /** @returns the canonical name prefixed by its namespace, used as the key in {@link NodeDefinition.getChildren}. */
     getQualifiedName() {
         return this.namespace.length === 0
-            ? this.normalizedName
-            : `${this.namespace}:${this.normalizedName}`;
+            ? this.canonicalName
+            : `${this.namespace}:${this.canonicalName}`;
     }
     /** @returns a plain object with the definition, so that JSON.stringify serializes it. */
     toJSON() {
         return {
             name: this.getName(),
-            normalizedName: this.getNormalizedName(),
+            canonicalName: this.getCanonicalName(),
             namespace: this.getNamespace(),
             min: this.getMin(),
             max: this.getMax(),

package/out/schema/NodeDefinition.d.ts

@@ -5,7 +5,7 @@ import { ChildDefinition } from "./ChildDefinition";
  */
 export declare class NodeDefinition {
     private readonly name;
-    private readonly normalizedName;
+    private readonly canonicalName;
     private readonly type;
     private description;
     private readonly children;
@@ -24,11 +24,6 @@ export declare class NodeDefinition {
     getName(): string;
     /** @returns the canonical name of the node. */
     getCanonicalName(): string;
-    /**
-     * @returns the canonical name of the node.
-     * @deprecated since 0.7.0, use getCanonicalName().
-     */
-    getNormalizedName(): string;
     /** @returns the name of the value type of this node (see {@link TypeRegistry}). */
     getType(): string;
     /** @returns the definitions of the expected children, indexed by their qualified canonical name. */
@@ -68,12 +63,12 @@ export declare class NodeDefinition {
     /** @returns a plain object with the definition, so that JSON.stringify serializes it. */
     toJSON(): {
         name: string;
-        normalizedName: string;
+        canonicalName: string;
         type: string;
         description: string | undefined;
         children: {
             name: string;
-            normalizedName: string;
+            canonicalName: string;
             namespace: string;
             min: number | null;
             max: number | null;

package/out/schema/NodeDefinition.js

@@ -21,7 +21,7 @@ class NodeDefinition {
         this.children = new Map();
         this.values = new Set();
         this.name = StringUtils_1.StringUtils.compactSpaces(name);
-        this.normalizedName = StringUtils_1.StringUtils.normalize(name);
+        this.canonicalName = StringUtils_1.StringUtils.normalize(name);
         this.type = type;
         this.description = description;
         if (!StringUtils_1.StringUtils.isValidNodeName(this.name)) {
@@ -34,14 +34,7 @@ class NodeDefinition {
     }
     /** @returns the canonical name of the node. */
     getCanonicalName() {
-        return this.normalizedName;
-    }
-    /**
-     * @returns the canonical name of the node.
-     * @deprecated since 0.7.0, use getCanonicalName().
-     */
-    getNormalizedName() {
-        return this.normalizedName;
+        return this.canonicalName;
     }
     /** @returns the name of the value type of this node (see {@link TypeRegistry}). */
     getType() {
@@ -113,7 +106,7 @@ class NodeDefinition {
     toJSON() {
         return {
             name: this.getName(),
-            normalizedName: this.getNormalizedName(),
+            canonicalName: this.getCanonicalName(),
             type: this.getType(),
             description: this.description,
             children: Array.from(this.getChildren().values()).map(c => c.toJSON()),

package/out/schema/Schema.d.ts

@@ -15,6 +15,8 @@ export declare class Schema {
      * @throws ParseException if the namespace is not well formed.
      */
     constructor(namespace: string | null | undefined, line: number, description: string | undefined);
+    /** @returns the description of the schema (STXT-SCHEMA-SPEC §6.1), or undefined if it has none. */
+    getDescription(): string | undefined;
     /** @returns the node definitions, indexed by their canonical name. */
     getNodes(): ReadonlyMap<string, NodeDefinition>;
     /**
@@ -38,12 +40,12 @@ export declare class Schema {
         namespace: string;
         nodes: {
             name: string;
-            normalizedName: string;
+            canonicalName: string;
             type: string;
             description: string | undefined;
             children: {
                 name: string;
-                normalizedName: string;
+                canonicalName: string;
                 namespace: string;
                 min: number | null;
                 max: number | null;

package/out/schema/Schema.js

@@ -20,6 +20,10 @@ class Schema {
         this.description = description;
         NamespaceValidator_1.NamespaceValidator.validateNamespaceFormat(this.namespace, line);
     }
+    /** @returns the description of the schema (STXT-SCHEMA-SPEC §6.1), or undefined if it has none. */
+    getDescription() {
+        return this.description;
+    }
     /** @returns the node definitions, indexed by their canonical name. */
     getNodes() {
         return this.nodes;

package/out/template/TemplateParser.d.ts

@@ -1,5 +1,8 @@
 import { Node } from "../core/Node";
 import { Schema } from "../schema/Schema";
+/** Namespace of the template language itself, `@stxt.template`. */
+/** Namespace of the template language itself, `@stxt.template`. */
+export declare const TEMPLATE_NAMESPACE = "@stxt.template";
 /**
  * Turns the tree of an already parsed `@stxt.template` document into an equivalent {@link Schema}.
  *

package/out/template/TemplateParser.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.TEMPLATE_NAMESPACE = void 0;
 exports.transformTemplateNodeToSchema = transformTemplateNodeToSchema;
 const InlineNode_1 = require("../core/InlineNode");
 const Parser_1 = require("../core/Parser");
@@ -13,7 +14,8 @@ const ParseException_1 = require("../exceptions/ParseException");
 const TypeRegistry_1 = require("../schema/TypeRegistry");
 const NamespaceValidator_1 = require("../core/NamespaceValidator");
 /** Namespace of the template language itself, `@stxt.template`. */
-const TEMPLATE_NAMESPACE = "@stxt.template";
+/** Namespace of the template language itself, `@stxt.template`. */
+exports.TEMPLATE_NAMESPACE = "@stxt.template";
 /**
  * Turns the tree of an already parsed `@stxt.template` document into an equivalent {@link Schema}.
  *
@@ -25,8 +27,8 @@ const TEMPLATE_NAMESPACE = "@stxt.template";
  */
 function transformTemplateNodeToSchema(node) {
     // The root must be `Template (@stxt.template): ns`
-    if (node.getCanonicalName() !== "template" || node.getNamespace() !== TEMPLATE_NAMESPACE) {
-        throw new ValidationException_1.ValidationException(node.getLine(), "TEMPLATE_ROOT_NOT_VALID", `Expected template(${TEMPLATE_NAMESPACE}) but got ${node.getCanonicalName()}(${node.getNamespace()})`);
+    if (node.getCanonicalName() !== "template" || node.getNamespace() !== exports.TEMPLATE_NAMESPACE) {
+        throw new ValidationException_1.ValidationException(node.getLine(), "TEMPLATE_ROOT_NOT_VALID", `Expected template(${exports.TEMPLATE_NAMESPACE}) but got ${node.getCanonicalName()}(${node.getNamespace()})`);
     }
     // The target namespace: required, and with a valid format
     const targetNamespace = StringUtils_1.StringUtils.lowerCase(node.getText());

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stxt-lang/core",
-  "version": "0.10.0",
+  "version": "0.11.1",
   "description": "Parser and schema validator for STXT, an indentation-based structured-text format.",
   "main": "out/all.js",
   "types": "out/all.d.ts",