@gabrielbryk/arc-devtools-mcp 1.3.0

package/build/src/formatters/ConsoleFormatter.js

@@ -0,0 +1,288 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { createStackTraceForConsoleMessage, SymbolizedError, } from '../devtools/DevtoolsUtils.js';
+import { UncaughtError } from '../PageCollector.js';
+import * as DevTools from '../third_party/index.js';
+export class ConsoleFormatter {
+    #id;
+    #type;
+    #text;
+    #argCount;
+    #resolvedArgs;
+    #stack;
+    #cause;
+    isIgnored;
+    constructor(params) {
+        this.#id = params.id;
+        this.#type = params.type;
+        this.#text = params.text;
+        this.#argCount = params.argCount ?? 0;
+        this.#resolvedArgs = params.resolvedArgs ?? [];
+        this.#stack = params.stack;
+        this.#cause = params.cause;
+        this.isIgnored = params.isIgnored;
+    }
+    static async from(msg, options) {
+        const ignoreListManager = options?.devTools?.universe.context.get(DevTools.DevTools.IgnoreListManager);
+        const isIgnored = options.isIgnoredForTesting ||
+            (frame => {
+                if (!ignoreListManager) {
+                    return false;
+                }
+                if (frame.uiSourceCode) {
+                    return ignoreListManager.isUserOrSourceMapIgnoreListedUISourceCode(frame.uiSourceCode);
+                }
+                if (frame.url) {
+                    return ignoreListManager.isUserIgnoreListedURL(frame.url);
+                }
+                return false;
+            });
+        if (msg instanceof UncaughtError) {
+            const error = await SymbolizedError.fromDetails({
+                devTools: options?.devTools,
+                details: msg.details,
+                targetId: msg.targetId,
+                includeStackAndCause: options?.fetchDetailedData,
+                resolvedStackTraceForTesting: options?.resolvedStackTraceForTesting,
+                resolvedCauseForTesting: options?.resolvedCauseForTesting,
+            });
+            return new ConsoleFormatter({
+                id: options.id,
+                type: 'error',
+                text: error.message,
+                stack: error.stackTrace,
+                cause: error.cause,
+                isIgnored,
+            });
+        }
+        let resolvedArgs = [];
+        if (options.resolvedArgsForTesting) {
+            resolvedArgs = options.resolvedArgsForTesting;
+        }
+        else if (options.fetchDetailedData) {
+            resolvedArgs = await Promise.all(msg.args().map(async (arg, i) => {
+                try {
+                    const remoteObject = arg.remoteObject();
+                    if (remoteObject.type === 'object' &&
+                        remoteObject.subtype === 'error') {
+                        return await SymbolizedError.fromError({
+                            devTools: options.devTools,
+                            error: remoteObject,
+                            // @ts-expect-error Internal ConsoleMessage API
+                            targetId: msg._targetId(),
+                        });
+                    }
+                    return await arg.jsonValue();
+                }
+                catch {
+                    return `<error: Argument ${i} is no longer available>`;
+                }
+            }));
+        }
+        let stack;
+        if (options.resolvedStackTraceForTesting) {
+            stack = options.resolvedStackTraceForTesting;
+        }
+        else if (options.fetchDetailedData && options.devTools) {
+            try {
+                stack = await createStackTraceForConsoleMessage(options.devTools, msg);
+            }
+            catch {
+                // ignore
+            }
+        }
+        return new ConsoleFormatter({
+            id: options.id,
+            type: msg.type(),
+            text: msg.text(),
+            argCount: resolvedArgs.length || msg.args().length,
+            resolvedArgs,
+            stack,
+            isIgnored,
+        });
+    }
+    // The short format for a console message.
+    toString() {
+        return convertConsoleMessageConciseToString(this.toJSON());
+    }
+    // The verbose format for a console message, including all details.
+    toStringDetailed() {
+        return convertConsoleMessageConciseDetailedToString(this.toJSONDetailed());
+    }
+    #getArgs() {
+        if (this.#resolvedArgs.length > 0) {
+            const args = [...this.#resolvedArgs];
+            // If there is no text, the first argument serves as text (see formatMessage).
+            if (!this.#text) {
+                args.shift();
+            }
+            return args;
+        }
+        return [];
+    }
+    toJSON() {
+        return {
+            type: this.#type,
+            text: this.#text,
+            argsCount: this.#argCount,
+            id: this.#id,
+        };
+    }
+    /**
+     * Groups consecutive messages with the same type, text, and argument count.
+     * Similar to Chrome DevTools' console grouping behavior.
+     */
+    static groupConsecutive(messages) {
+        const grouped = [];
+        for (const msg of messages) {
+            const prev = grouped[grouped.length - 1];
+            if (prev &&
+                prev.message instanceof ConsoleFormatter &&
+                msg instanceof ConsoleFormatter &&
+                prev.message.#type === msg.#type &&
+                prev.message.#text === msg.#text &&
+                prev.message.#argCount === msg.#argCount) {
+                prev.count++;
+            }
+            else {
+                grouped.push({ message: msg, count: 1 });
+            }
+        }
+        return grouped.map(({ message, count }) => count > 1 && message instanceof ConsoleFormatter
+            ? new GroupedConsoleFormatter({
+                id: message.#id,
+                type: message.#type,
+                text: message.#text,
+                argCount: message.#argCount,
+                isIgnored: message.isIgnored,
+            }, count)
+            : message);
+    }
+    toJSONDetailed() {
+        return {
+            id: this.#id,
+            type: this.#type,
+            text: this.#text,
+            argsCount: this.#argCount,
+            args: this.#getArgs().map(arg => formatArg(arg, this)),
+            stackTrace: this.#stack
+                ? formatStackTrace(this.#stack, this.#cause, this)
+                : undefined,
+        };
+    }
+}
+export class GroupedConsoleFormatter extends ConsoleFormatter {
+    #count;
+    constructor(params, count) {
+        super(params);
+        this.#count = count;
+    }
+    toString() {
+        return convertConsoleMessageConciseToString(this.toJSON());
+    }
+    toJSON() {
+        const json = super.toJSON();
+        json.count = this.#count;
+        return json;
+    }
+}
+function convertConsoleMessageConciseToString(msg) {
+    const countSuffix = msg.count && msg.count > 1 ? ` [${msg.count} times]` : '';
+    return `msgid=${msg.id} [${msg.type}] ${msg.text} (${msg.argsCount} args)${countSuffix}`;
+}
+function convertConsoleMessageConciseDetailedToString(msg) {
+    const result = [
+        `ID: ${msg.id}`,
+        `Message: ${msg.type}> ${msg.text}`,
+        formatArgs(msg),
+        ...(msg.stackTrace ? ['### Stack trace', msg.stackTrace] : []),
+    ].filter(line => !!line);
+    return result.join('\n');
+}
+function formatArgs(msg) {
+    const args = msg.args;
+    if (!args.length) {
+        return '';
+    }
+    const result = ['### Arguments'];
+    for (const [key, arg] of args.entries()) {
+        result.push(`Arg #${key}: ${arg}`);
+    }
+    return result.join('\n');
+}
+function formatArg(arg, formatter) {
+    if (arg instanceof SymbolizedError) {
+        return [
+            arg.message,
+            arg.stackTrace
+                ? formatStackTrace(arg.stackTrace, arg.cause, formatter)
+                : undefined,
+        ]
+            .filter(line => !!line)
+            .join('\n');
+    }
+    return typeof arg === 'object' ? JSON.stringify(arg) : String(arg);
+}
+const STACK_TRACE_MAX_LINES = 50;
+function formatStackTrace(stackTrace, cause, formatter) {
+    const lines = formatStackTraceInner(stackTrace, cause, formatter);
+    const includedLines = lines.slice(0, STACK_TRACE_MAX_LINES);
+    const reminderCount = lines.length - includedLines.length;
+    return [
+        ...includedLines,
+        reminderCount > 0 ? `... and ${reminderCount} more frames` : '',
+        'Note: line and column numbers use 1-based indexing',
+    ]
+        .filter(line => !!line)
+        .join('\n');
+}
+function formatStackTraceInner(stackTrace, cause, formatter) {
+    if (!stackTrace) {
+        return [];
+    }
+    return [
+        ...formatFragment(stackTrace.syncFragment, formatter),
+        ...stackTrace.asyncFragments
+            .map(item => formatAsyncFragment(item, formatter))
+            .flat(),
+        ...formatCause(cause, formatter),
+    ];
+}
+function formatFragment(fragment, formatter) {
+    const frames = fragment.frames.filter(frame => !formatter.isIgnored(frame));
+    return frames.map(formatFrame);
+}
+function formatAsyncFragment(fragment, formatter) {
+    const formattedFrames = formatFragment(fragment, formatter);
+    if (formattedFrames.length === 0) {
+        return [];
+    }
+    const separatorLineLength = 40;
+    const prefix = `--- ${fragment.description || 'async'} `;
+    const separator = prefix + '-'.repeat(separatorLineLength - prefix.length);
+    return [separator, ...formattedFrames];
+}
+function formatFrame(frame) {
+    let result = `at ${frame.name ?? '<anonymous>'}`;
+    if (frame.uiSourceCode) {
+        const location = frame.uiSourceCode.uiLocation(frame.line, frame.column);
+        result += ` (${location.linkText(/* skipTrim */ false, /* showColumnNumber */ true)})`;
+    }
+    else if (frame.url) {
+        result += ` (${frame.url}:${frame.line}:${frame.column})`;
+    }
+    return result;
+}
+function formatCause(cause, formatter) {
+    if (!cause) {
+        return [];
+    }
+    return [
+        `Caused by: ${cause.message}`,
+        ...formatStackTraceInner(cause.stackTrace, cause.cause, formatter),
+    ];
+}
+//# sourceMappingURL=ConsoleFormatter.js.map

package/build/src/formatters/HeapSnapshotFormatter.js

@@ -0,0 +1,97 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { DevTools } from '../third_party/index.js';
+import { stableIdSymbol } from '../utils/id.js';
+export function isNodeLike(item) {
+    return (typeof item === 'object' && item !== null && 'id' in item && 'name' in item);
+}
+export function isEdgeLike(item) {
+    return (typeof item === 'object' &&
+        item !== null &&
+        'name' in item &&
+        'node' in item &&
+        'type' in item &&
+        typeof item.node === 'object' &&
+        item.node !== null &&
+        'id' in item.node &&
+        'name' in item.node);
+}
+export class HeapSnapshotFormatter {
+    #aggregates;
+    constructor(aggregates) {
+        this.#aggregates = aggregates;
+    }
+    static formatNodes(items) {
+        const lines = [];
+        if (items.length > 0) {
+            const firstItem = items[0];
+            if (isNodeLike(firstItem)) {
+                lines.push('nodeId,nodeName,type,distance,selfSize,retainedSize');
+            }
+            else if (isEdgeLike(firstItem)) {
+                lines.push('name,type,nodeId,nodeName');
+            }
+        }
+        for (const item of items) {
+            if (isNodeLike(item)) {
+                lines.push(`${item.id},${item.name},${item.type},${item.distance},${DevTools.I18n.ByteUtilities.formatBytesToKb(item.selfSize)},${DevTools.I18n.ByteUtilities.formatBytesToKb(item.retainedSize)}`);
+            }
+            else if (isEdgeLike(item)) {
+                lines.push(`${item.name},${item.type},${item.node.id},${item.node.name}`);
+            }
+        }
+        return lines.join('\n');
+    }
+    static formatRetainingPaths(retainingPaths) {
+        const lines = [];
+        function formatEdge(edge, depth) {
+            const indent = '  '.repeat(depth);
+            lines.push(`${indent}<- @${edge.nodeId} ${edge.nodeName} via ${edge.edgeType} ${edge.edgeName} (distance: ${edge.distance})`);
+            for (const child of edge.children) {
+                formatEdge(child, depth + 1);
+            }
+        }
+        for (const path of retainingPaths) {
+            formatEdge(path, 0);
+        }
+        return lines.join('\n');
+    }
+    static formatDominators(dominators) {
+        const lines = [];
+        lines.push('nodeId,nodeName,selfSize,retainedSize');
+        for (const node of dominators) {
+            lines.push(`${node.nodeId},${node.nodeName},${DevTools.I18n.ByteUtilities.formatBytesToKb(node.selfSize)},${DevTools.I18n.ByteUtilities.formatBytesToKb(node.retainedSize)}`);
+        }
+        return lines.join('\n');
+    }
+    #getSortedAggregates() {
+        return Object.values(this.#aggregates).sort((a, b) => b.maxRet - a.maxRet);
+    }
+    toString() {
+        const sorted = this.#getSortedAggregates();
+        const lines = [];
+        lines.push('id,name,count,selfSize,maxRetainedSize');
+        for (const info of sorted) {
+            const id = info[stableIdSymbol] ?? '';
+            lines.push(`${id},${info.name},${info.count},${DevTools.I18n.ByteUtilities.formatBytesToKb(info.self)},${DevTools.I18n.ByteUtilities.formatBytesToKb(info.maxRet)}`);
+        }
+        return lines.join('\n');
+    }
+    toJSON() {
+        const sorted = this.#getSortedAggregates();
+        return sorted.map(info => ({
+            id: info[stableIdSymbol],
+            className: info.name,
+            count: info.count,
+            selfSize: DevTools.I18n.ByteUtilities.formatBytesToKb(info.self),
+            retainedSize: DevTools.I18n.ByteUtilities.formatBytesToKb(info.maxRet),
+        }));
+    }
+    static sort(aggregates) {
+        return Object.entries(aggregates).sort((a, b) => b[1].maxRet - a[1].maxRet);
+    }
+}
+//# sourceMappingURL=HeapSnapshotFormatter.js.map

package/build/src/formatters/IssueFormatter.js

@@ -0,0 +1,193 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { ISSUE_UTILS } from '../issue-descriptions.js';
+import { logger } from '../logger.js';
+import { DevTools } from '../third_party/index.js';
+export class IssueFormatter {
+    #issue;
+    #options;
+    constructor(issue, options) {
+        this.#issue = issue;
+        this.#options = options;
+    }
+    toString() {
+        return convertIssueConciseToString(this.toJSON());
+    }
+    toStringDetailed() {
+        return convertIssueDetailedToString(this.toJSONDetailed());
+    }
+    toJSON() {
+        return {
+            type: 'issue',
+            title: this.#getTitle(),
+            count: this.#issue.getAggregatedIssuesCount(),
+            id: this.#options.id,
+        };
+    }
+    toJSONDetailed() {
+        return {
+            id: this.#options.id,
+            type: 'issue',
+            count: this.#issue.getAggregatedIssuesCount(),
+            title: this.#getTitle(),
+            description: this.#getDescription(),
+            links: this.#issue.getDescription()?.links,
+            affectedResources: this.#getAffectedResources(),
+        };
+    }
+    #getAffectedResources() {
+        const issues = this.#issue.getAllIssues();
+        const affectedResources = [];
+        for (const singleIssue of issues) {
+            const details = singleIssue.details();
+            if (!details) {
+                continue;
+            }
+            // We send the remaining details as untyped JSON because the DevTools
+            // frontend code is currently not re-usable.
+            const data = structuredClone(details);
+            let uid;
+            let request;
+            if ('violatingNodeId' in details &&
+                details.violatingNodeId &&
+                this.#options.elementIdResolver) {
+                uid = this.#options.elementIdResolver(details.violatingNodeId);
+                delete data.violatingNodeId;
+            }
+            if ('nodeId' in details &&
+                details.nodeId &&
+                this.#options.elementIdResolver) {
+                uid = this.#options.elementIdResolver(details.nodeId);
+                delete data.nodeId;
+            }
+            if ('documentNodeId' in details &&
+                details.documentNodeId &&
+                this.#options.elementIdResolver) {
+                uid = this.#options.elementIdResolver(details.documentNodeId);
+                delete data.documentNodeId;
+            }
+            if ('request' in details && details.request) {
+                request = details.request.url;
+                if (details.request.requestId && this.#options.requestIdResolver) {
+                    const resolvedId = this.#options.requestIdResolver(details.request.requestId);
+                    if (resolvedId) {
+                        request = resolvedId;
+                        const requestData = data.request;
+                        delete requestData.requestId;
+                    }
+                }
+            }
+            // These fields has no use for the MCP client (redundant or irrelevant).
+            delete data.errorType;
+            delete data.frameId;
+            affectedResources.push({
+                uid,
+                data: data,
+                request,
+            });
+        }
+        return affectedResources;
+    }
+    isValid() {
+        return this.#getTitle() !== undefined;
+    }
+    // Helper to extract title
+    #getTitle() {
+        const markdownDescription = this.#issue.getDescription();
+        const filename = markdownDescription?.file;
+        if (!filename) {
+            logger?.(`no description found for issue:` + this.#issue.code());
+            return undefined;
+        }
+        // We already have the description logic in #getDescription, but title extraction is separate
+        // We can reuse the logic or cache it.
+        // Ideally we should process markdown once.
+        const rawMarkdown = ISSUE_UTILS.getIssueDescription(filename);
+        if (!rawMarkdown) {
+            logger?.(`no markdown ${filename} found for issue:` + this.#issue.code());
+            return undefined;
+        }
+        try {
+            const processedMarkdown = DevTools.MarkdownIssueDescription.substitutePlaceholders(rawMarkdown, markdownDescription?.substitutions);
+            const markdownAst = DevTools.Marked.Marked.lexer(processedMarkdown);
+            const title = DevTools.MarkdownIssueDescription.findTitleFromMarkdownAst(markdownAst);
+            if (!title) {
+                logger?.('cannot read issue title from ' + filename);
+                return undefined;
+            }
+            return title;
+        }
+        catch {
+            logger?.('error parsing markdown for issue ' + this.#issue.code());
+            return undefined;
+        }
+    }
+    #getDescription() {
+        const markdownDescription = this.#issue.getDescription();
+        const filename = markdownDescription?.file;
+        if (!filename) {
+            return undefined;
+        }
+        const rawMarkdown = ISSUE_UTILS.getIssueDescription(filename);
+        if (!rawMarkdown) {
+            return undefined;
+        }
+        try {
+            return DevTools.MarkdownIssueDescription.substitutePlaceholders(rawMarkdown, markdownDescription?.substitutions);
+        }
+        catch {
+            return undefined;
+        }
+    }
+}
+function convertIssueConciseToString(issue) {
+    return `msgid=${issue.id} [issue] ${issue.title} (count: ${issue.count})`;
+}
+function convertIssueDetailedToString(issue) {
+    const result = [];
+    result.push(`ID: ${issue.id}`);
+    const bodyParts = [];
+    const description = issue.description;
+    let processedMarkdown = description?.trim();
+    // Remove heading in order not to conflict with the whole console message response markdown
+    if (processedMarkdown?.startsWith('# ')) {
+        processedMarkdown = processedMarkdown.substring(2).trimStart();
+    }
+    if (processedMarkdown) {
+        bodyParts.push(processedMarkdown);
+    }
+    else {
+        bodyParts.push(issue.title ?? 'Unknown Issue');
+    }
+    const links = issue.links;
+    if (links && links.length > 0) {
+        bodyParts.push('Learn more:');
+        for (const link of links) {
+            bodyParts.push(`[${link.linkTitle}](${link.link})`);
+        }
+    }
+    const affectedResources = issue.affectedResources;
+    if (affectedResources.length) {
+        bodyParts.push('### Affected resources');
+        bodyParts.push(...affectedResources.map(item => {
+            const details = [];
+            if (item.uid) {
+                details.push(`uid=${item.uid}`);
+            }
+            if (item.request) {
+                details.push((typeof item.request === 'number' ? `reqid=` : 'url=') +
+                    item.request);
+            }
+            if (item.data) {
+                details.push(`data=${JSON.stringify(item.data)}`);
+            }
+            return details.join(' ');
+        }));
+    }
+    result.push(`Message: issue> ${bodyParts.join('\n')}`);
+    return result.join('\n');
+}
+//# sourceMappingURL=IssueFormatter.js.map