@dawmatt/api-grade-mcp 0.1.0

package/dist/tools/non-breaking.js

@@ -0,0 +1,138 @@
+import { statSync, readFileSync, writeFileSync, unlinkSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { z } from 'zod';
+import { GradeEngine } from '@dawmatt/api-grade-core';
+import { mcpError, buildAuthFailureResponse, ERROR_CODES } from '../utils/errors.js';
+import { loadWorkspaceConfig, loadGlobalConfig } from '../config/ruleset-config.js';
+import { resolveRuleset } from '../config/resolve-ruleset.js';
+import { fetchRulesetContent, RulesetAuthError, INITIAL_FETCH_TIMEOUT_MS, RETRY_FETCH_TIMEOUT_MS } from '../auth/github.js';
+import { EntraAuthRequired, acquireEntraToken } from '../auth/entra.js';
+import { classifyViolation, buildNonBreakingViolation } from '../utils/classify.js';
+const LARGE_SPEC_THRESHOLD_BYTES = 500_000;
+export function registerNonBreakingTool(server, sessionState) {
+    server.tool('get-non-breaking-violations', 'Return a classified, AI-actionable list of non-breaking violations in an API specification. Non-breaking violations are those whose fixes do not alter the API interface contract (paths, methods, required parameters, schema types, or response structures). Use this tool to obtain issues the AI can safely resolve — the AI generates the corrected specification content; the MCP server does not modify files.', {
+        specPath: z
+            .string()
+            .describe('Absolute or relative path to the OpenAPI or AsyncAPI specification file (YAML or JSON)'),
+        rulesetPath: z
+            .string()
+            .optional()
+            .describe('Optional path to a custom Spectral-compatible ruleset file'),
+        recoveryOption: z
+            .enum(['retry', 'use-builtin-once', 'use-builtin-session', 'cancel'])
+            .optional()
+            .describe('Recovery action when the configured default ruleset is inaccessible. Only supply in response to a RULESET_AUTH_FAILED response.'),
+    }, async ({ specPath, rulesetPath, recoveryOption }) => {
+        if (recoveryOption === 'cancel') {
+            return mcpError(ERROR_CODES.REQUEST_CANCELLED, 'Grading request cancelled by user.', { specPath });
+        }
+        if (recoveryOption === 'use-builtin-session') {
+            sessionState.sessionRulesetOverride = 'builtin';
+        }
+        const workspaceConfig = await loadWorkspaceConfig();
+        const globalConfig = await loadGlobalConfig();
+        const resolved = resolveRuleset(rulesetPath, sessionState, workspaceConfig, globalConfig);
+        let effectiveRulesetPath = resolved.rulesetPath ?? undefined;
+        let tempRulesetFile;
+        if (resolved.rulesetPath?.startsWith('http')) {
+            if (recoveryOption === 'use-builtin-once') {
+                effectiveRulesetPath = undefined;
+            }
+            else {
+                const timeoutMs = recoveryOption === 'retry' ? RETRY_FETCH_TIMEOUT_MS : INITIAL_FETCH_TIMEOUT_MS;
+                try {
+                    let content;
+                    if (resolved.auth?.type === 'github-pat') {
+                        const token = resolved.auth.githubToken ?? process.env.GITHUB_TOKEN ?? '';
+                        content = await fetchRulesetContent(resolved.rulesetPath, token || undefined, timeoutMs);
+                    }
+                    else if (resolved.auth?.type === 'entra-id' && resolved.auth.tenantId && resolved.auth.clientId) {
+                        const token = await acquireEntraToken(resolved.auth.tenantId, resolved.auth.clientId);
+                        content = await fetchRulesetContent(resolved.rulesetPath, token, timeoutMs);
+                    }
+                    else {
+                        content = await fetchRulesetContent(resolved.rulesetPath, undefined, timeoutMs);
+                    }
+                    tempRulesetFile = join(tmpdir(), `api-grade-ruleset-${Date.now()}.yaml`);
+                    writeFileSync(tempRulesetFile, content);
+                    effectiveRulesetPath = tempRulesetFile;
+                }
+                catch (err) {
+                    if (err instanceof EntraAuthRequired) {
+                        return {
+                            content: [{
+                                    type: 'text',
+                                    text: JSON.stringify({
+                                        error: ERROR_CODES.ENTRA_AUTH_REQUIRED,
+                                        deviceCodeUrl: err.verificationUri,
+                                        userCode: err.userCode,
+                                        expiresIn: err.expiresIn,
+                                        message: `Complete Entra ID sign-in: Visit ${err.verificationUri} and enter code ${err.userCode}`,
+                                    }),
+                                }],
+                            isError: true,
+                        };
+                    }
+                    const reason = err instanceof RulesetAuthError ? err.reason : 'network-unreachable';
+                    return buildAuthFailureResponse(reason, resolved.rulesetPath, resolved.scope, `Could not fetch ruleset from '${resolved.rulesetPath}' (${resolved.scope} default): ${reason.replace('-', ' ')}.`);
+                }
+            }
+        }
+        else if (effectiveRulesetPath) {
+            try {
+                statSync(effectiveRulesetPath);
+            }
+            catch {
+                return mcpError(ERROR_CODES.RULESET_NOT_FOUND, `The ruleset file '${effectiveRulesetPath}' does not exist. Check the path and try again.`, { rulesetPath: effectiveRulesetPath });
+            }
+        }
+        let largeSpecWarning;
+        let specContent = '';
+        try {
+            const stat = statSync(specPath);
+            if (stat.size > LARGE_SPEC_THRESHOLD_BYTES) {
+                largeSpecWarning = `Specification exceeds 500KB (${stat.size} bytes); diagnostic results may be truncated`;
+            }
+            specContent = readFileSync(specPath, 'utf-8');
+        }
+        catch {
+            if (tempRulesetFile)
+                try {
+                    unlinkSync(tempRulesetFile);
+                }
+                catch { /* ignore */ }
+            return mcpError(ERROR_CODES.SPEC_NOT_FOUND, `The specification file '${specPath}' does not exist. Check the path and try again.`, { specPath });
+        }
+        try {
+            const engine = new GradeEngine();
+            const result = await engine.grade({ specPath, rulesetPath: effectiveRulesetPath });
+            const nonBreakingViolations = result.diagnostics
+                .filter((d) => classifyViolation(d) === 'nonBreaking')
+                .map((d) => buildNonBreakingViolation(d, specContent));
+            const response = {
+                specPath: result.specPath,
+                format: result.format,
+                totalViolations: result.diagnostics.length,
+                nonBreakingCount: nonBreakingViolations.length,
+                nonBreakingViolations,
+            };
+            if (largeSpecWarning) {
+                response.largeSpecWarning = largeSpecWarning;
+            }
+            return { content: [{ type: 'text', text: JSON.stringify(response) }] };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return mcpError(ERROR_CODES.GRADE_ENGINE_ERROR, `GradeEngine error: ${message}`, { specPath });
+        }
+        finally {
+            if (tempRulesetFile)
+                try {
+                    unlinkSync(tempRulesetFile);
+                }
+                catch { /* ignore */ }
+        }
+    });
+}
+//# sourceMappingURL=non-breaking.js.map

package/dist/tools/non-breaking.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"non-breaking.js","sourceRoot":"","sources":["../../src/tools/non-breaking.ts"],"names":[],"mappings":"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"}

