@eagleoutice/flowr 1.3.11

package/util/cfg.js

@@ -0,0 +1,498 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cfg2quads = exports.equalCfg = exports.extractCFG = exports.emptyControlFlowInformation = exports.ControlFlowGraph = void 0;
+const r_bridge_1 = require("../r-bridge");
+const set_1 = require("./set");
+const quads_1 = require("./quads");
+const log_1 = require("./log");
+const json_1 = require("./json");
+/**
+ * This class represents the control flow graph of an R program.
+ * The control flow may be hierarchical when confronted with function definitions (see {@link CfgVertex} and {@link CFG#rootVertexIds|rootVertexIds()}).
+ */
+class ControlFlowGraph {
+    rootVertices = new Set();
+    vertexInformation = new Map();
+    edgeInformation = new Map();
+    addVertex(vertex, rootVertex = true) {
+        if (this.vertexInformation.has(vertex.id)) {
+            throw new Error(`Node with id ${vertex.id} already exists`);
+        }
+        this.vertexInformation.set(vertex.id, vertex);
+        if (rootVertex) {
+            this.rootVertices.add(vertex.id);
+        }
+        return this;
+    }
+    addEdge(from, to, edge) {
+        if (!this.edgeInformation.has(from)) {
+            this.edgeInformation.set(from, new Map());
+        }
+        this.edgeInformation.get(from)?.set(to, edge);
+        return this;
+    }
+    rootVertexIds() {
+        return this.rootVertices;
+    }
+    vertices() {
+        return this.vertexInformation;
+    }
+    edges() {
+        return this.edgeInformation;
+    }
+    merge(other, forceNested = false) {
+        for (const [id, node] of other.vertexInformation) {
+            this.addVertex(node, forceNested ? false : other.rootVertices.has(id));
+        }
+        for (const [from, edges] of other.edgeInformation) {
+            for (const [to, edge] of edges) {
+                this.addEdge(from, to, edge);
+            }
+        }
+        return this;
+    }
+}
+exports.ControlFlowGraph = ControlFlowGraph;
+function emptyControlFlowInformation() {
+    return {
+        returns: [],
+        breaks: [],
+        nexts: [],
+        entryPoints: [],
+        exitPoints: [],
+        graph: new ControlFlowGraph()
+    };
+}
+exports.emptyControlFlowInformation = emptyControlFlowInformation;
+const cfgFolds = {
+    foldNumber: cfgLeaf,
+    foldString: cfgLeaf,
+    foldLogical: cfgLeaf,
+    foldSymbol: cfgLeaf,
+    foldAccess: cfgAccess,
+    binaryOp: {
+        foldLogicalOp: cfgBinaryOp,
+        foldArithmeticOp: cfgBinaryOp,
+        foldComparisonOp: cfgBinaryOp,
+        foldAssignment: cfgBinaryOp,
+        foldPipe: cfgBinaryOp,
+        foldModelFormula: cfgBinaryOp
+    },
+    unaryOp: {
+        foldArithmeticOp: cfgUnaryOp,
+        foldLogicalOp: cfgUnaryOp,
+        foldModelFormula: cfgUnaryOp
+    },
+    other: {
+        foldComment: cfgIgnore,
+        foldLineDirective: cfgIgnore
+    },
+    loop: {
+        foldFor: cfgFor,
+        foldRepeat: cfgRepeat,
+        foldWhile: cfgWhile,
+        foldBreak: cfgBreak,
+        foldNext: cfgNext
+    },
+    foldIfThenElse: cfgIfThenElse,
+    foldExprList: cfgExprList,
+    functions: {
+        foldFunctionDefinition: cfgFunctionDefinition,
+        foldFunctionCall: cfgFunctionCall,
+        foldParameter: cfgArgumentOrParameter,
+        foldArgument: cfgArgumentOrParameter
+    }
+};
+function extractCFG(ast) {
+    return (0, r_bridge_1.foldAst)(ast.ast, cfgFolds);
+}
+exports.extractCFG = extractCFG;
+function cfgLeaf(leaf) {
+    const graph = new ControlFlowGraph();
+    graph.addVertex({ id: leaf.info.id, name: leaf.type });
+    return { graph, breaks: [], nexts: [], returns: [], exitPoints: [leaf.info.id], entryPoints: [leaf.info.id] };
+}
+function cfgBreak(leaf) {
+    return { ...cfgLeaf(leaf), breaks: [leaf.info.id] };
+}
+function cfgNext(leaf) {
+    return { ...cfgLeaf(leaf), nexts: [leaf.info.id] };
+}
+function cfgIgnore(_leaf) {
+    return { graph: new ControlFlowGraph(), breaks: [], nexts: [], returns: [], exitPoints: [], entryPoints: [] };
+}
+function cfgIfThenElse(ifNode, condition, then, otherwise) {
+    const graph = new ControlFlowGraph();
+    graph.addVertex({ id: ifNode.info.id, name: ifNode.type });
+    graph.addVertex({ id: ifNode.info.id + '-exit', name: 'if-exit' });
+    graph.merge(condition.graph);
+    graph.merge(then.graph);
+    if (otherwise) {
+        graph.merge(otherwise.graph);
+    }
+    for (const exitPoint of condition.exitPoints) {
+        for (const entryPoint of then.entryPoints) {
+            graph.addEdge(entryPoint, exitPoint, { label: 'CD', when: r_bridge_1.RTrue });
+        }
+        for (const entryPoint of otherwise?.entryPoints ?? []) {
+            graph.addEdge(entryPoint, exitPoint, { label: 'CD', when: r_bridge_1.RFalse });
+        }
+    }
+    for (const entryPoint of condition.entryPoints) {
+        graph.addEdge(entryPoint, ifNode.info.id, { label: 'FD' });
+    }
+    for (const exit of [...then.exitPoints, ...otherwise?.exitPoints ?? []]) {
+        graph.addEdge(ifNode.info.id + '-exit', exit, { label: 'FD' });
+    }
+    if (!otherwise) {
+        for (const exitPoint of condition.exitPoints) {
+            graph.addEdge(ifNode.info.id + '-exit', exitPoint, { label: 'CD', when: r_bridge_1.RFalse });
+        }
+    }
+    return {
+        graph,
+        breaks: [...then.breaks, ...otherwise?.breaks ?? []],
+        nexts: [...then.nexts, ...otherwise?.nexts ?? []],
+        returns: [...then.returns, ...otherwise?.returns ?? []],
+        exitPoints: [ifNode.info.id + '-exit'],
+        entryPoints: [ifNode.info.id]
+    };
+}
+function cfgRepeat(repeat, body) {
+    const graph = body.graph;
+    graph.addVertex({ id: repeat.info.id, name: repeat.type });
+    graph.addVertex({ id: repeat.info.id + '-exit', name: 'repeat-exit' });
+    for (const entryPoint of body.entryPoints) {
+        graph.addEdge(repeat.info.id, entryPoint, { label: 'FD' });
+    }
+    // loops automatically
+    for (const next of [...body.nexts, ...body.exitPoints]) {
+        graph.addEdge(repeat.info.id, next, { label: 'FD' });
+    }
+    for (const breakPoint of body.breaks) {
+        graph.addEdge(repeat.info.id + '-exit', breakPoint, { label: 'FD' });
+    }
+    return { graph, breaks: [], nexts: [], returns: body.returns, exitPoints: [repeat.info.id + '-exit'], entryPoints: [repeat.info.id] };
+}
+function cfgWhile(whileLoop, condition, body) {
+    const graph = condition.graph;
+    graph.addVertex({ id: whileLoop.info.id, name: whileLoop.type });
+    graph.addVertex({ id: whileLoop.info.id + '-exit', name: 'while-exit' });
+    graph.merge(body.graph);
+    for (const entry of condition.entryPoints) {
+        graph.addEdge(entry, whileLoop.info.id, { label: 'FD' });
+    }
+    for (const exit of condition.exitPoints) {
+        for (const entry of body.entryPoints) {
+            graph.addEdge(entry, exit, { label: 'CD', when: r_bridge_1.RTrue });
+        }
+    }
+    for (const entryPoint of body.entryPoints) {
+        graph.addEdge(whileLoop.info.id, entryPoint, { label: 'FD' });
+    }
+    for (const next of [...body.nexts, ...body.exitPoints]) {
+        graph.addEdge(whileLoop.info.id, next, { label: 'FD' });
+    }
+    for (const breakPoint of body.breaks) {
+        graph.addEdge(whileLoop.info.id + '-exit', breakPoint, { label: 'FD' });
+    }
+    // while can break on the condition as well
+    for (const exit of condition.exitPoints) {
+        graph.addEdge(whileLoop.info.id + '-exit', exit, { label: 'CD', when: r_bridge_1.RFalse });
+    }
+    return { graph, breaks: [], nexts: [], returns: body.returns, exitPoints: [whileLoop.info.id + '-exit'], entryPoints: [whileLoop.info.id] };
+}
+function cfgFor(forLoop, variable, vector, body) {
+    const graph = variable.graph;
+    graph.addVertex({ id: forLoop.info.id, name: forLoop.type });
+    graph.addVertex({ id: forLoop.info.id + '-exit', name: 'for-exit' });
+    graph.merge(vector.graph);
+    graph.merge(body.graph);
+    for (const entry of vector.entryPoints) {
+        graph.addEdge(entry, forLoop.info.id, { label: 'FD' });
+    }
+    for (const exit of vector.exitPoints) {
+        for (const entry of variable.entryPoints) {
+            graph.addEdge(entry, exit, { label: 'FD' });
+        }
+    }
+    for (const exit of variable.exitPoints) {
+        for (const entry of body.entryPoints) {
+            graph.addEdge(entry, exit, { label: 'CD', when: r_bridge_1.RTrue });
+        }
+    }
+    for (const next of [...body.nexts, ...body.exitPoints]) {
+        graph.addEdge(forLoop.info.id, next, { label: 'FD' });
+    }
+    for (const breakPoint of body.breaks) {
+        graph.addEdge(forLoop.info.id + '-exit', breakPoint, { label: 'FD' });
+    }
+    // while can break on the condition as well
+    for (const exit of variable.exitPoints) {
+        graph.addEdge(forLoop.info.id + '-exit', exit, { label: 'CD', when: r_bridge_1.RFalse });
+    }
+    return { graph, breaks: [], nexts: [], returns: body.returns, exitPoints: [forLoop.info.id + '-exit'], entryPoints: [forLoop.info.id] };
+}
+function cfgFunctionDefinition(fn, params, body) {
+    const graph = new ControlFlowGraph();
+    const children = [fn.info.id + '-params', fn.info.id + '-exit'];
+    graph.addVertex({ id: fn.info.id + '-params', name: 'function-parameters' }, false);
+    graph.addVertex({ id: fn.info.id + '-exit', name: 'function-exit' }, false);
+    graph.addVertex({ id: fn.info.id, name: fn.type, children });
+    graph.merge(body.graph, true);
+    children.push(...body.graph.rootVertexIds());
+    for (const param of params) {
+        graph.merge(param.graph, true);
+        children.push(...param.graph.rootVertexIds());
+        for (const entry of param.entryPoints) {
+            graph.addEdge(entry, fn.info.id, { label: 'FD' });
+        }
+        for (const exit of param.exitPoints) {
+            graph.addEdge(fn.info.id + '-params', exit, { label: 'FD' });
+        }
+    }
+    for (const entry of body.entryPoints) {
+        graph.addEdge(entry, fn.info.id + '-params', { label: 'FD' });
+    }
+    // breaks and nexts should be illegal but safe is safe i guess
+    for (const next of [...body.returns, ...body.breaks, ...body.nexts, ...body.exitPoints]) {
+        graph.addEdge(fn.info.id + '-exit', next, { label: 'FD' });
+    }
+    return { graph: graph, breaks: [], nexts: [], returns: body.returns, exitPoints: [fn.info.id], entryPoints: [fn.info.id] };
+}
+function cfgFunctionCall(call, name, args) {
+    const graph = name.graph;
+    const info = { graph, breaks: [...name.breaks], nexts: [...name.nexts], returns: [...name.returns], exitPoints: [call.info.id + '-exit'], entryPoints: [call.info.id] };
+    graph.addVertex({ id: call.info.id, name: call.type });
+    for (const entryPoint of name.entryPoints) {
+        graph.addEdge(entryPoint, call.info.id, { label: 'FD' });
+    }
+    graph.addVertex({ id: call.info.id + '-name', name: 'call-name' });
+    for (const exitPoint of name.exitPoints) {
+        graph.addEdge(call.info.id + '-name', exitPoint, { label: 'FD' });
+    }
+    graph.addVertex({ id: call.info.id + '-exit', name: 'call-exit' });
+    let lastArgExits = [call.info.id + '-name'];
+    for (const arg of args) {
+        if (arg === undefined) {
+            continue;
+        }
+        graph.merge(arg.graph);
+        info.breaks.push(...arg.breaks);
+        info.nexts.push(...arg.nexts);
+        info.returns.push(...arg.returns);
+        for (const entry of arg.entryPoints) {
+            for (const exit of lastArgExits) {
+                graph.addEdge(entry, exit, { label: 'FD' });
+            }
+        }
+        lastArgExits = arg.exitPoints;
+    }
+    for (const exit of lastArgExits) {
+        graph.addEdge(call.info.id + '-exit', exit, { label: 'FD' });
+    }
+    // should not contain any breaks, nexts, or returns, (except for the body if something like 'break()')
+    return info;
+}
+function cfgArgumentOrParameter(node, name, value) {
+    const graph = new ControlFlowGraph();
+    const info = { graph, breaks: [], nexts: [], returns: [], exitPoints: [node.info.id + '-exit'], entryPoints: [node.info.id] };
+    graph.addVertex({ id: node.info.id, name: node.type });
+    let currentExitPoint = [node.info.id];
+    if (name) {
+        graph.merge(name.graph);
+        info.breaks.push(...name.breaks);
+        info.nexts.push(...name.nexts);
+        info.returns.push(...name.returns);
+        for (const entry of name.entryPoints) {
+            graph.addEdge(entry, node.info.id, { label: 'FD' });
+        }
+        currentExitPoint = name.exitPoints;
+    }
+    graph.addVertex({ id: node.info.id + '-before-value', name: 'before-value' });
+    for (const exitPoints of currentExitPoint) {
+        graph.addEdge(node.info.id + '-before-value', exitPoints, { label: 'FD' });
+    }
+    currentExitPoint = [node.info.id + '-before-value'];
+    if (value) {
+        graph.merge(value.graph);
+        info.breaks.push(...value.breaks);
+        info.nexts.push(...value.nexts);
+        info.returns.push(...value.returns);
+        for (const exitPoint of currentExitPoint) {
+            for (const entry of value.entryPoints) {
+                graph.addEdge(entry, exitPoint, { label: 'FD' });
+            }
+        }
+        currentExitPoint = value.exitPoints;
+    }
+    graph.addVertex({ id: node.info.id + '-exit', name: 'exit' });
+    for (const exit of currentExitPoint) {
+        graph.addEdge(node.info.id + '-exit', exit, { label: 'FD' });
+    }
+    return info;
+}
+function cfgBinaryOp(binOp, lhs, rhs) {
+    const graph = new ControlFlowGraph().merge(lhs.graph).merge(rhs.graph);
+    const result = { graph, breaks: [...lhs.breaks, ...rhs.breaks], nexts: [...lhs.nexts, ...rhs.nexts], returns: [...lhs.returns, ...rhs.returns], entryPoints: [binOp.info.id], exitPoints: [binOp.info.id + '-exit'] };
+    graph.addVertex({ id: binOp.info.id, name: binOp.type });
+    graph.addVertex({ id: binOp.info.id + '-exit', name: 'binOp-exit' });
+    for (const exitPoint of lhs.exitPoints) {
+        for (const entryPoint of rhs.entryPoints) {
+            result.graph.addEdge(entryPoint, exitPoint, { label: 'FD' });
+        }
+    }
+    for (const entryPoint of lhs.entryPoints) {
+        graph.addEdge(entryPoint, binOp.info.id, { label: 'FD' });
+    }
+    for (const exitPoint of rhs.exitPoints) {
+        graph.addEdge(binOp.info.id + '-exit', exitPoint, { label: 'FD' });
+    }
+    return result;
+}
+function cfgAccess(access, name, accessors) {
+    const result = name;
+    const graph = result.graph;
+    graph.addVertex({ id: access.info.id, name: access.type });
+    graph.addVertex({ id: access.info.id + '-exit', name: 'access-exit' });
+    for (const entry of name.entryPoints) {
+        graph.addEdge(entry, access.info.id, { label: 'FD' });
+    }
+    for (const exit of name.exitPoints) {
+        graph.addEdge(access.info.id, exit, { label: 'FD' });
+    }
+    result.entryPoints = [access.info.id];
+    result.exitPoints = [access.info.id + '-exit'];
+    if (typeof accessors === 'string') {
+        return result;
+    }
+    for (const accessor of accessors) {
+        if (accessor === null) {
+            continue;
+        }
+        graph.merge(accessor.graph);
+        for (const entry of accessor.entryPoints) {
+            graph.addEdge(entry, access.info.id, { label: 'FD' });
+        }
+        for (const exit of accessor.exitPoints) {
+            graph.addEdge(access.info.id + '-exit', exit, { label: 'FD' });
+        }
+    }
+    return result;
+}
+function cfgUnaryOp(unary, operand) {
+    const graph = operand.graph;
+    const result = { ...operand, graph, exitPoints: [unary.info.id] };
+    graph.addVertex({ id: unary.info.id, name: unary.type });
+    return result;
+}
+function cfgExprList(_node, expressions) {
+    const result = { graph: new ControlFlowGraph(), breaks: [], nexts: [], returns: [], exitPoints: [], entryPoints: [] };
+    let first = true;
+    for (const expression of expressions) {
+        if (first) {
+            result.entryPoints = expression.entryPoints;
+            first = false;
+        }
+        else {
+            for (const previousExitPoint of result.exitPoints) {
+                for (const entryPoint of expression.entryPoints) {
+                    result.graph.addEdge(entryPoint, previousExitPoint, { label: 'FD' });
+                }
+            }
+        }
+        result.graph.merge(expression.graph);
+        result.breaks.push(...expression.breaks);
+        result.nexts.push(...expression.nexts);
+        result.returns.push(...expression.returns);
+        result.exitPoints = expression.exitPoints;
+    }
+    return result;
+}
+function equalChildren(a, b) {
+    if (!a || !b || a.length !== b.length) {
+        return false;
+    }
+    for (let i = 0; i < a.length; ++i) {
+        if (a[i] !== b[i]) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * Returns true if the given CFG equals the other CFG. False otherwise.
+ */
+function equalCfg(a, b) {
+    if (!a || !b) {
+        return a === b;
+    }
+    else if (!(0, set_1.setEquals)(a.rootVertexIds(), b.rootVertexIds())) {
+        log_1.log.debug(`root vertex ids differ ${JSON.stringify(a.rootVertexIds(), json_1.jsonReplacer)} vs. ${JSON.stringify(b.rootVertexIds(), json_1.jsonReplacer)}.`);
+        return false;
+    }
+    const aVert = a.vertices();
+    const bVert = b.vertices();
+    if (aVert.size !== bVert.size) {
+        log_1.log.debug(`vertex count differs ${aVert.size} vs. ${bVert.size}.`);
+        return false;
+    }
+    for (const [id, aInfo] of aVert) {
+        const bInfo = bVert.get(id);
+        if (bInfo === undefined || aInfo.name !== bInfo.name || equalChildren(aInfo.children, bInfo.children)) {
+            log_1.log.debug(`vertex ${id} differs ${JSON.stringify(aInfo, json_1.jsonReplacer)} vs. ${JSON.stringify(bInfo, json_1.jsonReplacer)}.`);
+            return false;
+        }
+    }
+    const aEdges = a.edges();
+    const bEdges = b.edges();
+    if (aEdges.size !== bEdges.size) {
+        log_1.log.debug(`edge count differs ${aEdges.size} vs. ${bEdges.size}.`);
+        return false;
+    }
+    for (const [from, aTo] of aEdges) {
+        const bTo = bEdges.get(from);
+        if (bTo === undefined || aTo.size !== bTo.size) {
+            log_1.log.debug(`edge count for ${from} differs ${aTo.size} vs. ${bTo?.size ?? '?'}.`);
+            return false;
+        }
+        for (const [to, aEdge] of aTo) {
+            const bEdge = bTo.get(to);
+            if (bEdge === undefined || aEdge.label !== bEdge.label) {
+                log_1.log.debug(`edge ${from} -> ${to} differs ${JSON.stringify(aEdge, json_1.jsonReplacer)} vs. ${JSON.stringify(bEdge, json_1.jsonReplacer)}.`);
+                return false;
+            }
+        }
+    }
+    return true;
+}
+exports.equalCfg = equalCfg;
+/**
+ * @see df2quads
+ * @see serialize2quads
+ * @see graph2quads
+ */
+function cfg2quads(cfg, config) {
+    return (0, quads_1.graph2quads)({
+        rootIds: [...cfg.graph.rootVertexIds()],
+        vertices: [...cfg.graph.vertices().entries()]
+            .map(([id, v]) => ({
+            id,
+            name: v.name,
+            children: v.children
+        })),
+        edges: [...cfg.graph.edges()].flatMap(([fromId, targets]) => [...targets].map(([toId, info]) => ({
+            from: fromId,
+            to: toId,
+            type: info.label,
+            when: info.when
+        }))),
+        entryPoints: cfg.entryPoints,
+        exitPoints: cfg.exitPoints,
+        breaks: cfg.breaks,
+        nexts: cfg.nexts,
+        returns: cfg.returns
+    }, config);
+}
+exports.cfg2quads = cfg2quads;
+//# sourceMappingURL=cfg.js.map

package/util/defaultmap.d.ts

@@ -0,0 +1,34 @@
+/**
+ * A default map allows for a generator to produce values automatically if you want to add something to a map that does not have a value associated with a given key.
+ * This does not implement the default map interface as return types (and some future methods may) change
+ */
+export declare class DefaultMap<K, V = K> {
+    /** the internal map the default map wraps around */
+    private readonly internal;
+    /** generator function to produce a default value for a given key */
+    private readonly generator;
+    /**
+   * @param generator - the generator to produce a default value for a given key
+   * @param map       - the initial map to start with
+   */
+    constructor(generator: (k: K) => V, map?: Map<K, V>);
+    /**
+   * Sets a value for a given key.
+   * As you provide value, this does not invoke the generator!
+   */
+    set(k: K, v: V): this;
+    /**
+   * Return a value for the given key, if the key does not exist within the default map,
+   * this will invoke the generator and assign the produced value.
+   */
+    get(k: K): V;
+    /**
+   * Iterates over all entries that have been set (explicitly or by the generator)
+   */
+    entries(): IterableIterator<[K, V]>;
+    /** returns only the keys really stored in the map */
+    keys(): IterableIterator<K>;
+    values(): IterableIterator<V>;
+    delete(k: K): boolean;
+    size(): number;
+}

package/util/defaultmap.js

@@ -0,0 +1,65 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DefaultMap = void 0;
+/**
+ * A default map allows for a generator to produce values automatically if you want to add something to a map that does not have a value associated with a given key.
+ * This does not implement the default map interface as return types (and some future methods may) change
+ */
+class DefaultMap {
+    /** the internal map the default map wraps around */
+    internal;
+    /** generator function to produce a default value for a given key */
+    generator;
+    /**
+   * @param generator - the generator to produce a default value for a given key
+   * @param map       - the initial map to start with
+   */
+    constructor(generator, map = new Map()) {
+        this.generator = generator;
+        this.internal = map;
+    }
+    /**
+   * Sets a value for a given key.
+   * As you provide value, this does not invoke the generator!
+   */
+    set(k, v) {
+        this.internal.set(k, v);
+        return this;
+    }
+    /**
+   * Return a value for the given key, if the key does not exist within the default map,
+   * this will invoke the generator and assign the produced value.
+   */
+    get(k) {
+        const potential = this.internal.get(k);
+        if (potential !== undefined) {
+            return potential;
+        }
+        else {
+            const defaultValue = this.generator(k);
+            this.internal.set(k, defaultValue);
+            return defaultValue;
+        }
+    }
+    /**
+   * Iterates over all entries that have been set (explicitly or by the generator)
+   */
+    entries() {
+        return this.internal.entries();
+    }
+    /** returns only the keys really stored in the map */
+    keys() {
+        return this.internal.keys();
+    }
+    values() {
+        return this.internal.values();
+    }
+    delete(k) {
+        return this.internal.delete(k);
+    }
+    size() {
+        return this.internal.size;
+    }
+}
+exports.DefaultMap = DefaultMap;
+//# sourceMappingURL=defaultmap.js.map

package/util/diff.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Provides utility types and functions to provide difference information if two structures
+ * are not equal. Maybe. Sometime, in the far future this will be as capable as the waldo package :dream:
+ *
+ * @module
+ */
+import { MergeableRecord } from './objects';
+/**
+ * Unifies the shape of all difference reports.
+ * They should have an array of comments on the potential differences/equality of
+ * the structures and a function to check if they are really equal.
+ */
+export interface DifferenceReport {
+    /**
+   * A human-readable description of differences during the comparison
+   * In combination with {@link isEqual} this can be used to provide detailed
+   * explanation on equal structures as well (e.g., if structures _could_ be equal).
+   */
+    comments(): readonly string[] | undefined;
+    /**
+   * @returns true iff the compared structures are equal
+   */
+    isEqual(): boolean;
+}
+export interface WriteableDifferenceReport extends DifferenceReport {
+    addComment(comment: string): void;
+}
+/**
+ * Identifies the information required by the core difference functions.
+ * The `leftname` and `rightname` fields are only used to provide more useful
+ * information in the difference report.
+ */
+export interface GenericDifferenceInformation extends MergeableRecord {
+    /** A human-readable name for the left structure in `left == right`. */
+    readonly leftname: string;
+    /** A human-readable name for the right structure in `left == right`. */
+    readonly rightname: string;
+    /** The report on the difference of the two structures. */
+    readonly report: WriteableDifferenceReport;
+    /** A human-readable indication of where we are (the prefix of the information if the structures differ) */
+    readonly position: string;
+}
+export declare function setDifference<T>(left: ReadonlySet<T>, right: ReadonlySet<T>, info: GenericDifferenceInformation): void;

package/util/diff.js

@@ -0,0 +1,28 @@
+"use strict";
+/**
+ * Provides utility types and functions to provide difference information if two structures
+ * are not equal. Maybe. Sometime, in the far future this will be as capable as the waldo package :dream:
+ *
+ * @module
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setDifference = void 0;
+const set_1 = require("./set");
+function setDifference(left, right, info) {
+    const lWithoutR = (0, set_1.setMinus)(left, right);
+    const rWithoutL = (0, set_1.setMinus)(right, left);
+    if (lWithoutR.size === 0 && rWithoutL.size === 0) {
+        return;
+    }
+    let message = info.position;
+    if (lWithoutR.size > 0) {
+        message += ` More elements in ${info.leftname}: ${JSON.stringify([...lWithoutR])}`;
+    }
+    if (rWithoutL.size > 0) {
+        message += lWithoutR.size > 0 ? ' and m' : 'M';
+        message += `ore in ${info.rightname}: ${JSON.stringify([...rWithoutL])}`;
+    }
+    info.report.addComment(message);
+}
+exports.setDifference = setDifference;
+//# sourceMappingURL=diff.js.map