design-constraint-validator 2.0.1 → 2.2.0

package/mcp/contracts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contracts.d.ts","sourceRoot":"","sources":["contracts.ts"],"names":[],"mappings":"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"}

package/mcp/contracts.js

@@ -0,0 +1,74 @@
+import { z } from 'zod';
+import { ConstraintsSchema } from '../cli/config-schema.js';
+const jsonPrimitiveSchema = z.union([z.string(), z.number(), z.boolean(), z.null()]);
+export const jsonValueSchema = z.lazy(() => z.union([jsonPrimitiveSchema, z.array(jsonValueSchema), z.record(jsonValueSchema)]));
+export const jsonObjectSchema = z.record(jsonValueSchema);
+export const tokenInputShape = {
+    tokens: jsonObjectSchema
+        .optional()
+        .describe('Inline DTCG-style token tree. Takes precedence over tokensPath.'),
+    tokensPath: z.string().optional().describe('Path to a token JSON file on the server filesystem.'),
+    constraints: ConstraintsSchema
+        .optional()
+        .describe('Inline constraints block from dcv.config.json. Takes precedence over configPath.'),
+    configPath: z.string().optional().describe('Path to a JSON DCV config file.'),
+    constraintsDir: z.string().optional().describe('Directory holding order and cross-axis constraints.'),
+    breakpoint: z.enum(['sm', 'md', 'lg']).optional().describe('Optional constraint breakpoint.'),
+};
+export const validateInputShape = {
+    ...tokenInputShape,
+};
+export const whyInputShape = {
+    ...tokenInputShape,
+    tokenId: z.string().describe('Token id to explain, for example color.role.text.default.'),
+};
+export const graphInputShape = {
+    ...tokenInputShape,
+    format: z.literal('json').optional().describe('Only json is supported; omitted defaults to json.'),
+};
+// A validation violation, as emitted by the `validate` tool. Accepted by
+// `explain` / `suggest-fix` so an agent can pipe a violation straight back in.
+export const violationInputSchema = z
+    .object({
+    ruleId: z.string().describe('Rule id, e.g. wcag-contrast, threshold, monotonic.'),
+    level: z.enum(['error', 'warn']).optional(),
+    message: z.string().optional(),
+    nodes: z.array(z.string()).optional().describe('Involved token ids.'),
+    edges: z.array(z.tuple([z.string(), z.string()])).optional(),
+    context: z.record(z.unknown()).optional(),
+})
+    .describe('A validation violation to explain or fix.');
+export const listConstraintsInputShape = {
+    ...tokenInputShape,
+};
+// `explain` / `suggest-fix` accept EITHER a full `violation` object OR the loose
+// `ruleId` + `nodes` (+ optional `context`) pair. The handler requires one path.
+const insightInputShape = {
+    ...tokenInputShape,
+    violation: violationInputSchema.optional(),
+    ruleId: z.string().optional().describe('Rule id, when not passing a full violation.'),
+    nodes: z
+        .array(z.string())
+        .optional()
+        .describe('Involved token ids, when not passing a full violation. WCAG: [foreground, background].'),
+    context: z
+        .record(z.unknown())
+        .optional()
+        .describe('Optional known facts (e.g. { required: 4.5 }) used as a fallback when the rule cannot be rediscovered.'),
+};
+export const explainInputShape = {
+    ...insightInputShape,
+};
+export const suggestFixInputShape = {
+    ...insightInputShape,
+    target: z
+        .enum(['foreground', 'background'])
+        .optional()
+        .describe('WCAG only: which side to adjust. Omit to get both candidates.'),
+};
+export const validateInputSchema = z.object(validateInputShape);
+export const whyInputSchema = z.object(whyInputShape);
+export const graphInputSchema = z.object(graphInputShape);
+export const listConstraintsInputSchema = z.object(listConstraintsInputShape);
+export const explainInputSchema = z.object(explainInputShape);
+export const suggestFixInputSchema = z.object(suggestFixInputShape);

package/mcp/contracts.ts

