carrick 0.3.102 → 0.3.104

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

@@ -0,0 +1,182 @@
+/**
+ * Every file the sidecar writes or deletes goes through a {@link WriteGuard}
+ * (carrick#1748).
+ *
+ * A scan reads the repo it scans and never writes it. carrick#1742 showed how
+ * easily that breaks: the capture self-check reaches the repo's own sources
+ * through a `node_modules` link, and a pass that "only rewrites its own
+ * declarations" rewrote them. Each write site used to be safe only by its own
+ * reasoning. Now each run names the directories it owns (its scratch, the stub
+ * it emits, a runtime cache) and every write and delete is checked against
+ * them, on the RESOLVED path, before it happens.
+ *
+ * Resolution follows the operation:
+ *  - a write lands where the path's links lead, so the whole path is resolved,
+ *    and a path that does not exist yet resolves through its deepest existing
+ *    ancestor (a dangling link resolves through its target);
+ *  - a delete, or a new link, touches the directory entry itself, so only the
+ *    parent is resolved. Unlinking the stub's `node_modules` link is allowed;
+ *    writing through it into the repo's packages is refused.
+ *
+ * `test/no-raw-writes.test.ts` fails when any other source file calls a
+ * mutating `fs` API.
+ */
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+/** A write or delete the guard refused, or a root it would not accept. */
+export class WriteRefused extends Error {
+    constructor(message) {
+        super(`${message} (carrick#1748)`);
+        this.name = 'WriteRefused';
+    }
+}
+export class WriteGuard {
+    dirs;
+    files;
+    protect;
+    constructor(dirs, files, protect) {
+        this.dirs = dirs;
+        this.files = files;
+        this.protect = protect;
+    }
+    /** A guard over `roots`. Throws when a root equals or contains a protected tree. */
+    static of(roots) {
+        const protect = (roots.protect ?? []).map(landing);
+        const dirs = (roots.dirs ?? []).map(landing);
+        const files = (roots.files ?? []).map(entry);
+        for (const root of [...dirs, ...files]) {
+            const covered = protect.find((tree) => within(root, tree));
+            if (covered !== undefined) {
+                throw new WriteRefused(`refused write root ${root}: it is or contains the scanned tree ${covered}`);
+            }
+        }
+        return new WriteGuard(dirs, files, protect);
+    }
+    /**
+     * A new, empty directory under `parent` (the OS temp dir by default) and a
+     * guard over it alone. `mkdtemp` picks an unused name, so creating it cannot
+     * overwrite anything; `parent` is created when missing.
+     */
+    static scratch(prefix, parent = os.tmpdir()) {
+        fs.mkdirSync(parent, { recursive: true });
+        const dir = fs.mkdtempSync(path.join(parent, prefix));
+        return { dir, guard: WriteGuard.of({ dirs: [dir] }) };
+    }
+    /** This guard with more roots, under the same protected trees. */
+    with(roots) {
+        return WriteGuard.of({
+            dirs: [...this.dirs, ...(roots.dirs ?? [])],
+            files: [...this.files, ...(roots.files ?? [])],
+            protect: [...this.protect],
+        });
+    }
+    /** A guard over `dir` alone, which must already be writable under this one. */
+    narrow(dir) {
+        this.check(dir, landing(dir), 'narrow to');
+        return WriteGuard.of({ dirs: [dir], protect: [...this.protect] });
+    }
+    /** Whether a write to `p` would land inside this guard's roots. */
+    allowsWrite(p) {
+        return this.holds(landing(p));
+    }
+    /** Throws unless `p` (a subprocess's working directory, say) lies inside the roots. */
+    assertWithin(p) {
+        this.check(p, landing(p), 'work in');
+    }
+    writeFile(p, data) {
+        this.check(p, landing(p), 'write');
+        fs.writeFileSync(p, data);
+    }
+    /** `mkdir -p`. A directory that already exists is no write and passes unchecked. */
+    mkdir(p) {
+        if (isDirectory(p))
+            return;
+        this.check(p, landing(p), 'create directory');
+        fs.mkdirSync(p, { recursive: true });
+    }
+    copyFile(from, to) {
+        this.check(to, landing(to), 'copy into');
+        fs.copyFileSync(from, to);
+    }
+    /** `cp -R`. Links in the source are copied as links, never written through. */
+    copyTree(from, to, filter) {
+        this.check(to, landing(to), 'copy into');
+        fs.cpSync(from, to, { recursive: true, filter });
+    }
+    /** `rm -rf`. A link is removed itself; its target is left alone. */
+    remove(p) {
+        this.check(p, entry(p), 'delete');
+        fs.rmSync(p, { recursive: true, force: true });
+    }
+    unlink(p) {
+        this.check(p, entry(p), 'delete');
+        fs.unlinkSync(p);
+    }
+    symlink(target, linkPath, type) {
+        this.check(linkPath, entry(linkPath), 'link');
+        fs.symlinkSync(target, linkPath, type);
+    }
+    holds(resolved) {
+        return this.files.includes(resolved) || this.dirs.some((root) => within(root, resolved));
+    }
+    check(p, resolved, verb) {
+        if (this.holds(resolved))
+            return;
+        throw new WriteRefused(`refused to ${verb} ${p}` +
+            (resolved === path.resolve(p) ? '' : ` (resolves to ${resolved})`) +
+            ': outside this run\'s scratch, stub and cache roots');
+    }
+}
+/** Whether `p` is `root` or lies beneath it. Both are resolved paths. */
+function within(root, p) {
+    const rel = path.relative(root, p);
+    return rel === '' || (rel !== '..' && !rel.startsWith(`..${path.sep}`) && !path.isAbsolute(rel));
+}
+function isDirectory(p) {
+    try {
+        return fs.statSync(p).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Where a write to `p` lands: every link resolved, through the deepest
+ * existing ancestor when `p` does not exist yet, and through a dangling link's
+ * target (writing to a dangling link creates its target).
+ */
+function landing(p, hops = 0) {
+    const abs = path.resolve(p);
+    try {
+        return fs.realpathSync.native(abs);
+    }
+    catch {
+        // Missing, or a link whose target is missing.
+    }
+    let link;
+    try {
+        if (fs.lstatSync(abs).isSymbolicLink())
+            link = fs.readlinkSync(abs);
+    }
+    catch {
+        // Not there at all.
+    }
+    if (link !== undefined) {
+        if (hops > 40)
+            throw new WriteRefused(`refused ${abs}: too many symbolic links`);
+        return landing(path.resolve(path.dirname(abs), link), hops + 1);
+    }
+    const parent = path.dirname(abs);
+    if (parent === abs)
+        return abs;
+    return path.join(landing(parent, hops), path.basename(abs));
+}
+/** The directory entry `p` names: its parent resolved, its own name kept. */
+function entry(p) {
+    const abs = path.resolve(p);
+    const parent = path.dirname(abs);
+    if (parent === abs)
+        return abs;
+    return path.join(landing(parent), path.basename(abs));
+}

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

@@ -30,7 +30,6 @@
 import ts from 'typescript';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import * as os from 'node:os';
 import { entryRelativeSpecifier, resolveAnchor } from './anchors.js';
 import { findAugmentationFiles } from './augmentations.js';
 import { installedVersions, lockfileVersions } from './lockfile.js';
@@ -40,8 +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';
@@ -126,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).
@@ -137,6 +142,17 @@ export function captureStub(opts) {
     // references others and the anchors' files do not all belong to one project.
     let ownerGroups;
     let emitProject;
+    // 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.
+    let guard;
+    try {
+        guard = WriteGuard.of({ dirs: [stubDir], protect: [repoRoot] });
+    }
+    catch (err) {
+        return fail(stubDir, packageName, [err instanceof Error ? err.message : String(err)]);
+    }
     let deno;
     try {
         const config = findDenoConfig(repoRoot, opts.tsconfigPath);
@@ -225,10 +241,19 @@ export function captureStub(opts) {
     const entryPath = deno
         ? path.join(deno.cacheDir, `${surfaceEntry}.ts`)
         : path.join(entryDir, `${surfaceEntry}.ts`);
-    fs.mkdirSync(path.dirname(entryPath), { recursive: true });
+    // The entry is the one file a capture writes inside the repo itself: tsc
+    // only emits it from inside rootDir. It is written, read and deleted, and
+    // the guard holds it to exactly that path. A Deno entry sits in the cache.
+    try {
+        guard = guard.with(deno ? { dirs: [deno.cacheDir] } : { files: [entryPath] });
+        guard.mkdir(path.dirname(entryPath));
+    }
+    catch (err) {
+        return fail(stubDir, packageName, [err instanceof Error ? err.message : String(err)]);
+    }
     // ---- Phase A: analysis program over placeholder entry + anchor sources ----
     let resolved;
-    const analysisCtx = { repoRoot, entryDir: path.dirname(entryPath), entryPath };
+    const analysisCtx = { repoRoot, entryDir: path.dirname(entryPath), entryPath, guard };
     try {
         resolved = ownerGroups && emitProject
             ? resolveAnchorsByOwner(opts, ownerGroups, emitProject, analysisCtx, errors)
@@ -247,7 +272,8 @@ export function captureStub(opts) {
             : '';
         entryLines.push(`export type ${anchor.request.alias} = ${anchor.aliasText};${comment}`);
     }
-    const staging = fs.mkdtempSync(path.join(os.tmpdir(), 'carrick-capture-v2-'));
+    const scratch = WriteGuard.scratch('carrick-capture-v2-');
+    const staging = scratch.dir;
     const emitted = new Map();
     // Input .d.ts files (ambient stubs, augmentation declarations, local
     // hand-written declarations in the import closure) are never re-emitted by
@@ -256,7 +282,7 @@ export function captureStub(opts) {
     const sourceByEmitted = new Map();
     let emitPartial = false;
     try {
-        fs.writeFileSync(entryPath, entryLines.join('\n') + '\n');
+        guard.writeFile(entryPath, entryLines.join('\n') + '\n');
         const emitOptions = {
             ...parsed.options,
             // The load-bearing trio: emit declarations without checking, so
@@ -306,8 +332,8 @@ export function captureStub(opts) {
     }
     finally {
         if (fs.existsSync(entryPath))
-            fs.unlinkSync(entryPath);
-        fs.rmSync(staging, { recursive: true, force: true });
+            guard.unlink(entryPath);
+        scratch.guard.remove(staging);
     }
     // ---- Partial-emit recovery ----
     // The corpus-2 notifications-svc shape: one file's declaration emit was
@@ -326,22 +352,28 @@ export function captureStub(opts) {
     }
     // ---- Relocate the emitted tree into the stub package ----
     const typesDir = path.join(stubDir, 'types');
-    fs.rmSync(stubDir, { recursive: true, force: true });
-    fs.mkdirSync(typesDir, { recursive: true });
+    guard.remove(stubDir);
+    guard.mkdir(typesDir);
+    // From here on, only the stub is written.
+    const stubGuard = guard.narrow(stubDir);
+    // A declaration for a source outside rootDir arrives at the source's own
+    // path; it is placed under the tree too (carrick#1770).
+    const placed = placeEmittedTree({ emitted, staging, entryDir, surfaceDeclaration });
     const emittedFiles = [];
     let surfaceAbsPath = '';
-    for (const [fileName, text] of emitted) {
-        let rel = path.relative(staging, fileName).split(path.sep).join('/');
-        if (path.basename(rel) === surfaceDeclaration) {
-            const source = sourceByEmitted.get(rel);
-            sourceByEmitted.delete(rel);
-            rel = 'surface.d.ts';
+    for (const fileName of emitted.keys()) {
+        const stagingRel = path.relative(staging, fileName).split(path.sep).join('/');
+        const rel = placed.relOf.get(fileName);
+        const text = placed.textOf.get(fileName);
+        if (rel !== stagingRel) {
+            const source = sourceByEmitted.get(stagingRel);
+            sourceByEmitted.delete(stagingRel);
             if (source)
                 sourceByEmitted.set(rel, source);
         }
         const dest = path.join(typesDir, rel);
-        fs.mkdirSync(path.dirname(dest), { recursive: true });
-        fs.writeFileSync(dest, text);
+        stubGuard.mkdir(path.dirname(dest));
+        stubGuard.writeFile(dest, text);
         emittedFiles.push(rel);
         if (rel === 'surface.d.ts')
             surfaceAbsPath = dest;
@@ -354,8 +386,8 @@ export function captureStub(opts) {
         if (emittedFiles.includes(rel))
             continue;
         const dest = path.join(typesDir, rel);
-        fs.mkdirSync(path.dirname(dest), { recursive: true });
-        fs.writeFileSync(dest, text);
+        stubGuard.mkdir(path.dirname(dest));
+        stubGuard.writeFile(dest, text);
         emittedFiles.push(rel);
     }
     // Tree-relative names of augmentation files that made it into the tree
@@ -364,6 +396,9 @@ export function captureStub(opts) {
         .map((abs) => {
         const noDts = abs.replace(/\.d\.ts$/, '');
         const noExt = noDts === abs ? abs.replace(/\.(ts|tsx|mts|cts)$/, '') : noDts;
+        const outside = placed.outside.get(path.resolve(noExt));
+        if (outside !== undefined)
+            return outside;
         const rel = path.relative(entryDir, noExt).split(path.sep).join('/');
         return `${rel}.d.ts`;
     })
@@ -372,19 +407,21 @@ export function captureStub(opts) {
     // ---- Post-emit specifier rewrite (paths mappings + absolute internals) ----
     let denoRewrites = 0;
     try {
-        denoRewrites = deno?.rewrite(typesDir, emittedFiles, sourceByEmitted) ?? 0;
+        denoRewrites = deno?.rewrite(stubGuard, typesDir, emittedFiles, sourceByEmitted) ?? 0;
     }
     catch (err) {
         return fail(stubDir, packageName, [err instanceof Error ? err.message : String(err)]);
     }
     const rewritten = rewriteEmittedSpecifiers({
+        guard: stubGuard,
+        outside: placed.outside,
         typesDir,
         files: emittedFiles,
         options: parsed.options,
         configPath: projectConfigPath,
         entryDir,
     });
-    const specifierRewrites = denoRewrites + rewritten.rewrites;
+    const specifierRewrites = denoRewrites + placed.rewrites + rewritten.rewrites;
     // ---- Pin external deps: installed node_modules first, lockfile fallback ----
     // Externals are collected AFTER the rewrite pass: a rewritten paths
     // specifier is internal, not a dependency.
@@ -427,14 +464,14 @@ export function captureStub(opts) {
     }
     const dependencyRoot = deno?.config.workspaceRoot ?? repoRoot;
     const bareCheckout = !deno && !fs.existsSync(path.join(dependencyRoot, 'node_modules'));
-    fs.writeFileSync(path.join(stubDir, 'package.json'), JSON.stringify({
+    stubGuard.writeFile(path.join(stubDir, 'package.json'), JSON.stringify({
         name: packageName,
         version: '0.0.0-carrick',
         private: true,
         types: './types/surface.d.ts',
         dependencies: pinned,
     }, null, 2) + '\n');
-    fs.writeFileSync(path.join(stubDir, 'tsconfig.snapshot.json'), JSON.stringify({
+    stubGuard.writeFile(path.join(stubDir, 'tsconfig.snapshot.json'), JSON.stringify({
         ts_version: ts.version,
         strict: parsed.options.strict ?? false,
         strictNullChecks: parsed.options.strictNullChecks ?? parsed.options.strict ?? false,
@@ -444,6 +481,7 @@ export function captureStub(opts) {
     }, null, 2) + '\n');
     // ---- Capture-time self-check (per-alias closure attribution) ----
     const aliases = selfCheckStub({
+        guard: stubGuard,
         stubDir,
         surfaceAbsPath,
         resolved,
@@ -455,7 +493,7 @@ export function captureStub(opts) {
             : undefined,
     });
     const fidelity = computeFidelity(aliases);
-    fs.writeFileSync(path.join(stubDir, 'carrick-manifest.json'), JSON.stringify({
+    stubGuard.writeFile(path.join(stubDir, 'carrick-manifest.json'), JSON.stringify({
         package_name: packageName,
         ts_version: ts.version,
         bare_checkout: bareCheckout,
@@ -600,7 +638,7 @@ function resolveAnchors(opts, parsed, ctx, deno) {
     for (const anchor of opts.anchors) {
         placeholderLines.push(`export type ${anchor.alias} = unknown;`);
     }
-    fs.writeFileSync(ctx.entryPath, placeholderLines.join('\n') + '\n');
+    ctx.guard.writeFile(ctx.entryPath, placeholderLines.join('\n') + '\n');
     try {
         const anchorSources = [
             ...new Set(opts.anchors
@@ -638,6 +676,6 @@ function resolveAnchors(opts, parsed, ctx, deno) {
     }
     finally {
         if (fs.existsSync(ctx.entryPath))
-            fs.unlinkSync(ctx.entryPath);
+            ctx.guard.unlink(ctx.entryPath);
     }
 }

package/sidecar/dist/src/capture/outside-root.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Place every emitted declaration inside the stub's types tree
+ * (carrick#1770).
+ *
+ * The tree mirrors the emit's rootDir. A program can also reach a source
+ * outside it: a service that reads a sibling package's SOURCE through a
+ * `paths` mapping or a relative import. tsc does not emit that file's
+ * declaration under `outDir`; it hands the write callback the source's own
+ * path with `.d.ts`. Such a file is placed under `OUTSIDE_DIR`, mirroring its
+ * path from the deepest directory it shares with rootDir, and every relative
+ * specifier that crosses between the two parts of the tree is rewritten to
+ * where its target now sits. Specifiers are read the way tsc wrote them:
+ * relative to the SOURCE location of the file that holds them.
+ *
+ * A capture whose program stays inside rootDir is placed exactly as before.
+ */
+/** Tree directory holding declarations of sources outside rootDir. */
+export declare const OUTSIDE_DIR = "__outside__";
+export interface PlacedTree {
+    /** Emitted file name (as tsc gave it) -> tree-relative POSIX path. */
+    relOf: Map<string, string>;
+    /** Emitted file name -> declaration text, cross-root specifiers rewritten. */
+    textOf: Map<string, string>;
+    /**
+     * Absolute source-side path of each outside declaration, extension
+     * stripped -> its tree-relative path. Empty when nothing was outside.
+     */
+    outside: Map<string, string>;
+    /** Relative specifiers rewritten across the root. */
+    rewrites: number;
+}
+/**
+ * Where each emitted declaration goes. `emitted` maps tsc's file name to its
+ * text; `surfaceDeclaration` is renamed to `surface.d.ts` at the tree root.
+ */
+export declare function placeEmittedTree(args: {
+    emitted: Map<string, string>;
+    staging: string;
+    entryDir: string;
+    surfaceDeclaration: string;
+}): PlacedTree;

package/sidecar/dist/src/capture/outside-root.js

@@ -0,0 +1,101 @@
+/**
+ * Place every emitted declaration inside the stub's types tree
+ * (carrick#1770).
+ *
+ * The tree mirrors the emit's rootDir. A program can also reach a source
+ * outside it: a service that reads a sibling package's SOURCE through a
+ * `paths` mapping or a relative import. tsc does not emit that file's
+ * declaration under `outDir`; it hands the write callback the source's own
+ * path with `.d.ts`. Such a file is placed under `OUTSIDE_DIR`, mirroring its
+ * path from the deepest directory it shares with rootDir, and every relative
+ * specifier that crosses between the two parts of the tree is rewritten to
+ * where its target now sits. Specifiers are read the way tsc wrote them:
+ * relative to the SOURCE location of the file that holds them.
+ *
+ * A capture whose program stays inside rootDir is placed exactly as before.
+ */
+import * as path from 'node:path';
+import { rewriteSpecifiers } from './specifiers.js';
+/** Tree directory holding declarations of sources outside rootDir. */
+export const OUTSIDE_DIR = '__outside__';
+const DECLARATION_EXT = /\.d\.(ts|mts|cts)$/;
+/**
+ * Where each emitted declaration goes. `emitted` maps tsc's file name to its
+ * text; `surfaceDeclaration` is renamed to `surface.d.ts` at the tree root.
+ */
+export function placeEmittedTree(args) {
+    const relOf = new Map();
+    const textOf = new Map(args.emitted);
+    // Where tsc would have put each file in the source tree: the place its
+    // relative specifiers are written from.
+    const sourceSideOf = new Map();
+    const outsideFiles = [];
+    for (const fileName of args.emitted.keys()) {
+        const rel = posix(path.relative(args.staging, fileName));
+        if (escapes(rel)) {
+            outsideFiles.push(fileName);
+            sourceSideOf.set(fileName, path.resolve(fileName));
+            continue;
+        }
+        sourceSideOf.set(fileName, path.join(args.entryDir, rel));
+        relOf.set(fileName, path.basename(rel) === args.surfaceDeclaration ? 'surface.d.ts' : rel);
+    }
+    const outside = new Map();
+    if (outsideFiles.length === 0)
+        return { relOf, textOf, outside, rewrites: 0 };
+    const shared = commonDirectory([args.entryDir, ...outsideFiles.map((f) => path.dirname(path.resolve(f)))]);
+    for (const fileName of outsideFiles) {
+        const rel = path.posix.join(OUTSIDE_DIR, posix(path.relative(shared, path.resolve(fileName))));
+        relOf.set(fileName, rel);
+        outside.set(path.resolve(fileName).replace(DECLARATION_EXT, ''), rel);
+    }
+    // Source-side module id (absolute, extensionless) -> tree path.
+    const treeOf = new Map();
+    for (const [fileName, rel] of relOf) {
+        treeOf.set(sourceSideOf.get(fileName).replace(DECLARATION_EXT, ''), rel);
+    }
+    let rewrites = 0;
+    for (const [fileName, rel] of relOf) {
+        const fromSource = path.dirname(sourceSideOf.get(fileName));
+        const fromTree = path.posix.dirname(rel);
+        const result = rewriteSpecifiers(textOf.get(fileName), (spec) => {
+            if (!spec.startsWith('./') && !spec.startsWith('../'))
+                return undefined;
+            const extension = /\.(m|c)?js$/.exec(spec)?.[0] ?? '';
+            const target = path.resolve(fromSource, spec.slice(0, spec.length - extension.length));
+            const targetRel = treeOf.get(target) ?? treeOf.get(path.join(target, 'index'));
+            if (targetRel === undefined)
+                return undefined;
+            const targetId = targetRel.replace(DECLARATION_EXT, '');
+            // Unchanged when the specifier, read from the file's place in the tree,
+            // already reaches the same declaration.
+            const literal = path.posix.normalize(path.posix.join(fromTree, spec.slice(0, spec.length - extension.length)));
+            if (literal === targetId || `${literal}/index` === targetId)
+                return undefined;
+            let next = path.posix.relative(fromTree, targetId);
+            if (!next.startsWith('.'))
+                next = `./${next}`;
+            return next + extension;
+        });
+        textOf.set(fileName, result.text);
+        rewrites += result.rewrites;
+    }
+    return { relOf, textOf, outside, rewrites };
+}
+function posix(p) {
+    return p.split(path.sep).join('/');
+}
+function escapes(rel) {
+    return rel === '..' || rel.startsWith('../') || path.isAbsolute(rel);
+}
+/** The deepest directory containing every one of `dirs` (absolute). */
+function commonDirectory(dirs) {
+    let shared = path.resolve(dirs[0]);
+    for (const dir of dirs.slice(1)) {
+        const resolved = path.resolve(dir);
+        while (shared !== path.dirname(shared) && path.relative(shared, resolved).startsWith('..')) {
+            shared = path.dirname(shared);
+        }
+    }
+    return shared;
+}

package/sidecar/dist/src/capture/paths-rewrite.d.ts

@@ -13,8 +13,11 @@
  * as dangling internals with a recorded reason, which is the honest outcome.
  */
 import ts from 'typescript';
+import type { WriteGuard } from './guarded-fs.js';
 import { type PathsPattern } from './specifiers.js';
 export interface RewriteArgs {
+    /** Writes are held to the stub (carrick#1748). */
+    guard: WriteGuard;
     /** Absolute path of the stub's types/ directory. */
     typesDir: string;
     /** Tree-relative emitted file paths (as recorded in emitted_files, without
@@ -26,6 +29,11 @@ export interface RewriteArgs {
     configPath: string;
     /** Effective rootDir the emit ran with (tree layout mirrors it). */
     entryDir: string;
+    /**
+     * Declarations of sources outside rootDir, placed under the tree
+     * (carrick#1770): absolute source-side path without extension -> tree path.
+     */
+    outside: Map<string, string>;
 }
 export declare function parsePathsPatterns(options: ts.CompilerOptions, configPath: string): PathsPattern[];
 export interface RewriteResult {

package/sidecar/dist/src/capture/paths-rewrite.js

@@ -37,11 +37,13 @@ export function parsePathsPatterns(options, configPath) {
     return patterns;
 }
 /** Map an absolute source path to its tree-relative emitted file, if any. */
-function treeFileFor(absSource, entryDir, emitted) {
+function treeFileFor(absSource, entryDir, emitted, outside) {
     const noExt = absSource.replace(/\.(d\.ts|ts|tsx|mts|cts)$/, '');
     const rel = path.relative(entryDir, noExt).split(path.sep).join('/');
-    if (rel.startsWith('..'))
-        return undefined;
+    if (rel.startsWith('..')) {
+        const resolved = path.resolve(noExt);
+        return outside.get(resolved) ?? outside.get(path.join(resolved, 'index'));
+    }
     for (const candidate of [`${rel}.d.ts`, `${rel}/index.d.ts`]) {
         if (emitted.has(candidate))
             return candidate;
@@ -89,7 +91,7 @@ export function rewriteEmittedSpecifiers(args) {
         // Import types first, while the member name is still attached to its
         // specifier; an in-tree target is left for the general pass below.
         const text = original.replace(ABSOLUTE_IMPORT_TYPE, (whole, open, quote, spec, close, dot, name) => {
-            if (treeFileFor(spec, args.entryDir, emitted))
+            if (treeFileFor(spec, args.entryDir, emitted, args.outside))
                 return whole;
             const replacement = installed(spec, name);
             if (replacement === undefined)
@@ -100,7 +102,7 @@ export function rewriteEmittedSpecifiers(args) {
         const { text: rewritten, rewrites } = rewriteSpecifiers(text, (spec) => {
             // Absolute paths: an emitted tree file, else an installed package.
             if (spec.startsWith('/')) {
-                const target = treeFileFor(spec, args.entryDir, emitted);
+                const target = treeFileFor(spec, args.entryDir, emitted, args.outside);
                 return target ? relativeSpecifier(file, target) : installed(spec);
             }
             if (isRelative(spec))
@@ -113,7 +115,7 @@ export function rewriteEmittedSpecifiers(args) {
                     continue;
                 for (const targetTemplate of pattern.targets) {
                     const absTarget = targetTemplate.replace('*', star);
-                    const target = treeFileFor(absTarget, args.entryDir, emitted);
+                    const target = treeFileFor(absTarget, args.entryDir, emitted, args.outside);
                     if (target)
                         return relativeSpecifier(file, target);
                 }
@@ -124,7 +126,7 @@ export function rewriteEmittedSpecifiers(args) {
             return undefined;
         });
         if (rewrites + importTypeRewrites > 0) {
-            fs.writeFileSync(absFile, rewritten);
+            args.guard.writeFile(absFile, rewritten);
             total += rewrites + importTypeRewrites;
         }
     }

package/sidecar/dist/src/capture/repair-dangling.d.ts

@@ -28,6 +28,7 @@
  *
  * Seam: node builtins + `typescript`, like the rest of this directory.
  */
+import type { WriteGuard } from './guarded-fs.js';
 /** What one file's repair removed, for the caller's re-check. */
 export interface RepairedFile {
     /** Specifiers whose import statements were dropped. */
@@ -42,5 +43,14 @@ export interface RepairedFile {
  * `failing` maps an absolute file path to the specifiers the stub could not
  * resolve from it. Returns the files actually rewritten; a file whose names
  * cannot all be replaced by `unknown` is left exactly as it was.
+ *
+ * Only a file `tree` (a guard over the stub's types tree) lets it write is
+ * repaired (carrick#1742). The self-check program also loads files the stub
+ * merely reaches: the repo's own sources, through a workspace package linked
+ * into the `node_modules` the stub borrows, or a runtime's dependency cache.
+ * Those report their missing modules exactly as an emitted declaration does,
+ * and they belong to the user: a scan reads them and never writes them. The
+ * guard decides on the resolved path, so a file reached through the link is
+ * the repo's, whatever path the program loaded it by.
  */
-export declare function repairDanglingImports(failing: Map<string, Set<string>>): Map<string, RepairedFile>;
+export declare function repairDanglingImports(failing: Map<string, Set<string>>, tree: WriteGuard): Map<string, RepairedFile>;