roam-research-mcp 2.4.3 → 2.13.0

package/build/query/index.js

@@ -0,0 +1,149 @@
+/**
+ * Roam Query Block Parser and Executor
+ *
+ * Parses Roam query block syntax and executes as Datalog queries
+ *
+ * Usage:
+ *   import { QueryExecutor } from './query/index.js';
+ *
+ *   const executor = new QueryExecutor(graph);
+ *   const results = await executor.execute('{{[[query]]: {and: [[Project]] [[TODO]]}}}');
+ */
+export { QueryParser, QueryParseError } from './parser.js';
+export { DatalogGenerator, buildDatalogQuery } from './generator.js';
+import { q } from '@roam-research/roam-api-sdk';
+import { QueryParser } from './parser.js';
+import { DatalogGenerator, buildDatalogQuery } from './generator.js';
+import { resolveRefs } from '../tools/helpers/refs.js';
+export class QueryExecutor {
+    constructor(graph) {
+        this.graph = graph;
+        this.generator = new DatalogGenerator();
+    }
+    /**
+     * Parse and execute a Roam query block
+     *
+     * @param queryBlock - The query block text, e.g., "{{[[query]]: {and: [[tag1]] [[tag2]]}}}"
+     * @param options - Execution options (limit, offset, pageUid)
+     * @returns Query results
+     */
+    async execute(queryBlock, options = {}) {
+        try {
+            // Parse the query
+            const ast = QueryParser.parse(queryBlock);
+            // Generate Datalog clauses
+            const clauses = this.generator.generate(ast);
+            // Build the full query
+            const { query, args } = buildDatalogQuery(clauses, {
+                limit: options.limit,
+                offset: options.offset,
+                pageUid: options.pageUid,
+                orderBy: options.orderBy || '?block-uid asc'
+            });
+            // Execute query
+            const rawResults = await q(this.graph, query, args);
+            // Resolve block references in content
+            const resolvedResults = await Promise.all(rawResults.map(async ([uid, content, pageTitle]) => {
+                const resolvedContent = await resolveRefs(this.graph, content);
+                return {
+                    block_uid: uid,
+                    content: resolvedContent,
+                    page_title: pageTitle
+                };
+            }));
+            // Get total count if pagination is used
+            let totalCount = resolvedResults.length;
+            if (options.limit !== undefined && options.limit !== -1) {
+                const countQuery = this.buildCountQuery(clauses, options.pageUid);
+                const countResults = await q(this.graph, countQuery.query, countQuery.args);
+                totalCount = countResults[0]?.[0] ?? 0;
+            }
+            return {
+                success: true,
+                matches: resolvedResults,
+                message: `Found ${resolvedResults.length} block(s) matching query`,
+                total_count: totalCount,
+                query // Include for debugging
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                matches: [],
+                message: error instanceof Error ? error.message : String(error)
+            };
+        }
+    }
+    /**
+     * Parse a query block without executing (for validation/debugging)
+     */
+    parse(queryBlock) {
+        const ast = QueryParser.parse(queryBlock);
+        const clauses = this.generator.generate(ast);
+        const datalog = buildDatalogQuery(clauses);
+        return { ast, datalog };
+    }
+    buildCountQuery(clauses, pageUid) {
+        let inClause = ':in $';
+        if (clauses.inputs.length > 0) {
+            inClause += ' ' + clauses.inputs.join(' ');
+        }
+        if (pageUid) {
+            inClause += ' ?target-page-uid';
+        }
+        const baseClauses = [
+            '[?b :block/string ?block-str]',
+            '[?b :block/uid ?block-uid]',
+            '[?b :block/page ?p]'
+        ];
+        if (pageUid) {
+            baseClauses.push('[?p :block/uid ?target-page-uid]');
+        }
+        const allWhereClauses = [...baseClauses, ...clauses.where];
+        const query = `[:find (count ?b)
+                    ${inClause}
+                    :where
+                    ${allWhereClauses.join('\n                    ')}]`;
+        const args = [...clauses.inputValues];
+        if (pageUid) {
+            args.push(pageUid);
+        }
+        return { query, args };
+    }
+}
+/**
+ * Detect if a block string contains a query block
+ */
+export function isQueryBlock(text) {
+    return /^\s*\{\{\[\[query\]\]:/i.test(text);
+}
+/**
+ * Extract all query blocks from a string (handles nested braces)
+ */
+export function extractQueryBlocks(text) {
+    const matches = [];
+    const prefix = '{{[[query]]:';
+    let startIdx = 0;
+    while (startIdx < text.length) {
+        const foundIdx = text.indexOf(prefix, startIdx);
+        if (foundIdx === -1)
+            break;
+        // Find matching closing }}
+        let depth = 2; // We've seen {{
+        let pos = foundIdx + prefix.length;
+        while (pos < text.length && depth > 0) {
+            if (text[pos] === '{') {
+                depth++;
+            }
+            else if (text[pos] === '}') {
+                depth--;
+            }
+            pos++;
+        }
+        if (depth === 0) {
+            matches.push(text.slice(foundIdx, pos));
+        }
+        startIdx = pos;
+    }
+    return matches;
+}

package/build/query/parser.js

@@ -0,0 +1,319 @@
+/**
+ * Parser for Roam Query Block syntax
+ *
+ * Parses queries like:
+ *   {{[[query]]: {and: [[tag1]] [[tag2]]}}}
+ *   {{[[query]]: {or: [[a]] {not: [[b]]}}}}
+ *   {{[[query]]: {and: {between: [[January 1st, 2026]] [[January 31st, 2026]]} [[Project]]}}}
+ */
+export class QueryParseError extends Error {
+    constructor(message, position) {
+        super(message);
+        this.position = position;
+        this.name = 'QueryParseError';
+    }
+}
+export class QueryParser {
+    constructor(input) {
+        this.input = input;
+        this.pos = 0;
+    }
+    /**
+     * Parse a Roam query block string into an AST
+     * Accepts either the full block syntax or just the query expression
+     */
+    static parse(input) {
+        const result = QueryParser.parseWithName(input);
+        return result.query;
+    }
+    /**
+     * Parse a Roam query block string into an AST with optional name
+     * Returns both the name (if present) and the query AST
+     */
+    static parseWithName(input) {
+        const parser = new QueryParser(input);
+        return parser.parseQueryWithName();
+    }
+    /**
+     * Extract query expression from a full query block
+     * {{[[query]]: expression}} -> expression
+     * {{[[query]]: "name" expression}} -> expression (name extracted separately)
+     */
+    extractQueryExpression() {
+        const trimmed = this.input.trim();
+        // Full query block format
+        const fullMatch = trimmed.match(/^\{\{\[\[query\]\]:\s*(.+)\}\}$/s);
+        if (fullMatch) {
+            return fullMatch[1].trim();
+        }
+        // Already just the expression
+        return trimmed;
+    }
+    parseQueryWithName() {
+        this.input = this.extractQueryExpression();
+        this.pos = 0;
+        this.skipWhitespace();
+        // Check for optional name prefix (quoted string)
+        let name;
+        if (this.peek() === '"') {
+            name = this.parseQuotedString();
+            this.skipWhitespace();
+        }
+        const query = this.parseExpression();
+        this.skipWhitespace();
+        if (this.pos < this.input.length) {
+            throw new QueryParseError(`Unexpected content after query: "${this.input.slice(this.pos)}"`, this.pos);
+        }
+        return { name, query };
+    }
+    parseQuery() {
+        return this.parseQueryWithName().query;
+    }
+    parseQuotedString() {
+        this.expect('"');
+        let value = '';
+        while (this.pos < this.input.length && this.peek() !== '"') {
+            if (this.peek() === '\\' && this.input[this.pos + 1] === '"') {
+                value += '"';
+                this.pos += 2;
+            }
+            else {
+                value += this.input[this.pos];
+                this.pos++;
+            }
+        }
+        if (this.peek() === '"') {
+            this.pos++; // Skip closing quote
+        }
+        else {
+            throw new QueryParseError('Unclosed quoted string', this.pos);
+        }
+        return value;
+    }
+    parseExpression() {
+        this.skipWhitespace();
+        if (this.peek() === '{') {
+            return this.parseOperator();
+        }
+        else if (this.input.slice(this.pos, this.pos + 2) === '[[') {
+            return this.parseTag();
+        }
+        else if (this.input.slice(this.pos, this.pos + 2) === '((') {
+            return this.parseBlockRef();
+        }
+        else {
+            throw new QueryParseError(`Expected '{', '[[', or '((' at position ${this.pos}, found: "${this.input.slice(this.pos, this.pos + 10)}..."`, this.pos);
+        }
+    }
+    parseOperator() {
+        this.expect('{');
+        this.skipWhitespace();
+        const operator = this.parseOperatorName();
+        this.skipWhitespace();
+        this.expect(':');
+        this.skipWhitespace();
+        let node;
+        switch (operator.toLowerCase()) {
+            case 'and':
+                node = this.parseAndOr('and');
+                break;
+            case 'or':
+                node = this.parseAndOr('or');
+                break;
+            case 'not':
+                node = this.parseNot();
+                break;
+            case 'between':
+                node = this.parseBetween();
+                break;
+            case 'search':
+                node = this.parseSearch();
+                break;
+            case 'daily notes':
+                node = this.parseDailyNotes();
+                break;
+            case 'by':
+                node = this.parseUserClause('by');
+                break;
+            case 'created by':
+                node = this.parseUserClause('created-by');
+                break;
+            case 'edited by':
+                node = this.parseUserClause('edited-by');
+                break;
+            default:
+                throw new QueryParseError(`Unknown operator: ${operator}`, this.pos);
+        }
+        this.skipWhitespace();
+        this.expect('}');
+        return node;
+    }
+    parseAndOr(type) {
+        const children = [];
+        this.skipWhitespace();
+        while (this.pos < this.input.length && this.peek() !== '}') {
+            children.push(this.parseExpression());
+            this.skipWhitespace();
+        }
+        if (children.length === 0) {
+            throw new QueryParseError(`${type} operator requires at least one child`, this.pos);
+        }
+        return { type, children };
+    }
+    parseNot() {
+        this.skipWhitespace();
+        const child = this.parseExpression();
+        return { type: 'not', child };
+    }
+    parseBetween() {
+        this.skipWhitespace();
+        // Parse first date
+        const startTag = this.parseTag();
+        this.skipWhitespace();
+        // Parse second date
+        const endTag = this.parseTag();
+        return {
+            type: 'between',
+            startDate: startTag.value,
+            endDate: endTag.value
+        };
+    }
+    parseTag() {
+        this.expect('[');
+        this.expect('[');
+        let value = '';
+        let depth = 1;
+        while (this.pos < this.input.length && depth > 0) {
+            if (this.input.slice(this.pos, this.pos + 2) === ']]') {
+                depth--;
+                if (depth === 0) {
+                    this.pos += 2;
+                    break;
+                }
+                value += ']]';
+                this.pos += 2;
+            }
+            else if (this.input.slice(this.pos, this.pos + 2) === '[[') {
+                depth++;
+                value += '[[';
+                this.pos += 2;
+            }
+            else {
+                value += this.input[this.pos];
+                this.pos++;
+            }
+        }
+        if (depth !== 0) {
+            throw new QueryParseError('Unclosed tag reference', this.pos);
+        }
+        return { type: 'tag', value: value.trim() };
+    }
+    parseBlockRef() {
+        this.expect('(');
+        this.expect('(');
+        let uid = '';
+        while (this.pos < this.input.length) {
+            if (this.input.slice(this.pos, this.pos + 2) === '))') {
+                this.pos += 2;
+                break;
+            }
+            uid += this.input[this.pos];
+            this.pos++;
+        }
+        if (!uid) {
+            throw new QueryParseError('Empty block reference', this.pos);
+        }
+        return { type: 'block-ref', uid: uid.trim() };
+    }
+    parseSearch() {
+        // Search text is typically in quotes or just plain text until }
+        this.skipWhitespace();
+        let text = '';
+        // Check if quoted
+        if (this.peek() === '"') {
+            this.pos++; // Skip opening quote
+            while (this.pos < this.input.length && this.peek() !== '"') {
+                if (this.peek() === '\\' && this.input[this.pos + 1] === '"') {
+                    text += '"';
+                    this.pos += 2;
+                }
+                else {
+                    text += this.input[this.pos];
+                    this.pos++;
+                }
+            }
+            if (this.peek() === '"') {
+                this.pos++; // Skip closing quote
+            }
+        }
+        else {
+            // Unquoted - read until }
+            while (this.pos < this.input.length && this.peek() !== '}') {
+                text += this.input[this.pos];
+                this.pos++;
+            }
+            text = text.trim();
+        }
+        return { type: 'search', text };
+    }
+    parseDailyNotes() {
+        // Daily notes clause has no arguments, just empty or whitespace until }
+        return { type: 'daily-notes' };
+    }
+    parseUserClause(type) {
+        this.skipWhitespace();
+        const user = this.parseUserIdentifier();
+        return { type, user };
+    }
+    parseUserIdentifier() {
+        // User can be in [[display name]] format or plain text
+        if (this.input.slice(this.pos, this.pos + 2) === '[[') {
+            const tag = this.parseTag();
+            return tag.value;
+        }
+        // Plain text until }
+        let user = '';
+        while (this.pos < this.input.length && this.peek() !== '}') {
+            user += this.input[this.pos];
+            this.pos++;
+        }
+        return user.trim();
+    }
+    /**
+     * Parse operator name, handling multi-word operators like "created by"
+     */
+    parseOperatorName() {
+        const knownMultiWord = ['created by', 'edited by', 'daily notes'];
+        const remaining = this.input.slice(this.pos).toLowerCase();
+        for (const op of knownMultiWord) {
+            if (remaining.startsWith(op)) {
+                this.pos += op.length;
+                return op;
+            }
+        }
+        // Single word operator
+        return this.parseIdentifier();
+    }
+    parseIdentifier() {
+        let id = '';
+        while (this.pos < this.input.length && /[a-zA-Z]/.test(this.input[this.pos])) {
+            id += this.input[this.pos];
+            this.pos++;
+        }
+        return id;
+    }
+    skipWhitespace() {
+        while (this.pos < this.input.length && /\s/.test(this.input[this.pos])) {
+            this.pos++;
+        }
+    }
+    peek() {
+        return this.input[this.pos];
+    }
+    expect(char) {
+        if (this.input[this.pos] !== char) {
+            throw new QueryParseError(`Expected '${char}' at position ${this.pos}, found '${this.input[this.pos] || 'EOF'}'`, this.pos);
+        }
+        this.pos++;
+    }
+}