package/dist/tools/quick-fixes-only.d.ts

@@ -0,0 +1,4 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { SessionState } from '../types.js';
+export declare function registerQuickFixesOnlyTool(server: McpServer, sessionState: SessionState): void;
+//# sourceMappingURL=quick-fixes-only.d.ts.map

package/dist/tools/quick-fixes-only.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"quick-fixes-only.d.ts","sourceRoot":"","sources":["../../src/tools/quick-fixes-only.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAOzE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAIhD,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,SAAS,EAAE,YAAY,EAAE,YAAY,GAAG,IAAI,CAgJ9F"}

package/dist/tools/quick-fixes-only.js

@@ -0,0 +1,138 @@
+import { statSync, readFileSync, writeFileSync, unlinkSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { z } from 'zod';
+import { GradeEngine } from '@dawmatt/api-grade-core';
+import { mcpError, buildAuthFailureResponse, ERROR_CODES } from '../utils/errors.js';
+import { loadWorkspaceConfig, loadGlobalConfig } from '../config/ruleset-config.js';
+import { resolveRuleset } from '../config/resolve-ruleset.js';
+import { fetchRulesetContent, RulesetAuthError, INITIAL_FETCH_TIMEOUT_MS, RETRY_FETCH_TIMEOUT_MS } from '../auth/github.js';
+import { EntraAuthRequired, acquireEntraToken } from '../auth/entra.js';
+import { classifyViolation, buildQuickFix } from '../utils/classify.js';
+const LARGE_SPEC_THRESHOLD_BYTES = 500_000;
+export function registerQuickFixesOnlyTool(server, sessionState) {
+    server.tool('grade-api-quick-fixes-only', 'Return a classified, AI-actionable list of quick fixes for an API specification. Quick fixes are improvements that can be made via non-breaking changes — those that do not alter the API interface contract (paths, methods, required parameters, schema types, or response structures). Use this tool (not grade-api-detailed) when the goal is for the AI to safely resolve violations; the AI generates the corrected specification content and the MCP server does not modify files.', {
+        specPath: z
+            .string()
+            .describe('Absolute or relative path to the OpenAPI or AsyncAPI specification file (YAML or JSON)'),
+        rulesetPath: z
+            .string()
+            .optional()
+            .describe('Optional path to a custom Spectral-compatible ruleset file'),
+        recoveryOption: z
+            .enum(['retry', 'use-builtin-once', 'use-builtin-session', 'cancel'])
+            .optional()
+            .describe('Recovery action when the configured default ruleset is inaccessible. Only supply in response to a RULESET_AUTH_FAILED response.'),
+    }, async ({ specPath, rulesetPath, recoveryOption }) => {
+        if (recoveryOption === 'cancel') {
+            return mcpError(ERROR_CODES.REQUEST_CANCELLED, 'Grading request cancelled by user.', { specPath });
+        }
+        if (recoveryOption === 'use-builtin-session') {
+            sessionState.sessionRulesetOverride = 'builtin';
+        }
+        const workspaceConfig = await loadWorkspaceConfig();
+        const globalConfig = await loadGlobalConfig();
+        const resolved = resolveRuleset(rulesetPath, sessionState, workspaceConfig, globalConfig);
+        let effectiveRulesetPath = resolved.rulesetPath ?? undefined;
+        let tempRulesetFile;
+        if (resolved.rulesetPath?.startsWith('http')) {
+            if (recoveryOption === 'use-builtin-once') {
+                effectiveRulesetPath = undefined;
+            }
+            else {
+                const timeoutMs = recoveryOption === 'retry' ? RETRY_FETCH_TIMEOUT_MS : INITIAL_FETCH_TIMEOUT_MS;
+                try {
+                    let content;
+                    if (resolved.auth?.type === 'github-pat') {
+                        const token = resolved.auth.githubToken ?? process.env.GITHUB_TOKEN ?? '';
+                        content = await fetchRulesetContent(resolved.rulesetPath, token || undefined, timeoutMs);
+                    }
+                    else if (resolved.auth?.type === 'entra-id' && resolved.auth.tenantId && resolved.auth.clientId) {
+                        const token = await acquireEntraToken(resolved.auth.tenantId, resolved.auth.clientId);
+                        content = await fetchRulesetContent(resolved.rulesetPath, token, timeoutMs);
+                    }
+                    else {
+                        content = await fetchRulesetContent(resolved.rulesetPath, undefined, timeoutMs);
+                    }
+                    tempRulesetFile = join(tmpdir(), `api-grade-ruleset-${Date.now()}.yaml`);
+                    writeFileSync(tempRulesetFile, content);
+                    effectiveRulesetPath = tempRulesetFile;
+                }
+                catch (err) {
+                    if (err instanceof EntraAuthRequired) {
+                        return {
+                            content: [{
+                                    type: 'text',
+                                    text: JSON.stringify({
+                                        error: ERROR_CODES.ENTRA_AUTH_REQUIRED,
+                                        deviceCodeUrl: err.verificationUri,
+                                        userCode: err.userCode,
+                                        expiresIn: err.expiresIn,
+                                        message: `Complete Entra ID sign-in: Visit ${err.verificationUri} and enter code ${err.userCode}`,
+                                    }),
+                                }],
+                            isError: true,
+                        };
+                    }
+                    const reason = err instanceof RulesetAuthError ? err.reason : 'network-unreachable';
+                    return buildAuthFailureResponse(reason, resolved.rulesetPath, resolved.scope, `Could not fetch ruleset from '${resolved.rulesetPath}' (${resolved.scope} default): ${reason.replace('-', ' ')}.`);
+                }
+            }
+        }
+        else if (effectiveRulesetPath) {
+            try {
+                statSync(effectiveRulesetPath);
+            }
+            catch {
+                return mcpError(ERROR_CODES.RULESET_NOT_FOUND, `The ruleset file '${effectiveRulesetPath}' does not exist. Check the path and try again.`, { rulesetPath: effectiveRulesetPath });
+            }
+        }
+        let largeSpecWarning;
+        let specContent = '';
+        try {
+            const stat = statSync(specPath);
+            if (stat.size > LARGE_SPEC_THRESHOLD_BYTES) {
+                largeSpecWarning = `Specification exceeds 500KB (${stat.size} bytes); diagnostic results may be truncated`;
+            }
+            specContent = readFileSync(specPath, 'utf-8');
+        }
+        catch {
+            if (tempRulesetFile)
+                try {
+                    unlinkSync(tempRulesetFile);
+                }
+                catch { /* ignore */ }
+            return mcpError(ERROR_CODES.SPEC_NOT_FOUND, `The specification file '${specPath}' does not exist. Check the path and try again.`, { specPath });
+        }
+        try {
+            const engine = new GradeEngine();
+            const result = await engine.grade({ specPath, rulesetPath: effectiveRulesetPath });
+            const quickFixes = result.diagnostics
+                .filter((d) => classifyViolation(d) === 'nonBreaking')
+                .map((d) => buildQuickFix(d, specContent));
+            const response = {
+                specPath: result.specPath,
+                format: result.format,
+                totalViolations: result.diagnostics.length,
+                quickFixCount: quickFixes.length,
+                quickFixes,
+            };
+            if (largeSpecWarning) {
+                response.largeSpecWarning = largeSpecWarning;
+            }
+            return { content: [{ type: 'text', text: JSON.stringify(response) }] };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return mcpError(ERROR_CODES.GRADE_ENGINE_ERROR, `GradeEngine error: ${message}`, { specPath });
+        }
+        finally {
+            if (tempRulesetFile)
+                try {
+                    unlinkSync(tempRulesetFile);
+                }
+                catch { /* ignore */ }
+        }
+    });
+}
+//# sourceMappingURL=quick-fixes-only.js.map

package/dist/tools/quick-fixes-only.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"quick-fixes-only.js","sourceRoot":"","sources":["../../src/tools/quick-fixes-only.ts"],"names":[],"mappings":"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"}

