novac 2.0.1 → 2.2.0

package/kits/kitmpatch/kitdef.js

@@ -0,0 +1,906 @@
+// ============================================
+// novac monkey patching + live AST toolkit
+// ============================================
+
+// --------------------------------------------
+// utilities
+// --------------------------------------------
+
+function deepClone(obj) {
+    return structuredClone
+        ? structuredClone(obj)
+        : JSON.parse(JSON.stringify(obj));
+}
+
+function deepEqual(a, b) {
+    if (a === b) return true;
+
+    if (typeof a !== typeof b)
+        return false;
+
+    if (typeof a !== 'object' || a === null || b === null)
+        return false;
+
+    let aKeys = Object.keys(a);
+    let bKeys = Object.keys(b);
+
+    if (aKeys.length !== bKeys.length)
+        return false;
+
+    for (let key of aKeys) {
+        if (!deepEqual(a[key], b[key]))
+            return false;
+    }
+
+    return true;
+}
+
+function stripMeta(obj) {
+    if (typeof obj !== 'object' || obj === null)
+        return obj;
+
+    let out = Array.isArray(obj) ? [] : {};
+
+    for (let key in obj) {
+        if (
+            key === 'line' ||
+            key === 'column' ||
+            key === 'collumn' ||
+            key === 'loc'
+        ) continue;
+
+        out[key] = stripMeta(obj[key]);
+    }
+
+    return out;
+}
+
+function randomID() {
+    return Math.random()
+        .toString(36)
+        .slice(2);
+}
+
+// ============================================
+// AST factory helpers
+// ============================================
+
+class AST {
+    static node(kind, props = {}) {
+        return {
+            kind,
+            ...props
+        };
+    }
+
+    static return(value) {
+        return {
+            kind: 'return',
+            value
+        };
+    }
+
+    static log(msg) {
+        return AST.call('log', [msg]);
+    }
+
+    static throw(err) {
+        return {
+            kind: 'throw',
+            value: err
+        };
+    }
+
+    static raw(ast) {
+        return ast;
+    }
+}
+
+// ============================================
+// AST walker
+// ============================================
+
+class Walker {
+    static walk(node, visitor) {
+        function visit(n, parent = null) {
+            if (!n || typeof n !== 'object')
+                return;
+
+            visitor(n, parent);
+
+            for (let key in n) {
+                visit(n[key], n);
+            }
+        }
+
+        visit(node);
+    }
+
+    static map(node, mapper) {
+        function transform(n) {
+            if (!n || typeof n !== 'object')
+                return n;
+
+            n = mapper(n) || n;
+
+            for (let key in n) {
+                n[key] = transform(n[key]);
+            }
+
+            return n;
+        }
+
+        return transform(node);
+    }
+
+    static find(node, predicate) {
+        let matches = [];
+
+        Walker.walk(node, (n) => {
+            if (predicate(n))
+                matches.push(n);
+        });
+
+        return matches;
+    }
+}
+
+// ============================================
+// AST diffing engine
+// ============================================
+
+class ASTDiff {
+    static compare(a, b) {
+        return deepEqual(
+            stripMeta(a),
+            stripMeta(b)
+        );
+    }
+
+    static changed(a, b) {
+        return !ASTDiff.compare(a, b);
+    }
+
+    static diff(a, b) {
+        let diffs = [];
+
+        function scan(x, y, path = '') {
+            if (!deepEqual(x, y)) {
+                diffs.push({
+                    path,
+                    old: x,
+                    new: y
+                });
+            }
+
+            if (
+                typeof x === 'object' &&
+                typeof y === 'object'
+            ) {
+                for (let k in x) {
+                    scan(
+                        x[k],
+                        y[k],
+                        path + '.' + k
+                    );
+                }
+            }
+        }
+
+        scan(a, b);
+
+        return diffs;
+    }
+}
+
+// ============================================
+// patch transaction system
+// ============================================
+
+class PatchTransaction {
+    constructor(patcher) {
+        this.patcher = patcher;
+        this.snapshot = deepClone(
+            patcher.ast
+        );
+    }
+
+    rollback() {
+        this.patcher.ast =
+            deepClone(this.snapshot);
+
+        this.patcher.fn.body =
+            this.patcher.ast;
+
+        return this.patcher;
+    }
+
+    commit() {
+        return this.patcher.patch();
+    }
+}
+
+// ============================================
+// hook system
+// ============================================
+
+class HookManager {
+    constructor() {
+        this.hooks = {};
+    }
+
+    on(event, fn) {
+        if (!this.hooks[event])
+            this.hooks[event] = [];
+
+        this.hooks[event].push(fn);
+    }
+
+    emit(event, data) {
+        if (!this.hooks[event])
+            return;
+
+        this.hooks[event]
+            .forEach(fn => fn(data));
+    }
+
+    off(event, fn) {
+        if (!this.hooks[event])
+            return;
+
+        this.hooks[event] =
+            this.hooks[event]
+                .filter(x => x !== fn);
+    }
+}
+
+// ============================================
+// live function registry
+// ============================================
+
+class LiveRegistry {
+    constructor() {
+        this.functions = new Map();
+    }
+
+    register(name, fn) {
+        this.functions.set(name, fn);
+    }
+
+    get(name) {
+        return this.functions.get(name);
+    }
+
+    patch(name) {
+        return new Patcher(
+            this.get(name)
+        );
+    }
+
+    remove(name) {
+        this.functions.delete(name);
+    }
+
+    list() {
+        return [
+            ...this.functions.keys()
+        ];
+    }
+}
+
+// ============================================
+// main patcher
+// ============================================
+
+class Patcher {
+    static hooks = new HookManager();
+
+    constructor(fn) {
+        this.id = randomID();
+
+        this.fn = fn;
+
+        this.ast = fn.body;
+
+        this.original =
+            deepClone(fn.body);
+
+        this.history = [];
+
+        Patcher.hooks.emit(
+            'patcher:create',
+            this
+        );
+    }
+
+    // ----------------------------------------
+    // internals
+    // ----------------------------------------
+
+    _save(op, data) {
+        this.history.push({
+            op,
+            data,
+            time: Date.now()
+        });
+
+        Patcher.hooks.emit(
+            'patch',
+            {
+                patcher: this,
+                op,
+                data
+            }
+        );
+    }
+
+    _normalize(ast) {
+        return ast?.ast ?? ast;
+    }
+
+    // ----------------------------------------
+    // transactions
+    // ----------------------------------------
+
+    transaction() {
+        return new PatchTransaction(
+            this
+        );
+    }
+
+    // ----------------------------------------
+    // restore
+    // ----------------------------------------
+
+    old() {
+        this.fn.body =
+            deepClone(this.original);
+
+        this.ast = this.fn.body;
+
+        return this;
+    }
+
+    rollback(steps = 1) {
+        while (
+            steps-- > 0 &&
+            this.history.length > 0
+        ) {
+            let h = this.history.pop();
+
+            switch (h.op) {
+                case 'insert':
+                    this.ast.splice(
+                        h.data.idx,
+                        1
+                    );
+                    break;
+
+                case 'remove':
+                    this.ast.splice(
+                        h.data.idx,
+                        0,
+                        h.data.oldNode
+                    );
+                    break;
+
+                case 'replace':
+                    this.ast[h.data.idx] =
+                        h.data.oldNode;
+                    break;
+            }
+        }
+
+        return this;
+    }
+
+    // ----------------------------------------
+    // mutations
+    // ----------------------------------------
+
+    injectBefore(idx, ast) {
+        this._save('insert', { idx });
+
+        this.ast.splice(
+            idx,
+            0,
+            this._normalize(ast)
+        );
+
+        return this;
+    }
+
+    injectAfter(idx, ast) {
+        this._save('insert', {
+            idx: idx + 1
+        });
+
+        this.ast.splice(
+            idx + 1,
+            0,
+            this._normalize(ast)
+        );
+
+        return this;
+    }
+
+    replace(idx, ast) {
+        this._save('replace', {
+            idx,
+            oldNode: deepClone(
+                this.ast[idx]
+            )
+        });
+
+        this.ast[idx] =
+            this._normalize(ast);
+
+        return this;
+    }
+
+    remove(idx) {
+        this._save('remove', {
+            idx,
+            oldNode: deepClone(
+                this.ast[idx]
+            )
+        });
+
+        this.ast.splice(idx, 1);
+
+        return this;
+    }
+
+    append(ast) {
+        this.ast.push(
+            this._normalize(ast)
+        );
+
+        return this;
+    }
+
+    // inside the Patcher class
+
+    /**
+     * Match AST nodes by a predicate function or pattern object.
+     *
+     * Usage:
+     *   patcher.match(node => node.kind === "call")
+     *   patcher.match({ kind: "return" })
+     *
+     * Returns: array of { idx, node } objects
+     */
+    match(pattern) {
+        const matches = [];
+
+        function isMatch(node, pattern) {
+            // If pattern is a function
+            if (typeof pattern === 'function') {
+                return pattern(node);
+            }
+
+            // If pattern is an object
+            if (typeof pattern === 'object' && pattern !== null) {
+                // Strip metadata for comparison
+                const cleanNode = stripMeta(node);
+                const cleanPattern = stripMeta(pattern);
+
+                // Check every property in the pattern
+                for (let key in cleanPattern) {
+                    if (typeof cleanPattern[key] === 'object' && cleanPattern[key] !== null) {
+                        if (!isMatch(cleanNode[key], cleanPattern[key])) return false;
+                    } else {
+                        if (cleanNode[key] !== cleanPattern[key]) return false;
+                    }
+                }
+                return true;
+            }
+
+            return false;
+        }
+
+        this.ast.forEach((node, idx) => {
+            if (isMatch(node, pattern)) {
+                matches.push({ idx, node });
+            }
+        });
+
+        return matches;
+    }
+
+    prepend(ast) {
+        this.ast.unshift(
+            this._normalize(ast)
+        );
+
+        return this;
+    }
+
+    clear() {
+        this.ast.length = 0;
+        return this;
+    }
+
+    reverse() {
+        this.ast.reverse();
+        return this;
+    }
+
+    shuffle() {
+        this.ast.sort(
+            () => Math.random() - 0.5
+        );
+
+        return this;
+    }
+
+    duplicate(idx) {
+        this.ast.splice(
+            idx,
+            0,
+            deepClone(this.ast[idx])
+        );
+
+        return this;
+    }
+
+    // ----------------------------------------
+    // querying
+    // ----------------------------------------
+
+    find(kind) {
+        let out = [];
+
+        this.ast.forEach((n, i) => {
+            if (n.kind === kind)
+                out.push(i);
+        });
+
+        return out;
+    }
+
+    where(node) {
+        let out = [];
+
+        this.ast.forEach((n, i) => {
+            if (
+                deepEqual(
+                    stripMeta(n),
+                    stripMeta(node)
+                )
+            ) {
+                out.push(i);
+            }
+        });
+
+        return out;
+    }
+
+    select(predicate) {
+        let out = [];
+
+        this.ast.forEach((n, i) => {
+            if (predicate(n, i))
+                out.push(i);
+        });
+
+        return out;
+    }
+
+    // ----------------------------------------
+    // high level patching
+    // ----------------------------------------
+
+    before(kind, ast) {
+        this.find(kind)
+            .reverse()
+            .forEach(idx => {
+                this.injectBefore(
+                    idx,
+                    ast
+                );
+            });
+
+        return this;
+    }
+
+    after(kind, ast) {
+        this.find(kind)
+            .reverse()
+            .forEach(idx => {
+                this.injectAfter(
+                    idx,
+                    ast
+                );
+            });
+
+        return this;
+    }
+
+    replaceKind(kind, ast) {
+        this.find(kind)
+            .reverse()
+            .forEach(idx => {
+                this.replace(
+                    idx,
+                    ast
+                );
+            });
+
+        return this;
+    }
+
+    interceptCall(
+        name,
+        transformer
+    ) {
+        this.select(n =>
+            n.kind === 'call' &&
+            n.name === name
+        )
+            .reverse()
+            .forEach(idx => {
+                this.ast[idx] =
+                    transformer(
+                        this.ast[idx]
+                    );
+            });
+
+        return this;
+    }
+
+    renameCall(from, to) {
+        return this.interceptCall(
+            from,
+            call => {
+                call.name = to;
+                return call;
+            }
+        );
+    }
+
+    // ----------------------------------------
+    // instrumentation
+    // ----------------------------------------
+
+    trace() {
+        this.ast = this.ast.flatMap(
+            node => [
+                AST.log(
+                    `[TRACE] ${node.kind}`
+                ),
+                node
+            ]
+        );
+
+        return this;
+    }
+
+    profile() {
+        this.prepend(
+            AST.call(
+                '__profilerStart'
+            )
+        );
+
+        this.after(
+            'return',
+            AST.call(
+                '__profilerEnd'
+            )
+        );
+
+        return this;
+    }
+
+    freeze() {
+        Object.freeze(this.ast);
+        return this;
+    }
+
+    // ----------------------------------------
+    // compiler transforms
+    // ----------------------------------------
+
+    constantFold() {
+        this.walk(node => {
+            if (
+                node.kind === 'binary' &&
+                typeof node.left ===
+                'number' &&
+                typeof node.right ===
+                'number'
+            ) {
+                switch (node.op) {
+                    case '+':
+                        node.kind =
+                            'number';
+
+                        node.value =
+                            node.left +
+                            node.right;
+                }
+            }
+        });
+
+        return this;
+    }
+
+    deadCodeElimination() {
+        let foundReturn = false;
+
+        this.ast = this.ast.filter(
+            node => {
+                if (foundReturn)
+                    return false;
+
+                if (
+                    node.kind ===
+                    'return'
+                ) {
+                    foundReturn = true;
+                }
+
+                return true;
+            }
+        );
+
+        return this;
+    }
+
+    inlineCalls(name, body) {
+        this.select(n =>
+            n.kind === 'call' &&
+            n.name === name
+        )
+            .reverse()
+            .forEach(idx => {
+                this.replace(
+                    idx,
+                    deepClone(body)
+                );
+            });
+
+        return this;
+    }
+
+    // ----------------------------------------
+    // walking
+    // ----------------------------------------
+
+    walk(visitor) {
+        this.ast.forEach(node => {
+            Walker.walk(
+                node,
+                visitor
+            );
+        });
+
+        return this;
+    }
+
+    map(transformer) {
+        this.ast = this.ast.map(
+            transformer
+        );
+
+        return this;
+    }
+
+    filter(predicate) {
+        this.ast = this.ast.filter(
+            predicate
+        );
+
+        return this;
+    }
+
+    // ----------------------------------------
+    // snapshots
+    // ----------------------------------------
+
+    snapshot() {
+        return deepClone(this.ast);
+    }
+
+    compare(snapshot) {
+        return ASTDiff.diff(
+            snapshot,
+            this.ast
+        );
+    }
+
+    // ----------------------------------------
+    // finalize
+    // ----------------------------------------
+
+    patch() {
+        this.fn.body = this.ast;
+
+        Patcher.hooks.emit(
+            'patcher:commit',
+            this
+        );
+
+        return this.fn;
+    }
+}
+
+// ============================================
+// plugin system
+// ============================================
+
+class PluginSystem {
+    constructor() {
+        this.plugins = [];
+    }
+
+    use(plugin) {
+        this.plugins.push(plugin);
+
+        if (plugin.install)
+            plugin.install(this);
+    }
+
+    apply(patcher) {
+        this.plugins.forEach(p => {
+            if (p.transform)
+                p.transform(patcher);
+        });
+    }
+}
+
+// ============================================
+// built-in plugins
+// ============================================
+
+const DebugPlugin = {
+    transform(patcher) {
+        patcher.trace();
+    }
+};
+
+const SafetyPlugin = {
+    transform(patcher) {
+        patcher.before(
+            'return',
+            AST.log(
+                '[SAFE RETURN]'
+            )
+        );
+    }
+};
+
+// ============================================
+// exports
+// ============================================
+
+const registry =
+    new LiveRegistry();
+
+const plugins =
+    new PluginSystem();
+
+const kitdef = {
+    patcher: Patcher,
+    walker: Walker,
+    ast: AST,
+    diff: ASTDiff,
+    registry,
+    plugins,
+    hooks: Patcher.hooks,
+    transaction: PatchTransaction,
+    debugPlugin: DebugPlugin,
+    safetyPlugin: SafetyPlugin,
+
+    utils: {
+        deepClone,
+        deepEqual,
+        stripMeta,
+        randomID
+    }
+};
+
+module.exports = {
+    kitdef
+};