cgraphx 1.1.0 → 1.2.0

package/dist/search/impact.d.ts

@@ -0,0 +1,139 @@
+/**
+ * Impact analysis — transitive callers + type references for a method.
+ *
+ * Spec input (per `docs/features/2026-07-01-impact-command/spec.md`, drafted
+ * from clarify-requirements):
+ *   - Replace the existing indexed-DB `cgraphx impact` command (CLI surface only;
+ *     the graph API `CodeGraph.getImpactRadius` stays for the MCP server until
+ *     that's separately deprecated).
+ *   - Input: `Class#method` or `file:line` (same as `calls --from`).
+ *   - Output: transitive callers (BFS up to depth N) + type references to the
+ *     enclosing class (import / extends / implements / field / param / local /
+ *     cast / annotation / generic). All SNR-ranked, tiered-budget output.
+ *
+ * Isolation: lives entirely under `src/search/`, imports nothing from
+ * `src/graph/`, `src/resolution/`, `src/db/`, `src/mcp/`, or `src/extraction/`
+ * (beyond the grammar loader). When the indexed pipeline is eventually removed,
+ * this file is untouched.
+ */
+import type { Language } from '../types';
+import { type CallSite } from './call-sites';
+export { searchCallSites } from './call-sites';
+export interface ImpactCallSite extends CallSite {
+    /** 1 = direct caller, 2 = caller-of-caller, etc. */
+    hopDistance: number;
+}
+export type TypeReferenceKind = 'import' | 'extends' | 'implements' | 'field' | 'param' | 'local' | 'cast' | 'annotation' | 'generic' | 'return' | 'other';
+export interface TypeReference {
+    /** The class name being referenced (matches input symbol's enclosing class). */
+    className: string;
+    /** File path relative to projectRoot. */
+    filePath: string;
+    /** 1-based line number of the type_identifier node. */
+    line: number;
+    /** 0-based column. */
+    column: number;
+    kind: TypeReferenceKind;
+    /** Enclosing class (where the reference lives), if any. */
+    containingClass: string | null;
+    /** Enclosing method, if any. */
+    containingMethod: string | null;
+    /** 1-2 line snippet around the reference. */
+    snippet: string;
+    /** SNR score (extends/implements high; import low). */
+    snrScore: number;
+    /** Tier assigned by budget allocator. */
+    tier?: 'essential' | 'recommended' | 'optional';
+}
+export interface ImpactOptions {
+    /** BFS depth for transitive callers. Default 2 (callers + callers-of-callers). */
+    depth?: number;
+    /** Top callers per hop (clustering). Default 10. */
+    topPerHop?: number;
+    /** Top type references overall. Default 15. */
+    topTypeRefs?: number;
+    /** Char budget for total output. Default 6000 (impact is naturally larger than calls). */
+    budget?: number;
+    /** Languages to scan. Default ['java', 'kotlin']. */
+    languages?: Language[];
+    /** Directory globs to exclude. */
+    excludeDirs?: string[];
+    /** Force recommended tier for every emitted item (alias of --snippet). */
+    withSnippet?: boolean;
+    /** Force optional tier for every emitted item (--full). */
+    full?: boolean;
+}
+export interface ImpactResult {
+    /** Original symbol input. */
+    symbol: string;
+    /** Resolved Class#method. */
+    methodQualifiedName: string;
+    /** Enclosing class name (the type-refs scan target). */
+    enclosingClass: string | null;
+    /** File where the method is defined (relative to projectRoot). */
+    filePath: string;
+    /** Method body range. */
+    startLine: number;
+    endLine: number;
+    /** BFS depth actually reached (may be less than requested if no more callers). */
+    depthReached: number;
+    /** Distinct methods in the caller chain (excluding the start method). */
+    totalCallers: number;
+    /** Distinct files where the enclosing class is referenced. */
+    totalTypeRefFiles: number;
+    /** Total type references found. */
+    totalTypeRefs: number;
+    callers: ImpactCallSite[];
+    typeReferences: TypeReference[];
+    omitted: {
+        callersPrunedByTopPerHop: number;
+        typeRefsPrunedByTopK: number;
+        truncatedByBudget: number;
+    };
+}
+/**
+ * SNR score a transitive caller. Reuses computeSnrScore for the call-site
+ * itself, then applies hop-distance decay (hop 1 = 1.0, hop 2 = 0.6,
+ * hop 3 = 0.36, ...). Direct callers always outrank indirect ones.
+ */
+export declare function computeImpactCallSiteSnr(site: ImpactCallSite): number;
+/**
+ * Impact SNR breakdown — reuses the call-site breakdown then layers on
+ * hop-distance decay. Used by the `--explain` flag on `impact`.
+ *
+ * `base` is the pre-decay score (`computeSnrScore(site)`), `decayMultiplier`
+ * is the hop factor (1.0 at hop 1, 0.6 at hop 2, ...), `total` is
+ * `Math.round(base * decayMultiplier)`. `matchedRules` is forwarded from
+ * the underlying call-site breakdown so the agent sees which receiver /
+ * method rules fired.
+ */
+export interface ImpactSnrBreakdown {
+    base: number;
+    decayMultiplier: number;
+    total: number;
+    matchedRules: string[];
+    /** The underlying call-site breakdown (receiver / method split). */
+    receiver: number;
+    method: number;
+}
+export declare function computeImpactSnrBreakdown(site: ImpactCallSite): ImpactSnrBreakdown;
+export declare function searchImpact(projectRoot: string, symbol: string, options?: ImpactOptions): Promise<ImpactResult>;
+interface ImpactTieredResult {
+    tieredCallers: ImpactCallSite[];
+    tieredTypeRefs: TypeReference[];
+    truncatedByBudget: number;
+}
+/**
+ * Two-list tiered budget: allocate budget across callers AND type references.
+ * Callers get essential tier first (in SNR order), then type refs get essential
+ * tier. If budget remains, recommended tier fills in SNR order across both
+ * lists. Same for optional.
+ */
+export declare function applyImpactTieredBudget(callers: ImpactCallSite[], typeRefs: TypeReference[], budget: number, opts?: {
+    forceRecommended?: boolean;
+    forceOptional?: boolean;
+}): ImpactTieredResult;
+export declare function formatImpactResult(result: ImpactResult, options?: {
+    explain?: boolean;
+}): string;
+//# sourceMappingURL=impact.d.ts.map

package/dist/search/impact.d.ts.map

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