carrick 0.3.103 → 0.3.105

package/sidecar/dist/src/capture/deep-walk.js

@@ -14,6 +14,7 @@
  * wherever it is reported.
  */
 import ts from 'typescript';
+import { memberPath } from './member-name.js';
 /** Cap on findings reported per alias. The FIRST one is what the check phase
  * pre-gates on, so verdicts never depend on this number; the rest are there to
  * tell a reader which fields are `any` (carrick#376), and a type with more
@@ -73,7 +74,7 @@ export function findUnresolvedPlaceholders(root, program, checker, location) {
 }
 /** TypeScript's unresolved-reference placeholder: `TypeFlags.Any` with the
  * internal `intrinsicName === 'error'` (stable since TS 1.x; see `anchors.ts`). */
-function isErrorPlaceholder(t) {
+export function isErrorPlaceholder(t) {
     return ((t.flags & ts.TypeFlags.Any) !== 0 &&
         t.intrinsicName === 'error');
 }
@@ -230,7 +231,7 @@ function walkTopTypes(root, program, checker, location, flagOf) {
                 continue;
             }
             const propType = checker.getTypeOfSymbolAtLocation(prop, location);
-            walk(propType, path === '' ? prop.getName() : `${path}.${prop.getName()}`, depth + 1);
+            walk(propType, memberPath(path, prop, checker), depth + 1);
             if (exhausted)
                 return;
         }
@@ -276,8 +277,8 @@ function disqualifyingFlag(t) {
     }
     return t.flags & ts.TypeFlags.Unknown ? 'unknown' : undefined;
 }
-/** How many unresolved specifiers a detail names before it counts the rest. */
-const MAX_NAMED_SPECIFIERS = 3;
+/** How many specifiers or names a detail lists before it counts the rest. */
+const MAX_NAMED_IN_DETAIL = 3;
 /**
  * Turn a deep finding into the published provenance entry (carrick#376).
  *
@@ -321,12 +322,51 @@ function unresolvedDetail(specifiers) {
     const lead = "the type at this position did not resolve on the scanned checkout, so the compiler printed a placeholder 'any' rather than a declared type";
     if (specifiers.length === 0)
         return lead;
-    const named = specifiers
-        .slice(0, MAX_NAMED_SPECIFIERS)
-        .map((specifier) => `'${specifier}'`)
+    return `${lead}; unresolved imports reachable from the anchor: ${quotedList(specifiers)}`;
+}
+/**
+ * The entry for one position at which the emitted tree holds the
+ * unresolved-reference placeholder (carrick#1446): `path` is `''` for the
+ * alias's own type. `names` are the identifiers the self-check could not find
+ * in this alias's statement and the files it reaches.
+ *
+ * The cause is `unresolved_import`, the word a reader already has for "a
+ * reference here did not resolve"; the detail says where it failed to.
+ */
+export function unresolvedInTreeProvenance(path, names) {
+    const where = path === '' ? 'this type' : 'the type at this position';
+    const lead = `${where} does not resolve in the declarations the capture emitted, so the ` +
+        "compiler reads it as 'any' although the printed text shows the name it could not follow";
+    return {
+        path,
+        kind: 'any',
+        reason: 'unresolved_import',
+        detail: names.length === 0
+            ? lead
+            : `${lead}; names those declarations cannot find: ${quotedList(names)}`,
+    };
+}
+/**
+ * The root entry for a literal anchor demoted because its text names a module
+ * whose declaration emit was skipped (carrick#1446, carrick#1165): that text is
+ * what the index serves for it, and nothing in the emitted tree declares what
+ * it imports.
+ */
+export function unemittedModuleProvenance() {
+    return {
+        path: '',
+        kind: 'any',
+        reason: 'unresolved_import',
+        detail: 'this type names a module whose declarations the capture could not emit, so it ' +
+            "does not resolve in the declarations the capture emitted and the compiler reads it as 'any'",
+    };
+}
+/** `'a', 'b', 'c' and 2 more`. */
+function quotedList(items) {
+    const named = items
+        .slice(0, MAX_NAMED_IN_DETAIL)
+        .map((item) => `'${item}'`)
         .join(', ');
-    const more = specifiers.length > MAX_NAMED_SPECIFIERS
-        ? ` and ${specifiers.length - MAX_NAMED_SPECIFIERS} more`
-        : '';
-    return `${lead}; unresolved imports reachable from the anchor: ${named}${more}`;
+    const more = items.length > MAX_NAMED_IN_DETAIL ? ` and ${items.length - MAX_NAMED_IN_DETAIL} more` : '';
+    return `${named}${more}`;
 }

