@ffschrattenecker/tm1-mcp-server 6.0.0

package/dist/lib/naming/odata-filter.js

@@ -0,0 +1,81 @@
+// Server-side prefilter for the element naming audit.
+//
+// Auditing element names used to mean downloading them all: 15.2 MB for a
+// single 171k-element dimension, 66 MB across a real model, and — worse — a
+// cap (`maxElementsPerDim`) beyond which the audit silently checked only a
+// prefix of the dimension.
+//
+// Every element rule in ./rules.ts is character-based, and TM1 implements the
+// OData string functions those rules need (`startswith`, `endswith`,
+// `contains`, `indexof`, `trim`, `length` — all verified live against 11.8).
+// So the server can do the narrowing: ask it for the names that MIGHT violate
+// a rule, and check only those.
+//
+// The contract this file must honour is SOUNDNESS, not exactness:
+//
+//   checkName(name) is non-empty  ⟹  the filter matches name
+//
+// A filter that also matches innocent names costs a few extra rows and nothing
+// else, because `checkName` still decides. A filter that misses a violator
+// turns the audit into a lie. `matchesElementViolationFilter` mirrors the
+// emitted expression in TypeScript so the property can be tested directly;
+// tests/unit/naming-odata-filter.test.ts asserts it over every rule class,
+// and the live suite asserts that TM1 agrees.
+import { SERVER_RESERVED_CHARS } from "./rules.js";
+/** OData string literal: single quotes double. */
+function lit(value) {
+    return `'${value.replace(/'/g, "''")}'`;
+}
+/**
+ * `$filter` expression selecting elements that may violate a naming rule.
+ *
+ * Mirrors the element branch of `checkName`: empty/whitespace-only, leading or
+ * trailing whitespace, TM1-Server-reserved characters, the `}` control prefix,
+ * a leading `+`/`-`, and — on v12 only — an embedded TAB.
+ */
+export function elementViolationFilter() {
+    const clauses = [
+        // checkEmpty: name.trim() is empty. Covers "" and whitespace-only in one.
+        "length(trim(Name)) eq 0",
+        // checkLeadingTrailingWhitespace: name !== name.trim(). Expressed with
+        // trim() rather than a list of space characters, so every whitespace
+        // codepoint is covered instead of the handful someone remembered.
+        "trim(Name) ne Name",
+        // checkLeadingControlPrefix
+        `startswith(Name,${lit("}")})`,
+        // checkElementLeadingArithmetic
+        `startswith(Name,${lit("+")})`,
+        `startswith(Name,${lit("-")})`,
+        // checkServerReservedChars — elements are in scope for these too.
+        ...[...SERVER_RESERVED_CHARS].map((ch) => `contains(Name,${lit(ch)})`),
+    ];
+    // checkElementContainsTab applies on every version. The TAB goes in as a REAL
+    // tab character: every caller passes this string through
+    // encodeURIComponent(), which turns it into %09 on the wire. Writing "%09"
+    // here instead produced %2509 — the server then searched for the three
+    // characters "%09" and never matched, so the clause silently found nothing.
+    clauses.push("indexof(Name,'\t') ge 0");
+    return clauses.join(" or ");
+}
+/**
+ * The same predicate in TypeScript, for testing soundness against `checkName`
+ * without a server. Kept beside the builder so the two cannot drift: a rule
+ * added to one and forgotten in the other fails the unit test.
+ */
+export function matchesElementViolationFilter(name) {
+    if (name.trim().length === 0)
+        return true;
+    if (name !== name.trim())
+        return true;
+    if (name.startsWith("}"))
+        return true;
+    if (name.startsWith("+") || name.startsWith("-"))
+        return true;
+    for (const ch of SERVER_RESERVED_CHARS)
+        if (name.includes(ch))
+            return true;
+    if (name.includes("\t"))
+        return true;
+    return false;
+}
+//# sourceMappingURL=odata-filter.js.map

package/dist/lib/naming/rules.d.ts

