@codapult/guard 0.1.0 → 0.3.0

package/dist/core/policy/schemas.js

@@ -2,29 +2,31 @@ import { z } from 'zod';
 const severity = z.enum(['error', 'warning', 'info']);
 const status = z.enum(['active', 'proposed']);
 export const guardRuleSchema = z.object({
-    id: z.string(),
-    description: z.string(),
+    id: z.string().trim().min(1),
+    description: z.string().trim().min(1),
     severity,
     kind: z.enum(['forbidden-import', 'client-forbidden-import']),
-    patterns: z.array(z.string()),
-    files: z.array(z.string()).optional(),
+    patterns: z.array(z.string().trim().min(1)).min(1),
+    files: z.array(z.string().trim().min(1)).optional(),
     status: status.optional(),
     confidence: z.enum(['high', 'medium', 'low']).optional(),
     evidence: z.array(z.string()).optional(),
 });
 export const guardContractSchema = z.object({
-    id: z.string(),
-    statement: z.string(),
-    kind: z.enum(['guidance', 'import-boundary', 'required-call']).optional(),
+    id: z.string().trim().min(1),
+    statement: z.string().trim().min(1),
+    kind: z.enum(['guidance', 'import-boundary', 'required-call', 'package-boundary']).optional(),
     severity: severity.optional(),
-    scope: z.array(z.string()).optional(),
-    entrypoints: z.array(z.string()).optional(),
-    exclude: z.array(z.string()).optional(),
-    guidance: z.array(z.string()).optional(),
-    references: z.array(z.string()).optional(),
-    mustImport: z.array(z.string()).optional(),
-    mustNotImport: z.array(z.string()).optional(),
-    mustCall: z.array(z.string()).optional(),
+    scope: z.array(z.string().trim().min(1)).optional(),
+    entrypoints: z.array(z.string().trim().min(1)).optional(),
+    exclude: z.array(z.string().trim().min(1)).optional(),
+    guidance: z.array(z.string().trim().min(1)).optional(),
+    references: z.array(z.string().trim().min(1)).optional(),
+    mustImport: z.array(z.string().trim().min(1)).optional(),
+    mustNotImport: z.array(z.string().trim().min(1)).optional(),
+    mustCall: z.array(z.string().trim().min(1)).optional(),
+    fromPackages: z.array(z.string().trim().min(1)).optional(),
+    mustNotImportPackages: z.array(z.string().trim().min(1)).optional(),
     status: status.optional(),
     confidence: z.enum(['high', 'medium', 'low']).optional(),
     evidence: z.array(z.string()).optional(),
@@ -39,7 +41,7 @@ export const guardContractsFileSchema = z.object({
     contracts: z.array(guardContractSchema),
 });
 export const guardProposalDecisionSchema = z.object({
-    id: z.string(),
+    id: z.string().trim().min(1),
     type: z.enum(['rule', 'contract']),
     decision: z.enum(['approved', 'rejected']),
     decidedAt: z.string(),
@@ -62,7 +64,9 @@ export const guardProposalSchema = z.object({
 export const guardAgentConfigSchema = z.object({
     version: z.literal(1),
     tools: z.enum(['auto', 'on', 'off']),
-    tooling: z.record(z.string(), z.object({ script: z.string(), enabled: z.boolean() })).default({}),
+    tooling: z
+        .record(z.string().trim().min(1), z.object({ script: z.string().trim().min(1), enabled: z.boolean() }))
+        .default({}),
     completionGate: z.object({
         enabled: z.boolean(),
         maxIterations: z.number().int().min(1).max(10),

package/dist/core/verification/verify.d.ts

@@ -1,16 +1,21 @@
 import { type CommandResult } from '../../adapters/command.js';
 import { type GuardAdapter, type ProjectCheck, type ProjectCheckResults, type ProjectRuntimeDiagnostics } from '../../adapters/project-checks.js';
 import { type GuardToolMode, type GuardContractIssue, type GuardReport } from '../guard.js';
+import { type GuardImpactAnalysis } from '../analysis/impact.js';
 export type GuardVerificationCheck = ProjectCheck;
 export interface GuardVerificationResult {
     status: 'ok' | 'fail' | 'not-configured';
     outcome: 'pass' | 'fail' | 'warning' | 'needs-review' | 'not-configured';
+    errorCode?: 'GUARD_NOT_CONFIGURED' | 'GUARD_CONFIG_INVALID';
+    recoverable?: boolean;
     tools?: GuardToolMode;
     checks: ProjectCheckResults;
     workspaceChecks: Record<string, ProjectCheckResults>;
     adapters: Partial<Record<GuardAdapter, CommandResult>>;
     runtime: ProjectRuntimeDiagnostics;
+    configError?: string;
     architecture?: GuardReport;
+    impact?: GuardImpactAnalysis;
     contractIssues: GuardContractIssue[];
     requirement: {
         status: 'delegated-to-review';

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';
@@ -7,4 +8,5 @@ export * from './core/history/history.js';
 export * from './core/output/sarif.js';
 export * from './core/analysis/doctor.js';
 export * from './core/analysis/packs.js';
+export * from './core/analysis/impact.js';
 export * from './adapters/project-checks.js';

package/dist/index.js

@@ -1,9 +1,11 @@
 /** 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';
 export * from './core/output/sarif.js';
 export * from './core/analysis/doctor.js';
 export * from './core/analysis/packs.js';
+export * from './core/analysis/impact.js';
 export * from './adapters/project-checks.js';

package/dist/mcp/tools/guard.js

@@ -1,4 +1,6 @@
-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';
 const rootSchema = z.string().trim().min(1).optional().describe('Project path or workspace root.');
@@ -11,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.',
@@ -24,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 })
@@ -72,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) {
@@ -146,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) {
@@ -224,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 ?? []);
@@ -270,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));
@@ -291,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,
@@ -330,20 +454,13 @@ export function registerGuardTools(server) {
     }, ({ root: requestedRoot, files }) => {
         const root = getGuardRoot(requestedRoot);
         const model = discoverProject(root);
-        const changed = new Set(files);
-        const paths = model.insights.impactPaths.filter((impact) => impact.files.some((file) => changed.has(file)) || changed.has(impact.entrypoint));
-        const modules = model.modules.filter((module) => changed.has(module.path) || module.resolvedImports.some((file) => changed.has(file)));
-        const capabilities = Object.entries(model.capabilities)
-            .filter(([, signal]) => signal.files.some((file) => changed.has(file)))
-            .map(([id]) => id);
-        const contracts = (loadGuardConfig(root)?.contracts ?? []).filter((contract) => [...(contract.scope ?? []), ...(contract.entrypoints ?? [])].some((scope) => [...changed].some((file) => file === scope || file.startsWith(`${scope}/`))));
+        const loaded = loadConfigSafely(root);
+        if (loaded.error)
+            return loaded.error;
+        const impact = analyzeProjectImpact(model, files, loaded.config?.contracts ?? []);
         return jsonToolResult({
             status: 'ok',
-            files,
-            affectedModules: modules.map((module) => module.path),
-            impactPaths: paths,
-            capabilities,
-            relevantContracts: contracts,
+            ...impact,
         });
     });
     server.registerTool('codapult_guard_explain', {
@@ -355,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,9 +1,9 @@
 {
   "name": "@codapult/guard",
-  "version": "0.1.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@11.22.0+sha512.1ff870c4c6133dfd88fb2afc46dd13d47f09c9794b438c6fdb47ca98caf3bc16381ee0be93a091b8e3824cf01f889f46d7d9e20910fb0be1ab0fb5baa80dd621",
+  "packageManager": "pnpm@12.4.2+sha512.08adc6613180275c7c9edada39dcf08c9c61ad4e7eaf330a4f3461f102b0f907423454d117f98e72d47fef0616070644d7bffc973a6a57f5090a6d7c368b07c9",
   "engines": {
     "node": ">=20.19.0"
   },
@@ -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",
@@ -95,23 +100,23 @@
     "semver": "^7.8.5",
     "ts-morph": "^28.0.0",
     "typescript": "npm:@typescript/typescript6@^6.0.2",
-    "zod": "^4.4.3"
+    "zod": "^4.6.5"
   },
   "devDependencies": {
     "@js-toolkit/config-utils": "^1.0.1",
-    "@js-toolkit/eslint-config": "^1.1.4",
+    "@js-toolkit/eslint-config": "^1.3.0",
     "@js-toolkit/prettier-config": "^1.0.1",
     "@js-toolkit/tsconfig": "^1.0.1",
-    "@release-it/conventional-changelog": "^12.0.0",
-    "@types/node": "^26.2.0",
+    "@release-it/conventional-changelog": "^12.0.2",
+    "@types/node": "^26.6.1",
     "@typescript/native": "npm:typescript@^7.0.2",
-    "@vitest/coverage-v8": "^4.1.11",
-    "eslint": "^9.39.4",
+    "@vitest/coverage-v8": "^5.0.1",
+    "eslint": "^10.10.0",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-prettier": "^5.5.6",
-    "prettier": "^3.9.6",
-    "release-it": "^21.0.2",
-    "typescript-eslint": "^8.67.0",
-    "vitest": "^4.1.11"
+    "prettier": "^3.9.7",
+    "release-it": "^21.0.3",
+    "typescript-eslint": "^8.70.0",
+    "vitest": "^5.0.1"
   }
 }