@valoir/rizz-brain 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,474 @@
+type Confidence = 'verified' | 'inferred' | 'uncertain';
+type BenchmarkTaskCategory = 'component-explanation' | 'flow-explanation' | 'architecture-impact' | 'review-blast-radius' | 'evidence-unknown-coverage';
+type ComponentBoundaryType = 'entrypoint' | 'orchestration' | 'service' | 'adapter' | 'interface' | 'automation' | 'knowledge' | 'quality' | 'source' | 'unknown';
+type EntityType = 'project' | 'file' | 'folder' | 'component' | 'service' | 'api' | 'database/table' | 'config' | 'dependency' | 'command' | 'test' | 'flow' | 'decision' | 'risk' | 'agent' | 'task' | 'session' | 'handoff' | 'review' | 'finding' | 'evidence' | 'status';
+interface BrainRelationship {
+    readonly from: string;
+    readonly relation: 'owns' | 'depends_on' | 'used_by' | 'calls' | 'imports' | 'exposes' | 'configures' | 'tests' | 'breaks_if_removed' | 'changed_by' | 'reviewed_by' | 'handed_off_to' | 'produced' | 'supersedes' | 'contradicts' | 'related_to';
+    readonly to: string;
+    readonly evidence_ids: readonly string[];
+    readonly confidence: Confidence;
+}
+type ArchitectureImpactSurfaceType = 'component' | 'route';
+interface ComponentIntelligence {
+    readonly purpose: string;
+    readonly boundary_type: ComponentBoundaryType;
+    readonly responsibilities: readonly string[];
+    readonly interfaces: readonly string[];
+    readonly entry_points: readonly string[];
+    readonly consumers: readonly string[];
+    readonly dependencies: readonly string[];
+    readonly dependency_roles: readonly string[];
+    readonly exposed_apis: readonly string[];
+    readonly tests: readonly string[];
+    readonly configs: readonly string[];
+    readonly coupling: {
+        readonly level: 'low' | 'medium' | 'high';
+        readonly score: number;
+        readonly static_import_count: number;
+        readonly internal_imports: readonly string[];
+        readonly external_imports: readonly string[];
+        readonly reasons: readonly string[];
+    };
+    readonly criticality: 'low' | 'medium' | 'high';
+    readonly criticality_score: number;
+    readonly blast_radius: BlastRadius;
+    readonly ownership_confidence: {
+        readonly score: number;
+        readonly reason: string;
+        readonly signals: readonly string[];
+    };
+    readonly tradeoffs: readonly string[];
+    readonly failure_modes: readonly string[];
+    readonly what_breaks_if_removed: readonly string[];
+    readonly risky_seams: readonly string[];
+    readonly important_files: readonly string[];
+    readonly read_first: readonly string[];
+    readonly known_risks: readonly string[];
+    readonly unknowns: readonly string[];
+    readonly field_evidence: Readonly<Record<string, readonly string[]>>;
+    readonly signals: readonly string[];
+}
+type FlowKind = 'api' | 'cli' | 'job' | 'ui' | 'config' | 'test' | 'unknown';
+type FlowEntrypointType = 'route' | 'command' | 'function' | 'script' | 'file' | 'config';
+type FlowStepType = 'route' | 'handler' | 'service' | 'function' | 'config' | 'dependency' | 'test' | 'external';
+type FlowRiskKind = 'missing_test' | 'missing_config' | 'weak_evidence' | 'orphan_step' | 'changed_hotspot';
+interface FlowEntrypoint {
+    readonly type: FlowEntrypointType;
+    readonly path: string;
+    readonly symbol: string | null;
+    readonly component_id?: string | null;
+    readonly evidence: readonly string[];
+}
+interface FlowStep {
+    readonly step_id: string;
+    readonly order: number;
+    readonly type: FlowStepType;
+    readonly path: string;
+    readonly symbol: string | null;
+    readonly description: string;
+    readonly evidence: readonly string[];
+}
+interface FlowRisk {
+    readonly risk_id: string;
+    readonly kind: FlowRiskKind;
+    readonly description: string;
+    readonly evidence: readonly string[];
+}
+type ReviewSeverity = 'low' | 'medium' | 'high' | 'critical';
+type ReviewCategory = 'Correctness' | 'Regression risk' | 'Architecture drift' | 'Hidden coupling' | 'Missing tests' | 'Security' | 'Performance' | 'Maintainability' | 'Backward compatibility' | 'Overengineering';
+type OverallRisk = 'low' | 'medium' | 'high' | 'critical';
+type BlastRadius = 'narrow' | 'moderate' | 'broad';
+type RecommendedAction = 'approve' | 'request changes' | 'investigate';
+interface ReviewEvalArtifactData {
+    readonly schema_version: number;
+    readonly generated_at: string;
+    readonly review_id: string;
+    readonly deterministic: boolean;
+    readonly provider_calls_required: boolean;
+    readonly network_required: boolean;
+    readonly total_findings: number;
+    readonly findings_by_severity: Record<ReviewSeverity, number>;
+    readonly findings_by_category: Record<ReviewCategory, number>;
+    readonly affected_component_count: number;
+    readonly direct_affected_component_count: number;
+    readonly dependent_component_count: number;
+    readonly affected_flow_count: number;
+    readonly affected_relationship_count: number;
+    readonly architecture_impact_surface_count: number;
+    readonly architecture_impact_component_surface_count: number;
+    readonly architecture_impact_route_surface_count: number;
+    readonly architecture_what_breaks_note_count: number;
+    readonly architecture_evidence_gap_count: number;
+    readonly architecture_confidence_gap_count: number;
+    readonly architecture_affected_test_count: number;
+    readonly architecture_affected_config_count: number;
+    readonly required_test_count: number;
+    readonly evidence_id_count: number;
+    readonly blast_radius: BlastRadius;
+    readonly overall_risk: OverallRisk;
+    readonly surgicality_score: number;
+    readonly review_readiness_score: number;
+    readonly secret_safety: {
+        readonly redaction_applied: boolean;
+        readonly redacted_reference_count: number;
+        readonly unsafe_sensitive_reference_count: number;
+        readonly output_secret_safe: boolean;
+    };
+    readonly redaction: {
+        readonly redacted_reference_count: number;
+        readonly unsafe_sensitive_reference_count: number;
+        readonly note: string;
+    };
+    readonly scoring_notes: readonly string[];
+}
+interface ReviewFindingData {
+    readonly id: string;
+    readonly severity: ReviewSeverity;
+    readonly category: ReviewCategory;
+    readonly title: string;
+    readonly description: string;
+    readonly affected_files: readonly string[];
+    readonly affected_entities: readonly string[];
+    readonly evidence_ids: readonly string[];
+    readonly confidence: Confidence;
+    readonly recommendation: string;
+    readonly safer_alternative?: string;
+}
+interface AffectedFlowData {
+    readonly id: string;
+    readonly name: string;
+    readonly kind: string;
+    readonly framework?: string;
+    readonly route_path?: string;
+    readonly route_type?: string;
+    readonly confidence: Confidence;
+    readonly score: number;
+    readonly entrypoints: readonly string[];
+    readonly changed_files: readonly string[];
+    readonly components: readonly string[];
+    readonly tests: readonly string[];
+    readonly configs: readonly string[];
+    readonly risks: number;
+    readonly evidence_ids: readonly string[];
+    readonly reasons: readonly string[];
+}
+interface ReviewAffectedComponentData {
+    readonly id: string;
+    readonly name: string;
+    readonly boundary_type: string;
+    readonly criticality: string;
+    readonly blast_radius: string;
+    readonly changed_files: readonly string[];
+    readonly affected_flows: readonly string[];
+    readonly tests: readonly string[];
+    readonly configs: readonly string[];
+    readonly evidence_ids: readonly string[];
+    readonly reason: string;
+}
+interface ReviewAffectedRelationshipData {
+    readonly from: string;
+    readonly relation: BrainRelationship['relation'];
+    readonly to: string;
+    readonly confidence: Confidence;
+    readonly evidence_ids: readonly string[];
+}
+interface ReviewEvidenceSummaryData {
+    readonly changed_files: number;
+    readonly direct_components: number;
+    readonly dependent_components: number;
+    readonly affected_flows: number;
+    readonly architecture_impact_surfaces: number;
+    readonly architecture_confidence_gaps: readonly string[];
+    readonly architecture_evidence_gap_ids: readonly string[];
+    readonly architecture_what_breaks: readonly string[];
+    readonly affected_tests: readonly string[];
+    readonly affected_configs: readonly string[];
+    readonly evidence_ids: readonly string[];
+}
+interface ReviewArchitectureImpactData {
+    readonly impact_id: string;
+    readonly surface_type: ArchitectureImpactSurfaceType;
+    readonly entity_id: string;
+    readonly name: string;
+    readonly route_path?: string;
+    readonly route_type?: string;
+    readonly matched_changed_files: readonly string[];
+    readonly matched_components: readonly string[];
+    readonly matched_flows: readonly string[];
+    readonly affected_flows: readonly string[];
+    readonly affected_files: readonly string[];
+    readonly affected_tests: readonly string[];
+    readonly affected_configs: readonly string[];
+    readonly dependent_components: readonly string[];
+    readonly coupling_level: ComponentIntelligence['coupling']['level'];
+    readonly coupling_score: number;
+    readonly confidence: Confidence;
+    readonly confidence_score: number;
+    readonly evidence_ids: readonly string[];
+    readonly evidence_gap_ids: readonly string[];
+    readonly what_breaks: readonly string[];
+    readonly reasons: readonly string[];
+}
+interface ReviewSummaryData {
+    readonly id: string;
+    readonly generated_at: string;
+    readonly changed_files: readonly string[];
+    readonly direct_affected_components: readonly ReviewAffectedComponentData[];
+    readonly dependent_components: readonly ReviewAffectedComponentData[];
+    readonly affected_components: readonly string[];
+    readonly affected_flows: readonly AffectedFlowData[];
+    readonly affected_relationships: readonly ReviewAffectedRelationshipData[];
+    readonly architecture_impact_map: readonly ReviewArchitectureImpactData[];
+    readonly affected_entities: readonly string[];
+    readonly blast_radius_reasons: readonly string[];
+    readonly review_evidence_summary: ReviewEvidenceSummaryData;
+    readonly findings: readonly ReviewFindingData[];
+    readonly overall_risk: OverallRisk;
+    readonly surgicality_score: number;
+    readonly blast_radius: BlastRadius;
+    readonly required_tests: readonly string[];
+    readonly suggested_reviewer_focus_areas: readonly string[];
+    readonly recommended_action: RecommendedAction;
+}
+interface ExplainSummaryData {
+    readonly generated_at: string;
+    readonly target: string;
+    readonly resolved_entity_id: string;
+    readonly entity_type: EntityType;
+    readonly summary: string;
+    readonly purpose: string;
+    readonly responsibilities: readonly string[];
+    readonly dependencies: readonly string[];
+    readonly dependency_roles: readonly string[];
+    readonly consumers: readonly string[];
+    readonly important_files: readonly string[];
+    readonly entry_points: readonly string[];
+    readonly tests: readonly string[];
+    readonly configs: readonly string[];
+    readonly tradeoffs: readonly string[];
+    readonly failure_modes: readonly string[];
+    readonly breaks_if_changed: readonly string[];
+    readonly risks: readonly string[];
+    readonly read_first: readonly string[];
+    readonly evidence_ids: readonly string[];
+    readonly depends_on: readonly string[];
+    readonly depended_on_by: readonly string[];
+    readonly confidence: Confidence;
+    readonly confidence_basis: readonly string[];
+    readonly unknowns: readonly string[];
+    readonly evidence_summary: {
+        readonly evidence_count: number;
+        readonly direct_evidence_ids: readonly string[];
+        readonly field_evidence: readonly string[];
+        readonly records: readonly {
+            readonly id: string;
+            readonly label: string;
+            readonly description: string;
+            readonly confidence: Confidence;
+            readonly source_files: readonly string[];
+            readonly kind?: string;
+        }[];
+        readonly redacted_evidence_count: number;
+    };
+    readonly evidence_gaps: readonly string[];
+    readonly related_components: readonly string[];
+    readonly related_flows: readonly string[];
+    readonly benchmark_task_hints: readonly {
+        readonly id: string;
+        readonly category: BenchmarkTaskCategory;
+        readonly prompt: string;
+        readonly expected_artifact: string;
+        readonly expected_check_fields: readonly string[];
+        readonly confidence: Confidence;
+        readonly why_it_matters: string;
+    }[];
+    readonly research_artifacts: {
+        readonly proving: readonly string[];
+        readonly limiting: readonly string[];
+    };
+    readonly component?: {
+        readonly boundary_type: string;
+        readonly criticality: string;
+        readonly criticality_score?: number;
+        readonly ownership_confidence?: {
+            readonly score?: number;
+            readonly reason?: string;
+            readonly signals?: readonly string[];
+        };
+    };
+    readonly flow?: {
+        readonly kind: FlowKind;
+        readonly framework?: string;
+        readonly route_path?: string;
+        readonly route_type?: string;
+        readonly entrypoints: readonly FlowEntrypoint[];
+        readonly steps: readonly FlowStep[];
+        readonly components: readonly string[];
+        readonly files: readonly string[];
+        readonly dependencies: readonly string[];
+        readonly tests: readonly string[];
+        readonly configs: readonly string[];
+        readonly risks: readonly FlowRisk[];
+        readonly entry_contract: readonly string[];
+        readonly exit_contract: readonly string[];
+        readonly inputs: readonly string[];
+        readonly outputs: readonly string[];
+        readonly side_effects: readonly string[];
+        readonly state_transitions: readonly string[];
+        readonly failure_modes: readonly string[];
+        readonly required_tests: readonly string[];
+        readonly confidence_reasons: readonly string[];
+        readonly confidence_score: number;
+        readonly confidence_reason: string;
+    };
+}
+export interface GenerateProjectBrainOptions {
+    readonly rootDir: string;
+    readonly now?: Date;
+    readonly maxFiles?: number;
+}
+export interface GenerateProjectBrainSummary {
+    readonly rootDir: string;
+    readonly brainDir: string;
+    readonly researchDir: string;
+    readonly latestPath: string;
+    readonly reportPath: string;
+    readonly scannedFiles: number;
+    readonly changedFiles: number;
+    readonly staleFiles: number;
+    readonly components: number;
+    readonly flows: number;
+    readonly commands: number;
+    readonly tests: number;
+}
+export type GenerateProjectBrainResult = {
+    readonly ok: true;
+    readonly value: GenerateProjectBrainSummary;
+} | {
+    readonly ok: false;
+    readonly error: {
+        readonly code: string;
+        readonly message: string;
+    };
+};
+export interface ReviewProjectChangesOptions {
+    readonly rootDir: string;
+    readonly now?: Date;
+    readonly json?: boolean;
+}
+export interface ReviewProjectChangesSummary {
+    readonly rootDir: string;
+    readonly reviewPath: string;
+    readonly reviewEvalPath: string;
+    readonly latestPath: string;
+    readonly reportPath: string;
+    readonly changedFiles: number;
+    readonly affectedComponents: number;
+    readonly affectedFlows: number;
+    readonly findings: number;
+    readonly overallRisk: OverallRisk;
+    readonly surgicalityScore: number;
+    readonly blastRadius: BlastRadius;
+    readonly recommendedAction: RecommendedAction;
+    readonly review: ReviewSummaryData;
+    readonly reviewEval: ReviewEvalArtifactData;
+}
+export type ReviewProjectChangesResult = {
+    readonly ok: true;
+    readonly value: ReviewProjectChangesSummary;
+} | {
+    readonly ok: false;
+    readonly error: {
+        readonly code: string;
+        readonly message: string;
+    };
+};
+export interface ExplainProjectTargetOptions {
+    readonly rootDir: string;
+    readonly target: string;
+    readonly now?: Date;
+}
+export interface ExplainProjectTargetSummary {
+    readonly rootDir: string;
+    readonly latestPath: string;
+    readonly reportPath: string;
+    readonly targetId: string;
+    readonly confidence: Confidence;
+    readonly explanation: ExplainSummaryData;
+}
+export type ExplainProjectTargetResult = {
+    readonly ok: true;
+    readonly value: ExplainProjectTargetSummary;
+} | {
+    readonly ok: false;
+    readonly error: {
+        readonly code: string;
+        readonly message: string;
+    };
+};
+type AskQuestionIntent = 'read_first' | 'breaks_if_changed' | 'dependents' | 'why_exists' | 'evidence';
+type AskAnswerStatus = 'answered' | 'limited' | 'blocked';
+interface AskReadinessSummary {
+    readonly status: 'ready' | 'limited' | 'blocked';
+    readonly score: number;
+    readonly summary: string;
+    readonly reasons: readonly string[];
+    readonly next_required_improvements: readonly string[];
+}
+export interface AskProjectQuestionOptions {
+    readonly rootDir: string;
+    readonly question: string;
+    readonly now?: Date;
+}
+export interface AskProjectQuestionAnswer {
+    readonly schema_version: 1;
+    readonly generated_at: string;
+    readonly question: string;
+    readonly intent: AskQuestionIntent;
+    readonly status: AskAnswerStatus;
+    readonly answer: string;
+    readonly answer_items: readonly string[];
+    readonly confidence: Confidence;
+    readonly readiness: AskReadinessSummary;
+    readonly evidence_ids: readonly string[];
+    readonly evidence_summary: {
+        readonly evidence_count: number;
+        readonly records: readonly {
+            readonly id: string;
+            readonly description: string;
+            readonly confidence: Confidence;
+            readonly source_files: readonly string[];
+        }[];
+        readonly redacted_evidence_count: number;
+    };
+    readonly unknowns: readonly string[];
+    readonly related_entities: readonly string[];
+    readonly research_artifacts: readonly string[];
+    readonly deterministic: true;
+    readonly provider_calls_required: false;
+    readonly network_required: false;
+}
+export interface AskProjectQuestionSummary {
+    readonly rootDir: string;
+    readonly latestPath: string;
+    readonly reportPath: string;
+    readonly answer: AskProjectQuestionAnswer;
+}
+export type AskProjectQuestionResult = {
+    readonly ok: true;
+    readonly value: AskProjectQuestionSummary;
+} | {
+    readonly ok: false;
+    readonly error: {
+        readonly code: string;
+        readonly message: string;
+    };
+};
+export declare function generateProjectBrain(options: GenerateProjectBrainOptions): Promise<GenerateProjectBrainResult>;
+export declare function hasProjectBrain(rootDir: string): Promise<boolean>;
+export declare function reviewProjectChanges(options: ReviewProjectChangesOptions): Promise<ReviewProjectChangesResult>;
+export declare function explainProjectTarget(options: ExplainProjectTargetOptions): Promise<ExplainProjectTargetResult>;
+export declare function askProjectQuestion(options: AskProjectQuestionOptions): Promise<AskProjectQuestionResult>;
+export {};
+//# sourceMappingURL=index.d.ts.map