carrick 0.3.118 → 0.3.119

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "carrick",
-  "version": "0.3.118",
+  "version": "0.3.119",
   "carrickCache": {
     "cache_version": 22,
     "intent_cache_version": 2
@@ -113,11 +113,11 @@
     "zod": "^3.23.0"
   },
   "optionalDependencies": {
-    "@carrick-tools/cli-darwin-arm64": "0.3.118",
-    "@carrick-tools/cli-darwin-x64": "0.3.118",
-    "@carrick-tools/cli-linux-arm64": "0.3.118",
-    "@carrick-tools/cli-linux-x64": "0.3.118",
-    "@carrick-tools/cli-win32-x64": "0.3.118"
+    "@carrick-tools/cli-darwin-arm64": "0.3.119",
+    "@carrick-tools/cli-darwin-x64": "0.3.119",
+    "@carrick-tools/cli-linux-arm64": "0.3.119",
+    "@carrick-tools/cli-linux-x64": "0.3.119",
+    "@carrick-tools/cli-win32-x64": "0.3.119"
   },
   "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.118",
+  "version": "0.3.119",
   "author": {
     "name": "Carrick",
     "email": "hello@carrick.tools"

package/sidecar/dist/src/library-claims.js

@@ -89,6 +89,20 @@ const RUNTIME_TYPE_PACKAGES = new Set([
  * package's, never the runtime module.
  */
 const RUNTIME_MODULE = /^node:/;
+/**
+ * A key for the language's own library (carrick#2445): `lib:<lib file>`
+ * (`lib:lib.dom.d.ts`) names the globals that default-library file declares.
+ * Its installed version is the compiler's, so the store keys it
+ * `lib:lib.dom.d.ts@<typescript version>`. A global has no specifier: the
+ * probe reads it as `globalThis.<name>`, and its home is the default-library
+ * file set (`DEFAULT_LIBRARY_HOME`).
+ */
+const DEFAULT_LIBRARY = /^lib:/;
+/**
+ * The owner a home names for every default-library file. No package name
+ * holds a `:`, so only a `lib:` key's home ever holds it.
+ */
+const DEFAULT_LIBRARY_HOME = 'lib:';
 /** A dependency range that names the service's own source, not a registry release. */
 const LOCAL_RANGE = /^(workspace|file|link|portal):/;
 /** A resolved module lands on TypeScript: a declaration file or source. */
@@ -283,7 +297,7 @@ export class LibraryClaimsVerifier {
         }
         const importLines = importKeys.map((key, i) => {
             const [pkg, name] = JSON.parse(key);
-            return importLine(pkg, name, `__carrick_e${i}`);
+            return probeLine(pkg, name, `__carrick_e${i}`);
         });
         // One statement per receiver a message check's maker or scope claim
         // builds, after the imports: that receiver built with no argument and no
@@ -322,7 +336,8 @@ export class LibraryClaimsVerifier {
             const exportReads = new Map();
             const httpReceivers = new Map();
             const judged = new Map();
-            const declarationOf = (check) => file.statements[importIndex.get(exportKey(check))];
+            /** The probe's import of the check's export, or its read of a global (`probeLine`). */
+            const statementOf = (check) => file.statements[importIndex.get(exportKey(check))];
             /** The probe's no-argument build of `receiver` on the check's export, resolved. */
             const atDefaults = (check, receiver) => {
                 const index = builtIndex.get(builtKey(check, receiver));
@@ -333,7 +348,9 @@ export class LibraryClaimsVerifier {
                 const key = `${runtimeModules}\u0000${check.package}`;
                 let moduleRead = moduleReads.get(key);
                 if (!moduleRead) {
-                    moduleRead = reader.readModule(check.package, declarationOf(check), runtimeModules);
+                    moduleRead = DEFAULT_LIBRARY.test(check.package)
+                        ? reader.readDefaultLibrary(check.package)
+                        : reader.readModule(check.package, statementOf(check), runtimeModules);
                     moduleReads.set(key, moduleRead);
                 }
                 return moduleRead;
@@ -342,7 +359,9 @@ export class LibraryClaimsVerifier {
                 const key = exportKey(check);
                 let exportRead = exportReads.get(key);
                 if (!exportRead) {
-                    exportRead = reader.readExport(declarationOf(check));
+                    exportRead = DEFAULT_LIBRARY.test(check.package)
+                        ? reader.readGlobal(check.package, statementOf(check))
+                        : reader.readExport(statementOf(check));
                     exportReads.set(key, exportRead);
                 }
                 return exportRead;
@@ -534,15 +553,25 @@ export class LibraryClaimsVerifier {
             return { surfaces: [], surface_sha256: fullSurfaceSha256([]) };
         // Each specifier twice: as a namespace, which holds its named exports, and
         // as a default import, which is how a module that exports a value whole
-        // (`export =`) is imported as `default`.
-        const imports = packages.flatMap((pkg, i) => [
-            `import * as __carrick_ns${i} from ${JSON.stringify(pkg)};`,
-            importLine(pkg, 'default', `__carrick_d${i}`),
-        ]);
-        const probeOf = (file, i) => ({
-            namespace: file.statements[2 * i],
-            defaultImport: file.statements[2 * i + 1],
+        // (`export =`) is imported as `default`. A `lib:` key imports nothing: its
+        // globals are read from the file it names.
+        const imports = [];
+        const importAt = packages.map((pkg, i) => {
+            if (DEFAULT_LIBRARY.test(pkg))
+                return undefined;
+            const at = imports.length;
+            imports.push(`import * as __carrick_ns${i} from ${JSON.stringify(pkg)};`, importLine(pkg, 'default', `__carrick_d${i}`));
+            return at;
         });
+        const probeOf = (file, i) => {
+            const at = importAt[i];
+            return at === undefined
+                ? { defaultLibrary: packages[i] }
+                : {
+                    namespace: file.statements[at],
+                    defaultImport: file.statements[at + 1],
+                };
+        };
         const makers = this.readProbe(fromDir, imports, (_checker, reader, file) => packages.map((pkg, i) => reader.makersOf(pkg, probeOf(file, i), only[pkg])));
         const importLines = [];
         const buildLines = [];
@@ -550,7 +579,7 @@ export class LibraryClaimsVerifier {
         packages.forEach((pkg, i) => {
             for (const { export: name, receivers } of makers[i]) {
                 const local = `__carrick_e${importLines.length}`;
-                importLines.push(importLine(pkg, name, local));
+                importLines.push(probeLine(pkg, name, local));
                 for (const receiver of receivers) {
                     const expression = receiverExpression(local, receiver);
                     if (expression === undefined)
@@ -744,6 +773,18 @@ function typeSymbols(type) {
     }
     return symbols;
 }
+/**
+ * The probe's read of one export, bound to `local`: its import, or for a
+ * `lib:` key the global itself, as `globalThis` holds it. A block-scoped
+ * global (`declare const`) is not on `globalThis`; no default-library file
+ * declares one.
+ */
+function probeLine(pkg, name, local) {
+    if (!DEFAULT_LIBRARY.test(pkg))
+        return importLine(pkg, name, local);
+    const access = IDENTIFIER.test(name) ? `.${name}` : `[${JSON.stringify(name)}]`;
+    return `const ${local} = globalThis${access};`;
+}
 /** The probe's import of one export, bound to `local`. */
 function importLine(pkg, name, local) {
     const specifier = JSON.stringify(pkg);
@@ -943,6 +984,54 @@ class DeclarationReader {
             ?.redirectInfo?.redirectTarget;
         return target === file && this.isInstalledFile(file.fileName);
     }
+    /**
+     * A `lib:` key: the default-library file it names, as the program's own
+     * `lib` setting loads it, read by the compiler that built the program. A
+     * file the program does not load is no module reason: each global answers
+     * `export_missing` (`readGlobal`).
+     */
+    readDefaultLibrary(pkg) {
+        const entry = { package: pkg, installed_version: ts.version };
+        const file = this.defaultLibraryFile(pkg);
+        if (file)
+            entry.resolved_file = file.fileName;
+        return { entry };
+    }
+    /** The default-library file a `lib:` key names, when the program loads it. */
+    defaultLibraryFile(pkg) {
+        const name = pkg.slice('lib:'.length);
+        return this.program
+            .getSourceFiles()
+            .find(file => this.program.isSourceFileDefaultLibrary(file) && path.basename(file.fileName) === name);
+    }
+    /**
+     * `T` for a global (`probeLine`'s `globalThis` read): the type the probe's
+     * local gets, and the global it names. The global must be a value the
+     * key's lib file declares; one only another file declares (the runtime's
+     * types, the service) is missing from it.
+     */
+    readGlobal(pkg, statement) {
+        const declaration = statement && ts.isVariableStatement(statement) ? statement.declarationList.declarations[0] : undefined;
+        const access = declaration?.initializer;
+        const name = access && ts.isPropertyAccessExpression(access)
+            ? access.name
+            : access && ts.isElementAccessExpression(access)
+                ? access.argumentExpression
+                : undefined;
+        const target = name ? this.checker.getSymbolAtLocation(name) : undefined;
+        const file = this.defaultLibraryFile(pkg);
+        if (!declaration ||
+            !target ||
+            !file ||
+            !(target.flags & ts.SymbolFlags.Value) ||
+            !(target.declarations ?? []).some(each => each.getSourceFile() === file)) {
+            return { reason: 'export_missing' };
+        }
+        const type = this.checker.getTypeAtLocation(declaration.name);
+        if (this.isOpenTop(type))
+            return { reason: 'export_untyped' };
+        return { value: { type, target } };
+    }
     /** `T`: the type the probe's import gets, and the declaration it names. */
     readExport(declaration) {
         const clause = declaration.importClause;
@@ -1038,6 +1127,9 @@ class DeclarationReader {
      * sub-object's, along a claim's `path`).
      */
     homeOf(pkg, symbols, base) {
+        // A global's home is the default-library file set, and only that.
+        if (DEFAULT_LIBRARY.test(pkg))
+            return base ?? new Set([DEFAULT_LIBRARY_HOME]);
         const named = packageNameOf(pkg);
         const home = new Set(base ?? [named, typesPackageOf(named)]);
         const runtime = RUNTIME_MODULE.test(pkg) || RUNTIME_TYPE_PACKAGES.has(named) || RUNTIME_TYPE_PACKAGES.has(typesPackageOf(named));
@@ -1061,6 +1153,8 @@ class DeclarationReader {
         return installed === undefined ? undefined : installed.packageName ?? installed.directoryName;
     }
     isOwnFile(file, home) {
+        if (this.program.isSourceFileDefaultLibrary(file))
+            return home.has(DEFAULT_LIBRARY_HOME);
         const owner = this.packageOf(file);
         return owner !== undefined && home.has(owner);
     }
@@ -2231,7 +2325,7 @@ class DeclarationReader {
         this.setPackage(pkg);
         // Runtime modules on: a `node:` specifier is listed from the runtime's
         // types package, as the message roles read it.
-        const moduleRead = this.readModule(pkg, probe.namespace, true);
+        const moduleRead = 'defaultLibrary' in probe ? this.readDefaultLibrary(pkg) : this.readModule(pkg, probe.namespace, true);
         const surface = { package: pkg, truncated: 0, exports: [] };
         if (moduleRead.entry.resolved_file)
             surface.resolved_file = moduleRead.entry.resolved_file;
@@ -2294,7 +2388,7 @@ class DeclarationReader {
      */
     makersOf(pkg, probe, only) {
         this.setPackage(pkg);
-        if (this.readModule(pkg, probe.namespace, true).reason)
+        if ('namespace' in probe && this.readModule(pkg, probe.namespace, true).reason)
             return [];
         return (this.listedExports(probe, only) ?? [])
             .filter(({ type }) => !this.isOpenTop(type))
@@ -2314,6 +2408,8 @@ class DeclarationReader {
      * resolves to no module symbol.
      */
     listedExports(probe, only) {
+        if ('defaultLibrary' in probe)
+            return this.listedGlobals(probe.defaultLibrary, only);
         const moduleSymbol = this.checker.getSymbolAtLocation(probe.namespace.moduleSpecifier);
         if (!moduleSymbol)
             return undefined;
@@ -2339,6 +2435,23 @@ class DeclarationReader {
         }
         return listed.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
     }
+    /**
+     * The value globals a `lib:` key's file declares (every one, or only those
+     * `only` names), sorted by name, each with its declared type: none when the
+     * program's `lib` setting does not load the file.
+     */
+    listedGlobals(pkg, only) {
+        const file = this.defaultLibraryFile(pkg);
+        if (!file)
+            return [];
+        return this.checker
+            .getSymbolsInScope(this.probe, ts.SymbolFlags.Value)
+            .filter(symbol => (symbol.flags & ts.SymbolFlags.Prototype) === 0 &&
+            (only === undefined || only.includes(symbol.getName())) &&
+            (symbol.declarations ?? []).some(declaration => declaration.getSourceFile() === file))
+            .map(symbol => ({ name: symbol.getName(), target: symbol, type: this.checker.getTypeOfSymbol(symbol) }))
+            .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+    }
     /**
      * The ways an export makes a receiver, in listing order: calling it
      * (`instance:()`), constructing it (`instance:new`), then calling or

package/sidecar/dist/src/position-rows.d.ts

@@ -55,6 +55,15 @@ export declare const FLAG_CHECKER_THREW = 4;
 export declare const FLAG_DECLARATION_UNNAMED = 8;
 /** An `impl` row standing for more implementations than {@link IMPL_CAP}; it names none. */
 export declare const FLAG_TOO_MANY = 16;
+/**
+ * The declaration is published under the row's symbol name: its module
+ * exports it by that name, or it is a global (a script's top-level
+ * declaration, or one in `declare global`). A member of a class, interface,
+ * type literal or object literal never is (carrick#2508).
+ */
+export declare const FLAG_PUBLISHED = 32;
+/** The declaration is what its module exports as `export =` or `default` (carrick#2508). */
+export declare const FLAG_MODULE_DEFAULT = 64;
 /** The most implementations one declaration's `impl` rows list. */
 export declare const IMPL_CAP = 16;
 /** The kinds {@link kindOf} gives a node; `impl` and `jsx` rows are written beside them. */

package/sidecar/dist/src/position-rows.js

@@ -60,6 +60,15 @@ export const FLAG_CHECKER_THREW = 4;
 export const FLAG_DECLARATION_UNNAMED = 8;
 /** An `impl` row standing for more implementations than {@link IMPL_CAP}; it names none. */
 export const FLAG_TOO_MANY = 16;
+/**
+ * The declaration is published under the row's symbol name: its module
+ * exports it by that name, or it is a global (a script's top-level
+ * declaration, or one in `declare global`). A member of a class, interface,
+ * type literal or object literal never is (carrick#2508).
+ */
+export const FLAG_PUBLISHED = 32;
+/** The declaration is what its module exports as `export =` or `default` (carrick#2508). */
+export const FLAG_MODULE_DEFAULT = 64;
 /** The most implementations one declaration's `impl` rows list. */
 export const IMPL_CAP = 16;
 const COMPARE_OPERATORS = new Set([
@@ -379,6 +388,8 @@ class PositionWalker {
     implementations = new Map();
     /** The same for a member whose symbol has no declaration, keyed by symbol. */
     undeclaredImplementations = new Map();
+    /** Each module's exports by name, and its `export =` and `default` targets, aliases followed. */
+    moduleExports = new Map();
     constructor(program, service, paths, loader) {
         this.program = program;
         this.service = service;
@@ -424,6 +435,9 @@ class PositionWalker {
                 this.ownerDeclaration(kind, node, symbol);
             if (!declaration)
                 return [kind, start, end, ts.symbolName(symbol), null, null, null, typeText, flags];
+            // A declaration named through its owner's type is a member.
+            if ((symbol.declarations ?? []).includes(declaration))
+                flags |= this.publication(symbol, declaration);
             // A file's own module symbol is named by the compiler as the quoted
             // absolute file name (`"/<checkout>/pkg/index"`). Name it as `decl_file`
             // names the file. A symbol that merely lives in a file (CommonJS
@@ -580,6 +594,68 @@ class PositionWalker {
         const owner = holders[0].getSymbol() ?? holders[0].aliasSymbol;
         return attributedDeclaration(() => this.program, owner?.declarations ?? []);
     }
+    /**
+     * How `declaration`'s module publishes `symbol`: {@link FLAG_PUBLISHED}
+     * when under the symbol's own name (or as a global), and
+     * {@link FLAG_MODULE_DEFAULT} when as the module's `export =` or `default`.
+     * The module is the nearest ambient `declare module "…"` or the file.
+     */
+    publication(symbol, declaration) {
+        let container = declaration.parent;
+        while (container && !ts.isSourceFile(container) && !ts.isModuleBlock(container)) {
+            // Anything but a statement list between the declaration and its module
+            // (a class, interface, type or object literal, a function body) makes
+            // it a member or a local.
+            if (!ts.isVariableDeclarationList(container) && !ts.isVariableStatement(container))
+                return 0;
+            container = container.parent;
+        }
+        if (!container)
+            return 0;
+        const block = ts.isModuleBlock(container) ? container.parent : undefined;
+        if (block && block.flags & ts.NodeFlags.GlobalAugmentation)
+            return FLAG_PUBLISHED;
+        // A namespace's member is published when the module its file is publishes it.
+        if (block && !ts.isStringLiteral(block.name))
+            return this.publishedByExports(symbol, declaration);
+        const moduleSymbol = this.checker.getSymbolAtLocation(block ? block.name : container);
+        if (moduleSymbol)
+            return this.publishedIn(moduleSymbol, symbol);
+        // A script's top-level declaration is a global.
+        return ts.isSourceFile(container) && !ts.isExternalModule(container) ? FLAG_PUBLISHED : 0;
+    }
+    /** A namespace member, found among the exports of the module it sits in. */
+    publishedByExports(symbol, declaration) {
+        for (let node = declaration.parent; node; node = node.parent) {
+            if (ts.isModuleDeclaration(node) && ts.isStringLiteral(node.name)) {
+                const moduleSymbol = this.checker.getSymbolAtLocation(node.name);
+                return moduleSymbol ? this.publishedIn(moduleSymbol, symbol) : 0;
+            }
+            if (ts.isSourceFile(node)) {
+                const moduleSymbol = this.checker.getSymbolAtLocation(node);
+                return moduleSymbol ? this.publishedIn(moduleSymbol, symbol) & FLAG_PUBLISHED : 0;
+            }
+        }
+        return 0;
+    }
+    publishedIn(moduleSymbol, symbol) {
+        let exports = this.moduleExports.get(moduleSymbol);
+        if (!exports) {
+            const resolve = (s) => s.flags & ts.SymbolFlags.Alias ? this.checker.getAliasedSymbol(s) : s;
+            const byName = new Map();
+            for (const exported of this.checker.getExportsOfModule(moduleSymbol)) {
+                byName.set(exported.getName(), resolve(exported));
+            }
+            const wholes = [ts.InternalSymbolName.ExportEquals, ts.InternalSymbolName.Default]
+                .map((key) => moduleSymbol.exports?.get(key))
+                .filter((own) => own !== undefined)
+                .map(resolve);
+            exports = { byName, wholes };
+            this.moduleExports.set(moduleSymbol, exports);
+        }
+        return ((exports.byName.get(symbol.getName()) === symbol ? FLAG_PUBLISHED : 0) |
+            (exports.wholes.includes(symbol) ? FLAG_MODULE_DEFAULT : 0));
+    }
     /** The row's symbol, following aliases to a target that has a declaration. */
     symbolOf(kind, node) {
         let symbol;