@ffschrattenecker/tm1-mcp-server 6.0.0

package/dist/lib/callgraph/callGraph.js

@@ -0,0 +1,334 @@
+import { lookupReferences } from "./referenceIndex.js";
+function lc(s) {
+    return s.toLowerCase();
+}
+/** Build outgoing call edges for a given process (what it calls). */
+function outgoingCalls(index, process) {
+    const refs = index.bySourceProcess.get(lc(process)) ?? [];
+    const edges = [];
+    for (const r of refs) {
+        if (r.targetKind !== "process") {
+            continue;
+        }
+        if (!r.funcName) {
+            continue;
+        }
+        edges.push(refToEdge(r));
+    }
+    return edges;
+}
+/** Build incoming call edges (callers of this process). */
+function incomingCalls(index, process) {
+    const refs = index.byProcess.get(lc(process)) ?? [];
+    const edges = [];
+    for (const r of refs) {
+        if (r.sourceKind !== "process") {
+            continue;
+        }
+        if (!r.funcName) {
+            continue;
+        }
+        edges.push(refToEdge(r));
+    }
+    return edges;
+}
+function refToEdge(r) {
+    return {
+        caller: r.sourceName,
+        callee: r.targetName,
+        section: r.section,
+        line: r.line,
+        funcName: r.funcName ?? "ExecuteProcess",
+        snippet: r.snippet,
+        params: r.params ?? [],
+    };
+}
+// ─── Env resolution ──────────────────────────────────────────────────────────
+/**
+ * Resolve one call-site CallParamResolution against the parent node's env.
+ * - literal stays literal
+ * - passthrough → look up the named caller-param in parent env:
+ *     known literal → propagate; unknown → mark unknown; dynamic → dynamic
+ * - dynamic stays dynamic
+ */
+export function resolveEdgeParam(res, parentEnv) {
+    switch (res.kind) {
+        case "literal":
+            return { kind: "literal", value: res.value };
+        case "dynamic":
+            return { kind: "dynamic" };
+        case "passthrough": {
+            const up = parentEnv.get(res.paramName.toLowerCase());
+            if (!up) {
+                return { kind: "unknown", viaParam: res.paramName };
+            }
+            if (up.kind === "literal") {
+                return up;
+            }
+            if (up.kind === "unknown") {
+                return { kind: "unknown", viaParam: up.viaParam };
+            }
+            return { kind: "dynamic" };
+        }
+    }
+}
+/** Initial env for a process: its declared params, filled with defaults if known, else unknown. */
+function buildInitialEnv(procName, index) {
+    const env = new Map();
+    const params = index.processParams.get(lc(procName)) ?? [];
+    const defaults = index.processDefaults.get(lc(procName));
+    for (const p of params) {
+        const def = defaults?.get(p);
+        env.set(lc(p), def !== undefined
+            ? { kind: "literal", value: def }
+            : { kind: "unknown", viaParam: p });
+    }
+    return env;
+}
+/**
+ * Derive child's env from parent's env + edge params.
+ * Start from child's initial env (its own params + defaults), then overwrite
+ * anything the caller passed explicitly at this call site.
+ */
+function deriveChildEnv(childProc, edge, parentEnv, index) {
+    const env = buildInitialEnv(childProc, index);
+    const effectiveParams = [];
+    for (const cp of edge.params) {
+        const eff = resolveEdgeParam(cp.resolution, parentEnv);
+        env.set(lc(cp.name), eff);
+        effectiveParams.push({
+            name: cp.name,
+            effective: eff,
+            valueRaw: cp.valueRaw,
+        });
+    }
+    edge.effectiveParams = effectiveParams;
+    return env;
+}
+function unresolvedFor(index, process, direction) {
+    if (direction !== "downstream") {
+        return undefined;
+    }
+    const u = index.unresolvedCallsBySourceProcess.get(lc(process));
+    return u && u.length > 0 ? u : undefined;
+}
+// ─── Graph construction ─────────────────────────────────────────────────────
+/**
+ * Recursively build the call graph starting from `start`.
+ *
+ * downstream: children = processes that THIS process calls (with env-propagation)
+ * upstream:   children = processes that CALL this process (no env-propagation)
+ *
+ * Cycle detection uses the ancestor chain: if a candidate child is already
+ * on the path from the root, `cycle = true` and children are empty.
+ *
+ * Duplicate edges (same caller→callee, different lines/sections) are kept
+ * as separate nodes — each represents a distinct call site.
+ */
+export function buildCallGraph(index, start, opts) {
+    const maxDepth = opts.maxDepth ?? 20;
+    const includeSystem = opts.includeSystem ?? true;
+    const rootEnv = opts.direction === "downstream" ? buildInitialEnv(start, index) : undefined;
+    const root = {
+        process: start,
+        incomingEdge: null,
+        env: rootEnv,
+        children: [],
+        cycle: false,
+        unresolvedCalls: unresolvedFor(index, start, opts.direction),
+    };
+    const visit = (node, ancestors, depth) => {
+        if (depth >= maxDepth) {
+            node.depthLimitReached = true;
+            return;
+        }
+        const edges = opts.direction === "downstream"
+            ? outgoingCalls(index, node.process)
+            : incomingCalls(index, node.process);
+        edges.sort((a, b) => (opts.direction === "downstream"
+            ? a.callee.localeCompare(b.callee)
+            : a.caller.localeCompare(b.caller)) || a.line - b.line);
+        for (const edge of edges) {
+            const nextProc = opts.direction === "downstream" ? edge.callee : edge.caller;
+            if (!includeSystem && nextProc.startsWith("}")) {
+                continue;
+            }
+            const childEnv = opts.direction === "downstream" && node.env
+                ? deriveChildEnv(nextProc, edge, node.env, index)
+                : undefined;
+            const childNode = {
+                process: nextProc,
+                incomingEdge: edge,
+                env: childEnv,
+                children: [],
+                cycle: ancestors.has(lc(nextProc)),
+                unresolvedCalls: unresolvedFor(index, nextProc, opts.direction),
+            };
+            node.children.push(childNode);
+            if (!childNode.cycle) {
+                const nextAncestors = new Set(ancestors);
+                nextAncestors.add(lc(nextProc));
+                visit(childNode, nextAncestors, depth + 1);
+            }
+        }
+    };
+    const initialAncestors = new Set([lc(start)]);
+    visit(root, initialAncestors, 0);
+    return root;
+}
+// ─── Cube / Dimension usage ─────────────────────────────────────────────────
+// Functions that write cell/attribute data into a cube.
+const WRITE_FUNCS = new Set([
+    "cellputn",
+    "cellputs",
+    "cellincrementn",
+    "batchcellincrement",
+    "cellputproportionalspread",
+    "viewzeroout",
+    "cubecleardata",
+    "cubeprocessfeeders",
+    // Cube attribute value writes (target the }CubeAttributes control cube).
+    "cubeattrputn",
+    "cubeattrputs",
+    // Element/dimension attribute value writes (target the }ElementAttributes_<dim>
+    // control cube; classified as a write on the dimension).
+    "attrputn",
+    "attrputs",
+    "elementattrputn",
+    "elementattrputs",
+]);
+// Functions that read cell/attribute data from a cube.
+const READ_FUNCS = new Set([
+    "cellgetn",
+    "cellgets",
+    "cellexists",
+    "cellisrule",
+    "cellisundefined",
+    "cellisupdateable",
+    // Cube attribute value reads (locale form; CubeAttrN/S base form is not a real TI fn).
+    "cubeattrnl",
+    "cubeattrsl",
+    // Element/dimension attribute value reads (classified as a read on the dimension).
+    "attrn",
+    "attrs",
+    "attrnl",
+    "attrsl",
+    "elementattrn",
+    "elementattrs",
+    "elementattrnl",
+    "elementattrsl",
+    "db", // cube rule DB() reference
+]);
+export function classifyAccess(funcName, sourceKind) {
+    // Rule bracket-refs and DB() are always reads.
+    if (sourceKind === "rule")
+        return "read";
+    if (!funcName)
+        return "other";
+    const lc = funcName.toLowerCase();
+    if (WRITE_FUNCS.has(lc))
+        return "write";
+    if (READ_FUNCS.has(lc))
+        return "read";
+    return "other";
+}
+/**
+ * Collect all references to a cube or dimension as a flat list, sorted by
+ * source name and line. Self-references (a cube's own rules reading from the
+ * cube itself via DB()/`[...]`) are filtered out to avoid noise — the rule
+ * editor already shows them inline.
+ */
+export function buildCubeOrDimUsages(index, kind, name, opts = {}) {
+    const includeSystem = opts.includeSystem ?? true;
+    const accessMode = opts.accessMode ?? "all";
+    const refs = lookupReferences(index, kind, name);
+    const result = [];
+    const nameLc = name.toLowerCase();
+    for (const r of refs) {
+        // Skip self-refs: a cube's own rules referencing itself via DB()/`[...]`
+        if (kind === "cube" &&
+            r.sourceKind === "rule" &&
+            r.sourceName.toLowerCase() === nameLc) {
+            continue;
+        }
+        if (!includeSystem && r.sourceName.startsWith("}")) {
+            continue;
+        }
+        const accessType = classifyAccess(r.funcName, r.sourceKind);
+        if (accessMode !== "all" && accessType !== accessMode) {
+            continue;
+        }
+        result.push({
+            sourceKind: r.sourceKind,
+            sourceName: r.sourceName,
+            section: r.section,
+            line: r.line,
+            funcName: r.funcName,
+            snippet: r.snippet,
+            accessType,
+        });
+    }
+    result.sort((a, b) => a.sourceName.localeCompare(b.sourceName) || a.line - b.line);
+    return result;
+}
+/** Flattens the tree depth-first for simple list rendering. */
+export function flattenCallGraph(root) {
+    const out = [];
+    const walk = (n, depth) => {
+        out.push({ node: n, depth });
+        for (const c of n.children) {
+            walk(c, depth + 1);
+        }
+    };
+    walk(root, 0);
+    return out;
+}
+// ─── Formatting helpers ─────────────────────────────────────────────────────
+function formatEffective(eff, valueRaw) {
+    switch (eff.kind) {
+        case "literal": {
+            const wasQuoted = valueRaw.trim().startsWith("'");
+            return wasQuoted ? `'${eff.value}'` : eff.value;
+        }
+        case "unknown":
+            return `«${eff.viaParam}»`;
+        case "dynamic":
+            return "?";
+    }
+}
+/**
+ * Human-readable param summary using effective values (env-propagated).
+ * Falls back to raw resolution if no effective values are available (upstream mode).
+ *   pRegion='UK', pYear=2026, pSource=«pCaller», pDate=?
+ */
+export function formatEdgeParams(edge) {
+    if (edge.effectiveParams) {
+        if (edge.effectiveParams.length === 0) {
+            return "";
+        }
+        return edge.effectiveParams
+            .map((ep) => `${ep.name}=${formatEffective(ep.effective, ep.valueRaw)}`)
+            .join(", ");
+    }
+    // Upstream (no env): show resolution directly
+    if (edge.params.length === 0) {
+        return "";
+    }
+    return edge.params
+        .map((p) => {
+        switch (p.resolution.kind) {
+            case "literal": {
+                const wasQuoted = p.valueRaw.trim().startsWith("'");
+                return wasQuoted
+                    ? `${p.name}='${p.resolution.value}'`
+                    : `${p.name}=${p.resolution.value}`;
+            }
+            case "passthrough":
+                return `${p.name}=«${p.resolution.paramName}»`;
+            case "dynamic":
+                return `${p.name}=?`;
+        }
+    })
+        .join(", ");
+}
+//# sourceMappingURL=callGraph.js.map

