@neurcode-ai/cli 0.16.8 → 0.16.9

package/dist/utils/repo-brain-impact.d.ts

@@ -0,0 +1,255 @@
+/**
+ * Repo Brain Impact Intelligence (V1) — deterministic + advisory change-impact
+ * analysis over the source-free local repo brain.
+ *
+ * Given a changed file (or set of changed files) this module answers the
+ * question an engineering manager actually asks about an AI change *before or
+ * after* it lands: what does this touch, who owns it, what is sensitive, who
+ * imports it, is it a hub, where are the nearby tests/docs, is the helper
+ * duplicated elsewhere, and what should a reviewer ask?
+ *
+ * Hard rules (shared with utils/local-repo-brain.ts and utils/guided-eval.ts):
+ *   - Source-free: only relative paths, symbol *names*, counts, owner tokens,
+ *     sensitive-kind labels, and hashes are read or emitted. Never source code,
+ *     diff hunks, or file bodies.
+ *   - Honest labelling: every finding is tagged `deterministic` (a compiled
+ *     path / CODEOWNERS / static-import-graph fact) or `advisory` (a heuristic
+ *     reuse / proximity / reviewer-question signal). We never present an
+ *     advisory signal as a deterministic guarantee.
+ *
+ * The engine is pure (no I/O) — {@link computeRepoBrainImpact} takes an artifact
+ * (or null) and the changed paths. {@link buildRepoBrainImpactForRepo} is the
+ * thin I/O wrapper that reads (or builds) the brain and then computes.
+ */
+import { type LocalRepoBrainArtifact, type LocalRepoBrainSensitiveKind } from './local-repo-brain';
+export declare const REPO_BRAIN_IMPACT_SCHEMA_VERSION: "neurcode.repo-brain-impact.v1";
+export declare const IMPACT_SUMMARY_SCHEMA_VERSION: "neurcode.impact-summary.v1";
+/** Every finding is one of these two truth tiers — never blurred. */
+export type ImpactLabel = 'deterministic' | 'advisory';
+/** Coarse role of a file, derived deterministically from its path. */
+export type ImpactFileRole = 'source' | 'test' | 'docs' | 'config' | 'runtime_governance' | 'generated' | 'data' | 'unknown';
+/** A file imported by enough other files to be a structural hub. */
+export declare const HIGH_FAN_IN_THRESHOLD = 5;
+export interface ImpactChangedFile {
+    path: string;
+    /** Whether the path is present in the indexed brain (else classified by path only). */
+    indexed: boolean;
+    role: ImpactFileRole;
+    language: string | null;
+    module: string | null;
+    sensitiveKinds: LocalRepoBrainSensitiveKind[];
+    /** Declarations indexed in this file (null when not indexed). */
+    symbolCount: number | null;
+    /** Outbound import edges from this file (null when not indexed). */
+    importCount: number | null;
+    generated: boolean;
+}
+export interface ImpactOwnerMatch {
+    /** CODEOWNERS pattern that matched. */
+    pattern: string;
+    owners: string[];
+    /** Which of the changed paths this boundary covers. */
+    matchedPaths: string[];
+    /** True for the last-match-wins effective owner of at least one changed path. */
+    effective: boolean;
+}
+export interface ImpactSensitiveSurface {
+    path: string;
+    kinds: LocalRepoBrainSensitiveKind[];
+}
+export interface ImpactConsumer {
+    path: string;
+    role: ImpactFileRole;
+    /** Number of static import edges from this file into the changed set. */
+    edgeCount: number;
+    /** Up to a few of the changed paths this consumer imports. */
+    imports: string[];
+}
+export interface ImpactDependency {
+    /** The raw import specifier (e.g. "../retry" or "@scope/pkg"). */
+    target: string;
+    /** Resolved repo-relative file when the import is relative and in-repo. */
+    resolvedFile: string | null;
+    external: boolean;
+}
+export interface ImpactHotspot {
+    path: string;
+    score: number;
+    fanIn: number;
+    fanOut: number;
+    reasons: string[];
+    /** fanIn >= HIGH_FAN_IN_THRESHOLD — a structural hub. */
+    isHub: boolean;
+}
+export interface ImpactReuseAdvisory {
+    symbolName: string | null;
+    kind: string;
+    severity: string;
+    confidence: string;
+    files: string[];
+    reasonCodes: string[];
+}
+export type ImpactQuestionCategory = 'owners' | 'sensitive' | 'fanout' | 'reuse' | 'tests' | 'config' | 'general';
+export interface ImpactReviewQuestion {
+    category: ImpactQuestionCategory;
+    question: string;
+    rationale: string;
+}
+export interface RepoBrainImpactReport {
+    schemaVersion: typeof REPO_BRAIN_IMPACT_SCHEMA_VERSION;
+    generatedAt: string;
+    brain: {
+        status: 'found' | 'built' | 'missing';
+        artifactHash: string | null;
+        generatedAt: string | null;
+        filesIndexed: number | null;
+        ownerBoundaryStatus: 'found' | 'not_found' | null;
+        recoveryCommand: string;
+    };
+    requestedPaths: string[];
+    changedFiles: ImpactChangedFile[];
+    owners: {
+        label: 'deterministic';
+        status: 'found' | 'not_found';
+        matches: ImpactOwnerMatch[];
+        /** Distinct effective owners across the changed set (last-match-wins). */
+        routeTo: string[];
+    };
+    sensitiveSurfaces: {
+        label: 'deterministic';
+        surfaces: ImpactSensitiveSurface[];
+        kinds: LocalRepoBrainSensitiveKind[];
+    };
+    consumers: {
+        label: 'deterministic';
+        direct: ImpactConsumer[];
+        total: number;
+        truncated: boolean;
+        byRole: Record<ImpactFileRole, number>;
+    };
+    dependencies: {
+        label: 'deterministic';
+        internal: ImpactDependency[];
+        externalPackages: string[];
+        truncated: boolean;
+    };
+    highFanOut: {
+        label: 'deterministic';
+        hotspots: ImpactHotspot[];
+        isHighFanOut: boolean;
+    };
+    nearby: {
+        label: 'advisory';
+        tests: string[];
+        docs: string[];
+        config: string[];
+        runtime: string[];
+    };
+    reuse: {
+        label: 'advisory';
+        advisories: ImpactReuseAdvisory[];
+    };
+    reviewRouting: {
+        owners: string[];
+        reviewFirst: string[];
+    };
+    reviewQuestions: ImpactReviewQuestion[];
+    labels: {
+        deterministic: string[];
+        advisory: string[];
+    };
+    proves: string[];
+    doesNotProve: string[];
+    limitations: string[];
+}
+/**
+ * Compact, source-free impact digest embedded in AI Change Records, eval-demo
+ * reports, and the dashboard import. A trimmed projection of the full report.
+ */
+export interface ImpactSummary {
+    schemaVersion: typeof IMPACT_SUMMARY_SCHEMA_VERSION;
+    generatedAt: string;
+    brainStatus: 'found' | 'built' | 'missing';
+    artifactHash: string | null;
+    counts: {
+        changedFiles: number;
+        indexedChangedFiles: number;
+        directConsumers: number;
+        changedSymbols: number;
+        sensitiveSurfaces: number;
+        internalDependencies: number;
+        externalPackages: number;
+        owners: number;
+    };
+    changedFiles: Array<{
+        path: string;
+        role: ImpactFileRole;
+        module: string | null;
+        sensitiveKinds: LocalRepoBrainSensitiveKind[];
+    }>;
+    owners: string[];
+    sensitiveSurfaces: ImpactSensitiveSurface[];
+    deterministic: {
+        directConsumers: Array<{
+            path: string;
+            role: ImpactFileRole;
+            edgeCount: number;
+        }>;
+        highFanOut: Array<{
+            path: string;
+            fanIn: number;
+        }>;
+        isHighFanOut: boolean;
+    };
+    advisory: {
+        reuse: Array<{
+            symbolName: string | null;
+            confidence: string;
+            files: string[];
+        }>;
+        nearbyTests: string[];
+    };
+    reviewRouting: {
+        owners: string[];
+        reviewFirst: string[];
+    };
+    reviewQuestions: string[];
+    proves: string[];
+    doesNotProve: string[];
+}
+export interface ComputeRepoBrainImpactOptions {
+    generatedAt?: string;
+    brainStatus?: 'found' | 'built' | 'missing';
+    /** Max direct consumers / dependencies retained before truncation. */
+    maxConsumers?: number;
+    maxDependencies?: number;
+    maxReviewQuestions?: number;
+}
+export declare function normalizeImpactPath(value: string, projectRoot?: string): string;
+/**
+ * Deterministically classify a file's role from its path + sensitive kinds.
+ * Order matters: test > runtime_governance > config > docs > generated > data.
+ */
+export declare function classifyImpactFileRole(path: string, opts?: {
+    generated?: boolean;
+    sensitiveKinds?: LocalRepoBrainSensitiveKind[];
+}): ImpactFileRole;
+/**
+ * Faithful subset of gitignore/CODEOWNERS glob semantics, sufficient for the
+ * common enterprise patterns: `src/billing/`, `*.py`, `/.github/workflows/`,
+ * `packages/cli/`, `docs/*`, `apps/web/**`, and exact file paths.
+ */
+export declare function matchesCodeownersPattern(filePath: string, pattern: string): boolean;
+export declare function computeRepoBrainImpact(artifact: LocalRepoBrainArtifact | null, requestedPaths: string[], options?: ComputeRepoBrainImpactOptions): RepoBrainImpactReport;
+export declare function summarizeImpact(report: RepoBrainImpactReport): ImpactSummary;
+export interface BuildRepoBrainImpactOptions extends ComputeRepoBrainImpactOptions {
+    /** Build the brain when no artifact exists yet (default true). */
+    autoBuild?: boolean;
+}
+/**
+ * Read the local repo brain (building it once when missing if autoBuild) and
+ * compute the impact report for the given changed paths.
+ */
+export declare function buildRepoBrainImpactForRepo(projectRoot: string, requestedPaths: string[], options?: BuildRepoBrainImpactOptions): RepoBrainImpactReport;
+export declare function renderRepoBrainImpactText(report: RepoBrainImpactReport): string;
+//# sourceMappingURL=repo-brain-impact.d.ts.map

package/dist/utils/repo-brain-impact.d.ts.map

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