design-constraint-validator 2.0.1 → 2.2.0

package/mcp/tools.js

@@ -0,0 +1,299 @@
+import fs from 'node:fs';
+import { suggestIds } from '../core/cli-format.js';
+import { flattenTokens } from '../core/flatten.js';
+import { explain as explainWhy } from '../core/why.js';
+import { Engine } from '../core/engine.js';
+import { ConstraintsSchema } from '../cli/config-schema.js';
+import { loadConfig } from '../cli/config.js';
+import { discoverConstraints } from '../cli/constraint-registry.js';
+import { validate } from '../cli/validate-api.js';
+import { describeConstraints, explain as explainInsight, suggestFix as suggestFixInsight, InsightError, } from './insights.js';
+import { graphInputShape, validateInputShape, whyInputShape, listConstraintsInputShape, explainInputShape, suggestFixInputShape, } from './contracts.js';
+export class ToolExecutionError extends Error {
+    code;
+    details;
+    constructor(code, message, details) {
+        super(message);
+        this.code = code;
+        this.details = details;
+    }
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : 'Unknown tool failure';
+}
+function toFailure(tool, error) {
+    if (error instanceof ToolExecutionError) {
+        return {
+            ok: false,
+            tool,
+            error: {
+                code: error.code,
+                message: error.message,
+                ...(error.details ? { details: error.details } : {}),
+            },
+        };
+    }
+    // Pure derivation errors (bad input, unsupported rule) carry their own code.
+    if (error instanceof InsightError) {
+        return {
+            ok: false,
+            tool,
+            error: {
+                code: error.code,
+                message: error.message,
+            },
+        };
+    }
+    return {
+        ok: false,
+        tool,
+        error: {
+            code: 'tool_execution_failed',
+            message: errorMessage(error),
+        },
+    };
+}
+async function executeTool(tool, fn) {
+    try {
+        return {
+            tool,
+            ...(await fn()),
+        };
+    }
+    catch (error) {
+        return toFailure(tool, error);
+    }
+}
+function isToolFailure(result) {
+    return result.ok === false && 'error' in result;
+}
+function responseToContent(result) {
+    return JSON.stringify(result, null, 2);
+}
+function parseJsonFile(filePath) {
+    if (!fs.existsSync(filePath)) {
+        throw new ToolExecutionError('tokens_not_found', `Tokens file not found: ${filePath}`);
+    }
+    try {
+        return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    }
+    catch (error) {
+        throw new ToolExecutionError('invalid_tokens', `Tokens file is not valid JSON: ${filePath}`, {
+            cause: errorMessage(error),
+        });
+    }
+}
+function asJsonObject(value, label) {
+    if (value && typeof value === 'object' && !Array.isArray(value)) {
+        return value;
+    }
+    throw new ToolExecutionError('invalid_input', `${label} must be a JSON object.`);
+}
+function zodIssueMessages(error) {
+    return error.issues.map((issue) => {
+        const path = issue.path.length > 0 ? `.${issue.path.join('.')}` : '';
+        return `constraints${path}: ${issue.message}`;
+    });
+}
+function resolveTokens(input) {
+    if (input.tokens !== undefined) {
+        // TASK-017: validate inline tokens at the handler boundary. A direct caller
+        // (not going through the MCP SDK's schema check) could otherwise pass an
+        // array/null/scalar that silently flattened to an empty, passing set.
+        return asJsonObject(input.tokens, 'tokens');
+    }
+    if (input.tokensPath !== undefined) {
+        return asJsonObject(parseJsonFile(input.tokensPath), 'tokensPath contents');
+    }
+    throw new ToolExecutionError('invalid_input', 'Provide either tokens or tokensPath.');
+}
+function constraints(input) {
+    if (input.constraints === undefined)
+        return undefined;
+    // TASK-017: reject malformed inline constraints at the boundary.
+    const object = asJsonObject(input.constraints, 'constraints');
+    const parsed = ConstraintsSchema.safeParse(object);
+    if (!parsed.success) {
+        throw new ToolExecutionError('invalid_input', 'constraints must match DCV constraint config schema.', {
+            issues: zodIssueMessages(parsed.error),
+        });
+    }
+    return parsed.data;
+}
+export async function validateTool(input) {
+    return executeTool('validate', () => {
+        if (input.tokens === undefined && input.tokensPath === undefined) {
+            throw new ToolExecutionError('invalid_input', 'Provide either tokens or tokensPath.');
+        }
+        return validate({
+            ...(input.tokens !== undefined ? { tokens: asJsonObject(input.tokens, 'tokens') } : {}),
+            ...(input.tokens === undefined && input.tokensPath !== undefined ? { tokensPath: input.tokensPath } : {}),
+            ...(input.constraints !== undefined ? { constraints: constraints(input) } : {}),
+            ...(input.configPath !== undefined ? { configPath: input.configPath } : {}),
+            ...(input.constraintsDir !== undefined ? { constraintsDir: input.constraintsDir } : {}),
+            ...(input.breakpoint !== undefined ? { breakpoint: input.breakpoint } : {}),
+        });
+    });
+}
+export async function whyTool(input) {
+    return executeTool('why', () => {
+        const { flat, edges } = flattenTokens(resolveTokens(input));
+        if (!Object.prototype.hasOwnProperty.call(flat, input.tokenId)) {
+            throw new ToolExecutionError('unknown_token', `Unknown token id: ${input.tokenId}`, {
+                tokenId: input.tokenId,
+                suggestions: suggestIds(input.tokenId, Object.keys(flat)).map((suggestion) => suggestion.id),
+            });
+        }
+        return {
+            ok: true,
+            ...explainWhy(input.tokenId, flat, edges),
+        };
+    });
+}
+export async function graphTool(input) {
+    return executeTool('graph', () => {
+        const { flat, edges } = flattenTokens(resolveTokens(input));
+        const nodes = Object.keys(flat).sort();
+        return {
+            ok: true,
+            nodes,
+            edges,
+            meta: {
+                nodeCount: nodes.length,
+                edgeCount: edges.length,
+            },
+        };
+    });
+}
+/** Resolve the constraint config the same way validate() does: inline → configPath
+ *  → discovered cwd config. */
+function resolveConstraintsConfig(input) {
+    if (input.constraints !== undefined) {
+        return { constraints: constraints(input) };
+    }
+    const res = loadConfig(input.configPath);
+    if (!res.ok) {
+        throw new ToolExecutionError('invalid_config', res.error);
+    }
+    return res.value;
+}
+/** Flatten tokens, build an engine for value resolution, and discover the active
+ *  constraint sources — the shared substrate for the read-only insight tools. */
+function deriveContext(input) {
+    const tokens = resolveTokens(input);
+    const config = resolveConstraintsConfig(input);
+    const { flat, edges } = flattenTokens(tokens);
+    const init = {};
+    for (const t of Object.values(flat)) {
+        init[t.id] = t.value;
+    }
+    const engine = new Engine(init, edges);
+    const knownIds = new Set(Object.keys(init));
+    const sources = discoverConstraints({
+        config,
+        bp: input.breakpoint,
+        constraintsDir: input.constraintsDir ?? 'themes',
+    });
+    return {
+        descriptors: describeConstraints(sources),
+        // Token ids resolve to their value; anything else (a literal backdrop color)
+        // passes through, mirroring the WCAG plugin's resolveColor.
+        getValue: (idOrLiteral) => (knownIds.has(idOrLiteral) ? String(engine.get(idOrLiteral)) : idOrLiteral),
+    };
+}
+/** explain / suggest-fix accept a full violation OR loose ruleId + nodes. */
+function resolveInsightTarget(input) {
+    if (input.violation) {
+        return {
+            ruleId: input.violation.ruleId,
+            nodes: input.violation.nodes ?? [],
+            context: input.violation.context,
+        };
+    }
+    if (input.ruleId) {
+        return {
+            ruleId: input.ruleId,
+            nodes: input.nodes ?? [],
+            context: input.context,
+        };
+    }
+    throw new ToolExecutionError('invalid_input', 'Provide either a violation object or ruleId (with nodes).');
+}
+export async function listConstraintsTool(input) {
+    return executeTool('list-constraints', () => {
+        const { descriptors } = deriveContext(input);
+        return { ok: true, constraints: descriptors, meta: { count: descriptors.length } };
+    });
+}
+export async function explainTool(input) {
+    return executeTool('explain', () => {
+        const { descriptors, getValue } = deriveContext(input);
+        const target = resolveInsightTarget(input);
+        return explainInsight({ ...target, getValue, descriptors });
+    });
+}
+export async function suggestFixTool(input) {
+    return executeTool('suggest-fix', () => {
+        const { descriptors, getValue } = deriveContext(input);
+        const target = resolveInsightTarget(input);
+        return suggestFixInsight({ ...target, getValue, descriptors, target: input.target });
+    });
+}
+export const dcvMcpTools = [
+    {
+        name: 'validate',
+        description: 'Validate DTCG-style design tokens against DCV constraints and return structured violations.',
+        inputSchema: validateInputShape,
+        handler: validateTool,
+    },
+    {
+        name: 'why',
+        description: 'Explain token provenance, aliases, immediate dependencies, dependents, and alias chain.',
+        inputSchema: whyInputShape,
+        handler: whyTool,
+    },
+    {
+        name: 'graph',
+        description: 'Return the token dependency graph as nodes and directed edges.',
+        inputSchema: graphInputShape,
+        handler: graphTool,
+    },
+    {
+        name: 'list-constraints',
+        description: 'List the active constraints (WCAG pairs, thresholds, order/lightness scales, cross-axis) for a token set/config. Read-only.',
+        inputSchema: listConstraintsInputShape,
+        handler: listConstraintsTool,
+    },
+    {
+        name: 'explain',
+        description: 'Explain a validation violation (WCAG, threshold, monotonic) in plain English plus machine-readable facts. Read-only.',
+        inputSchema: explainInputShape,
+        handler: explainTool,
+    },
+    {
+        name: 'suggest-fix',
+        description: 'Compute a verified satisfying value for a violation without writing it (WCAG color, threshold/monotonic boundary). Read-only.',
+        inputSchema: suggestFixInputShape,
+        handler: suggestFixTool,
+    },
+];
+export function registerDcvMcpTools(server) {
+    for (const tool of dcvMcpTools) {
+        server.registerTool(tool.name, {
+            description: tool.description,
+            inputSchema: tool.inputSchema,
+        }, async (input) => {
+            const result = await tool.handler(input);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: responseToContent(result),
+                    },
+                ],
+                structuredContent: result,
+                ...(isToolFailure(result) ? { isError: true } : {}),
+            };
+        });
+    }
+}