@codapult/guard 0.2.0 → 0.3.0

package/dist/core/verification/verify.js

@@ -1,8 +1,8 @@
 import { runProjectAdapters, runProjectChecks, runWorkspaceProjectChecks, inspectProjectRuntime, } from '../../adapters/project-checks.js';
 import { loadBaseline, loadGuardAgentConfig, loadGuardConfig, scanGuard, classifyGuardOutcome, validateGuardContracts, } from '../guard.js';
+import { analyzeProjectImpact } from '../analysis/impact.js';
 import { discoverProject } from '../discovery/discovery.js';
 export function runGuardVerification(root, options = {}) {
-    const config = loadGuardConfig(root);
     const requirement = {
         status: 'delegated-to-review',
         provided: Boolean(options.requirement?.trim()),
@@ -11,10 +11,31 @@ export function runGuardVerification(root, options = {}) {
             : 'Requirement satisfaction is evaluated by guard review using the task and diff.',
     };
     const runtime = inspectProjectRuntime(root);
+    let config;
+    try {
+        config = loadGuardConfig(root);
+    }
+    catch (error) {
+        return {
+            status: 'fail',
+            outcome: 'fail',
+            errorCode: 'GUARD_CONFIG_INVALID',
+            recoverable: true,
+            checks: {},
+            workspaceChecks: {},
+            adapters: {},
+            runtime,
+            configError: error instanceof Error ? error.message : String(error),
+            contractIssues: [],
+            requirement,
+        };
+    }
     if (!config)
         return {
             status: 'not-configured',
             outcome: 'not-configured',
+            errorCode: 'GUARD_NOT_CONFIGURED',
+            recoverable: true,
             checks: {},
             workspaceChecks: {},
             adapters: {},
@@ -27,6 +48,9 @@ export function runGuardVerification(root, options = {}) {
     const checks = projectChecks ? (options.checks ?? agentConfig.completionGate.checks) : [];
     const results = runProjectChecks(root, checks, { timeout: options.timeout });
     const workspaceModel = discoverProject(root);
+    const impact = analyzeProjectImpact(workspaceModel, options.changedOnly === false
+        ? workspaceModel.modules.map((module) => module.path)
+        : workspaceModel.git.changedFiles, config.contracts ?? []);
     const workspaceChecks = runWorkspaceProjectChecks(root, workspaceModel.project.workspacePackages ?? [], checks, {
         timeout: options.timeout,
         rootResults: results,
@@ -71,6 +95,7 @@ export function runGuardVerification(root, options = {}) {
         adapters,
         runtime,
         architecture,
+        impact,
         contractIssues,
         requirement,
     };

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 /** Public, framework-agnostic Guard API. */
 export * from './core/guard.js';
+export * from './core/errors.js';
 export * from './core/discovery/discovery.js';
 export { runGuardVerification } from './core/verification/verify.js';
 export type { GuardVerificationCheck, GuardVerificationResult, } from './core/verification/verify.js';

package/dist/index.js

@@ -1,5 +1,6 @@
 /** Public, framework-agnostic Guard API. */
 export * from './core/guard.js';
+export * from './core/errors.js';
 export * from './core/discovery/discovery.js';
 export { runGuardVerification } from './core/verification/verify.js';
 export * from './core/history/history.js';

package/dist/mcp/tools/guard.js

@@ -1,4 +1,5 @@
-import { buildArchitectureMemory, buildConventionsMemory, buildGeneratedGuardConfig, buildGuardProposals, buildGuardReviewPacket, discoverProject, discoverProjectWithMetrics, findGuardRoot, GUARD_ARCHITECTURE_FILE, GUARD_CONVENTIONS_FILE, loadBaseline, loadGuardArtifact, loadGuardConfig, loadGuardAgentConfig, loadGuardProposals, getGuardProposalFreshness, loadProjectModel, writeGuardProposals, initializeGuard, GuardAlreadyInitializedError, recordGuardProposalDecision, writeGuardConfig, scanGuard, validateGuardContracts, classifyGuardOutcome, } from '../../core/guard.js';
+import { buildArchitectureMemory, buildConventionsMemory, buildGeneratedGuardConfig, buildGuardProposals, buildGuardReviewPacket, discoverProject, discoverProjectWithMetrics, fingerprintProjectModel, findGuardRoot, GUARD_ARCHITECTURE_FILE, GUARD_CONVENTIONS_FILE, loadBaseline, loadGuardArtifact, loadGuardConfig, loadGuardAgentConfig, loadGuardProposals, getPendingGuardProposals, getGuardProposalFreshness, loadProjectModel, writeGuardProposals, initializeGuard, GuardAlreadyInitializedError, recordGuardProposalDecision, writeGuardConfig, writeGuardMemory, writeProjectModel, writeProjectSnapshot, scanGuard, validateGuardContracts, classifyGuardOutcome, } from '../../core/guard.js';
+import { guardErrorPayload } from '../../core/errors.js';
 import { analyzeProjectImpact } from '../../core/analysis/impact.js';
 import { z } from 'zod';
 import { runGuardVerification } from '../../core/verification/verify.js';
@@ -12,7 +13,135 @@ function jsonToolResult(value, isError = false) {
         ...(isError ? { isError: true } : {}),
     };
 }
+function notConfiguredToolResult() {
+    return jsonToolResult({
+        status: 'error',
+        outcome: 'not-configured',
+        configured: false,
+        errorCode: 'GUARD_NOT_CONFIGURED',
+        message: 'Guard is not initialized.',
+        recoverable: true,
+    }, true);
+}
+function loadConfigSafely(root) {
+    try {
+        return { config: loadGuardConfig(root) };
+    }
+    catch (error) {
+        return {
+            error: jsonToolResult(guardErrorPayload('GUARD_CONFIG_INVALID', error instanceof Error ? error.message : String(error), {
+                configured: false,
+                outcome: 'error',
+                recoverable: true,
+                hint: 'Repair the invalid Guard artifact, then run codapult-guard doctor.',
+            }), true),
+        };
+    }
+}
 export function registerGuardTools(server) {
+    server.registerTool('codapult_guard_analyze', {
+        title: 'Refresh Guard Model',
+        description: 'Refresh persisted project facts and snapshots without changing rules, contracts, or baseline.',
+        inputSchema: {
+            root: rootSchema,
+            confirm: z
+                .boolean()
+                .default(false)
+                .describe('Required before writing refreshed Guard state.'),
+        },
+    }, ({ root: requestedRoot, confirm }) => {
+        const root = getGuardRoot(requestedRoot);
+        if (!confirm)
+            return jsonToolResult({ status: 'needs-confirmation', action: 'analyze' });
+        const discovery = discoverProjectWithMetrics(root, { persistCache: true });
+        writeProjectModel(root, discovery.model);
+        writeGuardMemory(root, discovery.model);
+        const revision = writeProjectSnapshot(root, discovery.model);
+        return jsonToolResult({
+            status: 'ok',
+            action: 'analyze',
+            revision,
+            discovery: discovery.metrics,
+        });
+    });
+    server.registerTool('codapult_guard_next_action', {
+        title: 'Guard Next Action',
+        description: 'Return the next bounded action for an AI coding-agent loop without modifying project files.',
+        inputSchema: { root: rootSchema },
+    }, ({ root: requestedRoot }) => {
+        const root = getGuardRoot(requestedRoot);
+        const loaded = loadConfigSafely(root);
+        if (loaded.error)
+            return loaded.error;
+        const config = loaded.config;
+        if (!config) {
+            return jsonToolResult({
+                status: 'needs-setup',
+                action: 'init',
+                reason: 'Guard policy is not initialized.',
+            });
+        }
+        const project = discoverProject(root);
+        const persisted = loadProjectModel(root);
+        if (persisted &&
+            'project' in persisted &&
+            fingerprintProjectModel(persisted) !== fingerprintProjectModel(project)) {
+            return jsonToolResult({
+                status: 'needs-refresh',
+                action: 'analyze',
+                reason: 'Persisted Guard project facts are stale after repository changes.',
+                canRetry: false,
+            });
+        }
+        const proposals = loadGuardProposals(root);
+        const proposedCount = getPendingGuardProposals(proposals).length;
+        if (proposals && getGuardProposalFreshness(project, proposals) === 'stale') {
+            return jsonToolResult({
+                status: 'needs-decision',
+                action: 'propose',
+                reason: 'Guard proposals are stale after project changes.',
+                canRetry: false,
+            });
+        }
+        if (proposedCount > 0) {
+            return jsonToolResult({
+                status: 'needs-decision',
+                action: 'policy-review',
+                reason: `${proposedCount} proposed policy item(s) await explicit approval or rejection.`,
+                canRetry: false,
+            });
+        }
+        const report = scanGuard(root, config, {
+            changedOnly: true,
+            baseline: loadBaseline(root),
+            includeArchitectureInsights: true,
+        });
+        const contractIssues = validateGuardContracts(root, config.contracts ?? []);
+        if (report.findings.some((finding) => finding.severity === 'error')) {
+            return jsonToolResult({
+                status: 'needs-repair',
+                action: 'repair',
+                reason: 'Active architecture findings remain in changed files.',
+                findings: report.findings,
+                canRetry: true,
+            });
+        }
+        if (contractIssues.length > 0) {
+            return jsonToolResult({
+                status: 'needs-decision',
+                action: 'policy-repair',
+                reason: 'Guard contracts are stale or invalid.',
+                contractIssues,
+                canRetry: false,
+            });
+        }
+        return jsonToolResult({
+            status: 'ready-for-verification',
+            action: 'verify',
+            reason: 'No changed-file architecture regressions remain.',
+            canRetry: true,
+        });
+    });
     server.registerTool('codapult_guard_context', {
         title: 'Guard Context',
         description: 'Read the discovered project model, architecture insights, and local rules used by Codapult Guard. Works before init by discovering the project on demand.',
@@ -25,7 +154,10 @@ export function registerGuardTools(server) {
         },
     }, ({ root: requestedRoot, refresh }) => {
         const root = getGuardRoot(requestedRoot);
-        const config = loadGuardConfig(root);
+        const loaded = loadConfigSafely(root);
+        if (loaded.error)
+            return loaded.error;
+        const config = loaded.config;
         const agentConfig = loadGuardAgentConfig(root);
         const discovery = refresh
             ? discoverProjectWithMetrics(root, { persistCache: true })
@@ -73,7 +205,10 @@ export function registerGuardTools(server) {
         if (persist && !confirm)
             return jsonToolResult({ status: 'needs-confirmation', persist: true });
         const project = discoverProject(root);
-        const config = loadGuardConfig(root) ?? buildGeneratedGuardConfig(project);
+        const loaded = loadConfigSafely(root);
+        if (loaded.error)
+            return loaded.error;
+        const config = loaded.config ?? buildGeneratedGuardConfig(project);
         const proposals = buildGuardProposals(project, config);
         const previous = loadGuardProposals(root);
         if (persist) {
@@ -147,7 +282,10 @@ export function registerGuardTools(server) {
         if (!confirm)
             return jsonToolResult({ status: 'needs-confirmation', decision, ids });
         if (decision === 'approved') {
-            const config = loadGuardConfig(root) ?? { version: 1, rules: [], contracts: [] };
+            const loaded = loadConfigSafely(root);
+            if (loaded.error)
+                return loaded.error;
+            const config = loaded.config ?? { version: 1, rules: [], contracts: [] };
             const nextRules = [...config.rules];
             const nextContracts = [...(config.contracts ?? [])];
             for (const item of selected) {
@@ -225,17 +363,12 @@ export function registerGuardTools(server) {
         inputSchema: { root: rootSchema },
     }, ({ root: requestedRoot }) => {
         const root = getGuardRoot(requestedRoot);
-        const config = loadGuardConfig(root);
+        const loaded = loadConfigSafely(root);
+        if (loaded.error)
+            return loaded.error;
+        const config = loaded.config;
         if (!config) {
-            return {
-                content: [
-                    {
-                        type: 'text',
-                        text: JSON.stringify({ configured: false, outcome: 'not-configured' }, null, 2),
-                    },
-                ],
-                isError: true,
-            };
+            return notConfiguredToolResult();
         }
         const report = scanGuard(root, config, { includeArchitectureInsights: true });
         const contractIssues = validateGuardContracts(root, config.contracts ?? []);
@@ -271,17 +404,12 @@ export function registerGuardTools(server) {
         },
     }, ({ root: requestedRoot, changed_only, max_diff_chars, requirement, base }) => {
         const root = getGuardRoot(requestedRoot);
-        const config = loadGuardConfig(root);
+        const loaded = loadConfigSafely(root);
+        if (loaded.error)
+            return loaded.error;
+        const config = loaded.config;
         if (!config) {
-            return {
-                content: [
-                    {
-                        type: 'text',
-                        text: JSON.stringify({ configured: false, outcome: 'not-configured' }, null, 2),
-                    },
-                ],
-                isError: true,
-            };
+            return notConfiguredToolResult();
         }
         const packet = buildGuardReviewPacket(root, config, changed_only ? loadBaseline(root) : new Set(), max_diff_chars, changed_only, requirement, base);
         return jsonToolResult({ ...packet, status: packet.diffError ? 'fail' : 'needs-review' }, Boolean(packet.diffError));
@@ -292,17 +420,12 @@ export function registerGuardTools(server) {
         inputSchema: { root: rootSchema, changed_only: z.boolean().optional() },
     }, ({ root: requestedRoot, changed_only }) => {
         const root = getGuardRoot(requestedRoot);
-        const config = loadGuardConfig(root);
+        const loaded = loadConfigSafely(root);
+        if (loaded.error)
+            return loaded.error;
+        const config = loaded.config;
         if (!config) {
-            return {
-                content: [
-                    {
-                        type: 'text',
-                        text: JSON.stringify({ configured: false, outcome: 'not-configured' }, null, 2),
-                    },
-                ],
-                isError: true,
-            };
+            return notConfiguredToolResult();
         }
         const report = scanGuard(root, config, {
             changedOnly: changed_only,
@@ -331,7 +454,10 @@ export function registerGuardTools(server) {
     }, ({ root: requestedRoot, files }) => {
         const root = getGuardRoot(requestedRoot);
         const model = discoverProject(root);
-        const impact = analyzeProjectImpact(model, files, loadGuardConfig(root)?.contracts ?? []);
+        const loaded = loadConfigSafely(root);
+        if (loaded.error)
+            return loaded.error;
+        const impact = analyzeProjectImpact(model, files, loaded.config?.contracts ?? []);
         return jsonToolResult({
             status: 'ok',
             ...impact,
@@ -346,7 +472,10 @@ export function registerGuardTools(server) {
         },
     }, ({ root: requestedRoot, id }) => {
         const root = getGuardRoot(requestedRoot);
-        const config = loadGuardConfig(root);
+        const loaded = loadConfigSafely(root);
+        if (loaded.error)
+            return loaded.error;
+        const config = loaded.config;
         const item = [...(config?.rules ?? []), ...(config?.contracts ?? [])].find((candidate) => candidate.id === id);
         if (!item)
             return jsonToolResult({ status: 'not-found', id }, true);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codapult/guard",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Local-first architecture guardrails for JavaScript and TypeScript projects, with first-class support for Next.js SaaS and AI-assisted development",
   "license": "MIT",
   "packageManager": "pnpm@12.4.2+sha512.08adc6613180275c7c9edada39dcf08c9c61ad4e7eaf330a4f3461f102b0f907423454d117f98e72d47fef0616070644d7bffc973a6a57f5090a6d7c368b07c9",
@@ -60,7 +60,12 @@
     "test:guard:fixtures": "pnpm build && node scripts/guard-fixture-smoke.mjs",
     "test:guard:fixtures:regression": "pnpm build && node scripts/guard-fixture-regression.mjs",
     "test:guard:fixtures:native": "pnpm build && node scripts/guard-fixture-native.mjs",
+    "test:guard:fixtures:adversarial": "pnpm build && node scripts/guard-fixture-adversarial.mjs",
+    "test:guard:fixtures:all": "pnpm build && node scripts/guard-fixture-suite.mjs",
+    "test:guard:fixtures:full": "pnpm build && node scripts/guard-fixture-suite.mjs --all",
+    "test:guard:concurrent": "pnpm build && node scripts/guard-concurrent-state.mjs",
     "test:guard:pr": "pnpm build && node scripts/guard-pr-review.mjs",
+    "test:guard:benchmark": "pnpm build && node scripts/guard-benchmark.mjs",
     "test:guard:golden": "pnpm build && node scripts/guard-golden-demo.mjs",
     "test:watch": "vitest",
     "typecheck": "tsc --noEmit",