@@ -0,0 +1,105 @@
+import { z } from 'zod';
+
+import { ConstraintsSchema } from '../cli/config-schema.js';
+
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonValue = JsonPrimitive | JsonObject | JsonValue[];
+
+export interface JsonObject {
+  [key: string]: JsonValue;
+}
+
+const jsonPrimitiveSchema = z.union([z.string(), z.number(), z.boolean(), z.null()]);
+
+export const jsonValueSchema: z.ZodType<JsonValue> = z.lazy(() =>
+  z.union([jsonPrimitiveSchema, z.array(jsonValueSchema), z.record(jsonValueSchema)]),
+);
+
+export const jsonObjectSchema: z.ZodType<JsonObject> = z.record(jsonValueSchema);
+
+export const tokenInputShape = {
+  tokens: jsonObjectSchema
+    .optional()
+    .describe('Inline DTCG-style token tree. Takes precedence over tokensPath.'),
+  tokensPath: z.string().optional().describe('Path to a token JSON file on the server filesystem.'),
+  constraints: ConstraintsSchema
+    .optional()
+    .describe('Inline constraints block from dcv.config.json. Takes precedence over configPath.'),
+  configPath: z.string().optional().describe('Path to a JSON DCV config file.'),
+  constraintsDir: z.string().optional().describe('Directory holding order and cross-axis constraints.'),
+  breakpoint: z.enum(['sm', 'md', 'lg']).optional().describe('Optional constraint breakpoint.'),
+};
+
+export const validateInputShape = {
+  ...tokenInputShape,
+};
+
+export const whyInputShape = {
+  ...tokenInputShape,
+  tokenId: z.string().describe('Token id to explain, for example color.role.text.default.'),
+};
+
+export const graphInputShape = {
+  ...tokenInputShape,
+  format: z.literal('json').optional().describe('Only json is supported; omitted defaults to json.'),
+};
+
+// A validation violation, as emitted by the `validate` tool. Accepted by
+// `explain` / `suggest-fix` so an agent can pipe a violation straight back in.
+export const violationInputSchema = z
+  .object({
+    ruleId: z.string().describe('Rule id, e.g. wcag-contrast, threshold, monotonic.'),
+    level: z.enum(['error', 'warn']).optional(),
+    message: z.string().optional(),
+    nodes: z.array(z.string()).optional().describe('Involved token ids.'),
+    edges: z.array(z.tuple([z.string(), z.string()])).optional(),
+    context: z.record(z.unknown()).optional(),
+  })
+  .describe('A validation violation to explain or fix.');
+
+export const listConstraintsInputShape = {
+  ...tokenInputShape,
+};
+
+// `explain` / `suggest-fix` accept EITHER a full `violation` object OR the loose
+// `ruleId` + `nodes` (+ optional `context`) pair. The handler requires one path.
+const insightInputShape = {
+  ...tokenInputShape,
+  violation: violationInputSchema.optional(),
+  ruleId: z.string().optional().describe('Rule id, when not passing a full violation.'),
+  nodes: z
+    .array(z.string())
+    .optional()
+    .describe('Involved token ids, when not passing a full violation. WCAG: [foreground, background].'),
+  context: z
+    .record(z.unknown())
+    .optional()
+    .describe('Optional known facts (e.g. { required: 4.5 }) used as a fallback when the rule cannot be rediscovered.'),
+};
+
+export const explainInputShape = {
+  ...insightInputShape,
+};
+
+export const suggestFixInputShape = {
+  ...insightInputShape,
+  target: z
+    .enum(['foreground', 'background'])
+    .optional()
+    .describe('WCAG only: which side to adjust. Omit to get both candidates.'),
+};
+
+export const validateInputSchema = z.object(validateInputShape);
+export const whyInputSchema = z.object(whyInputShape);
+export const graphInputSchema = z.object(graphInputShape);
+export const listConstraintsInputSchema = z.object(listConstraintsInputShape);
+export const explainInputSchema = z.object(explainInputShape);
+export const suggestFixInputSchema = z.object(suggestFixInputShape);
+
+export type ValidateToolInput = z.infer<typeof validateInputSchema>;
+export type WhyToolInput = z.infer<typeof whyInputSchema>;
+export type GraphToolInput = z.infer<typeof graphInputSchema>;
+export type ListConstraintsToolInput = z.infer<typeof listConstraintsInputSchema>;
+export type ExplainToolInput = z.infer<typeof explainInputSchema>;
+export type SuggestFixToolInput = z.infer<typeof suggestFixInputSchema>;
+export type ViolationInput = z.infer<typeof violationInputSchema>;

package/mcp/index.d.ts

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export { graphInputSchema, graphInputShape, jsonObjectSchema, jsonValueSchema, validateInputSchema, validateInputShape, whyInputSchema, whyInputShape, listConstraintsInputSchema, listConstraintsInputShape, explainInputSchema, explainInputShape, suggestFixInputSchema, suggestFixInputShape, violationInputSchema, } from './contracts.js';
+export type { GraphToolInput, JsonObject, JsonPrimitive, JsonValue, ValidateToolInput, WhyToolInput, ListConstraintsToolInput, ExplainToolInput, SuggestFixToolInput, ViolationInput, } from './contracts.js';
+export { dcvMcpTools, graphTool, registerDcvMcpTools, ToolExecutionError, validateTool, whyTool, listConstraintsTool, explainTool, suggestFixTool, } from './tools.js';
+export type { DcvMcpToolName, GraphToolResult, ToolFailure, ToolResponse, WhyToolResult, ListConstraintsResult, } from './tools.js';
+export { describeConstraints, InsightError, } from './insights.js';
+export type { ConstraintDescriptor, ExplainResult, SuggestResult, Suggestion, } from './insights.js';
+export declare function createDcvMcpServer(): McpServer;
+export declare function startStdioServer(): Promise<void>;
+//# sourceMappingURL=index.d.ts.map