@@ -0,0 +1,34 @@
+/**
+ * TM1 / Planning Analytics object naming rules.
+ *
+ * Sources:
+ *  - IBM PA 2.0: https://www.ibm.com/docs/en/planning-analytics/2.0.0?topic=development-tm1-object-naming-conventions
+ *  - IBM PA 3.1: https://www.ibm.com/docs/en/planning-analytics/3.1.0?topic=references-naming-conventions
+ *
+ * Pass/fail semantics: every rule in this file is a HARD violation. Soft
+ * "avoid" recommendations from the IBM docs are intentionally not modelled.
+ */
+export type ObjectKind = "cube" | "dimension" | "hierarchy" | "subset" | "view" | "process" | "chore" | "element" | "attribute" | "processVariable";
+export type TM1MajorVersion = 11 | 12;
+export interface Violation {
+    rule: string;
+    message: string;
+    /** Offending character (literal) when the rule is character-based. */
+    char?: string;
+    /** Zero-based position of the offending character. */
+    position?: number;
+}
+/**
+ * Characters explicitly reserved by the TM1 Server for Cube, Dimension,
+ * Subset, View, Process, and Chore names. Source: IBM PA naming docs,
+ * "Reserved characters per component" → "TM1 Server reserves these characters".
+ */
+export declare const SERVER_RESERVED_CHARS: ReadonlySet<string>;
+/**
+ * Validate a single TM1 object name. Returns all hard violations.
+ * Order: empty → length → whitespace → reserved-char → control-prefix → element-specific.
+ */
+export declare function checkName(name: string, kind: ObjectKind): Violation[];
+/** Parse "11.8.x" / "12.0.x" → 11 or 12. Falls back to 11. */
+export declare function parseMajorVersion(productVersion: string): TM1MajorVersion;
+//# sourceMappingURL=rules.d.ts.map

package/dist/lib/naming/rules.js

