@codapult/guard 0.1.0

package/dist/core/guard.d.ts

@@ -0,0 +1,189 @@
+import type { ProjectModel } from './discovery/discovery.js';
+import { discoverProject, discoverProjectWithMetrics, findGuardRoot } from './discovery/discovery.js';
+export type GuardSeverity = 'error' | 'warning' | 'info';
+export type GuardOutcomeStatus = 'pass' | 'fail' | 'warning' | 'needs-review' | 'not-configured';
+export declare function classifyGuardOutcome(input: {
+    configured?: boolean;
+    errors?: number;
+    warnings?: number;
+    needsReview?: boolean;
+}): GuardOutcomeStatus;
+export type GuardRuleKind = 'forbidden-import' | 'client-forbidden-import';
+export type GuardRuleStatus = 'active' | 'proposed';
+export type GuardContractKind = 'guidance' | 'import-boundary' | 'required-call';
+export interface GuardContract {
+    id: string;
+    statement: string;
+    kind?: GuardContractKind;
+    severity?: GuardSeverity;
+    scope?: string[];
+    entrypoints?: string[];
+    exclude?: string[];
+    guidance?: string[];
+    references?: string[];
+    mustImport?: string[];
+    mustNotImport?: string[];
+    mustCall?: string[];
+    status?: GuardRuleStatus;
+    confidence?: 'high' | 'medium' | 'low';
+    evidence?: string[];
+}
+export interface GuardRule {
+    id: string;
+    description: string;
+    severity: GuardSeverity;
+    kind: GuardRuleKind;
+    patterns: string[];
+    files?: string[];
+    status?: GuardRuleStatus;
+    confidence?: 'high' | 'medium' | 'low';
+    evidence?: string[];
+}
+export interface GuardConfig {
+    version: 1;
+    rules: GuardRule[];
+    contracts?: GuardContract[];
+}
+export interface GuardProposalFile {
+    version: 1;
+    generatedAt: string;
+    proposalId?: string;
+    projectFingerprint?: string;
+    revision?: number;
+    contentFingerprint?: string;
+    rules: GuardRule[];
+    contracts: GuardContract[];
+    questions: string[];
+    decisions?: GuardProposalDecision[];
+}
+export interface GuardProposalDecision {
+    id: string;
+    type: 'rule' | 'contract';
+    decision: 'approved' | 'rejected';
+    decidedAt: string;
+    proposalId?: string;
+    proposalFingerprint?: string;
+    revision?: number;
+}
+export type GuardProposalFreshness = 'current' | 'stale' | 'unknown';
+export interface GuardAgentConfig {
+    version: 1;
+    tools: GuardToolMode;
+    tooling: Partial<Record<GuardAdapterName, {
+        script: string;
+        enabled: boolean;
+    }>>;
+    completionGate: {
+        enabled: boolean;
+        maxIterations: number;
+        projectChecks: boolean;
+        checks: ('lint' | 'typecheck' | 'test' | 'build')[];
+    };
+}
+export type GuardToolMode = 'auto' | 'on' | 'off';
+export type GuardAdapterName = 'dependency-graph' | 'security' | 'dependency-hygiene';
+export interface GuardFinding {
+    ruleId: string;
+    severity: GuardSeverity;
+    file: string;
+    line: number;
+    importPath: string;
+    message: string;
+    fingerprint: string;
+}
+export interface GuardContractIssue {
+    contractId: string;
+    field: 'scope' | 'reference' | 'definition';
+    value: string;
+    message: string;
+}
+export interface GuardReport {
+    configured: boolean;
+    findings: GuardFinding[];
+    suppressed: number;
+    scannedFiles: number;
+}
+interface ScanGuardOptions {
+    changedOnly?: boolean;
+    changedFiles?: Set<string>;
+    baseline?: Set<string>;
+    includeArchitectureInsights?: boolean;
+}
+export interface GuardReviewPacket {
+    version: 1;
+    outcome: GuardOutcomeStatus;
+    diffBase?: string;
+    changedFiles: string[];
+    diff: string;
+    truncated: boolean;
+    redacted: boolean;
+    diffError?: string;
+    project: ProjectModel;
+    contracts: GuardContract[];
+    requirement?: string;
+    deterministicFindings: GuardFinding[];
+    reviewInstructions: string[];
+}
+export declare const GUARD_DIR: string;
+export declare const GUARD_RULES_FILE: string;
+export declare const GUARD_BASELINE_FILE: string;
+export declare const GUARD_BASELINE_META_FILE: string;
+export declare const GUARD_PROJECT_FILE: string;
+export declare const GUARD_HISTORY_DIR: string;
+export declare const GUARD_ARCHITECTURE_FILE: string;
+export declare const GUARD_CONVENTIONS_FILE: string;
+export declare const GUARD_AGENT_FILE: string;
+export declare const GUARD_CONTRACTS_FILE: string;
+export declare const GUARD_PROPOSALS_FILE: string;
+export declare const defaultGuardConfig: GuardConfig;
+export declare const defaultGuardAgentConfig: GuardAgentConfig;
+export declare class GuardAlreadyInitializedError extends Error {
+    constructor();
+}
+export declare function isGuardContractsFile(value: unknown): value is {
+    version: 1;
+    contracts: GuardContract[];
+};
+export declare function isGuardProposalFile(value: unknown): value is GuardProposalFile;
+export declare function fingerprintProjectModel(model: ProjectModel): string;
+export declare function getGuardProposalFreshness(model: ProjectModel, proposals: GuardProposalFile | undefined): GuardProposalFreshness;
+export declare function loadGuardConfig(root: string): GuardConfig | undefined;
+export declare function loadGuardProposals(root: string): GuardProposalFile | undefined;
+export declare function isGuardAgentConfig(value: unknown): value is GuardAgentConfig;
+export declare function loadGuardAgentConfig(root: string): GuardAgentConfig;
+export declare function writeGuardAgentConfig(root: string, agentConfig?: GuardAgentConfig): void;
+export declare function loadGuardArtifact(root: string, relativePath: string): unknown;
+export declare function loadBaseline(root: string): Set<string>;
+export declare function updateBaseline(root: string, options?: {
+    add?: string[];
+    remove?: string[];
+    reason?: string;
+}): Set<string>;
+export declare function writeGuardConfig(root: string, guardConfig: GuardConfig): void;
+export declare function writeGuardProposals(root: string, proposals: GuardProposalFile): void;
+export declare function recordGuardProposalDecision(root: string, decisions: Pick<GuardProposalDecision, 'id' | 'type' | 'decision'>[]): void;
+export declare function buildGuardProposals(model: ProjectModel, guardConfig: GuardConfig): GuardProposalFile;
+export declare function buildArchitectureMemory(model: ProjectModel): Record<string, unknown>;
+export declare function buildConventionsMemory(model: ProjectModel): Record<string, unknown>;
+export declare function buildGeneratedGuardConfig(model: ProjectModel): GuardConfig;
+export declare function writeGuardMemory(root: string, model: ProjectModel): void;
+export declare function writeBaseline(root: string, findings: GuardFinding[], model?: ProjectModel): void;
+export declare function loadProjectModel(root: string): ProjectModel | undefined;
+export declare function writeProjectModel(root: string, model: ProjectModel): void;
+export declare function writeProjectSnapshot(root: string, model: ProjectModel): string;
+export declare function validateGuardContracts(root: string, contracts?: GuardContract[]): GuardContractIssue[];
+/** @internal Redacts common credential shapes before a diff enters an AI review packet. */
+export declare function redactSensitiveText(value: string): {
+    value: string;
+    redacted: boolean;
+    redactionCount: number;
+};
+export declare function scanGuard(root: string, guardConfig: GuardConfig, options?: ScanGuardOptions): GuardReport;
+export declare function buildGuardReviewPacket(root: string, guardConfig: GuardConfig, baseline?: Set<string>, maxDiffChars?: number, changedOnly?: boolean, requirement?: string, base?: string): GuardReviewPacket;
+export declare function initializeGuard(root: string, options?: {
+    force?: boolean;
+}): {
+    config: GuardConfig;
+    report: GuardReport;
+};
+export { discoverProject, discoverProjectWithMetrics, findGuardRoot };