attention-manifest-protocol 0.4.0 → 0.4.2

package/lib/structure/abstractSyntaxTree.js

@@ -0,0 +1,400 @@
+/**
+ * Generic, language-agnostic abstract syntax tree.
+ *
+ * This module is not a parser. It defines a plain node shape plus traversal,
+ * search, mapping, cloning, and structural comparison primitives that parsers
+ * and interpreters can build on. Node payloads are opaque values owned by the
+ * caller; the tree never inspects or clones them.
+ *
+ * Nodes and their `children` arrays are mutable by design. The class stores the
+ * supplied root by reference and performs no deep validation, so manually
+ * assembled nodes are accepted. The static {@link AbstractSyntaxTree.leaf} and
+ * {@link AbstractSyntaxTree.branch} helpers do enforce a non-empty `kind`.
+ */
+/**
+ * Throw unless `kind` is a non-empty string.
+ */
+function assertKind(kind) {
+    if (typeof (kind) !== "string" || kind.length === 0) {
+        throw new TypeError("kind must be a non-empty string");
+    }
+}
+/**
+ * Build a plain node, omitting absent optional fields.
+ */
+function makeNode(kind, children, value, span) {
+    const node = { kind, children };
+    if (value !== (void 0)) {
+        node.value = value;
+    }
+    if (span !== (void 0)) {
+        node.span = span;
+    }
+    return node;
+}
+/**
+ * Copy a span into a fresh plain object.
+ */
+function copySpan(span) {
+    const copy = { start: span.start, end: span.end };
+    if ("source" in span) {
+        copy.source = span.source;
+    }
+    return copy;
+}
+/**
+ * Deep-copy nodes and spans, preserving value references.
+ *
+ * Iterative and memoized by node identity so tall trees do not consume the
+ * call stack and shared subtrees stay shared.
+ */
+function cloneNode(root) {
+    const copies = new WeakMap();
+    const originals = [];
+    const pending = [root];
+    while (pending.length > 0) {
+        const node = pending.pop();
+        if (node === (void 0) || copies.has(node)) {
+            continue;
+        }
+        const copy = { kind: node.kind, children: [] };
+        if ("value" in node) {
+            copy.value = node.value;
+        }
+        if (node.span !== (void 0)) {
+            copy.span = copySpan(node.span);
+        }
+        copies.set(node, copy);
+        originals.push(node);
+        for (const child of node.children) {
+            pending.push(child);
+        }
+    }
+    for (const node of originals) {
+        const copy = copies.get(node);
+        if (copy === (void 0)) {
+            continue;
+        }
+        for (const child of node.children) {
+            const childCopy = copies.get(child);
+            if (childCopy !== (void 0)) {
+                copy.children.push(childCopy);
+            }
+        }
+    }
+    const rootCopy = copies.get(root);
+    if (rootCopy === (void 0)) {
+        throw new Error("failed to clone the AST root");
+    }
+    return rootCopy;
+}
+/**
+ * Compare optional spans field by field, using SameValue semantics.
+ */
+function spansEqual(left, right) {
+    if (left === (void 0) || right === (void 0)) {
+        return left === right;
+    }
+    return Object.is(left.start, right.start) && Object.is(left.end, right.end) && Object.is(left.source, right.source);
+}
+/**
+ * A mutable-rooted tree with non-mutating traversal and transformation helpers.
+ *
+ * The constructor accepts an arbitrary node value and stores it by reference.
+ * It does not inspect the subtree, so callers that build nodes manually are
+ * responsible for maintaining the {@link AstNode} shape.
+ *
+ * @typeParam T - Value payload stored on nodes.
+ */
+export class AbstractSyntaxTree {
+    rootNode;
+    /**
+     * Wrap an existing root node.
+     *
+     * @param root - Root node, stored by reference.
+     */
+    constructor(root) {
+        this.rootNode = root;
+    }
+    /**
+     * Create a tree with one leaf node.
+     *
+     * @param kind - Non-empty node category.
+     * @param value - Optional leaf payload.
+     * @param span - Optional source extent.
+     * @throws TypeError if `kind` is not a non-empty string.
+     */
+    static leaf(kind, value, span) {
+        assertKind(kind);
+        return new AbstractSyntaxTree(makeNode(kind, [], value, span));
+    }
+    /**
+     * Create a tree with one branch node and the supplied children.
+     *
+     * The children iterable is copied into a new mutable array.
+     *
+     * @param kind - Non-empty node category.
+     * @param children - Direct children, in order.
+     * @param value - Optional branch payload.
+     * @param span - Optional source extent.
+     * @throws TypeError if `kind` is not a non-empty string.
+     */
+    static branch(kind, children, value, span) {
+        assertKind(kind);
+        return new AbstractSyntaxTree(makeNode(kind, [...children], value, span));
+    }
+    /**
+     * The stored root node, by reference.
+     */
+    get root() {
+        return this.rootNode;
+    }
+    /**
+     * Total node count, recomputed on demand because children are mutable.
+     */
+    get size() {
+        const iterator = this.walk();
+        let count = 0;
+        while (!iterator.next().done) {
+            count += 1;
+        }
+        return count;
+    }
+    /**
+     * Number of nodes on the longest root-to-leaf path; a leaf has height 1.
+     */
+    get height() {
+        let maximum = 0;
+        const stack = [{ node: this.rootNode, depth: 1 }];
+        while (stack.length > 0) {
+            const frame = stack.pop();
+            if (frame === (void 0)) {
+                break;
+            }
+            if (frame.depth > maximum) {
+                maximum = frame.depth;
+            }
+            for (const child of frame.node.children) {
+                stack.push({ node: child, depth: frame.depth + 1 });
+            }
+        }
+        return maximum;
+    }
+    /**
+     * Number of nodes with no children.
+     */
+    get leaves() {
+        let count = 0;
+        const stack = [this.rootNode];
+        while (stack.length > 0) {
+            const node = stack.pop();
+            if (node === (void 0)) {
+                break;
+            }
+            if (node.children.length === 0) {
+                count += 1;
+            }
+            else {
+                for (const child of node.children) {
+                    stack.push(child);
+                }
+            }
+        }
+        return count;
+    }
+    /**
+     * Walk the tree in the requested order.
+     *
+     * Preorder and postorder visit children left-to-right. Level order visits
+     * nodes breadth-first, also left-to-right within each level.
+     *
+     * @param order - Traversal order; defaults to `'preorder'`.
+     * @throws RangeError if `order` is not a supported traversal name.
+     */
+    *walk(order = "preorder") {
+        switch (order) {
+            case "preorder": {
+                const stack = [this.rootNode];
+                while (stack.length > 0) {
+                    const node = stack.pop();
+                    if (node === (void 0)) {
+                        break;
+                    }
+                    yield node;
+                    for (let index = node.children.length - 1; index >= 0; index -= 1) {
+                        const child = node.children[index];
+                        if (child !== (void 0)) {
+                            stack.push(child);
+                        }
+                    }
+                }
+                return;
+            }
+            case "postorder": {
+                const stack = [{ node: this.rootNode, expanded: false }];
+                while (stack.length > 0) {
+                    const frame = stack.pop();
+                    if (frame === (void 0)) {
+                        break;
+                    }
+                    if (frame.expanded) {
+                        yield frame.node;
+                        continue;
+                    }
+                    stack.push({ node: frame.node, expanded: true });
+                    for (let index = frame.node.children.length - 1; index >= 0; index -= 1) {
+                        const child = frame.node.children[index];
+                        if (child !== (void 0)) {
+                            stack.push({ node: child, expanded: false });
+                        }
+                    }
+                }
+                return;
+            }
+            case "levelorder": {
+                const queue = [this.rootNode];
+                let next = 0;
+                while (next < queue.length) {
+                    const node = queue[next];
+                    next += 1;
+                    if (node === (void 0)) {
+                        continue;
+                    }
+                    yield node;
+                    for (const child of node.children) {
+                        queue.push(child);
+                    }
+                }
+                return;
+            }
+            default:
+                throw new RangeError(`unknown AST traversal order: ${`${order}`}`);
+        }
+    }
+    /**
+     * Return the first node in preorder that satisfies `predicate`.
+     *
+     * @param predicate - Test applied to each node.
+     */
+    find(predicate) {
+        for (const node of this.walk("preorder")) {
+            if (predicate(node)) {
+                return node;
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Return every node that satisfies `predicate`, in preorder.
+     *
+     * @param predicate - Test applied to each node.
+     */
+    findAll(predicate) {
+        const matches = [];
+        for (const node of this.walk("preorder")) {
+            if (predicate(node)) {
+                matches.push(node);
+            }
+        }
+        return matches;
+    }
+    /**
+     * Transform every node bottom-up into a new tree.
+     *
+     * For each original node, `transform` receives that original node and its
+     * already mapped children, in order. The original tree is never modified.
+     *
+     * @param transform - Post-order mapping callback.
+     * @typeParam U - Value payload type of the mapped tree.
+     */
+    map(transform) {
+        const mapped = new WeakMap();
+        const stack = [{ node: this.rootNode, nextChild: 0 }];
+        while (stack.length > 0) {
+            const frame = stack[stack.length - 1];
+            if (frame === (void 0)) {
+                break;
+            }
+            if (frame.nextChild < frame.node.children.length) {
+                const child = frame.node.children[frame.nextChild];
+                frame.nextChild += 1;
+                stack.push({ node: child, nextChild: 0 });
+                continue;
+            }
+            const children = [];
+            for (const child of frame.node.children) {
+                const mappedChild = mapped.get(child);
+                if (mappedChild === (void 0)) {
+                    throw new Error("cannot map an AST child before it has been visited");
+                }
+                children.push(mappedChild);
+            }
+            mapped.set(frame.node, transform(frame.node, children));
+            stack.pop();
+        }
+        const mappedRoot = mapped.get(this.rootNode);
+        if (mappedRoot === (void 0)) {
+            throw new Error("AST mapping produced no root");
+        }
+        return new AbstractSyntaxTree(mappedRoot);
+    }
+    /**
+     * Deep-copy all nodes, child arrays, and spans.
+     *
+     * Payload values are copied by reference.
+     */
+    clone() {
+        return new AbstractSyntaxTree(cloneNode(this.rootNode));
+    }
+    /**
+     * Compare kinds, values (`Object.is`), spans, and ordered children.
+     *
+     * @param other - Tree to compare against.
+     */
+    equals(other) {
+        const stack = [[this.rootNode, other.rootNode]];
+        while (stack.length > 0) {
+            const pair = stack.pop();
+            if (pair === (void 0)) {
+                break;
+            }
+            const [left, right] = pair;
+            if (left.kind !== right.kind) {
+                return false;
+            }
+            if (!Object.is(left.value, right.value)) {
+                return false;
+            }
+            if (!spansEqual(left.span, right.span)) {
+                return false;
+            }
+            if (left.children.length !== right.children.length) {
+                return false;
+            }
+            for (let index = 0; index < left.children.length; index += 1) {
+                const leftChild = left.children[index];
+                const rightChild = right.children[index];
+                if (leftChild === (void 0) || rightChild === (void 0)) {
+                    return false;
+                }
+                stack.push([leftChild, rightChild]);
+            }
+        }
+        return true;
+    }
+    /**
+     * Return a plain deep clone suitable for serialization.
+     *
+     * Node and span objects are freshly allocated and contain no class
+     * instances. Payload values are copied by reference, as with `clone()`.
+     */
+    toJSON() {
+        return cloneNode(this.rootNode);
+    }
+    /**
+     * Iterate in preorder; equivalent to `walk('preorder')`.
+     */
+    [Symbol.iterator]() {
+        return this.walk("preorder");
+    }
+}

package/lib/structure/avlTree.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Height-balanced AVL search tree.
+ *
+ * Every node stores its subtree height, and each insertion or deletion walks
+ * back up the affected path applying LL/RR/LR/RL rotations until every balance
+ * factor is in `[-1, 1]`. The tree therefore keeps its height O(log n) even for
+ * sorted insertion sequences, and `insert`, `has`, `delete`, `min`, `max`,
+ * `floor` and `ceil` are O(log n) worst case.
+ */
+import type { TreeOptions } from "./binarySearchTree.js";
+export type { TreeOptions };
+/**
+ * A self-balancing AVL binary search tree.
+ *
+ * Duplicate values (comparator result 0) are rejected. The stored
+ * representative is never replaced by an equivalent insert; deleting with an
+ * equivalent value removes the stored representative.
+ */
+export declare class AVLTree<T> implements Iterable<T> {
+    private rootNode;
+    private count;
+    private readonly compare;
+    /**
+     * Create an empty AVL tree.
+     *
+     * @param options - Comparator override; defaults to natural ordering.
+     */
+    constructor(options?: TreeOptions<T>);
+    /**
+     * Number of stored values.
+     */
+    get size(): number;
+    /**
+     * Height of the tree in nodes: 0 when empty, 1 for a leaf.
+     */
+    get height(): number;
+    /**
+     * Whether the tree contains no values.
+     */
+    get isEmpty(): boolean;
+    /**
+     * Insert a value unless an equivalent one is already stored.
+     *
+     * @param value - Value to insert.
+     * @returns `true` if a node was added, `false` for an equivalent duplicate.
+     */
+    insert(value: T): boolean;
+    /**
+     * Test whether an equivalent value is stored.
+     *
+     * @param value - Value to look up.
+     */
+    has(value: T): boolean;
+    /**
+     * Delete the value equivalent to `value` and rebalance the path to the root.
+     *
+     * A two-child node is replaced by its in-order successor. Rotation is applied
+     * on every ancestor whose balance factor leaves `[-1, 1]`.
+     *
+     * @param value - Value to remove.
+     * @returns `true` if a value was removed, `false` when none is equivalent.
+     */
+    delete(value: T): boolean;
+    /**
+     * Minimum stored value according to the comparator, or `undefined` when
+     * empty.
+     */
+    min(): T | undefined;
+    /**
+     * Maximum stored value according to the comparator, or `undefined` when
+     * empty.
+     */
+    max(): T | undefined;
+    /**
+     * Greatest stored value that is less than or equal to `value` in comparator
+     * order, or `undefined` when there is none.
+     */
+    floor(value: T): T | undefined;
+    /**
+     * Least stored value that is greater than or equal to `value` in comparator
+     * order, or `undefined` when there is none.
+     */
+    ceil(value: T): T | undefined;
+    /**
+     * Remove every value and reset the height to 0.
+     */
+    clear(): void;
+    /**
+     * Collect values in ascending comparator order.
+     */
+    toArray(): T[];
+    /**
+     * Iterate values in ascending comparator order.
+     *
+     * Mutating the tree while iterating is not supported.
+     */
+    [Symbol.iterator](): Generator<T>;
+    /**
+     * Check the tree's invariants.
+     *
+     * Verifies strict in-order ordering, the maintained size, every node's stored
+     * height against the actual subtree height, and the AVL balance condition
+     * `|balanceFactor| <= 1`. An empty array means the tree is valid.
+     */
+    validate(): string[];
+    private insertNode;
+    private deleteNode;
+    /**
+     * Recompute this node's height and repair its subtree with rotations.
+     */
+    private rebalance;
+    /**
+     * Right rotation; returns the new subtree root.
+     */
+    private rotateRight;
+    /**
+     * Left rotation; returns the new subtree root.
+     */
+    private rotateLeft;
+    private updateHeight;
+    private balanceFactor;
+    private static heightOf;
+    private static minimumNode;
+    private inorderValues;
+}