package/dist/lib/callgraph/choreGraph.d.ts

@@ -0,0 +1,23 @@
+import type { ReferenceIndex, ChoreTaskRef } from "./referenceIndex.js";
+import type { CallGraphNode } from "./callGraph.js";
+export interface ChoreTaskTree {
+    step: number;
+    processName: string;
+    choreParams: ChoreTaskRef["params"];
+    tree: CallGraphNode;
+}
+export interface ChoreGraph {
+    choreName: string;
+    tasks: ChoreTaskTree[];
+}
+export interface BuildChoreGraphOptions {
+    /** Mirrors the call-graph option — filters }-prefixed sub-processes. Default: true. */
+    includeSystem?: boolean;
+}
+/**
+ * Build one downstream tree per chore task. Task params are seeded into the
+ * task-process's root env as literals and re-propagated down the tree.
+ * Returns null if the chore is not indexed.
+ */
+export declare function buildChoreGraph(index: ReferenceIndex, choreName: string, opts?: BuildChoreGraphOptions): ChoreGraph | null;
+//# sourceMappingURL=choreGraph.d.ts.map

package/dist/lib/callgraph/choreGraph.js

@@ -0,0 +1,102 @@
+import { buildCallGraph } from "./callGraph.js";
+/**
+ * Build one downstream tree per chore task. Task params are seeded into the
+ * task-process's root env as literals and re-propagated down the tree.
+ * Returns null if the chore is not indexed.
+ */
+export function buildChoreGraph(index, choreName, opts = {}) {
+    const tasks = index.choreTasks.get(choreName.toLowerCase());
+    if (!tasks) {
+        return null;
+    }
+    const includeSystem = opts.includeSystem ?? true;
+    const taskTrees = tasks.map((t) => {
+        const tree = buildCallGraph(index, t.processName, {
+            direction: "downstream",
+            includeSystem,
+        });
+        if (tree.env) {
+            for (const p of t.params) {
+                tree.env.set(p.name.toLowerCase(), { kind: "literal", value: p.value });
+            }
+            propagateNewRootEnv(tree, index);
+        }
+        return {
+            step: t.step,
+            processName: t.processName,
+            choreParams: t.params,
+            tree,
+        };
+    });
+    return { choreName, tasks: taskTrees };
+}
+/**
+ * Re-derive `effectiveParams` on each edge below the root after the chore has
+ * overwritten the root's env. We can't reuse `buildCallGraph` because we must
+ * keep the same tree instance; instead we re-resolve per child.
+ */
+function propagateNewRootEnv(root, index) {
+    const walk = (node, env) => {
+        for (const child of node.children) {
+            const edge = child.incomingEdge;
+            if (!edge) {
+                continue;
+            }
+            const childEnv = buildInitialEnv(child.process, index);
+            const effective = [];
+            for (const cp of edge.params) {
+                const eff = resolveEdgeParam(cp.resolution, env);
+                childEnv.set(cp.name.toLowerCase(), eff);
+                effective.push({
+                    name: cp.name,
+                    effective: eff,
+                    valueRaw: cp.valueRaw,
+                });
+            }
+            edge.effectiveParams = effective;
+            child.env = childEnv;
+            if (!child.cycle) {
+                walk(child, childEnv);
+            }
+        }
+    };
+    if (root.env) {
+        walk(root, root.env);
+    }
+}
+// Local copies of two helpers from callGraph.ts — keeps the module free of
+// new exports and preserves the existing public surface. Small and stable.
+function buildInitialEnv(procName, index) {
+    const env = new Map();
+    const params = index.processParams.get(procName.toLowerCase()) ?? [];
+    const defaults = index.processDefaults.get(procName.toLowerCase());
+    for (const p of params) {
+        const def = defaults?.get(p);
+        env.set(p.toLowerCase(), def !== undefined
+            ? { kind: "literal", value: def }
+            : { kind: "unknown", viaParam: p });
+    }
+    return env;
+}
+function resolveEdgeParam(res, parentEnv) {
+    switch (res.kind) {
+        case "literal":
+            return { kind: "literal", value: res.value };
+        case "dynamic":
+            return { kind: "dynamic" };
+        case "passthrough": {
+            const up = parentEnv.get(res.paramName.toLowerCase());
+            if (!up) {
+                return { kind: "unknown", viaParam: res.paramName };
+            }
+            if (up.kind === "literal") {
+                return up;
+            }
+            if (up.kind === "unknown") {
+                return { kind: "unknown", viaParam: up.viaParam };
+            }
+            return { kind: "dynamic" };
+        }
+    }
+}
+//# sourceMappingURL=choreGraph.js.map