@@ -0,0 +1,215 @@
+/**
+ * TM1 / Planning Analytics object naming rules.
+ *
+ * Sources:
+ *  - IBM PA 2.0: https://www.ibm.com/docs/en/planning-analytics/2.0.0?topic=development-tm1-object-naming-conventions
+ *  - IBM PA 3.1: https://www.ibm.com/docs/en/planning-analytics/3.1.0?topic=references-naming-conventions
+ *
+ * Pass/fail semantics: every rule in this file is a HARD violation. Soft
+ * "avoid" recommendations from the IBM docs are intentionally not modelled.
+ */
+/**
+ * Characters explicitly reserved by the TM1 Server for Cube, Dimension,
+ * Subset, View, Process, and Chore names. Source: IBM PA naming docs,
+ * "Reserved characters per component" → "TM1 Server reserves these characters".
+ */
+export const SERVER_RESERVED_CHARS = new Set([
+    "\\",
+    "/",
+    ":",
+    "*",
+    "?",
+    '"',
+    "<",
+    ">",
+    "|",
+    "'",
+    ";",
+    ",",
+]);
+/**
+ * Allowed pattern for TI process variable identifiers (must start with letter).
+ * Backtick is included because TI tolerates it in data-source column references
+ * (e.g., `\`col_name\``-style identifiers exported from SQL/ODBC sources).
+ */
+const PROCESS_VAR_ALLOWED = /^[A-Za-z][A-Za-z0-9.$%_`]*$/;
+/** Conservative TM1 name length cap (cube/dim/process historically 256). */
+const MAX_NAME_LENGTH = 256;
+const SERVER_RESERVED_KINDS = new Set([
+    "cube",
+    "dimension",
+    "hierarchy",
+    "subset",
+    "view",
+    "process",
+    "chore",
+]);
+function checkServerReservedChars(name) {
+    for (let i = 0; i < name.length; i++) {
+        const ch = name[i];
+        if (SERVER_RESERVED_CHARS.has(ch)) {
+            return {
+                rule: "server_reserved_char",
+                message: `Contains TM1-Server-reserved character '${ch}' at position ${i}. Reserved set: \\ / : * ? " < > | ' ; ,`,
+                char: ch,
+                position: i,
+            };
+        }
+    }
+    return null;
+}
+function checkLeadingControlPrefix(name) {
+    if (name.startsWith("}")) {
+        return {
+            rule: "leading_control_prefix",
+            message: "Starts with '}' — reserved prefix for TM1 control objects. User objects with this prefix are hidden when Display Control Objects is off.",
+            char: "}",
+            position: 0,
+        };
+    }
+    return null;
+}
+function checkEmpty(name) {
+    if (name.length === 0 || name.trim().length === 0) {
+        return {
+            rule: "empty",
+            message: "Name is empty or whitespace-only.",
+        };
+    }
+    return null;
+}
+function checkLength(name) {
+    if (name.length > MAX_NAME_LENGTH) {
+        return {
+            rule: "length_exceeds",
+            message: `Name length ${name.length} exceeds the conservative TM1 cap of ${MAX_NAME_LENGTH} characters.`,
+        };
+    }
+    return null;
+}
+function checkLeadingTrailingWhitespace(name) {
+    if (name.length === 0)
+        return null;
+    if (name !== name.trim()) {
+        return {
+            rule: "leading_trailing_whitespace",
+            message: "Has leading or trailing whitespace.",
+        };
+    }
+    return null;
+}
+function checkElementLeadingArithmetic(name) {
+    const first = name[0];
+    if (first === "+" || first === "-") {
+        return {
+            rule: "element_leading_arithmetic",
+            message: `Element name starts with '${first}' — breaks MDX active-form sets and rule references.`,
+            char: first,
+            position: 0,
+        };
+    }
+    return null;
+}
+// TAB is a hygiene problem on every version, not a v12 one. Measured on 11.8
+// and 12.5 alike: the element is created, the name round-trips verbatim, no
+// alias attribute appears, and MDX addresses it exactly like a plain element.
+// So the rule no longer keys off the server version — it flags a character
+// that is invisible in every UI, ambiguous against surrounding whitespace, and
+// splits the name in TI and CSV round trips. Planning Analytics 3.1 is also
+// reported to reserve TAB as the name/alias separator; that is a documented
+// claim, not something either reachable server demonstrates.
+function checkElementContainsTab(name) {
+    const idx = name.indexOf("\t");
+    if (idx >= 0) {
+        return {
+            rule: "element_contains_tab",
+            message: "Element name contains TAB — invisible in UIs, ambiguous against other whitespace, and a field separator in TI and CSV round trips. Planning Analytics 3.1 additionally reserves it as the name/alias separator.",
+            char: "\t",
+            position: idx,
+        };
+    }
+    return null;
+}
+function checkProcessVariable(name) {
+    if (name.length === 0) {
+        return { rule: "empty", message: "Process variable name is empty." };
+    }
+    if (PROCESS_VAR_ALLOWED.test(name))
+        return null;
+    const first = name[0];
+    if (!/[A-Za-z]/.test(first)) {
+        return {
+            rule: "process_var_leading_non_letter",
+            message: `Process variable '${name}' must start with a letter (got '${first}').`,
+            char: first,
+            position: 0,
+        };
+    }
+    for (let i = 0; i < name.length; i++) {
+        const ch = name[i];
+        if (!/[A-Za-z0-9.$%_`]/.test(ch)) {
+            return {
+                rule: "process_var_invalid_char",
+                message: `Process variable contains disallowed character '${ch}' at position ${i}. Allowed: letters, digits, . $ % _ \``,
+                char: ch,
+                position: i,
+            };
+        }
+    }
+    return null;
+}
+/**
+ * Validate a single TM1 object name. Returns all hard violations.
+ * Order: empty → length → whitespace → reserved-char → control-prefix → element-specific.
+ */
+export function checkName(name, kind) {
+    if (kind === "processVariable") {
+        const v = checkProcessVariable(name);
+        return v ? [v] : [];
+    }
+    const violations = [];
+    const empty = checkEmpty(name);
+    if (empty) {
+        violations.push(empty);
+        return violations;
+    }
+    // Elements/attributes have no IBM-defined hard length limit; the 256-char
+    // cap is only documented for cube/dim/view/subset/process/chore names.
+    // TM1 v11 servers accept element names well beyond 256 chars via REST.
+    if (kind !== "element" && kind !== "attribute") {
+        const length = checkLength(name);
+        if (length)
+            violations.push(length);
+    }
+    const whitespace = checkLeadingTrailingWhitespace(name);
+    if (whitespace)
+        violations.push(whitespace);
+    if (SERVER_RESERVED_KINDS.has(kind) ||
+        kind === "element" ||
+        kind === "attribute") {
+        const reserved = checkServerReservedChars(name);
+        if (reserved)
+            violations.push(reserved);
+    }
+    const controlPrefix = checkLeadingControlPrefix(name);
+    if (controlPrefix)
+        violations.push(controlPrefix);
+    if (kind === "element" || kind === "attribute") {
+        const arithmetic = checkElementLeadingArithmetic(name);
+        if (arithmetic)
+            violations.push(arithmetic);
+        const tab = checkElementContainsTab(name);
+        if (tab)
+            violations.push(tab);
+    }
+    return violations;
+}
+/** Parse "11.8.x" / "12.0.x" → 11 or 12. Falls back to 11. */
+export function parseMajorVersion(productVersion) {
+    const match = productVersion.match(/^(\d+)/);
+    if (!match)
+        return 11;
+    const major = Number(match[1]);
+    return major >= 12 ? 12 : 11;
+}
+//# sourceMappingURL=rules.js.map

