@alex-dbs/coderuler 1.5.0 → 1.6.0

package/dist/app/concurrency.d.ts

@@ -1 +1 @@
-export declare function mapConcurrent<T, R>(items: readonly T[], concurrency: number, mapper: (item: T, index: number, reportFailure: (error: unknown) => void) => Promise<R>): Promise<R[]>;
+export declare function mapConcurrent<T, R>(items: readonly T[], concurrency: number, mapper: (item: T, index: number, reportFailure: (error: unknown) => void) => Promise<R>, scheduler?: (work: Promise<R>) => Promise<R>): Promise<R[]>;

package/dist/app/concurrency.js

@@ -6,7 +6,7 @@ function requirePositiveSafeInteger(concurrency) {
         throw invalidConcurrency(String(concurrency));
     }
 }
-export async function mapConcurrent(items, concurrency, mapper) {
+export async function mapConcurrent(items, concurrency, mapper, scheduler = work => work) {
     requirePositiveSafeInteger(concurrency);
     const results = new Array(items.length);
     if (items.length === 0)
@@ -14,12 +14,12 @@ export async function mapConcurrent(items, concurrency, mapper) {
     const workerCount = Math.min(items.length, concurrency);
     let nextIndex = 0;
     let failureObserved = false;
-    let failure;
-    // A mapper may need to drain started work after it has already failed.
+    const { promise: failureSignal, resolve: signalFailure } = Promise.withResolvers();
+    // A mapper may report failure before its own cleanup finishes.
     const reportFailure = (error) => {
         if (!failureObserved) {
             failureObserved = true;
-            failure = error;
+            signalFailure({ error });
         }
     };
     const runWorker = async () => {
@@ -29,7 +29,8 @@ export async function mapConcurrent(items, concurrency, mapper) {
             if (index >= items.length)
                 return;
             try {
-                results[index] = await mapper(items[index], index, reportFailure);
+                const work = scheduler(Promise.resolve().then(() => mapper(items[index], index, reportFailure)));
+                results[index] = await work;
             }
             catch (error) {
                 reportFailure(error);
@@ -37,8 +38,11 @@ export async function mapConcurrent(items, concurrency, mapper) {
         }
     };
     const workers = Array.from({ length: workerCount }, () => runWorker());
-    await Promise.all(workers);
-    if (failureObserved)
-        throw failure;
+    const outcome = await Promise.race([
+        Promise.all(workers).then(() => ({ error: undefined, failed: false })),
+        failureSignal.then(({ error }) => ({ error, failed: true })),
+    ]);
+    if (outcome.failed)
+        throw outcome.error;
     return results;
 }

package/dist/app/execute.js

@@ -1,9 +1,15 @@
 import { matchesGlob } from 'node:path';
+import { createRunLsp } from './lsp.js';
 import { mapConcurrent } from './concurrency.js';
 import { evaluateAi } from './evaluators.js';
 import { wholeFileScope } from './selection.js';
 import { addUsage } from './usage.js';
 import { validateCheckResult, validatePredicateResult, validateScopeMatch, validateScopeSubjects, } from './validate.js';
+function trackWork(pending, work) {
+    pending.add(work);
+    void work.then(() => { pending.delete(work); }, () => { pending.delete(work); });
+    return work;
+}
 function isEligibleRelativePath(filepath) {
     if (filepath === '' || filepath.startsWith('/'))
         return false;
@@ -26,6 +32,55 @@ function folderPath(filepath, level) {
     return segments.slice(0, keep).join('/');
 }
 export async function executeRules(rules, context) {
+    const goLsp = createRunLsp(context.project, context.createLspBackend);
+    const rubyLsp = createRunLsp(context.project, context.createRubyLspBackend);
+    const typescriptLsp = createRunLsp(context.project, context.createTypescriptLspBackend);
+    const closeLspSessions = async () => {
+        const results = await Promise.allSettled([goLsp.close(), rubyLsp.close(), typescriptLsp.close()]);
+        const goResult = results[0];
+        if (goResult.status === 'rejected')
+            throw goResult.reason;
+        const rubyResult = results[1];
+        if (rubyResult.status === 'rejected')
+            throw rubyResult.reason;
+        const typescriptResult = results[2];
+        if (typescriptResult.status === 'rejected')
+            throw typescriptResult.reason;
+    };
+    const abortLsp = () => { void closeLspSessions().catch(() => undefined); };
+    const startedWork = new Set();
+    const scheduleWork = (work) => {
+        startedWork.add(work);
+        void work.then(() => { startedWork.delete(work); }, () => { startedWork.delete(work); });
+        return work;
+    };
+    const drainStartedWork = async () => {
+        while (startedWork.size > 0)
+            await Promise.allSettled([...startedWork]);
+    };
+    let failed = false;
+    try {
+        const reports = await executeRun(rules, context, goLsp.tools, rubyLsp.tools, typescriptLsp.tools, scheduleWork, abortLsp);
+        await drainStartedWork();
+        return reports;
+    }
+    catch (error) {
+        failed = true;
+        abortLsp();
+        await drainStartedWork();
+        throw error;
+    }
+    finally {
+        try {
+            await closeLspSessions();
+        }
+        catch (error) {
+            if (!failed)
+                throw error;
+        }
+    }
+}
+async function executeRun(rules, context, goLsp, rubyLsp, typescriptLsp, scheduleWork, abortLsp) {
     let completedSelections = 0;
     let completedEvaluations = 0;
     const emit = (event) => {
@@ -47,6 +102,9 @@ export async function executeRules(rules, context) {
     };
     const projectContextFor = (name, evaluationId) => ({
         project: context.project,
+        goLsp,
+        rubyLsp,
+        typescriptLsp,
         ...(changedFiles === undefined ? {} : { changedFiles }),
         ...(changedLines === undefined ? {} : { changedLines }),
         trace: traceFor(name, evaluationId),
@@ -83,7 +141,7 @@ export async function executeRules(rules, context) {
             }
         }
     };
-    const selectFromRule = async (name, selection, evaluationId, changedOnly = false) => {
+    const selectFromRule = async (name, selection, evaluationId, changedOnly = false, pendingWork) => {
         const exclude = selection.exclude ?? [];
         const candidates = await context.project.glob(selection.files);
         const chosen = [];
@@ -105,6 +163,9 @@ export async function executeRules(rules, context) {
                 chosen.push(filepath);
         }
         const scope = selection.scope;
+        const scheduler = pendingWork === undefined
+            ? scheduleWork
+            : (work) => trackWork(pendingWork, work);
         const collected = await mapConcurrent(chosen, context.concurrency, async (filepath) => {
             const source = await context.project.readText(filepath);
             const matches = scope === undefined
@@ -122,7 +183,7 @@ export async function executeRules(rules, context) {
                 subjects.push({ kind: 'scope', filepath, ...valid });
             }
             return subjects;
-        });
+        }, scheduler);
         return collected.flat();
     };
     const selectionContextFor = (name, changedOnly) => ({
@@ -142,13 +203,14 @@ export async function executeRules(rules, context) {
         const { name, rule } = plan;
         emit({ type: 'evaluation', evaluationId, name, subject });
         let trackedUsage;
-        let pendingAi;
+        let pendingWork;
         let accountingFailure;
         const retainAccountingFailure = (error) => {
             if (accountingFailure !== undefined)
                 return;
             const failure = error instanceof Error ? error : new Error(String(error));
             accountingFailure = { error: failure };
+            abortLsp();
             reportFailure(failure);
         };
         const throwIfAccountingFailed = () => {
@@ -183,14 +245,13 @@ export async function executeRules(rules, context) {
         const checkContext = {
             ...projectContextFor(name, evaluationId),
             ruleName: name,
-            select: selection => selectFromRule(name, selection, evaluationId),
+            // Let the check catch a nested selection rejection. If it escapes, the
+            // enclosing check handler records it before aborting sibling work.
+            select: selection => selectFromRule(name, selection, evaluationId, false, pendingWork ??= new Set()),
             ai: options => {
                 const call = evaluateAi(subject, options, { ...projectContextFor(name, evaluationId), ruleName: name }, runtimeOf(plan), observer);
-                const pending = pendingAi ??= new Set();
-                pending.add(call);
-                // Observe both outcomes immediately; the check still receives the original promise.
-                void call.then(() => { pending.delete(call); }, () => { pending.delete(call); });
-                return call;
+                const pending = pendingWork ??= new Set();
+                return trackWork(pending, call);
             },
         };
         let result;
@@ -223,12 +284,13 @@ export async function executeRules(rules, context) {
                 const cause = accountingFailure === undefined ? error : accountingFailure.error;
                 const failure = cause instanceof Error ? cause : new Error(String(cause));
                 reportFailure(failure);
+                abortLsp();
                 throw failure;
             }
             finally {
-                // Promise.all may reject while sibling calls are still producing usage events.
-                while (pendingAi !== undefined && pendingAi.size > 0) {
-                    await Promise.allSettled(pendingAi);
+                // The check can settle while sibling AI calls or selector workers still produce usage.
+                while (pendingWork !== undefined && pendingWork.size > 0) {
+                    await Promise.allSettled(pendingWork);
                 }
             }
             // A custom check may catch context.ai failures, but cannot discard accounting failures.
@@ -372,7 +434,7 @@ export async function executeRules(rules, context) {
         }
     }
     context.emit?.({ type: 'progress', phase: 'evaluation', completed: 0, total: tasks.length });
-    const results = await mapConcurrent(tasks, context.concurrency, (task, _index, reportFailure) => evaluateSubject(task.plan, task.subject, task.evaluationId, reportFailure));
+    const results = await mapConcurrent(tasks, context.concurrency, (task, _index, reportFailure) => evaluateSubject(task.plan, task.subject, task.evaluationId, reportFailure), scheduleWork);
     for (let index = 0; index < tasks.length; index += 1) {
         const task = tasks[index];
         task.plan.evaluations.push({ subject: task.subject, result: results[index] });

package/dist/app/lsp.d.ts

@@ -0,0 +1,6 @@
+import type { LspTools } from './rule.js';
+import type { LspBackendFactory, Project } from './ports.js';
+export declare function createRunLsp(project: Project, createBackend?: LspBackendFactory): {
+    readonly tools: LspTools;
+    close(): Promise<void>;
+};

package/dist/app/lsp.js

@@ -0,0 +1,141 @@
+export function createRunLsp(project, createBackend) {
+    const controller = new AbortController();
+    const pending = new Set();
+    let startup;
+    let backend;
+    let backendClose;
+    let closeFailure;
+    let hasCloseFailure = false;
+    let closePromise;
+    let closed = false;
+    const closedError = () => new Error('LSP session is closed');
+    const closeBackend = (owned) => {
+        if (backendClose === undefined) {
+            backendClose = Promise.resolve().then(() => owned.close());
+            void backendClose.catch(error => {
+                closeFailure = error;
+                hasCloseFailure = true;
+            });
+        }
+        return backendClose;
+    };
+    const getBackend = () => {
+        if (closed)
+            return Promise.reject(closedError());
+        if (startup !== undefined)
+            return startup;
+        if (createBackend === undefined) {
+            startup = Promise.reject(new Error('LSP is not configured for this run'));
+            void startup.catch(() => undefined);
+            return startup;
+        }
+        startup = Promise.resolve().then(async () => {
+            if (controller.signal.aborted)
+                throw closedError();
+            const created = await createBackend(project, controller.signal);
+            backend = created;
+            if (closed) {
+                await closeBackend(created);
+                throw closedError();
+            }
+            return created;
+        });
+        void startup.catch(() => undefined);
+        return startup;
+    };
+    const observe = (promise) => {
+        pending.add(promise);
+        void promise.then(() => pending.delete(promise), () => pending.delete(promise));
+        return promise;
+    };
+    const rejectCall = (error) => observe(Promise.reject(error));
+    const invoke = (operation) => observe(Promise.resolve().then(async () => {
+        if (closed)
+            throw closedError();
+        const active = await getBackend();
+        if (closed || controller.signal.aborted)
+            throw closedError();
+        return operation(active);
+    }));
+    const validateTarget = (target) => {
+        if (!Number.isSafeInteger(target.line) || target.line < 1) {
+            throw new Error('LSP line must be a positive safe integer');
+        }
+        if (target.column !== undefined && (!Number.isSafeInteger(target.column) || target.column < 1)) {
+            throw new Error('LSP column must be a positive safe integer');
+        }
+    };
+    const withTarget = (target, operation) => {
+        if (closed)
+            return rejectCall(closedError());
+        try {
+            validateTarget(target);
+        }
+        catch (error) {
+            return rejectCall(error);
+        }
+        return invoke(operation);
+    };
+    const withGraph = (target, options, operation) => {
+        if (closed)
+            return rejectCall(closedError());
+        if (!Number.isSafeInteger(options.depth) || options.depth < 0) {
+            return rejectCall(new Error('LSP call depth must be a nonnegative safe integer'));
+        }
+        try {
+            validateTarget(target);
+        }
+        catch (error) {
+            return rejectCall(error);
+        }
+        if (options.depth === 0)
+            return Promise.resolve([]);
+        return invoke(operation);
+    };
+    const tools = {
+        definitions: (target, options) => withTarget(target, active => active.definitions(target, options)),
+        declarations: (target, options) => withTarget(target, active => active.declarations(target, options)),
+        typeDefinitions: (target, options) => withTarget(target, active => active.typeDefinitions(target, options)),
+        implementations: (target, options) => withTarget(target, active => active.implementations(target, options)),
+        references: (target, options) => withTarget(target, active => active.references(target, options)),
+        hover: (target, options) => withTarget(target, active => active.hover(target, options)),
+        documentSymbols: (filepath, options) => invoke(active => active.documentSymbols(filepath, options)),
+        workspaceSymbols: (query, options) => {
+            if (closed)
+                return rejectCall(closedError());
+            return query.length === 0 ? Promise.resolve([]) : invoke(active => active.workspaceSymbols(query, options));
+        },
+        callers: (target, options) => withGraph(target, options, active => active.callers(target, options)),
+        callees: (target, options) => withGraph(target, options, active => active.callees(target, options)),
+    };
+    const close = () => {
+        if (closePromise !== undefined)
+            return closePromise;
+        closed = true;
+        controller.abort();
+        closePromise = Promise.resolve().then(async () => {
+            if (startup !== undefined) {
+                try {
+                    backend = await startup;
+                }
+                catch {
+                    // The request reports startup failures. There is no backend to close.
+                }
+            }
+            if (backend !== undefined) {
+                try {
+                    await closeBackend(backend);
+                }
+                catch {
+                    // Preserve the close failure after pending calls settle.
+                }
+            }
+            await Promise.allSettled([...pending]);
+            if (hasCloseFailure)
+                throw closeFailure;
+        });
+        void closePromise.catch(() => undefined);
+        return closePromise;
+    };
+    return { tools, close };
+}

package/dist/app/ports.d.ts

@@ -1,4 +1,4 @@
-import type { AiUsage, CheckResult, GroupSubject, JsonValue, LineRange, Rule, RuleSettings, ScopeSubject, Subject, TokenPricing, TokenUsage } from './rule.js';
+import type { AiUsage, Awaitable, CheckResult, GroupSubject, JsonValue, LineRange, LspTools, Rule, RuleSettings, ScopeSubject, Subject, TokenPricing, TokenUsage } from './rule.js';
 export interface DiffChanges {
     readonly changedFiles: ReadonlySet<string>;
     readonly changedLines: ReadonlyMap<string, readonly LineRange[]>;
@@ -15,6 +15,10 @@ export interface Project {
     readYaml(path: string): Promise<readonly JsonValue[]>;
     readCsv(path: string, options?: CsvOptions): Promise<readonly CsvRow[]>;
 }
+export interface LspBackend extends LspTools {
+    close(): Promise<void>;
+}
+export type LspBackendFactory = (project: Project, signal: AbortSignal) => Awaitable<LspBackend>;
 export interface CsvOptions {
     readonly headers?: boolean;
     readonly delimiter?: string;
@@ -75,6 +79,9 @@ export interface DecisionRuntime {
 export interface RunContext {
     readonly project: Project;
     readonly isTarget: (filepath: string) => boolean;
+    readonly createLspBackend?: LspBackendFactory;
+    readonly createRubyLspBackend?: LspBackendFactory;
+    readonly createTypescriptLspBackend?: LspBackendFactory;
     readonly changedFiles?: ReadonlySet<string>;
     readonly changedLines?: ReadonlyMap<string, readonly LineRange[]>;
     readonly concurrency: number;

package/dist/app/rule.d.ts

@@ -1,4 +1,6 @@
+import type { DocumentSymbol, Hover, Location, SymbolInformation, WorkspaceSymbol } from 'vscode-languageserver-protocol';
 import type { Project } from './ports.js';
+export type { DocumentSymbol, Hover, Location, SymbolInformation, WorkspaceSymbol, } from 'vscode-languageserver-protocol';
 export type Awaitable<T> = T | Promise<T>;
 export type JsonValue = null | boolean | number | string | readonly JsonValue[] | {
     readonly [key: string]: JsonValue;
@@ -15,6 +17,39 @@ export interface LineRange {
     readonly start: number;
     readonly end: number;
 }
+export interface LspTarget {
+    readonly filepath: string;
+    readonly line: number;
+    readonly column?: number;
+}
+export interface LspOptions {
+    readonly includeDependencies?: boolean;
+}
+export interface LspReferenceOptions extends LspOptions {
+    readonly includeDeclaration?: boolean;
+}
+export interface LspCallOptions extends LspOptions {
+    readonly depth: number;
+}
+export interface LspCall {
+    readonly name: string;
+    readonly filepath: string;
+    readonly source: string;
+    readonly lines: LineRange;
+    readonly depth: number;
+}
+export interface LspTools {
+    definitions(target: LspTarget, options?: LspOptions): Promise<readonly Location[]>;
+    declarations(target: LspTarget, options?: LspOptions): Promise<readonly Location[]>;
+    typeDefinitions(target: LspTarget, options?: LspOptions): Promise<readonly Location[]>;
+    implementations(target: LspTarget, options?: LspOptions): Promise<readonly Location[]>;
+    references(target: LspTarget, options?: LspReferenceOptions): Promise<readonly Location[]>;
+    hover(target: LspTarget, options?: LspOptions): Promise<Hover | null>;
+    documentSymbols(filepath: string, options?: LspOptions): Promise<readonly DocumentSymbol[] | readonly SymbolInformation[]>;
+    workspaceSymbols(query: string, options?: LspOptions): Promise<readonly (SymbolInformation | WorkspaceSymbol)[]>;
+    callers(target: LspTarget, options: LspCallOptions): Promise<readonly LspCall[]>;
+    callees(target: LspTarget, options: LspCallOptions): Promise<readonly LspCall[]>;
+}
 export interface ScopeMatch<T = JsonValue> {
     readonly id: string;
     readonly source: string;
@@ -96,6 +131,9 @@ export type AiOptions<T = JsonValue> = {
 export type Evaluator<T = JsonValue> = (subject: Subject<T>, context: CheckContext<T>) => Awaitable<CheckResult>;
 export interface ProjectContext {
     readonly project: Project;
+    readonly goLsp: LspTools;
+    readonly rubyLsp: LspTools;
+    readonly typescriptLsp: LspTools;
     readonly changedFiles?: ReadonlySet<string>;
     readonly changedLines?: ReadonlyMap<string, readonly LineRange[]>;
     trace(message: string, details?: JsonValue): void;
@@ -112,6 +150,8 @@ export interface CheckContext<T = JsonValue> extends SelectionContext {
     readonly ruleName: string;
     ai(options: AiOptions<T>): Promise<CheckResult>;
 }
+export declare function isDiffMode(context: ProjectContext): boolean;
+export declare function isInDiff(subject: ScopeSubject<unknown>, context: ProjectContext): boolean;
 export declare const RULE_BRAND: symbol;
 export declare abstract class Rule<T = JsonValue> {
     enabled: boolean;

package/dist/app/rule.js

@@ -1,3 +1,17 @@
+export function isDiffMode(context) {
+    return context.changedFiles !== undefined || context.changedLines !== undefined;
+}
+export function isInDiff(subject, context) {
+    const lines = subject.lines;
+    const ranges = context.changedLines?.get(subject.filepath);
+    if (lines === undefined || ranges === undefined)
+        return false;
+    for (const range of ranges) {
+        if (range.start <= lines.end && lines.start <= range.end)
+            return true;
+    }
+    return false;
+}
 export const RULE_BRAND = Symbol.for('coderuler.Rule');
 export class Rule {
     enabled = true;

package/dist/index.d.ts

@@ -1,10 +1,10 @@
-export { Rule } from './app/rule.js';
+export { Rule, isDiffMode, isInDiff } from './app/rule.js';
 export { test } from './app/rule-tests.js';
 export type { RuleTestCase } from './app/rule-tests.js';
-export type { AiExamples, AiOptions, AiUsage, Awaitable, CheckContext, CheckResult, Evaluator, Grouping, GroupSubject, JsonValue, PredicateResult, LineRange, ProjectContext, RuleSettings, ScopeMatch, ScopeSelector, ScopeSubject, Selection, SelectionContext, SourceFile, Subject, TokenPricing, TokenUsage, ViolationLocation, } from './app/rule.js';
+export type { AiExamples, AiOptions, AiUsage, Awaitable, CheckContext, CheckResult, DocumentSymbol, Evaluator, Grouping, GroupSubject, Hover, JsonValue, LineRange, Location, LspCall, LspCallOptions, LspOptions, LspReferenceOptions, LspTarget, LspTools, PredicateResult, ProjectContext, RuleSettings, ScopeMatch, ScopeSelector, ScopeSubject, Selection, SelectionContext, SourceFile, Subject, SymbolInformation, TokenPricing, TokenUsage, ViolationLocation, WorkspaceSymbol, } from './app/rule.js';
 export { ai, pass, regex, violation } from './app/evaluators.js';
 export type { RegexOptions } from './app/evaluators.js';
-export type { CsvOptions, DiffChanges, CsvRow, DecisionBackend, DecisionExchange, DecisionInstructions, DecisionObserver, DecisionOutcome, DecisionRequest, DecisionRuntime, LoadedRule, Project, RuleEvaluation, RuleLoader, RuleReport, RuleSelection, RunContext, RunEvent, } from './app/ports.js';
+export type { CsvOptions, DiffChanges, CsvRow, DecisionBackend, DecisionExchange, DecisionInstructions, DecisionObserver, DecisionOutcome, DecisionRequest, DecisionRuntime, LoadedRule, LspBackend, LspBackendFactory, Project, RuleEvaluation, RuleLoader, RuleReport, RuleSelection, RunContext, RunEvent, } from './app/ports.js';
 import { astGrep } from './adapter/scope/astgrep.js';
 import { csv } from './adapter/scope/csv.js';
 import { file } from './adapter/scope/file.js';

package/dist/index.js

@@ -1,4 +1,4 @@
-export { Rule } from './app/rule.js';
+export { Rule, isDiffMode, isInDiff } from './app/rule.js';
 export { test } from './app/rule-tests.js';
 export { ai, pass, regex, violation } from './app/evaluators.js';
 import { astGrep } from './adapter/scope/astgrep.js';

package/dist/infra/runtime.js

@@ -1,6 +1,7 @@
 import { stat } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { join, resolve } from 'node:path';
+import { createLspBackend, createRubyLspBackend, createTypescriptLspBackend } from '../adapter/lsp/backend.js';
 import { runProgram } from '../adapter/cli/program.js';
 import { terminalCapabilities } from '../adapter/cli/progress.js';
 import { createRedactor, escapeDiagnostic } from '../adapter/cli/text.js';
@@ -67,7 +68,12 @@ export function createServices(cwd, env) {
                     ...ruleServices,
                     createProject: project.createProject,
                     resolveTarget: project.resolveTarget,
-                    runRules: execution.executeRules,
+                    runRules: (rules, runContext) => execution.executeRules(rules, {
+                        ...runContext,
+                        createLspBackend: runContext.createLspBackend ?? createLspBackend,
+                        createRubyLspBackend: runContext.createRubyLspBackend ?? createRubyLspBackend,
+                        createTypescriptLspBackend: runContext.createTypescriptLspBackend ?? createTypescriptLspBackend,
+                    }),
                     decisionResolver: (thresholdOverride, pricingOverrides) => settings.createDecisionResolver(env, thresholdOverride, pricingOverrides),
                     async collectChanges(root, base) {
                         const { collectChanges } = await import('../adapter/git/changes.js');
@@ -98,7 +104,12 @@ export function createServices(cwd, env) {
                     ...ruleServices,
                     createProject: project.createProject,
                     resolveTarget: project.resolveTarget,
-                    runRules: execution.executeRules,
+                    runRules: (rules, runContext) => execution.executeRules(rules, {
+                        ...runContext,
+                        createLspBackend: runContext.createLspBackend ?? createLspBackend,
+                        createRubyLspBackend: runContext.createRubyLspBackend ?? createRubyLspBackend,
+                        createTypescriptLspBackend: runContext.createTypescriptLspBackend ?? createTypescriptLspBackend,
+                    }),
                     decisionResolver: (thresholdOverride, pricingOverrides) => settings.createDecisionResolver(env, thresholdOverride, pricingOverrides),
                 };
             },
@@ -107,7 +118,7 @@ export function createServices(cwd, env) {
                 const { runRuleTests } = await import('../adapter/filesystem/rule-tests.js');
                 return {
                     ...ruleServices,
-                    testRules: (rules, onResult, timeoutMs, concurrency, includeAI) => runRuleTests(rules, onResult, timeoutMs, concurrency, includeAI),
+                    testRules: (rules, onResult, timeoutMs, concurrency, includeAI) => runRuleTests(rules, onResult, timeoutMs, concurrency, includeAI, false, createLspBackend, createRubyLspBackend, createTypescriptLspBackend),
                 };
             },
             async update(_context) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alex-dbs/coderuler",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "license": "Apache-2.0",
   "keywords": [
     "ai",
@@ -95,6 +95,7 @@
     "skills": "1.7.2",
     "ssri": "14.0.0",
     "string-width": "8.3.0",
+    "vscode-languageserver-protocol": "3.18.5",
     "yaml": "^2.9.1"
   },
   "devDependencies": {

package/skills/coderuler-new-rule/reference.md

@@ -334,9 +334,62 @@ Results validate; supplied messages survive reporting. Violations without a mess
 
 `changedFiles` contains paths that changed in the project. `changedLines` maps changed paths to added or replaced lines. These values are absent outside `--diff` and `--pr` runs. In those runs, an empty set means no changed files. An empty map means no exact line ranges are available. A missing entry for a path means line data is unavailable, for example for binary or conversion-attributed files. An entry with `[]` means the file changed but has no added lines.
 
+`isDiffMode(context)` returns `true` when either `changedFiles` or `changedLines` is defined, even if empty; it returns `false` when both are absent. `isInDiff(subject, context)` returns `true` when the subject's line span overlaps a known changed range; a missing span or range returns `false`.
+
+Use both helpers to keep full scans outside diff mode:
+
+```ts
+import {
+  Rule,
+  isDiffMode,
+  isInDiff,
+  type ProjectContext,
+  type ScopeSubject,
+} from '@alex-dbs/coderuler';
+
+export default class Local extends Rule {
+  filter = (subject: ScopeSubject, context: ProjectContext) =>
+    !isDiffMode(context) || isInDiff(subject, context);
+}
+```
 
 Use `trace` for decision evidence visible during inspection; keep normal execution free of ad-hoc console output. AI/regex projection callbacks receive only `ProjectContext`, not the full check context.
 
+`context.goLsp` provides Go-to-definition, declaration, type-definition, implementation, reference, hover, document-symbol, workspace-symbol, caller, and callee queries. `context.rubyLsp` provides Ruby definitions, references, hover, document symbols, and workspace symbols. `context.typescriptLsp` provides TypeScript definitions, type definitions, implementations, references, hover, document symbols, workspace symbols, callers, and callees; declaration lookup is not supported. LSP use is optional. Install Go and `gopls`, Shopify Ruby LSP (`ruby-lsp`), or native TypeScript 7's `tsc` on `PATH` only when a rule uses that language's helpers. CodeRuler does not install these servers. An unsupported operation rejects with a capability error; for example, gopls v0.24.0 does not support declaration lookup.
+
+Pass file paths and positive, 1-based line and UTF-16 column coordinates. A column counts UTF-16 code units. Navigation and hover use column 1 when omitted. Caller and callee queries (Go and TypeScript) use the enclosing named function or method when the column is omitted. Their required `depth` is a nonnegative integer; depth 1 returns direct neighbors. Set `includeDependencies: true` to include available dependency or standard-library source outside the project; the default is `false`. Ruby dependency definitions are excluded by default and can be requested with `includeDependencies: true`.
+
+Caller and callee results are a static call graph. They can omit dynamic calls and do not load every possible package consumer. Use them as the server's known call relationships, not as a complete runtime graph.
+
+Call graph helpers from an async custom check:
+
+```ts
+import { Rule, pass, scopes, violation } from '@alex-dbs/coderuler';
+import type { Evaluator } from '@alex-dbs/coderuler';
+
+export default class CallGraphCheck extends Rule {
+  files = ['**/*.go'];
+  scope = scopes.astGrep({
+    language: 'go',
+    rule: { any: [{ kind: 'function_declaration' }, { kind: 'method_declaration' }] },
+  });
+
+  check: Evaluator = async (subject, context) => {
+    if (subject.kind !== 'scope' || subject.lines === undefined) return pass();
+    const target = { filepath: subject.filepath, line: subject.lines.start };
+    const [callers, callees] = await Promise.all([
+      context.goLsp.callers(target, { depth: 2 }),
+      context.goLsp.callees(target, { depth: 2, includeDependencies: true }),
+    ]);
+    return callers.length + callees.length === 0
+      ? pass()
+      : violation('Review callers and callees');
+  };
+}
+```
+
+The example assumes `pass` and `violation` are imported from the SDK.
+
 ## Regex: matching means passing
 
 `regex<T = JsonValue>(options: RegexOptions<T>): Evaluator<T>` takes `{ readonly pattern: RegExp; readonly violationMessage?: string; readonly input?: (subject: ScopeSubject<T>, context: ProjectContext) => Awaitable<string> }`.