package/dist/lib/callgraph/dataFlow.d.ts

@@ -0,0 +1,74 @@
+import { type ReferenceIndex } from "./referenceIndex.js";
+import type { DatasourceMembership, MembershipVia } from "./datasourceMembership.js";
+/** How a process touches a traced element (from in-code subset usage + datasource join). */
+export type AccessKind = "source" | "write" | "zero-out" | "indeterminate";
+export interface DataSourceEntry {
+    name: string;
+    type: string;
+    sourceName?: string | undefined;
+    view?: string | undefined;
+    subset?: string | undefined;
+}
+export type Direction = "upstream" | "downstream" | "both";
+export interface UpstreamWriter {
+    process: string;
+    /** Cubes this writer reads from (code reads + a TM1CubeView datasource cube). */
+    sourceCubes: string[];
+    /** This writer's datasource type (where it pulls rows from). */
+    datasourceType: string;
+    /** For non-cube datasources (ASCII/ODBC/TM1Process/subset): a short source label. */
+    externalSource?: string;
+    /** In-code subset-membership elements this process manipulates (SubsetElementInsert/Add/Delete). */
+    elements?: string[];
+}
+export interface DownstreamReader {
+    process: string;
+    /** Cubes this reader writes into. */
+    targetCubes: string[];
+    /** How the reader accesses the cube: code CellGet, a view datasource, or both. */
+    readsVia: "code" | "datasource" | "both";
+    /** In-code subset-membership elements this process manipulates (SubsetElementInsert/Add/Delete). */
+    elements?: string[];
+}
+export interface DataFlowResult {
+    cube: string;
+    direction: Direction;
+    upstream?: UpstreamWriter[];
+    downstream?: DownstreamReader[];
+    /** Present only when an element filter was supplied — processes that touch element (dimension, name). */
+    element?: {
+        dimension: string;
+        name: string;
+        processes: Array<{
+            process: string;
+            funcNames: string[];
+            access: AccessKind[];
+            via?: MembershipVia[];
+        }>;
+        /** Processes where this dimension has an UNRESOLVED element arg (element identity not statically known). */
+        unresolvedInProcesses?: string[];
+        /** Count of touching processes hidden because their only access classification was 'indeterminate' (opts.elementAccess default excludes it). */
+        suppressedIndeterminate?: number;
+        /** Processes whose datasource scopes elements via a computed selector (element identity not literally verifiable). */
+        computedInProcesses?: string[];
+        /** Honesty marker: what element resolution this result covers. */
+        resolution: string;
+    };
+    counts: {
+        upstream?: number;
+        downstream?: number;
+    };
+}
+/**
+ * Trace data flow into/out of a cube. Case-insensitive cube matching; output
+ * preserves original casing. Lists are sorted by process name.
+ */
+export declare function traceDataFlow(index: ReferenceIndex, dsList: DataSourceEntry[], cubeName: string, direction: Direction, opts?: {
+    element?: {
+        dimension: string;
+        name: string;
+    };
+    elementAccess?: AccessKind[];
+    datasourceMembership?: DatasourceMembership;
+}): DataFlowResult;
+//# sourceMappingURL=dataFlow.d.ts.map