package/dist/lib/pro-parser.d.ts

@@ -0,0 +1,19 @@
+import type { DataSource, ProcessParameter, ProcessVariable } from "../types.js";
+export interface ParsedPro {
+    name: string | null;
+    prolog: string;
+    metadata: string;
+    data: string;
+    epilog: string;
+    parameters: ProcessParameter[];
+    variables: ProcessVariable[];
+    /**
+     * Raw line block 582: one entry per datasource COLUMN, ignored ones included.
+     * Empty when the file carries none. See src/lib/variables-ui-data.ts — the
+     * ignore flag exists nowhere else, so dropping this block loses it.
+     */
+    variablesUIData: string[];
+    dataSource: DataSource;
+}
+export declare function parseProFile(content: string): ParsedPro;
+//# sourceMappingURL=pro-parser.d.ts.map

package/dist/lib/pro-parser.js

@@ -0,0 +1,260 @@
+const SECTION_RE = /^(572|573|574|575),(\d*)$/;
+// Header codes whose value is a counted block ("560,3" + 3 lines), not a scalar.
+// 566 is the ODBC query — TM1 writes "566,0" for every non-ODBC datasource.
+const BLOCK_CODES = new Set([
+    "560",
+    "561",
+    "566",
+    "577",
+    "578",
+    "579",
+    "580",
+    "581",
+    "582",
+    "590",
+    "637",
+]);
+function stripQuotes(s) {
+    if (s.length >= 2 && s.startsWith('"') && s.endsWith('"')) {
+        return s.slice(1, -1).replace(/""/g, '"');
+    }
+    return s;
+}
+function lineValue(line) {
+    const idx = line.indexOf(",");
+    return idx === -1 ? "" : line.slice(idx + 1);
+}
+function parseProcessName(lines) {
+    for (const line of lines) {
+        const m = line.match(/^602,"(.+)"$/);
+        if (m)
+            return m[1] ?? null;
+        if (/^572,/.test(line))
+            break;
+    }
+    return null;
+}
+// Read everything before the first code section into scalars ("585,\"DSN\"") and
+// counted blocks ("566,3" + 3 lines). Consuming blocks by their count matters:
+// an ODBC query line such as `FROM dbo."570,Sales"` must not be read as a header.
+function parseHeaderFields(lines) {
+    const scalars = new Map();
+    const rawScalars = new Map();
+    const blocks = new Map();
+    const sectionIdx = lines.findIndex((l) => SECTION_RE.test(l));
+    const pre = sectionIdx === -1 ? lines : lines.slice(0, sectionIdx);
+    let i = 0;
+    while (i < pre.length) {
+        const line = pre[i];
+        const block = line.match(/^(\d{3}),(\d+)$/);
+        if (block && BLOCK_CODES.has(block[1])) {
+            const count = parseInt(block[2], 10);
+            blocks.set(block[1], pre.slice(i + 1, i + 1 + count));
+            i += 1 + count;
+            continue;
+        }
+        const m = line.match(/^(\d{3}),/);
+        // First occurrence wins, mirroring the old first-match lookup.
+        if (m && !scalars.has(m[1])) {
+            scalars.set(m[1], stripQuotes(lineValue(line)));
+            rawScalars.set(m[1], lineValue(line));
+        }
+        i++;
+    }
+    return { scalars, rawScalars, blocks };
+}
+function parseSections(lines) {
+    const map = {
+        "572": [],
+        "573": [],
+        "574": [],
+        "575": [],
+    };
+    let i = 0;
+    while (i < lines.length) {
+        const m = lines[i].match(SECTION_RE);
+        if (!m) {
+            i++;
+            continue;
+        }
+        const code = m[1];
+        const rawCount = m[2];
+        i++;
+        if (rawCount !== "") {
+            // TM1 writes an explicit line count ("572,138"). Trust it, so code lines
+            // that look like a header (e.g. a literal "930,0") stay in the section.
+            const count = parseInt(rawCount, 10);
+            for (let taken = 0; taken < count && i < lines.length; taken++, i++) {
+                map[code].push(lines[i]);
+            }
+            continue;
+        }
+        // Countless header (older files written by this serializer): read until the
+        // next numeric header line.
+        while (i < lines.length && !/^\d{3},/.test(lines[i])) {
+            map[code].push(lines[i]);
+            i++;
+        }
+    }
+    return {
+        prolog: map["572"].join("\n").trimEnd(),
+        metadata: map["573"].join("\n").trimEnd(),
+        data: map["574"].join("\n").trimEnd(),
+        epilog: map["575"].join("\n").trimEnd(),
+    };
+}
+function parseParameters(blocks) {
+    const names = (blocks.get("560") ?? []).map((l) => l.trim());
+    const types = (blocks.get("561") ?? []).map((l) => parseInt(l.trim(), 10) || 1);
+    const defaults = {};
+    const prompts = {};
+    for (const [code, target] of [
+        ["590", defaults],
+        ["637", prompts],
+    ]) {
+        for (const line of blocks.get(code) ?? []) {
+            const ci = line.indexOf(",");
+            if (ci === -1)
+                continue;
+            target[line.slice(0, ci)] = stripQuotes(line.slice(ci + 1));
+        }
+    }
+    return names.map((name, idx) => {
+        const proType = types[idx] ?? 1;
+        const restType = proType === 2 ? "String" : "Numeric";
+        const rawValue = defaults[name] ?? "";
+        const defaultValue = restType === "Numeric" ? Number(rawValue || "0") || 0 : rawValue;
+        return {
+            name,
+            type: restType,
+            defaultValue,
+            prompt: prompts[name] ?? "",
+        };
+    });
+}
+function parseVariables(blocks) {
+    const names = (blocks.get("577") ?? []).map((l) => l.trim());
+    const types = (blocks.get("578") ?? []).map((l) => parseInt(l.trim(), 10) || 2);
+    const positions = (blocks.get("579") ?? []).map((l) => parseInt(l.trim(), 10) || 1);
+    const startBytes = (blocks.get("580") ?? []).map((l) => parseInt(l.trim(), 10) || 0);
+    const endBytes = (blocks.get("581") ?? []).map((l) => parseInt(l.trim(), 10) || 0);
+    return names.map((name, idx) => {
+        const proType = types[idx] ?? 2;
+        const restType = proType === 1 ? "Numeric" : "String";
+        const variable = {
+            name,
+            type: restType,
+            position: positions[idx] ?? idx + 1,
+        };
+        // Byte offsets only mean something for fixed-width sources; TM1 writes 0
+        // for every other kind, and carrying those zeros around adds nothing.
+        if (startBytes[idx])
+            variable.startByte = startBytes[idx];
+        if (endBytes[idx])
+            variable.endByte = endBytes[idx];
+        return variable;
+    });
+}
+function parseDataSource(fields) {
+    const { scalars, rawScalars, blocks } = fields;
+    const get = (code) => scalars.get(code) ?? "";
+    const proType = (get("562") || "NULL").toUpperCase();
+    const TYPE_MAP = {
+        NULL: "None",
+        VIEW: "TM1CubeView",
+        SUBSET: "TM1DimensionSubset",
+        CHARACTERDELIMITED: "ASCII",
+        // A fixed-width ASCII source carries its own type name.
+        POSITIONDELIMITED: "ASCII",
+        ODBC: "ODBC",
+    };
+    const restType = TYPE_MAP[proType] ?? "None";
+    if (restType === "None")
+        return { type: "None" };
+    // 586 = DataSourceNameForServer, 585 = DataSourceNameForClient (verified
+    // against .pro files TM1 wrote itself; 585 is empty when no client name is
+    // set). Files written by this serializer before that was known carry only
+    // 585 — recognisable by the missing 586 — and put the server name there.
+    const tm1Layout = scalars.has("586");
+    const server = tm1Layout ? get("586") : get("585");
+    const client = tm1Layout ? get("585") : get("585");
+    // TM1 writes view and subset names unquoted, so a name may legitimately start
+    // and end with a quote; only our own older files need unquoting here.
+    const rawName = (code) => {
+        const value = tm1Layout ? rawScalars.get(code) : scalars.get(code);
+        return value ?? "";
+    };
+    if (restType === "TM1CubeView") {
+        return {
+            type: restType,
+            dataSourceNameForServer: server,
+            dataSourceNameForClient: client,
+            view: rawName("570"),
+        };
+    }
+    if (restType === "TM1DimensionSubset") {
+        return {
+            type: restType,
+            dataSourceNameForServer: server,
+            dataSourceNameForClient: client,
+            // 571 holds the subset; 570 is the fallback for our own older files.
+            subset: rawName("571") || rawName("570"),
+        };
+    }
+    const ds = {
+        type: restType,
+        dataSourceNameForServer: server,
+        dataSourceNameForClient: client,
+    };
+    if (restType === "ASCII") {
+        ds.asciiDelimiterType =
+            proType === "POSITIONDELIMITED" ? "FixedWidth" : "Character";
+        ds.asciiDelimiterChar = scalars.get("567") ?? ",";
+        ds.asciiQuoteCharacter = scalars.get("568") ?? '"';
+        ds.asciiDecimalSeparator = scalars.get("588") ?? ".";
+        ds.asciiThousandSeparator = scalars.get("589") ?? ",";
+        const headerVal = scalars.get("569");
+        if (headerVal !== undefined)
+            ds.asciiHeaderRecords = parseInt(headerVal, 10) || 0;
+    }
+    if (restType === "ODBC") {
+        const user = get("564");
+        if (user)
+            ds.userName = user;
+        const query = (blocks.get("566") ?? []).join("\n");
+        if (query.length > 0)
+            ds.query = query;
+        // 565 is the password slot. Files TM1 wrote hold its own encoding of the
+        // credential, which is not what the REST API accepts, so only values this
+        // serializer wrote (an exported REST password) are worth carrying — those
+        // are recognisable by the file being in our layout rather than TM1's, i.e.
+        // no 601 version header.
+        const password = get("565");
+        if (password && !scalars.has("601"))
+            ds.password = password;
+        // 559 — ODBC unicode interface. TM1 writes it for every process, so an
+        // absent line means an older/hand-written file, not "unicode off".
+        const unicode = get("559");
+        if (unicode === "1" || unicode === "0")
+            ds.usesUnicode = unicode === "1";
+    }
+    return ds;
+}
+export function parseProFile(content) {
+    const lines = content
+        // TM1 writes .pro files with a UTF-8 BOM.
+        .replace(/^\uFEFF/, "")
+        .split("\n")
+        .map((l) => l.replace(/\r$/, ""));
+    const fields = parseHeaderFields(lines);
+    const sections = parseSections(lines);
+    return {
+        name: parseProcessName(lines),
+        ...sections,
+        parameters: parseParameters(fields.blocks),
+        variables: parseVariables(fields.blocks),
+        variablesUIData: fields.blocks.get("582") ?? [],
+        dataSource: parseDataSource(fields),
+    };
+}
+//# sourceMappingURL=pro-parser.js.map

package/dist/lib/pro-serializer.d.ts

@@ -0,0 +1,19 @@
+import type { DataSource, ProcessParameter, ProcessVariable } from "../types.js";
+export interface ProcessSerializeInput {
+    name: string;
+    prolog?: string;
+    metadata?: string;
+    data?: string;
+    epilog?: string;
+    parameters?: ProcessParameter[];
+    variables?: ProcessVariable[];
+    /**
+     * Raw `VariablesUIData` / line block 582 — one entry per datasource column,
+     * ignored ones included. Omit it and the ignored columns are gone: they have
+     * no representation in the variables list.
+     */
+    variablesUIData?: string[];
+    dataSource?: DataSource;
+}
+export declare function serializeToPro(input: ProcessSerializeInput): string;
+//# sourceMappingURL=pro-serializer.d.ts.map