package/dist/tools/set-ruleset-config.d.ts

@@ -0,0 +1,4 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { SessionState } from '../types.js';
+export declare function registerSetRulesetConfigTool(server: McpServer, sessionState: SessionState): void;
+//# sourceMappingURL=set-ruleset-config.d.ts.map

package/dist/tools/set-ruleset-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"set-ruleset-config.d.ts","sourceRoot":"","sources":["../../src/tools/set-ruleset-config.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AASzE,OAAO,KAAK,EAAE,YAAY,EAA6B,MAAM,aAAa,CAAC;AAE3E,wBAAgB,4BAA4B,CAAC,MAAM,EAAE,SAAS,EAAE,YAAY,EAAE,YAAY,GAAG,IAAI,CAwHhG"}

package/dist/tools/set-ruleset-config.js

@@ -0,0 +1,94 @@
+import { z } from 'zod';
+import { mcpError, ERROR_CODES } from '../utils/errors.js';
+import { saveWorkspaceConfig, saveGlobalConfig, getWorkspaceConfigPath, getGlobalConfigPath, ConfigWriteError, } from '../config/ruleset-config.js';
+export function registerSetRulesetConfigTool(server, sessionState) {
+    server.tool('set-ruleset-config', 'Set the default Spectral ruleset used by this MCP server when no rulesetPath is supplied on a grading request. Supports three scopes: session (in-memory, resets on server restart), workspace (persisted to .api-grade/config.json in the workspace root), and global (persisted to ~/.api-grade/config.json). Optionally configure authentication for rulesets hosted in secured locations.', {
+        scope: z
+            .enum(['session', 'workspace', 'global'])
+            .describe("Where to store this default: 'session' is in-memory for this server process only; 'workspace' persists to .api-grade/config.json in the current workspace root; 'global' persists to ~/.api-grade/config.json."),
+        rulesetPath: z
+            .string()
+            .nullish()
+            .describe('Absolute or relative file path, or HTTPS URL, to a Spectral-compatible ruleset file. To clear the default at this scope, omit this field or pass null.'),
+        auth: z
+            .object({
+            type: z.enum(['github-pat', 'entra-id']).describe("'github-pat' uses a Bearer token for GitHub Enterprise URLs. 'entra-id' uses Microsoft Entra ID OAuth 2.0 device-code flow."),
+            githubToken: z
+                .string()
+                .optional()
+                .describe("GitHub Personal Access Token. Only used when type is 'github-pat'. If omitted, falls back to GITHUB_TOKEN environment variable."),
+            tenantId: z
+                .string()
+                .optional()
+                .describe("Microsoft Entra ID tenant ID. Required when type is 'entra-id'."),
+            clientId: z
+                .string()
+                .optional()
+                .describe("Microsoft Entra ID application (client) ID. Required when type is 'entra-id'."),
+        })
+            .optional(),
+    }, async ({ scope, rulesetPath, auth }) => {
+        const input = { scope, rulesetPath, auth };
+        if (auth?.type === 'entra-id' && (!auth.tenantId || !auth.clientId)) {
+            return mcpError(ERROR_CODES.INVALID_AUTH_CONFIG, "auth.type 'entra-id' requires tenantId and clientId fields.", input);
+        }
+        const resolvedPath = rulesetPath ?? null;
+        const resolvedAuth = auth
+            ? {
+                type: auth.type,
+                ...(auth.type === 'github-pat' && auth.githubToken ? { githubToken: auth.githubToken } : {}),
+                ...(auth.type === 'entra-id' ? { tenantId: auth.tenantId, clientId: auth.clientId } : {}),
+            }
+            : null;
+        const config = { rulesetPath: resolvedPath, auth: resolvedAuth };
+        if (scope === 'session') {
+            sessionState.defaultRuleset = resolvedPath !== null ? config : null;
+            if (resolvedPath !== null) {
+                sessionState.sessionRulesetOverride = null;
+            }
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            scope,
+                            rulesetPath: resolvedPath,
+                            auth: resolvedAuth ? { type: resolvedAuth.type } : null,
+                            message: resolvedPath !== null
+                                ? 'Session default ruleset configured. This setting applies for the duration of this server process.'
+                                : 'Session default ruleset cleared.',
+                        }),
+                    },
+                ],
+            };
+        }
+        const configFile = scope === 'workspace' ? getWorkspaceConfigPath() : getGlobalConfigPath();
+        const saveFn = scope === 'workspace' ? saveWorkspaceConfig : saveGlobalConfig;
+        try {
+            await saveFn(config);
+        }
+        catch (err) {
+            if (err instanceof ConfigWriteError) {
+                return mcpError(ERROR_CODES.CONFIG_WRITE_ERROR, err.message, input);
+            }
+            return mcpError(ERROR_CODES.CONFIG_WRITE_ERROR, `Could not write ${scope} config: ${err instanceof Error ? err.message : String(err)}`, input);
+        }
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({
+                        scope,
+                        rulesetPath: resolvedPath,
+                        auth: resolvedAuth ? { type: resolvedAuth.type } : null,
+                        configFile,
+                        message: resolvedPath !== null
+                            ? `${scope.charAt(0).toUpperCase() + scope.slice(1)} default ruleset configured. This setting will apply to all grading requests in this ${scope} unless overridden by a higher-precedence default or a per-request rulesetPath.`
+                            : `${scope.charAt(0).toUpperCase() + scope.slice(1)} default ruleset cleared.`,
+                    }),
+                },
+            ],
+        };
+    });
+}
+//# sourceMappingURL=set-ruleset-config.js.map

