design-constraint-validator 2.1.0 → 2.2.1

package/mcp/tools.js

@@ -1,9 +1,14 @@
 import fs from 'node:fs';
 import { suggestIds } from '../core/cli-format.js';
 import { flattenTokens } from '../core/flatten.js';
-import { explain } from '../core/why.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 { graphInputShape, validateInputShape, whyInputShape } from './contracts.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;
@@ -28,6 +33,17 @@ function toFailure(tool, error) {
             },
         };
     }
+    // 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,
@@ -73,9 +89,18 @@ function asJsonObject(value, label) {
     }
     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) {
-        return input.tokens;
+        // 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');
@@ -83,7 +108,17 @@ function resolveTokens(input) {
     throw new ToolExecutionError('invalid_input', 'Provide either tokens or tokensPath.');
 }
 function constraints(input) {
-    return input.constraints;
+    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', () => {
@@ -91,7 +126,7 @@ export async function validateTool(input) {
             throw new ToolExecutionError('invalid_input', 'Provide either tokens or tokensPath.');
         }
         return validate({
-            ...(input.tokens !== undefined ? { tokens: input.tokens } : {}),
+            ...(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 } : {}),
@@ -111,7 +146,7 @@ export async function whyTool(input) {
         }
         return {
             ok: true,
-            ...explain(input.tokenId, flat, edges),
+            ...explainWhy(input.tokenId, flat, edges),
         };
     });
 }
@@ -130,6 +165,80 @@ export async function graphTool(input) {
         };
     });
 }
