carrick 0.3.111 → 0.3.113

package/sidecar/dist/src/project-loader.js

@@ -12,7 +12,7 @@
 import { Project, getCompilerOptionsFromTsConfig } from 'ts-morph';
 import * as path from 'node:path';
 import * as fs from 'node:fs';
-import { DenoProject, findDenoConfig, findServiceTsconfig, serviceConfigPath, sidecarCompilerOptions, } from './capture/index.js';
+import { DenoProject, findDenoConfig, findServiceTsconfig, serviceConfigPath, sidecarCompilerOptions, untrustedReadBound, } from './capture/index.js';
 import { moduleFormatResolutionHost } from './module-format.js';
 import { ExternalImports, registerExternalImports } from './origin.js';
 /**
@@ -177,6 +177,7 @@ export class ProjectLoader {
                 this.log('Project will load with tsconfig snapshot');
                 this.buildProject = () => {
                     const project = new Project({
+                        ...this.fileSystemOption(),
                         compilerOptions: sidecarCompilerOptions(this.snapshotToCompilerOptions(snapshot)),
                         skipAddingFilesFromTsConfig: true,
                     });
@@ -197,6 +198,7 @@ export class ProjectLoader {
                         // rebuilds that drop them (carrick#1731).
                         const imports = new ExternalImports();
                         const project = new Project({
+                            ...this.fileSystemOption(),
                             compilerOptions: sidecarCompilerOptions(deno.parsed.options),
                             skipAddingFilesFromTsConfig: true,
                             resolutionHost: imports.recording((host, getOptions) => ({
@@ -221,6 +223,7 @@ export class ProjectLoader {
                     this.log('No tsconfig.json found, using default compiler options');
                     this.buildProject = () => {
                         const project = new Project({
+                            ...this.fileSystemOption(),
                             compilerOptions: sidecarCompilerOptions(DEFAULT_COMPILER_OPTIONS),
                             skipAddingFilesFromTsConfig: true,
                         });
@@ -318,10 +321,20 @@ export class ProjectLoader {
         }
         return result;
     }
+    /**
+     * Under CARRICK_UNTRUSTED_TREE, the file system every project reads
+     * through: nothing whose real path is outside the checkout (carrick#2230).
+     * Nothing at all otherwise, so a project is built as it always was.
+     */
+    fileSystemOption() {
+        const bound = untrustedReadBound(this.repoRoot);
+        return bound ? { fileSystem: boundedFileSystem(bound) } : {};
+    }
     /** A ts-morph project built from one tsconfig and the files it lists. */
     projectFromConfig(configPath) {
         const imports = new ExternalImports();
         const project = new Project({
+            ...this.fileSystemOption(),
             tsConfigFilePath: configPath,
             // Over the tsconfig's own options: ts-morph lays these on top.
             compilerOptions: sidecarCompilerOptions(getCompilerOptionsFromTsConfig(configPath).options),
@@ -492,3 +505,53 @@ export class ProjectLoader {
         console.error(`[sidecar:project-loader:error] ${message}`);
     }
 }
+/**
+ * A ts-morph file system that reads only inside the bound. ts-morph reads the
+ * tsconfig, lists the files it names and reads each through this host, and its
+ * module resolution asks it whether a file exists. Writes are not bounded:
+ * the write guard owns them (carrick#1748).
+ */
+function boundedFileSystem(bound) {
+    const base = new Project({
+        compilerOptions: sidecarCompilerOptions({}),
+        skipAddingFilesFromTsConfig: true,
+        skipFileDependencyResolution: true,
+    }).getFileSystem();
+    const missing = (filePath) => Object.assign(new Error(`ENOENT: no such file or directory, open '${filePath}'`), { code: 'ENOENT' });
+    return new Proxy(base, {
+        get(target, prop, receiver) {
+            const value = Reflect.get(target, prop, receiver);
+            if (typeof value !== 'function')
+                return value;
+            const fn = value.bind(target);
+            switch (prop) {
+                case 'readFileSync':
+                    return (p, e) => {
+                        if (!bound.allows(p))
+                            throw missing(p);
+                        return fn(p, e);
+                    };
+                case 'readFile':
+                    return async (p, e) => {
+                        if (!bound.allows(p))
+                            throw missing(p);
+                        return fn(p, e);
+                    };
+                case 'fileExistsSync':
+                case 'directoryExistsSync':
+                    return (p) => bound.allows(p) && fn(p);
+                case 'fileExists':
+                case 'directoryExists':
+                    return async (p) => bound.allows(p) && (await fn(p));
+                case 'readDirSync':
+                    return (p) => (bound.allows(p) ? fn(p) : []);
+                case 'globSync':
+                    return (patterns) => fn(patterns).filter((f) => bound.allows(f));
+                case 'glob':
+                    return async (patterns) => (await fn(patterns)).filter((f) => bound.allows(f));
+                default:
+                    return fn;
+            }
+        },
+    });
+}

package/sidecar/dist/src/type-inferrer.d.ts

@@ -38,6 +38,21 @@ import type { InferRequestItem, InferResult, ExtractionConfig } from './types.js
  * test (`machinery-indicator-mirror.test.ts`) asserts the two sets stay equal.
  */
 export declare const MACHINERY_MEMBER_INDICATORS: Set<string>;
+/**
+ * `text` is `string`, alone or beside `null` and `undefined` in either order:
+ * the only payload a raw-text read publishes (carrick#1842).
+ */
+/**
+ * Source text with every plain string literal written in double quotes:
+ * `'/a'`, `"/a"` and an interpolation-free `` `/a` `` are one value, so text
+ * that differs only in its quotes compares equal (carrick#2056).
+ *
+ * The text is read left to right, pairing quotes the way the scanner does,
+ * so a template's closing backtick never pairs with the next template's
+ * opening one. A literal holding a quote, a backslash or an interpolation is
+ * copied as it is, and so is an unterminated one with everything after it.
+ */
+export declare function canonicalStringQuotes(text: string): string;
 /**
  * Options for TypeInferrer construction
  */
@@ -385,6 +400,11 @@ export declare class TypeInferrer {
      * belongs to a read.
      */
     private typeNodeStatedAtRead;
+    /**
+     * A wrapper between a body read and the binding it initialises that leaves
+     * the read's value as it is: `await`, parentheses, `!`, a cast, `satisfies`.
+     */
+    private wrapsReadTransparently;
     /**
      * A stated type with `any` or `unknown` written anywhere in it (`unknown`,
      * `Record<string, unknown>`, `{ items: any[] }`) leaves a position open: it
@@ -924,6 +944,180 @@ export declare class TypeInferrer {
      * return statements are.
      */
     private recoverPayloadFromResponseExpressions;
+    /** How one payload node reads: its stated annotation, else its resolved type. */
+    private payloadCandidateOf;
+    /** A payload whose contract a type node in the source states. */
+    private statedPayloadCandidate;
+    /**
+     * Join the payloads of several response branches into one contract, as
+     * several return statements are joined: an empty object drops beside a
+     * branch with members, equal texts dedupe, and the rest is a union.
+     */
+    private joinPayloadCandidates;
+    /**
+     * True when a handler's awaited return, or a member of its union, is a
+     * serialised-body envelope: an object with a numeric `statusCode` or
+     * `status` member and a `body` member typed `string`. Either member may be
+     * optional, as a platform's result type declares them.
+     *
+     * HTTP vocabulary only, the class `RESPONSE_INIT_MEMBER_NAMES` is. A `body`
+     * typed as an object is not an envelope: a runtime that serialises the
+     * handler's return value sends that object as the payload, so the shape is
+     * ambiguous and keeps the ordinary reading.
+     */
+    private typeIsSerialisedBodyEnvelope;
+    /** A member's type with `undefined` and `null` removed, or `undefined` if absent. */
+    private envelopeMemberType;
+    /**
+     * True when a handler's return is a serialised-body envelope AND the source
+     * shows the body is serialised, so the envelope reading applies:
+     *  - a returned branch builds an envelope whose `body` is `JSON.stringify`
+     *    of a value, inline, through a `const`, or in a builder the reading can
+     *    follow (`branchShowsSerialisation`); or
+     *  - the envelope type is declared outside the repository (a platform's
+     *    result type) with every member optional. Nothing else returns such a
+     *    type, so a value of it returned as-is is still transport. The repo's
+     *    own all-optional types (`Partial<Article>`) engage only on evidence.
+     *
+     * A domain object that merely has `status` and `body` members (an article,
+     * a message) shows neither and keeps the ordinary reading.
+     */
+    private serialisedBodyEnvelopeEngages;
+    /**
+     * True when a returned branch builds an envelope from a serialised value:
+     * a literal whose `body` is `JSON.stringify(...)`, a call to a builder the
+     * reading can follow, or a call handing on one such envelope.
+     */
+    private branchShowsSerialisation;
+    /**
+     * The arguments a call could hand back as its result: every argument but
+     * an object literal, which is the call's input (`create({ body:
+     * JSON.stringify(doc) })` stores a document, it does not respond with it),
+     * and but a function, whose returns are read as the call's callbacks.
+     */
+    private handedOnArguments;
+    /**
+     * The returned branches of an envelope handler: each returned expression,
+     * conditional sides split. A returned call whose callbacks return values
+     * (`settle().then(ok, fail)`) is carried by those returns, plus every
+     * envelope it is handed directly (`withFallback(() => a, b)` can answer
+     * `b`); a call whose callbacks return nothing stays a branch of its own.
+     */
+    private envelopeBranches;
+    /**
+     * The `function_return` answer for a handler that returns a serialised-body
+     * envelope: the union of the values its success branches serialised.
+     *
+     * Each returned branch is read by `readEnvelopeBranch`. Error and redirect
+     * branches contribute nothing (carrick#1161). If any branch cannot be read,
+     * the answer is `unknown` with the decided reason `serialised_body_unread`
+     * and one sentence per cause: the branches that did read are part of the
+     * contract, and neither the envelope nor its `string` body is any of it.
+     */
+    private inferSerialisedBodyEnvelope;
+    /** An `unknown` answer the inferrer decided, carrying its reason at the root. */
+    private decidedAbstain;
+    /**
+     * What one returned branch of an envelope handler serialised:
+     *  - an envelope object literal: the argument of the `JSON.stringify` that
+     *    produced its `body`, inline or through a `const` in the same function;
+     *    its status member decides the branch;
+     *  - a call to a response builder this repository declares
+     *    (`envelopeBuilderOf`): the argument the builder serialises; the
+     *    argument or literal its status member takes decides the branch;
+     *  - any other call handing on exactly one envelope argument (never an
+     *    object literal, which is the call's input): that
+     *    envelope is read in its place. Its own stated status decides the
+     *    branch; only when it states none does a status the outer call's
+     *    arguments state decide (`log(ctx, 503, "code", prebuilt)`).
+     * Anything else, and a payload holding `any` or `unknown`, is unread, with
+     * its cause.
+     */
+    private readEnvelopeBranch;
+    /** The status a builder call sends: its status argument, or the builder's literal. */
+    private builderCallStatus;
+    /**
+     * The status an envelope expression states itself: a literal's status
+     * member, or what a followable builder call sends. `'undecided'` for
+     * anything else (a variable holding an envelope states nothing here).
+     */
+    private envelopeOwnStatus;
+    /** The status an envelope literal's `statusCode` or `status` member states. */
+    private envelopeLiteralStatus;
+    /** The status a value states, classified as a send's status argument is. */
+    private statusOfValue;
+    /**
+     * The value node an object literal gives a member: a property assignment's
+     * initializer, or a shorthand's own name.
+     */
+    private envelopeMemberValue;
+    /**
+     * The value an envelope literal's `body` serialises: the argument of a
+     * `JSON.stringify` written there, or written as the initializer of a
+     * `const` that `scope` declares and `body` names. `undefined` when `body`
+     * is built any other way.
+     */
+    private serialisedBodyArgument;
+    /**
+     * The initializer of the `const` an identifier (or a shorthand member's
+     * name) refers to, when `scope` itself declares it.
+     */
+    private constInitializerInScope;
+    /**
+     * The symbol of the value a node names: a shorthand member's value symbol
+     * (its own symbol is the property), else the identifier's symbol.
+     */
+    private valueSymbolOf;
+    /** The index of the `params` entry a node names, or `undefined`. */
+    private parameterIndexOf;
+    /**
+     * How a call's callee builds an envelope, when the callee is a function this
+     * repository declares (not lib, not an installed package) and every return
+     * it makes is an envelope literal:
+     *  - returns whose status member is a literal 4xx or 5xx are its failure
+     *    path and are ignored; a builder with nothing else is `'failure'`, so a
+     *    call to it is an error branch;
+     *  - every other return must serialise the same parameter into `body` and
+     *    take its status from the same parameter, or state the same literal
+     *    success or redirect status.
+     * `undefined` when the callee is anything else.
+     */
+    private envelopeBuilderOf;
+    /**
+     * The single function a callee symbol declares with a body: a function
+     * declaration, or a variable initialised with an arrow or function
+     * expression.
+     */
+    private builderFunctionOf;
+    /**
+     * The payload a builder call serialises. The source states it, and the
+     * answer is explicit, when the argument carries `satisfies`/`as`, when the
+     * builder's parameter is one of its type parameters and the call passes
+     * type arguments (`reply<AddNoteResult>(201, x)`), or when the parameter is
+     * declared with a type that says something. Otherwise the argument's own
+     * type is read.
+     */
+    private builderPayloadCandidate;
+    /**
+     * True when a declared parameter type does not say what is sent: a top
+     * type, the `object` keyword, an object type that names no member (`{}`,
+     * `Record<string, unknown>`), a union that admits both primitives and
+     * objects (a JSON-value type such as `string | number | Json[] | { [k:
+     * string]: Json }`), or a type that mentions a type parameter. A builder
+     * that takes "any value" states nothing about the payload a call hands it,
+     * so the argument's own type is read instead.
+     */
+    private typeNodeStatesNothing;
+    /** A serialised value's candidate, unread when it holds a top type. */
+    private envelopePayloadCandidate;
+    /**
+     * A payload candidate, or unread when its printed type is or holds `any`
+     * or `unknown` anywhere (`{ [x: string]: any }`, `{ data: any }`). A
+     * contract with a hole in it is not published on this path: the capture
+     * would refuse the text and re-read the line, which can publish the
+     * envelope.
+     */
+    private checkedEnvelopeCandidate;
     /**
      * The request field each member of a joined union answers
      * (`response-modes.ts`). Case texts are joined by the published union's
@@ -1133,6 +1327,19 @@ export declare class TypeInferrer {
      * followed to a small depth; anything else is returned as itself.
      */
     private expandResponseBranches;
+    /**
+     * The symbol an anchor is named from: the type's own symbol, unless that
+     * symbol's name is synthetic (`__type`, `__object`, ...), in which case the
+     * alias symbol (carrick#2148).
+     *
+     * `type Widget = { id: string }` and an instantiated `Page<Order>` carry
+     * the anonymous `__type` as their own symbol and the alias as their alias
+     * symbol. Reading the own symbol first and stopping because it is truthy
+     * left every object-literal alias without an anchor, while the same shape
+     * declared as an interface had one. The own symbol still wins whenever it
+     * has a real name, so every type anchored before keeps its anchor.
+     */
+    private anchorSymbolOf;
     /**
      * The deterministic source symbol of a resolved type (`Payment` for a payload
      * typed `Payment`), or `undefined` when there is no single user-defined
@@ -1154,7 +1361,8 @@ export declare class TypeInferrer {
      * declarations IN its `source_file`, so the request must point at the file
      * that actually declares the tsc-witnessed payload type.
      *
-     * The declarations read are those of the type's own symbol, so a name
+     * The declarations read are those of the symbol the anchor is named from
+     * (`anchorSymbolOf`: the type's own symbol, or its alias's), so a name
      * imported through a barrel reports the file that declares it, and a name
      * two files declare reports the one this type resolves to. A declaration in
      * an installed package or a TypeScript lib is reported as it is found, as
@@ -1460,6 +1668,18 @@ export declare class TypeInferrer {
      * The first such call in source order: a body is read once.
      */
     private platformBodyReadIn;
+    /**
+     * The platform body read whose result `located` is a MEMBER of, or
+     * `undefined` (carrick#2057).
+     *
+     * A member is a property or element access off a binding, or a name
+     * destructured out of one. The binding must be initialised by the body read
+     * `platformBodyReadIn` finds in the function that declares it, with only
+     * transparent wrappers between the two (`await`, parentheses, `!`, a cast,
+     * `satisfies`). The binding itself is not a member, and neither is a member
+     * of anything else (a query object, a parameter, an outbound response).
+     */
+    private parsedBodyReadHolding;
     /**
      * The request contract the source states AT a body read, or null when it
      * states none there (carrick#807).
@@ -1888,6 +2108,20 @@ export declare class TypeInferrer {
      * then substring match (preferring containing matches).
      */
     private matchByText;
+    /**
+     * What a locator's text names, read off its own parse (carrick#2056):
+     *
+     *  - `texts`: the normalized text of the expression it names and of each
+     *    wrapper it carries around it (`return`, a `const x =` binding, a label,
+     *    `await`, parentheses, a cast, `satisfies`, `!`). A node strictly inside
+     *    that expression is not among them;
+     *  - `rootKind` and `rootStart`: the innermost of those, its kind, and where
+     *    its text starts in the locator.
+     *
+     * `null` when the text does not parse as one expression or one statement:
+     * there is no structure to read, and the caller keeps its text rule.
+     */
+    private locatorNames;
     /**
      * Pick the best match from a set of candidate nodes:
      * smallest range, then closest to target line.