package/mcp/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["index.ts"],"names":[],"mappings":";AAGA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAMpE,OAAO,EACL,gBAAgB,EAChB,eAAe,EACf,gBAAgB,EAChB,eAAe,EACf,mBAAmB,EACnB,kBAAkB,EAClB,cAAc,EACd,aAAa,EACb,0BAA0B,EAC1B,yBAAyB,EACzB,kBAAkB,EAClB,iBAAiB,EACjB,qBAAqB,EACrB,oBAAoB,EACpB,oBAAoB,GACrB,MAAM,gBAAgB,CAAC;AACxB,YAAY,EACV,cAAc,EACd,UAAU,EACV,aAAa,EACb,SAAS,EACT,iBAAiB,EACjB,YAAY,EACZ,wBAAwB,EACxB,gBAAgB,EAChB,mBAAmB,EACnB,cAAc,GACf,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,WAAW,EACX,SAAS,EACT,mBAAmB,EACnB,kBAAkB,EAClB,YAAY,EACZ,OAAO,EACP,mBAAmB,EACnB,WAAW,EACX,cAAc,GACf,MAAM,YAAY,CAAC;AACpB,YAAY,EACV,cAAc,EACd,eAAe,EACf,WAAW,EACX,YAAY,EACZ,aAAa,EACb,qBAAqB,GACtB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,mBAAmB,EACnB,YAAY,GACb,MAAM,eAAe,CAAC;AACvB,YAAY,EACV,oBAAoB,EACpB,aAAa,EACb,aAAa,EACb,UAAU,GACX,MAAM,eAAe,CAAC;AAEvB,wBAAgB,kBAAkB,IAAI,SAAS,CAS9C;AAED,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC,CAItD"}