package/sidecar/dist/src/capture/guarded-fs.d.ts

@@ -42,7 +42,11 @@ export declare class WriteGuard {
     private readonly files;
     private readonly protect;
     private constructor();
-    /** A guard over `roots`. Throws when a root equals or contains a protected tree. */
+    /**
+     * A guard over `roots`. Throws when a root equals or contains a protected
+     * tree, or when a directory root lies inside one anywhere but beneath a
+     * `.carrick` directory (carrick#1768).
+     */
     static of(roots: WriteRoots): WriteGuard;
     /**
      * A new, empty directory under `parent` (the OS temp dir by default) and a

package/sidecar/dist/src/capture/guarded-fs.js

@@ -40,7 +40,11 @@ export class WriteGuard {
         this.files = files;
         this.protect = protect;
     }
-    /** A guard over `roots`. Throws when a root equals or contains a protected tree. */
+    /**
+     * A guard over `roots`. Throws when a root equals or contains a protected
+     * tree, or when a directory root lies inside one anywhere but beneath a
+     * `.carrick` directory (carrick#1768).
+     */
     static of(roots) {
         const protect = (roots.protect ?? []).map(landing);
         const dirs = (roots.dirs ?? []).map(landing);
@@ -51,6 +55,16 @@ export class WriteGuard {
                 throw new WriteRefused(`refused write root ${root}: it is or contains the scanned tree ${covered}`);
             }
         }
+        // Inside a scanned tree, a directory root is Carrick's only beneath a
+        // `.carrick` directory. Anywhere else it is the repo's own (a sibling
+        // service, say), and a stub dir is emptied before it is written. A file
+        // root is exempt: the surface entry has to sit inside rootDir.
+        for (const root of dirs) {
+            const inside = protect.find((tree) => within(tree, root) && !carrickOwned(tree, root));
+            if (inside !== undefined) {
+                throw new WriteRefused(`refused write root ${root}: it lies inside the scanned tree ${inside}, outside a .carrick directory`);
+            }
+        }
         return new WriteGuard(dirs, files, protect);
     }
     /**
@@ -133,6 +147,14 @@ function within(root, p) {
     const rel = path.relative(root, p);
     return rel === '' || (rel !== '..' && !rel.startsWith(`..${path.sep}`) && !path.isAbsolute(rel));
 }
+/**
+ * Whether `root`, inside `tree`, lies beneath a `.carrick` directory between
+ * the two. `.carrick` itself is not enough: it holds the workspace's proposal,
+ * jobs and scan logs. Both are resolved paths.
+ */
+function carrickOwned(tree, root) {
+    return path.relative(tree, root).split(path.sep).slice(0, -1).includes('.carrick');
+}
 function isDirectory(p) {
     try {
         return fs.statSync(p).isDirectory();

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

@@ -31,6 +31,7 @@ import type { CaptureStubOptions, CaptureStubResult } from './api.js';
 export type { CaptureStubOptions, CaptureStubResult } from './api.js';
 export { DenoProject, findDenoConfig } from './deno-project.js';
 export { serviceConfigPath } from './project-references.js';
+export { findServiceTsconfig } from './service-config.js';
 export { runCheck } from './check.js';
 export type { CheckProgress } from './check.js';
 export { jsonWireDeclarations } from './check-probe.js';

package/sidecar/dist/src/capture/index.js

@@ -39,10 +39,12 @@ import { selfCheckStub } from './self-check.js';
 import { collectSpecifiers, isRelative, packageNameOf } from './specifiers.js';
 import { DenoProject, findDenoConfig } from './deno-project.js';
 import { emitsAlike, ProjectGraph } from './project-references.js';
+import { findServiceTsconfig } from './service-config.js';
 import { placeEmittedTree } from './outside-root.js';
 import { WriteGuard } from './guarded-fs.js';
 export { DenoProject, findDenoConfig } from './deno-project.js';
 export { serviceConfigPath } from './project-references.js';
+export { findServiceTsconfig } from './service-config.js';
 // v2 check core ("tsc as the judge"). Same bundle, same seam: the sidecar
 // reaches it only through this door (index.js).
 export { runCheck } from './check.js';
@@ -127,9 +129,11 @@ export function captureStub(opts) {
     const packageName = `@carrick/${sanitizeServiceName(opts.serviceName)}`;
     const stubDir = path.resolve(opts.outDir);
     const errors = [];
+    // The named config, else the one the init'd project reads too
+    // (carrick#1776). A service with neither is typed under defaults below.
     const configPath = opts.tsconfigPath
         ? path.resolve(repoRoot, opts.tsconfigPath)
-        : path.join(repoRoot, 'tsconfig.json');
+        : findServiceTsconfig(repoRoot, opts.scanRoot) ?? path.join(repoRoot, 'tsconfig.json');
     let parsed;
     // The config the emit's options came from: the named one, or the project
     // that owns the most anchors' files (carrick#1604).
@@ -141,10 +145,13 @@ export function captureStub(opts) {
     // Everything this capture writes, it writes through `guard` (carrick#1748):
     // the stub dir, the staging dir, and the surface entry. A stub dir is
     // emptied before it is written, so one that is or holds the repo is refused
-    // before anything is touched.
+    // before anything is touched. The scan root is protected too: a stub dir
+    // in a sibling service of the same repo is refused unless it sits beneath
+    // a `.carrick` directory (carrick#1768).
     let guard;
     try {
-        guard = WriteGuard.of({ dirs: [stubDir], protect: [repoRoot] });
+        const protect = opts.scanRoot === undefined ? [repoRoot] : [repoRoot, path.resolve(opts.scanRoot)];
+        guard = WriteGuard.of({ dirs: [stubDir], protect });
     }
     catch (err) {
         return fail(stubDir, packageName, [err instanceof Error ? err.message : String(err)]);
@@ -559,6 +566,7 @@ function demoteDanglingAliases(args) {
             serialization: 'structural_fallback',
             failureReason: `declaration emit was skipped for module '${dangling}'; ` +
                 'alias demoted to keep the partially emitted tree usable',
+            namesUnemittedModule: true,
         };
     });
     if (surfaceKey !== undefined && demoted.size > 0) {

package/sidecar/dist/src/capture/member-name.d.ts

@@ -0,0 +1,20 @@
+/**
+ * A member's place in a path, written the same way on every scan
+ * (carrick#1766).
+ *
+ * A member keyed by a unique symbol (`[Symbol.iterator]`, or a user's
+ * `const KEY: unique symbol`) has no name of its own. The checker escapes it as
+ * `__@<description>@<symbol id>`, and the id counts the symbols the process
+ * made before this one, so it differs between two scans of one tree and a
+ * stored sentence naming it changed on every scan. The checker prints such a
+ * member from its key instead, `[Symbol.iterator]`, which is how the source
+ * writes it.
+ *
+ * Every other member keeps `getName()`. A string key that starts with `__` is
+ * escaped with one more underscore, so it never reads as symbol-keyed here, and
+ * `symbolToString` would quote a key such as `content-type`, changing text that
+ * is already stable.
+ */
+import ts from 'typescript';
+/** `parent.name`, or `parent[KEY]` for a member keyed by a unique symbol. */
+export declare function memberPath(parent: string, member: ts.Symbol, checker: ts.TypeChecker): string;

package/sidecar/dist/src/capture/member-name.js

@@ -0,0 +1,24 @@
+/**
+ * A member's place in a path, written the same way on every scan
+ * (carrick#1766).
+ *
+ * A member keyed by a unique symbol (`[Symbol.iterator]`, or a user's
+ * `const KEY: unique symbol`) has no name of its own. The checker escapes it as
+ * `__@<description>@<symbol id>`, and the id counts the symbols the process
+ * made before this one, so it differs between two scans of one tree and a
+ * stored sentence naming it changed on every scan. The checker prints such a
+ * member from its key instead, `[Symbol.iterator]`, which is how the source
+ * writes it.
+ *
+ * Every other member keeps `getName()`. A string key that starts with `__` is
+ * escaped with one more underscore, so it never reads as symbol-keyed here, and
+ * `symbolToString` would quote a key such as `content-type`, changing text that
+ * is already stable.
+ */
+/** `parent.name`, or `parent[KEY]` for a member keyed by a unique symbol. */
+export function memberPath(parent, member, checker) {
+    if (!member.escapedName.startsWith('__@')) {
+        return parent === '' ? member.getName() : `${parent}.${member.getName()}`;
+    }
+    return `${parent}${checker.symbolToString(member)}`;
+}

package/sidecar/dist/src/capture/self-check.js

@@ -34,7 +34,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { collectSpecifiers, isRelative, packageNameOf } from './specifiers.js';
 import { repairDanglingImports } from './repair-dangling.js';
-import { findDisqualifyingTopTypes, provenanceOf, } from './deep-walk.js';
+import { findDisqualifyingTopTypes, findUnresolvedPlaceholders, isErrorPlaceholder, provenanceOf, unemittedModuleProvenance, unresolvedInTreeProvenance, } from './deep-walk.js';
 export function selfCheckStub(args) {
     const typesDir = path.join(args.stubDir, 'types');
     const treeFiles = [];
@@ -104,6 +104,7 @@ function runSelfCheck(args, treeFiles, repaired) {
     const emptyFailures = () => ({
         externalPinned: new Set(),
         internal: new Set(),
+        unfoundNames: new Set(),
     });
     const bucketIn = (map, key) => {
         let entry = map.get(key);
@@ -113,11 +114,24 @@ function runSelfCheck(args, treeFiles, repaired) {
         }
         return entry;
     };
+    // A surface diagnostic outside every alias statement (a file-level import,
+    // a reference directive) is attributable to no alias and keeps the
+    // service-wide file bucket: soundness over precision, the same fallback
+    // check-poison.ts makes.
+    const bucketFor = (abs, start) => {
+        const owner = abs === surfaceAbs ? aliasAtSurfacePosition(start) : undefined;
+        return owner ? bucketIn(surfaceFailuresByAlias, owner) : bucketIn(failuresByFile, abs);
+    };
     for (const d of diagnostics) {
         if (!d.file)
             continue;
         const abs = path.resolve(d.file.fileName);
         const msg = ts.flattenDiagnosticMessageText(d.messageText, ' ');
+        // A name the compiler cannot find is the placeholder's cause wherever a
+        // type uses it; the record names it beside those positions (carrick#1446).
+        const unfound = /Cannot find (?:name|namespace) '([^']+)'/.exec(msg);
+        if (unfound)
+            bucketFor(abs, d.start).unfoundNames.add(unfound[1]);
         // A name the repair did not reach: the import that bound it is gone, so
         // the module is no longer reported missing and only this diagnostic is
         // left to say the tree is incomplete. Blamed on the specifier that bound
@@ -133,14 +147,7 @@ function runSelfCheck(args, treeFiles, repaired) {
         if (!m)
             continue;
         const spec = m[1];
-        // A surface diagnostic outside every alias statement (a file-level import,
-        // a reference directive) is attributable to no alias and keeps the
-        // service-wide file bucket: soundness over precision, the same fallback
-        // check-poison.ts makes.
-        const owner = abs === surfaceAbs ? aliasAtSurfacePosition(d.start) : undefined;
-        const bucket = owner
-            ? bucketIn(surfaceFailuresByAlias, owner)
-            : bucketIn(failuresByFile, abs);
+        const bucket = bucketFor(abs, d.start);
         if (!isRelative(spec) && args.pinned[packageNameOf(spec)]) {
             bucket.externalPinned.add(spec);
         }
@@ -254,12 +261,23 @@ function demotedRecord(anchor) {
         self_check_detail: anchor.failureReason,
         capture_failure_reason: anchor.failureReason,
         top_type_at_self_check: true,
+        // A literal's text is what the index serves for it, and a module it
+        // names never reached the tree (carrick#1446). A symbol anchor's served
+        // declaration comes from elsewhere, so its demotion says nothing about it.
+        ...(anchor.request.kind === 'literal' && anchor.namesUnemittedModule
+            ? { unresolved_in_tree: [unemittedModuleProvenance()] }
+            : {}),
     };
 }
 function checkedRecord(anchor, ctx) {
     const alias = anchor.request.alias;
     let topType = true;
     let deepFindings = [];
+    // Where the alias's type holds the unresolved-reference placeholder in this
+    // tree (carrick#1446): `''` for its own type. The deep walk leaves the
+    // placeholder out because the check heals a pinned external; what the index
+    // publishes is this tree, so the record says where it does not resolve.
+    let unresolvedPaths = [];
     const seeds = [];
     if (ctx.surfaceSource) {
         for (const stmt of ctx.surfaceSource.statements) {
@@ -270,6 +288,10 @@ function checkedRecord(anchor, ctx) {
                 (type.flags & (ts.TypeFlags.Any | ts.TypeFlags.Unknown | ts.TypeFlags.Never)) !== 0;
             if (!topType) {
                 deepFindings = findDisqualifyingTopTypes(type, ctx.program, ctx.checker, stmt.name);
+                unresolvedPaths = findUnresolvedPlaceholders(type, ctx.program, ctx.checker, stmt.name);
+            }
+            else if (isErrorPlaceholder(type)) {
+                unresolvedPaths = [''];
             }
             // Seed the closure with the alias's own import-type targets.
             const visit = (node) => {
@@ -300,6 +322,7 @@ function checkedRecord(anchor, ctx) {
     let blamedExternal;
     let internalFailure;
     const danglingSpecifiers = new Set();
+    const unfoundNames = new Set();
     // This alias's own surface statement, then the closure's files. The surface
     // file bucket now holds only the diagnostics no alias statement covers.
     const closureFailures = [
@@ -315,6 +338,8 @@ function checkedRecord(anchor, ctx) {
             internalFailure = [...failures.internal][0];
         for (const specifier of failures.internal)
             danglingSpecifiers.add(specifier);
+        for (const name of failures.unfoundNames)
+            unfoundNames.add(name);
     }
     // Classification consults the closure failures REGARDLESS of the root
     // type: a dangling internal specifier means part of this alias's closure
@@ -416,6 +441,13 @@ function checkedRecord(anchor, ctx) {
             ? { dangling_specifiers: [...danglingSpecifiers].sort() }
             : {}),
         ...(anchor.undeclaredNames ? { undeclared_names: anchor.undeclaredNames } : {}),
+        ...(unresolvedPaths.length > 0
+            ? {
+                unresolved_in_tree: [...unresolvedPaths]
+                    .sort()
+                    .map((p) => unresolvedInTreeProvenance(p, [...unfoundNames].sort())),
+            }
+            : {}),
     };
 }
 /** Resolve a relative specifier from `fromAbs` to a tree file, if present. */

package/sidecar/dist/src/capture/service-config.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Which tsconfig types a service that names none (carrick#1776).
+ *
+ * Both readers of a service, the init'd project and capture, ask this one
+ * function, so they type the service under the same options.
+ *
+ * The service root is searched first, for the names a service keeps its own
+ * config under. Above it, the search is `tsc`'s own when it is run with no
+ * `-p`: the nearest `tsconfig.json` in an ancestor directory. A layout that
+ * keeps one config above several services (their module resolution, `paths`,
+ * `lib`) is typed under that config, as the repo's own `tsc` types it; without
+ * it, every import only that config resolves read `any`.
+ *
+ * The walk stops at the scan root, inclusive: a config outside the scanned
+ * tree is never read. With no scan root, or a service outside it, only the
+ * service root is searched.
+ */
+/** Absolute path of the config that types the service, or undefined for none. */
+export declare function findServiceTsconfig(serviceRoot: string, scanRoot?: string): string | undefined;

package/sidecar/dist/src/capture/service-config.js

@@ -0,0 +1,57 @@
+/**
+ * Which tsconfig types a service that names none (carrick#1776).
+ *
+ * Both readers of a service, the init'd project and capture, ask this one
+ * function, so they type the service under the same options.
+ *
+ * The service root is searched first, for the names a service keeps its own
+ * config under. Above it, the search is `tsc`'s own when it is run with no
+ * `-p`: the nearest `tsconfig.json` in an ancestor directory. A layout that
+ * keeps one config above several services (their module resolution, `paths`,
+ * `lib`) is typed under that config, as the repo's own `tsc` types it; without
+ * it, every import only that config resolves read `any`.
+ *
+ * The walk stops at the scan root, inclusive: a config outside the scanned
+ * tree is never read. With no scan root, or a service outside it, only the
+ * service root is searched.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+/** The names a service root is searched for, in order. */
+const SERVICE_ROOT_NAMES = ['tsconfig.json', 'tsconfig.build.json', 'tsconfig.app.json'];
+/** The name an ancestor directory is searched for, as `tsc` searches. */
+const ANCESTOR_NAME = 'tsconfig.json';
+/** Absolute path of the config that types the service, or undefined for none. */
+export function findServiceTsconfig(serviceRoot, scanRoot) {
+    const root = path.resolve(serviceRoot);
+    for (const name of SERVICE_ROOT_NAMES) {
+        const candidate = path.join(root, name);
+        if (fs.existsSync(candidate))
+            return candidate;
+    }
+    if (scanRoot === undefined)
+        return undefined;
+    // Containment is decided on real paths, so a symlink on either end cannot
+    // hide the service inside the scan root or place it outside; the walk then
+    // climbs the path as given, one directory per level between them.
+    const fromBound = path.relative(realPath(scanRoot), realPath(root));
+    if (fromBound === '' || fromBound.startsWith('..') || path.isAbsolute(fromBound))
+        return undefined;
+    let dir = root;
+    for (let level = fromBound.split(path.sep).length; level > 0; level--) {
+        dir = path.dirname(dir);
+        const candidate = path.join(dir, ANCESTOR_NAME);
+        if (fs.existsSync(candidate))
+            return candidate;
+    }
+    return undefined;
+}
+/** The path with every symlink resolved; the path as given when it does not exist. */
+function realPath(p) {
+    try {
+        return fs.realpathSync(p);
+    }
+    catch {
+        return path.resolve(p);
+    }
+}

package/sidecar/dist/src/failure-path.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Whether the source reaches a node only when an HTTP response FAILED
+ * (carrick#1796).
+ *
+ * A consumer reads the success body on one path and the error text or the
+ * error body on another. Only the first is the call's response contract, so
+ * the def-use walk behind a `call_result` row must not take a read from the
+ * second. Which path a read is on is told by the source's own tests of the
+ * response, read two ways:
+ *
+ *  - the read sits in a branch of a test: `if (!res.ok) { ... }`, the `else`
+ *    of `if (res.ok)`, either arm of a conditional expression;
+ *  - the read follows an `if` whose other branch cannot complete, so the rest
+ *    of the block runs only on the side that did not leave:
+ *    `if (res.ok) { return ... } const text = await res.text()`.
+ *
+ * A test is read as the set of statuses it lets through. `ok` is true for
+ * 200-299 and false for every other status; a comparison of the status with a
+ * number lets through what it admits; `!`, `&&` and `||` combine the sets, and
+ * any other condition lets everything through. A node is on the failure path
+ * only when NO status in 200-299 can reach it.
+ *
+ * That is deliberately stricter than the retype check's reading of a status
+ * test (`okWhenTrue` in retype.ts), which reads the false side of
+ * `res.status === 200` as the failure path so it can find a success read to
+ * judge. Here a decided failure REMOVES a read, so the reading has to be sound
+ * the other way round: after `if (res.status === 204) return null`, 200 still
+ * gets through, and the json read that follows is the payload.
+ */
+import { Node } from 'ts-morph';
+/**
+ * True when the source reaches `node` only after the response named by
+ * `isResponse` failed. The walk climbs from `node` to `boundary` (the function
+ * the call sits in) and never looks at a test outside it.
+ */
+export declare function reachedOnlyOnFailure(node: Node, boundary: Node, isResponse: (node: Node) => boolean): boolean;