carrick 0.3.125 → 0.3.127

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "carrick",
-  "version": "0.3.125",
+  "version": "0.3.127",
   "carrickCache": {
     "cache_version": 22,
     "intent_cache_version": 2
@@ -113,11 +113,11 @@
     "zod": "^3.23.0"
   },
   "optionalDependencies": {
-    "@carrick-tools/cli-darwin-arm64": "0.3.125",
-    "@carrick-tools/cli-darwin-x64": "0.3.125",
-    "@carrick-tools/cli-linux-arm64": "0.3.125",
-    "@carrick-tools/cli-linux-x64": "0.3.125",
-    "@carrick-tools/cli-win32-x64": "0.3.125"
+    "@carrick-tools/cli-darwin-arm64": "0.3.127",
+    "@carrick-tools/cli-darwin-x64": "0.3.127",
+    "@carrick-tools/cli-linux-arm64": "0.3.127",
+    "@carrick-tools/cli-linux-x64": "0.3.127",
+    "@carrick-tools/cli-win32-x64": "0.3.127"
   },
   "devDependencies": {
     "@types/node": "^24.13.3"

package/plugin/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "carrick",
   "description": "Claude Code plugin for Carrick, which indexes TypeScript codebases across service and repository boundaries. After each edit it adds the file's routes, calls, and cross-service type mismatches to the session, and it registers Carrick's language server. It pairs with the Carrick MCP server, which lets agents search functions by intent rather than name.",
-  "version": "0.3.125",
+  "version": "0.3.127",
   "author": {
     "name": "Carrick",
     "email": "hello@carrick.tools"

package/sidecar/dist/src/capture/api.d.ts

@@ -212,10 +212,14 @@ export type SelfCheckOutcome = 'ok' | 'allowlisted_external' | 'decayed_internal
  *    serialised itself, and at least one return builds that string in a way
  *    the inferrer cannot trace to a typed value, so it publishes no part of
  *    the contract (carrick#2200).
+ *  - `body_built_by_callee`: a request locator names an argument of a call
+ *    into a function that builds the request body from it, and the body that
+ *    function builds cannot be typed, so the argument is not the body and no
+ *    contract is published (carrick#2628).
  *  - `not_recorded`: the position carries a top type and this layer has no
  *    cause for it.
  */
-export type TypeProvenanceReason = 'declared' | 'unresolved_import' | 'budget_exhausted' | 'no_payload_evidence' | 'machinery_envelope' | 'coerced_input' | 'no_success_payload' | 'no_request_body' | 'projected_value_only' | 'serialised_body_unread' | 'not_recorded';
+export type TypeProvenanceReason = 'declared' | 'unresolved_import' | 'budget_exhausted' | 'no_payload_evidence' | 'machinery_envelope' | 'coerced_input' | 'no_success_payload' | 'no_request_body' | 'projected_value_only' | 'serialised_body_unread' | 'body_built_by_callee' | 'not_recorded';
 /**
  * One `any`/`unknown` finding inside a captured or inferred type, with its
  * position and its cause. Sorted by `path` wherever a list is emitted, so the

package/sidecar/dist/src/capture/deno-project.d.ts

@@ -39,6 +39,13 @@ export declare class DenoProject {
      * no identity. A file the workspace itself owns belongs to no package and
      * answers nothing, exactly as a workspace-declared type does under Node. */
     packageOf(file: string): string | undefined;
+    /** The npm package directory a resolved file lies in, and the package's
+     * name: its cache directory, which carries no `node_modules` segment, so
+     * only the graph can say where the package starts (carrick#2599). */
+    packageDirectoryOf(file: string): {
+        directory: string;
+        name: string;
+    } | undefined;
     private isNpmFile;
     /** Let TypeScript interpret real package exports/types using Deno's exact
      * dependency graph. Only the resolution host sees virtual node_modules;

package/sidecar/dist/src/capture/deno-project.js

@@ -280,6 +280,13 @@ export class DenoProject {
         const specifier = this.specifiersByPath.get(resolved);
         return specifier ? jsrPackageName(specifier) : undefined;
     }
+    /** The npm package directory a resolved file lies in, and the package's
+     * name: its cache directory, which carries no `node_modules` segment, so
+     * only the graph can say where the package starts (carrick#2599). */
+    packageDirectoryOf(file) {
+        const owner = this.npmOwner(path.resolve(file));
+        return owner?.localPath ? { directory: owner.localPath, name: owner.name } : undefined;
+    }
     isNpmFile(file) {
         return !!this.npmOwner(file) || file.split(path.sep).includes('node_modules');
     }

package/sidecar/dist/src/declaration-attribution.d.ts

@@ -20,6 +20,17 @@ import type { ts } from 'ts-morph';
  * with one declaration needs none.
  */
 export declare function attributedDeclaration<T extends ts.Node>(programOf: () => ts.Program, declarations: readonly T[]): T | undefined;
+/**
+ * The declaration a member is attributed to when it is read on `holder`: its
+ * own ({@link attributedDeclaration}), or, for a member with none (a mapped
+ * type's), the declaration of the holder's type: its symbol's, else its alias
+ * symbol's (carrick#2448). The per-position rows and a library verdict's
+ * `declarations` (carrick#2654) both name a member this way, so a verdict
+ * joins the row of the call it judges.
+ */
+export declare function memberDeclaration(programOf: () => ts.Program, member: ts.Symbol, holder: ts.Type): ts.Declaration | undefined;
+/** The declaration of a type's symbol, else of its alias symbol: a mapped type node, or the alias naming it. */
+export declare function typeDeclaration(programOf: () => ts.Program, type: ts.Type): ts.Declaration | undefined;
 /**
  * The npm package a declaring file belongs to, by the module graph where
  * there is one and by its path otherwise. `undefined` when neither names one.

package/sidecar/dist/src/declaration-attribution.js

@@ -31,6 +31,22 @@ export function attributedDeclaration(programOf, declarations) {
         return pathA < pathB ? -1 : pathA > pathB ? 1 : a.getStart() - b.getStart();
     })[0];
 }
+/**
+ * The declaration a member is attributed to when it is read on `holder`: its
+ * own ({@link attributedDeclaration}), or, for a member with none (a mapped
+ * type's), the declaration of the holder's type: its symbol's, else its alias
+ * symbol's (carrick#2448). The per-position rows and a library verdict's
+ * `declarations` (carrick#2654) both name a member this way, so a verdict
+ * joins the row of the call it judges.
+ */
+export function memberDeclaration(programOf, member, holder) {
+    return attributedDeclaration(programOf, member.declarations ?? []) ?? typeDeclaration(programOf, holder);
+}
+/** The declaration of a type's symbol, else of its alias symbol: a mapped type node, or the alias naming it. */
+export function typeDeclaration(programOf, type) {
+    const owner = type.getSymbol() ?? type.aliasSymbol;
+    return attributedDeclaration(programOf, owner?.declarations ?? []);
+}
 /**
  * The npm package a declaring file belongs to, by the module graph where
  * there is one and by its path otherwise. `undefined` when neither names one.

package/sidecar/dist/src/implementations.d.ts

@@ -0,0 +1,43 @@
+/**
+ * The implementations of a bodyless declaration, asked where discovery stops
+ * at one (carrick#2432 slice B): a call through an interface's method, a
+ * function-typed property or an abstract member, whose receiver the scanner
+ * cannot follow to a value.
+ *
+ * Each question is the span of a `call` (or `member`) position row, in the
+ * rows' numbering (UTF-16 code units from the start of the file, as the
+ * scanner's `sidecar_position` gives). The call's symbol and declaration are
+ * read exactly as the row read them ({@link PositionWalker.symbolOf}), and
+ * go-to-implementation is asked once per declaration, at its name, over the
+ * language service's program of the project that owns the file. That is the
+ * analysis program: nothing here releases it.
+ *
+ * Each answer:
+ * - holds none of the declaration's own signatures: asked at an overloaded
+ *   interface or abstract method, go-to-implementation names only the bodies
+ *   that implement it (TypeScript 6.0, pinned in implementations.test.ts).
+ *   The walk's filter for them (`implementationRows`, removed in #2561) is
+ *   not carried over: no bodyless declaration reaches it;
+ * - names each implementation as a row names a declaration
+ *   ({@link PositionWalker.located}), at the implementation's declaration's
+ *   start, so it joins to a definition as a `call` row at it would;
+ * - is sorted by file, then position;
+ * - holds at most {@link IMPLEMENTATIONS_CAP}; past it, none, and `too_many`.
+ *
+ * The position rows carry no implementations (version 4, carrick#2561): this
+ * action is the only place they are asked.
+ */
+import type { ProjectLoader } from './project-loader.js';
+import type { ImplementationsAnswer, ImplementationsQuery } from './types.js';
+/** The most implementations one answer lists. */
+export declare const IMPLEMENTATIONS_CAP = 16;
+export interface ImplementationsOptions {
+    loader: ProjectLoader;
+    /** Every name in an answer is relative to it, as in the position rows. */
+    scanRoot: string;
+    queries: ImplementationsQuery[];
+    /** Called after each question is answered. */
+    onAnswer?: () => void;
+}
+/** One answer per question, in request order. */
+export declare function findImplementations(options: ImplementationsOptions): ImplementationsAnswer[];

package/sidecar/dist/src/implementations.js

@@ -0,0 +1,224 @@
+/**
+ * The implementations of a bodyless declaration, asked where discovery stops
+ * at one (carrick#2432 slice B): a call through an interface's method, a
+ * function-typed property or an abstract member, whose receiver the scanner
+ * cannot follow to a value.
+ *
+ * Each question is the span of a `call` (or `member`) position row, in the
+ * rows' numbering (UTF-16 code units from the start of the file, as the
+ * scanner's `sidecar_position` gives). The call's symbol and declaration are
+ * read exactly as the row read them ({@link PositionWalker.symbolOf}), and
+ * go-to-implementation is asked once per declaration, at its name, over the
+ * language service's program of the project that owns the file. That is the
+ * analysis program: nothing here releases it.
+ *
+ * Each answer:
+ * - holds none of the declaration's own signatures: asked at an overloaded
+ *   interface or abstract method, go-to-implementation names only the bodies
+ *   that implement it (TypeScript 6.0, pinned in implementations.test.ts).
+ *   The walk's filter for them (`implementationRows`, removed in #2561) is
+ *   not carried over: no bodyless declaration reaches it;
+ * - names each implementation as a row names a declaration
+ *   ({@link PositionWalker.located}), at the implementation's declaration's
+ *   start, so it joins to a definition as a `call` row at it would;
+ * - is sorted by file, then position;
+ * - holds at most {@link IMPLEMENTATIONS_CAP}; past it, none, and `too_many`.
+ *
+ * The position rows carry no implementations (version 4, carrick#2561): this
+ * action is the only place they are asked.
+ */
+import * as path from 'node:path';
+import { ts } from 'ts-morph';
+import { attributedDeclaration } from './declaration-attribution.js';
+import { PathNames, PositionWalker, compareNames, kindOf } from './position-rows.js';
+/** The most implementations one answer lists. */
+export const IMPLEMENTATIONS_CAP = 16;
+/** One answer per question, in request order. */
+export function findImplementations(options) {
+    const { loader, scanRoot, queries } = options;
+    const paths = new PathNames(scanRoot);
+    const answers = new Array(queries.length);
+    const groups = new Map();
+    queries.forEach((query, index) => {
+        const key = loader.projectKeyFor(path.resolve(query.file));
+        groups.set(key, [...(groups.get(key) ?? []), index]);
+    });
+    for (const [key, indexes] of groups) {
+        const service = loader.getProjectFor(key).getLanguageService().compilerObject;
+        const program = service.getProgram();
+        if (!program)
+            throw new Error('the language service built no program');
+        const finder = new ImplementationFinder(program, service, new PositionWalker(program, paths, loader));
+        for (const index of indexes) {
+            answers[index] = finder.answer(queries[index]);
+            options.onAnswer?.();
+        }
+    }
+    return answers;
+}
+/** An answer with nothing found, and why. */
+function none(reason, declaration = null) {
+    return { declaration, implementations: [], too_many: false, reason };
+}
+class ImplementationFinder {
+    program;
+    service;
+    walker;
+    checker;
+    /** Answers by declaration: a declaration is searched once, however many calls reach it. */
+    searched = new Map();
+    constructor(program, service, walker) {
+        this.program = program;
+        this.service = service;
+        this.walker = walker;
+        this.checker = program.getTypeChecker();
+    }
+    answer(query) {
+        const sourceFile = this.program.getSourceFile(path.resolve(query.file));
+        if (!sourceFile)
+            return none('not_in_program');
+        const found = positionAt(sourceFile, query.start, query.end);
+        if (!found)
+            return none('no_call');
+        let declaration;
+        let named = null;
+        try {
+            const symbol = this.walker.symbolOf(found.kind, found.node);
+            if (!symbol)
+                return none('no_symbol');
+            declaration = attributedDeclaration(() => this.program, symbol.declarations ?? []);
+            if (!declaration)
+                return none('no_declaration');
+            named = this.named(declaration, ts.symbolName(symbol));
+            if (!isBodyless(declaration, this.checker))
+                return none('has_body', named);
+        }
+        catch {
+            return none('checker_threw', named);
+        }
+        let searched = this.searched.get(declaration);
+        if (!searched) {
+            try {
+                searched = this.implementationsOf(declaration);
+            }
+            catch {
+                return none('checker_threw', named);
+            }
+            this.searched.set(declaration, searched);
+        }
+        return { declaration: named, ...searched };
+    }
+    /** A declaration as a row names it: its symbol, file and line. */
+    named(declaration, symbol) {
+        const file = declaration.getSourceFile();
+        const { declFile, declLine, declPackage } = this.walker.located(file, declaration.getStart(file));
+        return { symbol, decl_file: declFile, decl_line: declLine, decl_package: declPackage };
+    }
+    /**
+     * What go-to-implementation names for `declaration`, asked at its name,
+     * in file and position order.
+     */
+    implementationsOf(declaration) {
+        const name = ts.getNameOfDeclaration(declaration) ?? declaration;
+        const declaringFile = name.getSourceFile();
+        const found = new Map();
+        for (const location of this.service.getImplementationAtPosition(declaringFile.fileName, name.getStart(declaringFile)) ?? []) {
+            const file = this.program.getSourceFile(location.fileName);
+            if (!file)
+                continue;
+            const start = location.textSpan.start;
+            found.set(`${location.fileName}\u0000${start}`, { file, start });
+        }
+        if (found.size > IMPLEMENTATIONS_CAP)
+            return { implementations: [], too_many: true };
+        const implementations = [...found.values()].map(({ file, start }) => {
+            const at = nodeStartingAt(file, start);
+            const symbol = at ? this.checker.getSymbolAtLocation(at) : undefined;
+            // The declaration the answer points into, so its line is the one a
+            // `call` row at the implementation names: the declaration's start,
+            // decorators and modifiers included, not its name's.
+            const holder = symbol?.declarations?.find((d) => d.getSourceFile() === file && d.getStart(file) <= start && start < d.end) ??
+                (at ? enclosingDeclaration(at) : undefined);
+            const placed = holder ? holder.getStart(file) : start;
+            const { declFile, declLine, declPackage } = this.walker.located(file, placed);
+            return {
+                file: declFile,
+                start: placed,
+                named: { symbol: symbol ? ts.symbolName(symbol) : null, decl_file: declFile, decl_line: declLine, decl_package: declPackage },
+            };
+        });
+        implementations.sort((a, b) => compareNames(a.file, b.file) || a.start - b.start);
+        return { implementations: implementations.map(({ named }) => named), too_many: false };
+    }
+}
+/**
+ * The `call` or `member` position whose span is exactly `start..end`: the
+ * node a row of that kind was written at. A call is preferred where both
+ * kinds share the span.
+ */
+function positionAt(file, start, end) {
+    let member;
+    let call;
+    const visit = (node) => {
+        const nodeStart = node.getStart(file);
+        if (end <= nodeStart || node.getEnd() < start)
+            return;
+        if (nodeStart === start && node.getEnd() === end) {
+            const kind = kindOf(node);
+            if (kind === 'call')
+                call ??= node;
+            if (kind === 'member')
+                member ??= node;
+        }
+        ts.forEachChild(node, visit);
+    };
+    ts.forEachChild(file, visit);
+    if (call)
+        return { kind: 'call', node: call };
+    if (member)
+        return { kind: 'member', node: member };
+    return undefined;
+}
+/**
+ * Whether a declaration has no body for a call to run: an interface's or type
+ * literal's method, a function-typed property signature, an abstract method or
+ * property, or a function-typed class property or parameter with no
+ * initializer. Its implementations are what go-to-implementation names.
+ */
+function isBodyless(declaration, checker) {
+    const functionTyped = () => checker.getTypeAtLocation(declaration).getNonNullableType().getCallSignatures().length > 0;
+    if (ts.isMethodSignature(declaration))
+        return true;
+    if (ts.isPropertySignature(declaration))
+        return functionTyped();
+    if (ts.isMethodDeclaration(declaration) || ts.isPropertyDeclaration(declaration)) {
+        if (ts.getCombinedModifierFlags(declaration) & ts.ModifierFlags.Abstract)
+            return true;
+        return ts.isPropertyDeclaration(declaration) && !declaration.initializer && functionTyped();
+    }
+    if (ts.isParameter(declaration))
+        return !declaration.initializer && functionTyped();
+    return false;
+}
+/** The innermost node of `file` that starts at `position` (an implementation's name). */
+function nodeStartingAt(file, position) {
+    let found;
+    const visit = (node) => {
+        if (position < node.getStart(file) || position >= node.getEnd())
+            return;
+        if (node.getStart(file) === position)
+            found = node;
+        ts.forEachChild(node, visit);
+    };
+    ts.forEachChild(file, visit);
+    return found;
+}
+/** The nearest declaration holding `node`: what an answer with no symbol points into. */
+function enclosingDeclaration(node) {
+    for (let at = node; at && !ts.isSourceFile(at); at = at.parent) {
+        if (ts.isFunctionLike(at) || ts.isClassLike(at) || ts.isPropertyAssignment(at) || ts.isVariableDeclaration(at)) {
+            return at;
+        }
+    }
+    return undefined;
+}

package/sidecar/dist/src/index.js

@@ -30,6 +30,7 @@ import { PROGRESS_INTERVAL_MS, atMostEvery } from './progress.js';
 import { mergeInferTimings } from './infer-timing.js';
 import { addProgramFiles, listProgramFiles } from './program-files.js';
 import { writePositionRows } from './position-rows.js';
+import { findImplementations } from './implementations.js';
 // ===========================================================================
 // Module-level state
 // ===========================================================================
@@ -55,6 +56,18 @@ function initializedLoader() {
     }
     return projectLoader;
 }
+/**
+ * carrick#2100: the unwidened reading's budget in milliseconds, when
+ * `CARRICK_UNWIDENED_BUDGET_MS` sets one. A switch for tests that drive the
+ * scanner's binary: it forces the budget to run out on any machine. Unset or
+ * not a whole number of milliseconds, the inferrer's default stands.
+ */
+function unwidenedBudgetFromEnv() {
+    const value = process.env.CARRICK_UNWIDENED_BUDGET_MS;
+    if (value === undefined || !/^\d+$/.test(value.trim()))
+        return undefined;
+    return Number(value.trim());
+}
 /**
  * Get the project-backed components, building the project if this is the
  * first request that needs it.
@@ -77,6 +90,7 @@ function projectComponents(key = '') {
             project,
             repoRoot,
             packageOf: (filePath) => loader.packageOf(filePath),
+            unwidenedBudgetMs: unwidenedBudgetFromEnv(),
         });
         built = {
             typeBundler: new TypeBundler({ project, repoRoot }),
@@ -90,7 +104,10 @@ function projectComponents(key = '') {
             // (`npm/carrick/package.json`) resolves `typescript ^5.8.0` unpinned,
             // so an install can pair ts-morph's copy with a newer 5.x.
             retyper: new Retyper(project, typeInferrer, jsonWireDeclarations, findDisqualifyingTopTypes),
-            claimsVerifier: new LibraryClaimsVerifier(project),
+            claimsVerifier: new LibraryClaimsVerifier(project, {
+                packageDirectoryOf: (file) => loader.packageDirectoryOf(file),
+                resolveModule: (name, from, options) => loader.resolveThroughGraph(name, from, options),
+            }),
         };
         components.set(key, built);
     }
@@ -556,6 +573,34 @@ function handleAddProgramFiles(request) {
         return { request_id: request.request_id, status: 'error', errors: [error] };
     }
 }
+/**
+ * Handle the 'implementations' action - the implementations of the bodyless
+ * declaration each call goes through (carrick#2432). Asked of the analysis
+ * process: it reads the programs the service's other actions read, and
+ * releases none of them.
+ */
+function handleImplementations(request) {
+    try {
+        const loader = initializedLoader();
+        let done = 0;
+        const report = atMostEvery(PROGRESS_INTERVAL_MS, () => writeProgress(request.request_id, 'implementations', `${done} of ${request.queries.length}`));
+        const answers = findImplementations({
+            loader,
+            scanRoot: request.scan_root,
+            queries: request.queries,
+            onAnswer: () => {
+                done += 1;
+                report();
+            },
+        });
+        return { request_id: request.request_id, status: 'success', result: { answers } };
+    }
+    catch (err) {
+        const error = err instanceof Error ? err.message : String(err);
+        logError(`Implementations failed: ${error}`);
+        return { request_id: request.request_id, status: 'error', errors: [error] };
+    }
+}
 /**
  * Handle the 'position_rows' action - write the compiler's rows for each
  * call, member access, comparison and identifier of the given files
@@ -648,6 +693,8 @@ function handleRequest(request) {
             return handleAddProgramFiles(request);
         case 'position_rows':
             return handlePositionRows(request);
+        case 'implementations':
+            return handleImplementations(request);
         case 'health':
             return handleHealth(request);
         case 'shutdown':

package/sidecar/dist/src/library-claims.d.ts

@@ -35,7 +35,8 @@
  * package's: a `paths` alias or a `declare module` block the service writes
  * for itself is not evidence about the library.
  */
-import { type Project } from 'ts-morph';
+import { ts, type Project } from 'ts-morph';
+import { type PackageDirectoryOf } from './position-rows.js';
 import type { LibraryCheck, LibrarySurface, SemanticsCheck, SemanticsModule, SemanticsResult } from './types.js';
 export interface VerifyResult {
     semantics: SemanticsResult[];
@@ -54,9 +55,23 @@ export interface VerifyResult {
  *   options at argument 1; `request_body` adds the body key there.
  */
 export declare function httpCheck(check: SemanticsCheck): LibraryCheck;
+/**
+ * What a project's module graph says, where it resolved through one rather
+ * than through `node_modules` (carrick#2599). Such a resolver serves a package
+ * from a cache whose path has no `node_modules` segment, so neither the path
+ * nor a Node resolution of the package name finds the files the program
+ * loaded.
+ */
+export interface ModuleGraph {
+    /** The installed package directory a file lies in, and its name. */
+    packageDirectoryOf: PackageDirectoryOf;
+    /** How the program resolves `name` from `from`; `undefined` where there is no graph, and Node resolution answers. */
+    resolveModule(name: string, from: string, options: ts.CompilerOptions): ts.ResolvedModuleFull | undefined;
+}
 export declare class LibraryClaimsVerifier {
     private readonly project;
-    constructor(project: Project);
+    private readonly graph;
+    constructor(project: Project, graph?: ModuleGraph);
     /**
      * Judge every check, in request order, spending at most `budgetMs`. Checks
      * the budget does not reach come back `unchecked` with reason `budget`.