package/mcp/index.js

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { getVersionInfo } from '../cli/version-banner.js';
+import { registerDcvMcpTools } from './tools.js';
+export { graphInputSchema, graphInputShape, jsonObjectSchema, jsonValueSchema, validateInputSchema, validateInputShape, whyInputSchema, whyInputShape, listConstraintsInputSchema, listConstraintsInputShape, explainInputSchema, explainInputShape, suggestFixInputSchema, suggestFixInputShape, violationInputSchema, } from './contracts.js';
+export { dcvMcpTools, graphTool, registerDcvMcpTools, ToolExecutionError, validateTool, whyTool, listConstraintsTool, explainTool, suggestFixTool, } from './tools.js';
+export { describeConstraints, InsightError, } from './insights.js';
+export function createDcvMcpServer() {
+    const version = getVersionInfo().version;
+    const server = new McpServer({
+        name: 'dcv-mcp',
+        version,
+    });
+    registerDcvMcpTools(server);
+    return server;
+}
+export async function startStdioServer() {
+    const server = createDcvMcpServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+function isEntrypoint() {
+    const entry = process.argv[1];
+    return entry !== undefined && resolve(fileURLToPath(import.meta.url)) === resolve(entry);
+}
+if (isEntrypoint()) {
+    startStdioServer().catch((error) => {
+        const message = error instanceof Error ? error.message : 'Unknown MCP server failure';
+        console.error(`[dcv-mcp] ${message}`);
+        process.exitCode = 1;
+    });
+}

package/mcp/index.ts

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+
+import { getVersionInfo } from '../cli/version-banner.js';
+import { registerDcvMcpTools } from './tools.js';
+
+export {
+  graphInputSchema,
+  graphInputShape,
+  jsonObjectSchema,
+  jsonValueSchema,
+  validateInputSchema,
+  validateInputShape,
+  whyInputSchema,
+  whyInputShape,
+  listConstraintsInputSchema,
+  listConstraintsInputShape,
+  explainInputSchema,
+  explainInputShape,
+  suggestFixInputSchema,
+  suggestFixInputShape,
+  violationInputSchema,
+} from './contracts.js';
+export type {
+  GraphToolInput,
+  JsonObject,
+  JsonPrimitive,
+  JsonValue,
+  ValidateToolInput,
+  WhyToolInput,
+  ListConstraintsToolInput,
+  ExplainToolInput,
+  SuggestFixToolInput,
+  ViolationInput,
+} from './contracts.js';
+export {
+  dcvMcpTools,
+  graphTool,
+  registerDcvMcpTools,
+  ToolExecutionError,
+  validateTool,
+  whyTool,
+  listConstraintsTool,
+  explainTool,
+  suggestFixTool,
+} from './tools.js';
+export type {
+  DcvMcpToolName,
+  GraphToolResult,
+  ToolFailure,
+  ToolResponse,
+  WhyToolResult,
+  ListConstraintsResult,
+} from './tools.js';
+export {
+  describeConstraints,
+  InsightError,
+} from './insights.js';
+export type {
+  ConstraintDescriptor,
+  ExplainResult,
+  SuggestResult,
+  Suggestion,
+} from './insights.js';
+
+export function createDcvMcpServer(): McpServer {
+  const version = getVersionInfo().version;
+  const server = new McpServer({
+    name: 'dcv-mcp',
+    version,
+  });
+
+  registerDcvMcpTools(server);
+  return server;
+}
+
+export async function startStdioServer(): Promise<void> {
+  const server = createDcvMcpServer();
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+function isEntrypoint(): boolean {
+  const entry = process.argv[1];
+  return entry !== undefined && resolve(fileURLToPath(import.meta.url)) === resolve(entry);
+}
+
+if (isEntrypoint()) {
+  startStdioServer().catch((error: unknown) => {
+    const message = error instanceof Error ? error.message : 'Unknown MCP server failure';
+    console.error(`[dcv-mcp] ${message}`);
+    process.exitCode = 1;
+  });
+}

package/mcp/insights.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Pure derivation logic for the read-only insight tools
+ * (`list-constraints`, `explain`, `suggest-fix`).
+ *
+ * Everything here is side-effect free: no filesystem, no engine construction, no
+ * writes. Callers pass in a value resolver and the already-discovered constraint
+ * sources; these functions turn raw violations into explanations and verified
+ * suggestions. The WCAG math reuses core/color so suggestions are checked against
+ * the same contrast pipeline the validator uses.
+ */
+import { type ConstraintSource, type OrderRule } from '../cli/constraint-registry.js';
+/** Thrown for caller-facing problems (bad input, unsupported rule). The MCP
+ *  handler maps `.code` onto a structured tool error. */
+export declare class InsightError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/** Resolves a token id to its value string, or returns the argument unchanged
+ *  when it is a literal (e.g. a backdrop color), mirroring the WCAG plugin. */
+export type ValueResolver = (idOrLiteral: string) => string;
+export type ConstraintDescriptor = {
+    kind: 'wcag';
+    source: 'builtin' | 'config';
+    foreground: string;
+    background: string;
+    minRatio: number;
+    backdrop?: string;
+    where?: string;
+} | {
+    kind: 'threshold';
+    source: 'builtin' | 'config';
+    tokenId: string;
+    op: '>=' | '<=';
+    valuePx: number;
+    where?: string;
+} | {
+    kind: 'order';
+    source: 'file';
+    axis: string;
+    path: string;
+    orders: OrderRule[];
+} | {
+    kind: 'lightness';
+    source: 'file';
+    path: string;
+    orders: OrderRule[];
+} | {
+    kind: 'cross-axis';
+    source: 'file';
+    path: string;
+    breakpoint?: string;
+};
+/** Flatten discovered constraint sources into a stable, agent-friendly list. */
+export declare function describeConstraints(sources: ConstraintSource[]): ConstraintDescriptor[];
+type RuleKind = 'wcag' | 'threshold' | 'monotonic' | 'monotonic-lightness';
+export interface InsightRequest {
+    ruleId: string;
+    nodes: string[];
+    context?: Record<string, unknown>;
+    getValue: ValueResolver;
+    descriptors: ConstraintDescriptor[];
+}
+export interface ExplainResult {
+    ok: true;
+    ruleId: string;
+    kind: RuleKind;
+    nodes: string[];
+    facts: Record<string, unknown>;
+    explanation: string;
+}
+export declare function explain(req: InsightRequest): ExplainResult;
+export interface Suggestion {
+    tokenId: string;
+    role: string;
+    currentValue: string;
+    suggestedValue: string;
+    resultingValue: number;
+    satisfies: string;
+    why: string;
+}
+export interface SuggestResult {
+    ok: true;
+    ruleId: string;
+    kind: RuleKind;
+    nodes: string[];
+    suggestions: Suggestion[];
+    note?: string;
+}
+export interface SuggestRequest extends InsightRequest {
+    target?: 'foreground' | 'background';
+}
+export declare function suggestFix(req: SuggestRequest): SuggestResult;
+export {};
+//# sourceMappingURL=insights.d.ts.map

package/mcp/insights.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"insights.d.ts","sourceRoot":"","sources":["insights.ts"],"names":[],"mappings":"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"}