+/** 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',
@@ -149,6 +258,24 @@ export const dcvMcpTools = [
         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) {

package/mcp/tools.ts

@@ -4,15 +4,44 @@ import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
 import type { z } from 'zod';
 
 import { suggestIds } from '../core/cli-format.js';
-import { flattenTokens, type TokenNode } from '../core/flatten.js';
-import { explain, type WhyReport } from '../core/why.js';
+import { flattenTokens, type TokenNode, type FlatToken } from '../core/flatten.js';
+import { explain as explainWhy, type WhyReport } 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, type ValidateResult } from '../cli/validate-api.js';
 import type { DcvConfig } from '../cli/types.js';
 import type { Breakpoint } from '../core/breakpoints.js';
-import type { JsonObject, ValidateToolInput, WhyToolInput, GraphToolInput } from './contracts.js';
-import { graphInputShape, validateInputShape, whyInputShape } from './contracts.js';
-
-export type DcvMcpToolName = 'validate' | 'why' | 'graph';
+import {
+  describeConstraints,
+  explain as explainInsight,
+  suggestFix as suggestFixInsight,
+  InsightError,
+  type ConstraintDescriptor,
+  type ExplainResult,
+  type SuggestResult,
+  type ValueResolver,
+} from './insights.js';
+import type {
+  JsonObject,
+  ValidateToolInput,
+  WhyToolInput,
+  GraphToolInput,
+  ListConstraintsToolInput,
+  ExplainToolInput,
+  SuggestFixToolInput,
+} from './contracts.js';
+import {
+  graphInputShape,
+  validateInputShape,
+  whyInputShape,
+  listConstraintsInputShape,
+  explainInputShape,
+  suggestFixInputShape,
+} from './contracts.js';
+
+export type DcvMcpToolName = 'validate' | 'why' | 'graph' | 'list-constraints' | 'explain' | 'suggest-fix';
 
 export interface ToolFailure {
   ok: false;
@@ -52,7 +81,7 @@ export type WhyToolResult = { ok: true } & WhyReport;
 interface TokenInput {
   tokens?: JsonObject;
   tokensPath?: string;
-  constraints?: JsonObject;
+  constraints?: unknown;
   configPath?: string;
   constraintsDir?: string;
   breakpoint?: Breakpoint;
@@ -82,6 +111,18 @@ function toFailure(tool: DcvMcpToolName, error: unknown): ToolFailure {
     };
   }
 
+  // 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,
@@ -136,9 +177,19 @@ function asJsonObject(value: unknown, label: string): JsonObject {
   throw new ToolExecutionError('invalid_input', `${label} must be a JSON object.`);
 }
 
+function zodIssueMessages(error: z.ZodError): string[] {
+  return error.issues.map((issue) => {
+    const path = issue.path.length > 0 ? `.${issue.path.join('.')}` : '';
+    return `constraints${path}: ${issue.message}`;
+  });
+}
+
 function resolveTokens(input: TokenInput): TokenNode {
   if (input.tokens !== undefined) {
-    return input.tokens as unknown as TokenNode;
+    // 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') as unknown as TokenNode;
   }
 
   if (input.tokensPath !== undefined) {
@@ -149,7 +200,16 @@ function resolveTokens(input: TokenInput): TokenNode {
 }
 
 function constraints(input: TokenInput): DcvConfig['constraints'] | undefined {
-  return input.constraints as DcvConfig['constraints'] | undefined;
+  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: ValidateToolInput): Promise<ToolResponse<ValidateResult>> {
@@ -159,7 +219,7 @@ export async function validateTool(input: ValidateToolInput): Promise<ToolRespon
     }
 
     return validate({
-      ...(input.tokens !== undefined ? { tokens: input.tokens as unknown as TokenNode } : {}),
+      ...(input.tokens !== undefined ? { tokens: asJsonObject(input.tokens, 'tokens') as unknown as TokenNode } : {}),
       ...(input.tokens === undefined && input.tokensPath !== undefined ? { tokensPath: input.tokensPath } : {}),
       ...(input.constraints !== undefined ? { constraints: constraints(input) } : {}),
       ...(input.configPath !== undefined ? { configPath: input.configPath } : {}),
@@ -181,7 +241,7 @@ export async function whyTool(input: WhyToolInput): Promise<ToolResponse<WhyTool
 
     return {
       ok: true as const,
-      ...explain(input.tokenId, flat, edges),
+      ...explainWhy(input.tokenId, flat, edges),
     };
   });
 }
@@ -203,10 +263,109 @@ export async function graphTool(input: GraphToolInput): Promise<ToolResponse<Gra
   });
 }
 
+export interface ListConstraintsResult {
+  ok: true;
+  constraints: ConstraintDescriptor[];
+  meta: { count: number };
+}
+
+/** Resolve the constraint config the same way validate() does: inline → configPath
+ *  → discovered cwd config. */
+function resolveConstraintsConfig(input: TokenInput): DcvConfig {
+  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;
+}
+
+interface DerivedContext {
+  descriptors: ConstraintDescriptor[];
+  getValue: ValueResolver;
+}
+
+/** 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: TokenInput): DerivedContext {
+  const tokens = resolveTokens(input);
+  const config = resolveConstraintsConfig(input);
+
+  const { flat, edges } = flattenTokens(tokens);
+  const init: Record<string, string | number> = {};
+  for (const t of Object.values(flat)) {
+    init[(t as FlatToken).id] = (t as FlatToken).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: ExplainToolInput | SuggestFixToolInput,
+): { ruleId: string; nodes: string[]; context?: Record<string, unknown> } {
+  if (input.violation) {
+    return {
+      ruleId: input.violation.ruleId,
+      nodes: input.violation.nodes ?? [],
+      context: input.violation.context as Record<string, unknown> | undefined,
+    };
+  }
+  if (input.ruleId) {
+    return {
+      ruleId: input.ruleId,
+      nodes: input.nodes ?? [],
+      context: input.context as Record<string, unknown> | undefined,
+    };
+  }
+  throw new ToolExecutionError('invalid_input', 'Provide either a violation object or ruleId (with nodes).');
+}
+
+export async function listConstraintsTool(input: ListConstraintsToolInput): Promise<ToolResponse<ListConstraintsResult>> {
+  return executeTool('list-constraints', () => {
+    const { descriptors } = deriveContext(input);
+    return { ok: true as const, constraints: descriptors, meta: { count: descriptors.length } };
+  });
+}
+
+export async function explainTool(input: ExplainToolInput): Promise<ToolResponse<ExplainResult>> {
+  return executeTool('explain', () => {
+    const { descriptors, getValue } = deriveContext(input);
+    const target = resolveInsightTarget(input);
+    return explainInsight({ ...target, getValue, descriptors });
+  });
+}
+
+export async function suggestFixTool(input: SuggestFixToolInput): Promise<ToolResponse<SuggestResult>> {
+  return executeTool('suggest-fix', () => {
+    const { descriptors, getValue } = deriveContext(input);
+    const target = resolveInsightTarget(input);
+    return suggestFixInsight({ ...target, getValue, descriptors, target: input.target });
+  });
+}
+
 export const dcvMcpTools: Array<
   | ToolDefinition<ValidateToolInput, ValidateResult>
   | ToolDefinition<WhyToolInput, WhyToolResult>
   | ToolDefinition<GraphToolInput, GraphToolResult>
+  | ToolDefinition<ListConstraintsToolInput, ListConstraintsResult>
+  | ToolDefinition<ExplainToolInput, ExplainResult>
+  | ToolDefinition<SuggestFixToolInput, SuggestResult>
 > = [
   {
     name: 'validate',
@@ -226,6 +385,24 @@ export const dcvMcpTools: Array<
     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: McpServer): void {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "design-constraint-validator",
-  "version": "2.1.0",
+  "version": "2.2.1",
   "description": "Mathematical constraint validator for design systems — ensuring consistency, accessibility, and logical coherence",
   "type": "module",
   "engines": {
@@ -26,16 +26,11 @@
     "design-constraint-validator": "./cli/index.js",
     "dcv-mcp": "./mcp/index.js"
   },
-  "mcpName": "io.github.cseperkepapp/design-constraint-validator",
+  "mcpName": "io.github.CseperkePapp/design-constraint-validator",
   "scripts": {
     "test": "vitest run --exclude \"**/*.test.js\"",
     "test:watch": "vitest --exclude \"**/*.test.js\"",
     "typecheck": "tsc --noEmit",
-    "workflow:typecheck": "tsc -p tsconfig.workflow-automation.json --noEmit",
-    "validate-headers": "tsx scripts/validate-headers.ts",
-    "workflow:test": "vitest run src/__tests__/task-workflow-integrity.test.ts src/__tests__/sync-task-index.test.ts",
-    "task:sync": "tsx scripts/sync-task-index.ts",
-    "rename-done-tasks": "tsx scripts/rename-done-tasks.ts",
     "build": "tsc",
     "lint": "eslint . --ext .js,.ts,.mjs,.cjs",
     "format": "prettier -w .",

package/server.json

@@ -1,9 +1,9 @@
 {
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
-  "name": "io.github.cseperkepapp/design-constraint-validator",
+  "name": "io.github.CseperkePapp/design-constraint-validator",
   "title": "Design Constraint Validator",
   "description": "Validate design tokens for accessibility, scales, and design-system constraint consistency.",
-  "version": "2.1.0",
+  "version": "2.2.1",
   "repository": {
     "url": "https://github.com/CseperkePapp/design-constraint-validator",
     "source": "github"
@@ -12,7 +12,7 @@
     {
       "registryType": "npm",
       "identifier": "design-constraint-validator",
-      "version": "2.1.0",
+      "version": "2.2.1",
       "transport": {
         "type": "stdio"
       }