package/dist/tools/set-ruleset-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"set-ruleset-config.js","sourceRoot":"","sources":["../../src/tools/set-ruleset-config.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,27 @@
+export interface AuthConfig {
+    type: 'github-pat' | 'entra-id';
+    githubToken?: string;
+    tenantId?: string;
+    clientId?: string;
+}
+export interface RulesetConfig {
+    rulesetPath: string | null;
+    auth: AuthConfig | null;
+}
+export type RulesetScope = 'per-request' | 'session' | 'workspace' | 'global' | 'built-in';
+export interface RulesetResolution {
+    rulesetPath: string | null;
+    scope: RulesetScope;
+    auth: AuthConfig | null;
+}
+export interface SessionState {
+    defaultRuleset: RulesetConfig | null;
+    sessionRulesetOverride: 'builtin' | null;
+}
+export type RecoveryOptionId = 'retry' | 'use-builtin-once' | 'use-builtin-session' | 'cancel';
+export interface RecoveryOption {
+    id: RecoveryOptionId;
+    label: string;
+    description: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,YAAY,GAAG,UAAU,CAAC;IAChC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,aAAa;IAC5B,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,IAAI,EAAE,UAAU,GAAG,IAAI,CAAC;CACzB;AAED,MAAM,MAAM,YAAY,GAAG,aAAa,GAAG,SAAS,GAAG,WAAW,GAAG,QAAQ,GAAG,UAAU,CAAC;AAE3F,MAAM,WAAW,iBAAiB;IAChC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,KAAK,EAAE,YAAY,CAAC;IACpB,IAAI,EAAE,UAAU,GAAG,IAAI,CAAC;CACzB;AAED,MAAM,WAAW,YAAY;IAC3B,cAAc,EAAE,aAAa,GAAG,IAAI,CAAC;IACrC,sBAAsB,EAAE,SAAS,GAAG,IAAI,CAAC;CAC1C;AAED,MAAM,MAAM,gBAAgB,GAAG,OAAO,GAAG,kBAAkB,GAAG,qBAAqB,GAAG,QAAQ,CAAC;AAE/F,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,gBAAgB,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;CACrB"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/dist/utils/classify.d.ts

@@ -0,0 +1,14 @@
+import type { Diagnostic } from '@dawmatt/api-grade-core';
+export type ViolationClass = 'nonBreaking' | 'breaking' | 'unknown';
+export declare function classifyViolation(diagnostic: Diagnostic): ViolationClass;
+export interface QuickFix {
+    ruleId: string;
+    message: string;
+    severity: string;
+    path: string[];
+    location: string;
+    currentValue: string | null;
+    expectedImprovement: string;
+}
+export declare function buildQuickFix(diagnostic: Diagnostic, specContent: string): QuickFix;
+//# sourceMappingURL=classify.d.ts.map

package/dist/utils/classify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"classify.d.ts","sourceRoot":"","sources":["../../src/utils/classify.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAE1D,MAAM,MAAM,cAAc,GAAG,aAAa,GAAG,UAAU,GAAG,SAAS,CAAC;AAgDpE,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,UAAU,GAAG,cAAc,CAWxE;AASD,MAAM,WAAW,QAAQ;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,mBAAmB,EAAE,MAAM,CAAC;CAC7B;AAED,wBAAgB,aAAa,CAC3B,UAAU,EAAE,UAAU,EACtB,WAAW,EAAE,MAAM,GAClB,QAAQ,CAsCV"}

package/dist/utils/classify.js

@@ -0,0 +1,123 @@
+const RULE_ID_NON_BREAKING_PREFIXES = [
+    'operation-description',
+    'operation-summary',
+    'info-contact',
+    'info-description',
+    'info-license',
+    'oas3-examples-',
+    'tag-description',
+];
+const NON_BREAKING_SEGMENTS = new Set([
+    'description',
+    'summary',
+    'title',
+    'contact',
+    'license',
+    'termsOfService',
+    'externalDocs',
+    'example',
+    'examples',
+    'tags',
+    'info',
+]);
+const BREAKING_SEGMENTS = new Set([
+    'required',
+    'type',
+    'format',
+]);
+function isNonBreakingPath(path) {
+    for (const segment of path) {
+        if (segment.startsWith('x-'))
+            return true;
+        if (NON_BREAKING_SEGMENTS.has(segment))
+            return true;
+    }
+    return false;
+}
+function isBreakingPath(path) {
+    for (const segment of path) {
+        if (BREAKING_SEGMENTS.has(segment))
+            return true;
+        if (segment === 'parameters')
+            return true;
+    }
+    return false;
+}
+export function classifyViolation(diagnostic) {
+    // Rule ID overrides take priority
+    for (const prefix of RULE_ID_NON_BREAKING_PREFIXES) {
+        if (diagnostic.ruleId.startsWith(prefix))
+            return 'nonBreaking';
+    }
+    const path = diagnostic.path ?? [];
+    if (isBreakingPath(path))
+        return 'breaking';
+    if (isNonBreakingPath(path))
+        return 'nonBreaking';
+    return 'unknown';
+}
+const SEVERITY_LABELS = {
+    0: 'error',
+    1: 'warn',
+    2: 'info',
+    3: 'hint',
+};
+export function buildQuickFix(diagnostic, specContent) {
+    const path = (diagnostic.path ?? []);
+    const location = path.join('.');
+    let currentValue = null;
+    try {
+        if (path.length > 0) {
+            const parsed = JSON.parse(specContent);
+            let node = parsed;
+            for (const segment of path) {
+                if (node === null || typeof node !== 'object') {
+                    node = undefined;
+                    break;
+                }
+                node = node[segment];
+            }
+            if (node !== undefined && node !== null) {
+                currentValue = typeof node === 'string' ? node : JSON.stringify(node);
+            }
+        }
+    }
+    catch {
+        // JSON parse failed (e.g. YAML spec) — leave currentValue as null
+    }
+    const lastSegment = path[path.length - 1] ?? 'field';
+    const expectedImprovement = deriveExpectedImprovement(diagnostic.ruleId, diagnostic.message, lastSegment, path);
+    const severityNum = typeof diagnostic.severity === 'number' ? diagnostic.severity : 1;
+    return {
+        ruleId: diagnostic.ruleId,
+        message: diagnostic.message,
+        severity: SEVERITY_LABELS[severityNum] ?? 'warn',
+        path,
+        location,
+        currentValue,
+        expectedImprovement,
+    };
+}
+function deriveExpectedImprovement(ruleId, message, lastSegment, path) {
+    if (ruleId.includes('description')) {
+        const entity = path.length > 1 ? path[path.length - 2] : 'item';
+        return `Add a \`description\` field that explains the purpose of this ${entity}`;
+    }
+    if (ruleId.includes('summary')) {
+        return `Add a \`summary\` field with a brief one-line description`;
+    }
+    if (ruleId.includes('contact')) {
+        return `Add a \`contact\` object to the info block with name, email, or url`;
+    }
+    if (ruleId.includes('license')) {
+        return `Add a \`license\` object to the info block with name and url`;
+    }
+    if (ruleId.includes('example')) {
+        return `Add an \`example\` or \`examples\` field illustrating expected values`;
+    }
+    if (ruleId.includes('tag-description')) {
+        return `Add a \`description\` field to this tag explaining its purpose`;
+    }
+    return `Fix: ${message}. Add or update \`${lastSegment}\` as required`;
+}
+//# sourceMappingURL=classify.js.map

package/dist/utils/classify.js.map

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