@suss/extractor 0.34.0 → 0.34.1

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { Effect, MessageBusSemantics, DeployableUnit, CodeUnitKind, RequestSpellingMetadata, BehavioralSummary, Predicate, ValueRef, TypeShape, RenderNode, ProvenanceSlot, BoundaryBinding, WrapperReference, TestMetadata, GraphqlDeclaredContract, ConfidenceInfo, Transition, Gap, Input, Output } from '@suss/behavioral-ir';
+import { Effect, MessageBusSemantics, DeployableUnit, CodeUnitKind, RequestSpellingMetadata, BehavioralSummary, TypeShape, Predicate, ValueRef, RenderNode, ProvenanceSlot, BoundaryBinding, WrapperReference, TestMetadata, GraphqlDeclaredContract, ConfidenceInfo, Transition, Gap, Input, Output } from '@suss/behavioral-ir';
 import { z } from 'zod';
 
 /**
@@ -390,11 +390,32 @@ type DiscoveryMatch = {
      * `defaultStatusCodes`.
      */
     statusCodeDecorator?: string;
+    /**
+     * The number each of a library's own status constants is, by the
+     * path of the export (`HttpStatus.NO_CONTENT`), for when the
+     * library is not installed and its declaration cannot give them.
+     * `importModule` says which module exports them.
+     */
+    statusCodeConstants?: Record<string, number>;
     /**
      * The call that puts one path in front of every route the
      * application serves, NestJS's `app.setGlobalPrefix("api")`.
      */
     globalPrefix?: GlobalPrefixCall;
+    /**
+     * How a route states an API version and how the application serves
+     * one, NestJS's `@Controller({ version })` with
+     * `app.enableVersioning()`.
+     */
+    versioning?: RouteVersioning;
+    /**
+     * Decorators, on the route's method or its class, that list a
+     * status the route can respond with, such as `@nestjs/swagger`'s
+     * `@ApiNotFoundResponse()`. A generated spec declares these
+     * statuses because of the decorators, so a check does not expect a
+     * path to produce them.
+     */
+    declaredStatuses?: DeclaredStatusDecorators;
 } | {
     /**
      * A `for-of` loop over a literal array of route specs, read as one
@@ -675,6 +696,14 @@ type BindingExtraction = {
     } | {
         type: "fromClientMethod";
     };
+    /**
+     * Which argument is the request's options object, for a call that
+     * takes one: fetch's second argument, the config axios takes after the
+     * URL or after the body. The pack's `redirectOption` is read off it.
+     */
+    options?: {
+        position: number;
+    };
 };
 /**
  * Where a declared channel's spelling comes from.
@@ -793,6 +822,61 @@ interface GlobalPrefixCall {
         methods: Record<number, string>;
     };
 }
+/** Decorators that list a status a route can respond with. */
+interface DeclaredStatusDecorators {
+    /** The modules the decorators are imported from. */
+    importModule: string | string[];
+    /**
+     * The status each decorator declares, or null for one that reads the
+     * status from `statusKey` in its options object, `@ApiResponse({ status })`.
+     */
+    decorators: Readonly<Record<string, number | null>>;
+    statusKey: string;
+}
+/**
+ * Where an application puts the version a route serves. `path` puts it
+ * in the URL as a segment. `outsidePath` reads it from somewhere else
+ * in the request, such as a header, so every version of a route shares
+ * one path.
+ */
+type VersionPlacement = "path" | "outsidePath";
+/**
+ * API versions on decorated routes. A route serves the versions its own
+ * method decorator states, or else the ones its class decorator's
+ * options state, or else the application's default. The application
+ * ignores every version until a call on it turns versioning on.
+ */
+interface RouteVersioning {
+    /** The key in the class decorator's options object, NestJS's `version`. */
+    option: string;
+    /** A method decorator imported from `importModule` that sets one route's version, NestJS's `Version`. */
+    decorator: string;
+    /** The export from `importModule` that means every version, NestJS's `VERSION_NEUTRAL`. */
+    neutral: string;
+    /** The call on the application that turns versioning on, NestJS's `enableVersioning`. */
+    call: Pick<GlobalPrefixCall, "method" | "application">;
+    /** The key in the call's options that says the placement. */
+    typeKey: string;
+    /**
+     * The placement each of the library's constants means, by the path of
+     * the export (`VersioningType.URI`), and by the number the constant is
+     * equal to when the library is installed.
+     */
+    types: Readonly<Record<string, VersionPlacement>>;
+    typeNumbers: Readonly<Record<number, VersionPlacement>>;
+    /** The placement when the call takes no options at all. */
+    defaultType: VersionPlacement;
+    /**
+     * The key for the text put before a version in the path, and the text
+     * when the options leave it out. `false` there means no text at all.
+     */
+    pathPrefix: {
+        key: string;
+        default: string;
+    };
+    /** The key for the versions a route that states none serves. */
+    defaultVersionKey: string;
+}
 /** A wrapper handed to the routable's constructor as an option. */
 interface WrapperOptionRegistration extends WrapperFunctionShape {
     /** The option the wrapper is under, e.g. "defaultHook". */
@@ -1100,6 +1184,18 @@ type ResponsePropertyMeaning = {
 };
 /** Whether a refused request comes back as a response or as an exception. */
 type FailureDelivery = "response" | "exception";
+/** Whether the client follows a redirect itself or hands the 3xx to the caller. */
+type RedirectDelivery = "followed" | "response";
+/**
+ * The request option that decides, for one call, whether the client
+ * follows a redirect: `redirect` for fetch, `maxRedirects` for axios,
+ * `allow_redirects` for requests. A call that sets it to one of
+ * `handsBack` gets the 3xx, and any other value it settles on follows.
+ */
+interface RedirectOption {
+    name: string;
+    handsBack: ReadonlyArray<string | number | boolean>;
+}
 interface ResponsePropertyMapping {
     /** Property or method name on the response (e.g. "ok", "status", "json") */
     name: string;
@@ -1221,6 +1317,15 @@ interface PatternPack {
      * `"response"`.
      */
     failureDelivery?: FailureDelivery;
+    /**
+     * What this client does with a redirect by default. `fetch` and axios
+     * follow it, so the caller only ever sees the response at the end of
+     * the chain. httpx and Faraday hand the 3xx back. Defaults to
+     * `"response"`.
+     */
+    redirectDelivery?: RedirectDelivery;
+    /** The option one call sets to change `redirectDelivery` for itself. */
+    redirectOption?: RedirectOption;
     /**
      * Build extra code units from a parent unit's body, for callbacks the
      * runtime schedules that are not top-level declarations: React event
@@ -1967,6 +2072,70 @@ declare function runsBefore(effectLine: number, terminalEndLine: number): boolea
  */
 declare function markReturnsAsExitCode(summaries: readonly BehavioralSummary[], returnsTheCode: ReadonlySet<string>, workspaceRoot?: string): void;
 
+/**
+ * Splices a project helper's paths into the caller that handed it a
+ * value, so a client caller that leaves its status test to a helper
+ * still shows which statuses it handles.
+ *
+ *   resp = requests.get(url)
+ *   return check_response(resp)
+ *
+ * Each adapter finds the call, reads the helper's paths with the
+ * caller's terminals, and says which parameter got which value. Splitting
+ * the caller's branch along those paths is the same in every language,
+ * so it lives here.
+ */
+
+/**
+ * Past this many paths a helper is doing more than reading a response,
+ * and multiplying every caller path by it would bury the caller's own.
+ */
+declare const MAX_HELPER_PATHS = 16;
+/**
+ * The caller's branch split along each path of the helper called at
+ * `at`. A throw or an exit in the helper ends the caller at the call,
+ * and a path that returns goes on to the caller's own ending.
+ */
+declare function throughHelper(branch: RawBranch, at: {
+    start: number;
+    end: number;
+}, helperBranches: readonly RawBranch[]): RawBranch[];
+/**
+ * The fields two readers of one response read between them, as the
+ * records of field names a branch's `expectedInput` lists.
+ */
+declare function mergeReadShapes(a: TypeShape | null, b: TypeShape | null): TypeShape | null;
+/** One call in a caller's body that hands a helper the response, in source order. */
+interface HandOffSite {
+    /** The helper's paths, in the caller's terms. */
+    helper: readonly RawBranch[];
+    preconditions?: readonly RawCondition[] | undefined;
+    /** The line the statement holding the call starts on, which decides whether a branch reaches it. */
+    line: number;
+    /** The lines the call is written on. */
+    at: {
+        start: number;
+        end: number;
+    };
+    /** A call in a `finally` runs on every path, even one that left before it. */
+    alwaysRuns?: boolean;
+}
+/**
+ * The branch split at each hand-off on it, in source order. A path that
+ * ended in one helper goes no further, so the hand-offs after it are not
+ * asked about on that path.
+ */
+declare function splitAtHandOffs(branch: RawBranch, sites: readonly HandOffSite[], from?: number): RawBranch[];
+/**
+ * A helper's paths with each test on a parameter it was handed turned
+ * into a test on the caller's variable, keyed parameter to variable.
+ * Null when no path tests what it was handed, or when there are too many
+ * paths to splice. This is for an adapter that writes a variable's value
+ * as a dependency on the variable's name, the way the caller's own tests
+ * on it are written.
+ */
+declare function helperPathsOnVariables(helperBranches: readonly RawBranch[], passed: ReadonlyMap<string, string>): RawBranch[] | null;
+
 /**
  * Writes `metadata.moduleImports` on a set of summaries.
  *
@@ -2201,7 +2370,17 @@ interface StructuredPathConditionsInput<Cond, Terminal> {
      * where a terminal is.
      */
     terminalsByStmt: ReadonlyMap<StructuredStatement<Cond>, readonly Terminal[]>;
+    /**
+     * The tests whose arms go on as separate paths after they rejoin, so
+     * a terminal later in the body is reached once under each arm. A
+     * client's caller keeps the arms of a test on the response status,
+     * since which statuses it handles is the point of reading it, even
+     * when neither arm returns. Every other test is merged away as usual.
+     */
+    keepsArms?: KeepsArms<Cond>;
 }
+/** Whether the arms of the test written as this condition go on as separate paths. */
+type KeepsArms<Cond> = (condition: Cond) => boolean;
 interface StructuredPathConditionsResult<Cond, Terminal> {
     /** The paths to each terminal, keyed by the caller's own terminal handle. */
     byTerminal: Map<Terminal, ConditionInfo<Cond>[][]>;
@@ -2305,13 +2484,12 @@ declare class EnclosingNodes<T extends ParsedNode<T>> {
  * more places for a statement than anyone remembers to list. So an adapter
  * does not list the containers to descend into. The walk visits every
  * named child, and the adapter only lists the nodes whose body belongs to
- * what they declare, because that list is short and the grammar already
- * has a node type for each.
+ * what they declare, because that list is short.
+ *
+ * The adapter also says how to read a node's children. Its parser's own
+ * getters keep the array they build on the node, so each adapter reads
+ * children through one accessor of its own that leaves nothing behind.
  */
-/** The one thing the walk needs from a parse tree node. */
-interface WalkableNode<T> {
-    readonly namedChildren: ReadonlyArray<T | null>;
-}
 /**
  * Returned by `into` for a node whose children the walk should leave
  * unread, such as one whose body belongs to what it declares. It is a
@@ -2325,12 +2503,14 @@ interface NodeVisitor<T, C> {
     /** What to carry into this node's children, or `SKIP_CHILDREN` to leave them unread. */
     into(node: T, carried: C): C | typeof SKIP_CHILDREN;
 }
+/** A node's named children in source order, read by the adapter's own accessor. */
+type ChildrenOf<T> = (node: T) => readonly T[];
 /**
  * Every named node under `root`, depth first and in source order, with a
  * value the visitor updates as the walk descends. `root` itself is not
  * visited, because a caller starts from the body it is reading.
  */
-declare function walkDescendants<T extends WalkableNode<T>, C>(root: T, carried: C, visitor: NodeVisitor<T, C>): void;
+declare function walkDescendants<T, C>(root: T, carried: C, childrenOf: ChildrenOf<T>, visitor: NodeVisitor<T, C>): void;
 
 /**
  * The project root when nothing declares one.
@@ -2342,6 +2522,15 @@ declare function walkDescendants<T extends WalkableNode<T>, C>(root: T, carried:
 /** The deepest directory containing every file, or undefined when they share no absolute root. */
 declare function commonDirectoryOf(files: ReadonlyArray<string>): string | undefined;
 
+/**
+ * What a client call does with a redirect once the adapter has read the
+ * value the call gives the pack's redirect option. Each adapter reads
+ * the value in its own language, and all of them decide the same way.
+ */
+
+/** `"response"` when the value is one that hands the 3xx back, and `"followed"` otherwise. */
+declare function redirectDeliveryWhenSet(option: RedirectOption, value: string | number | boolean): RedirectDelivery;
+
 /**
  * Which files a test pack reads. `suss extract --intent` hands a test
  * pack the files the PRDs list under `coveredBy`, written the way the
@@ -2512,6 +2701,8 @@ interface ExtractionConfig {
     importRoots?: readonly string[] | undefined;
     /** The modules the project lists, which decide which units discovery finds. */
     modules?: readonly SettledModule[] | undefined;
+    /** The directory the run walks when it walks only part of its project. */
+    walkedDirectory?: string | undefined;
 }
 /**
  * The run options as one part of the cache key, so a run never reads an
@@ -2928,6 +3119,15 @@ declare function buildUngatedExtractionReport(args: {
     summaries: ReadonlyArray<BehavioralSummary>;
 }): ExtractionReport;
 
+/**
+ * A directory suss writes for itself, such as the extraction cache, can
+ * land in any package of a repository, where a root `.gitignore` entry
+ * for `/.suss` does not reach. A `.gitignore` of `*` inside it keeps it
+ * out of version control wherever it is, the way pytest's cache does.
+ */
+/** Creates `dir` and a `.gitignore` of `*` in it. A `.gitignore` already there is kept. */
+declare function makeIgnoredDirectory(dir: string): void;
+
 /**
  * Parses a process keeps between runs of one project, by file.
  *
@@ -3402,6 +3602,13 @@ interface RawTerminal {
         shape: TypeShape | null;
     } | null;
     exceptionType: string | null;
+    /** On a throw, what the exception inherits from, where the adapter read it. */
+    exceptionAncestry?: {
+        ancestors: string[];
+        incomplete: boolean;
+    };
+    /** On a throw, the status the framework sends when no handler catches it. */
+    statusWhenUncaught?: number;
     message: string | null;
     /** Set on a throw whose pack declared the thrown status is the wire response. */
     producesResponse?: boolean;
@@ -3614,6 +3821,10 @@ interface RawCodeStructure {
     successAccessors?: string[];
     /** Whether this client's non-2xx arrives as a response or a rejection. */
     failureDelivery?: FailureDelivery;
+    /** Whether this client follows a redirect or hands the 3xx back. */
+    redirectDelivery?: RedirectDelivery;
+    /** Statuses the handler's own code lists as possible responses, such as FastAPI's `responses=`. */
+    declaredStatuses?: number[];
     /** Left exactly as written, because the extractor does not depend on
      * graphql-js. The parsing happens at check time. */
     graphqlDocument?: string;
@@ -3654,6 +3865,13 @@ interface RawCodeStructure {
      * `unreadOutcome` gap, so no checker counts it against the unit.
      */
     unreadBinding?: string;
+    /**
+     * Why the adapter could not read this unit's body, when reading it threw.
+     * The summary keeps the unit's identity and binding, and the reason comes
+     * out as an `unreadOutcome` gap, so an empty body is not taken for one
+     * that does nothing.
+     */
+    readFailure?: string;
     /**
      * Readings the adapter passed along without collapsing. This module writes
      * the reason for any that came back unreadable or ambiguous. Written and
@@ -3689,4 +3907,4 @@ declare function rawConditionToPredicate(c: RawCondition): Predicate;
 declare function effectToIR(effect: RawEffect): Effect;
 declare function paramToInput(param: RawParameter): Input;
 
-export { type AccessRecognizer, type AdapterCodeStamp, type AdapterStamp, type ArgumentParser, type AstCapableOps, type BindingExtraction, type BodyContent, type CacheAttribution, type CacheDiagnostic, type CacheInput, type CacheLayer, type CacheLookup, type CallOps, type CaseGroup, type ChannelSource, type ChosenReading, type ClassOps, type ConditionHandle, type ConditionInfo, type ConditionSource, type ConstructedFrom, type ContractPattern, type DeclaredBinding, type DeclaredBy, type DeclaredMatch, type DeclaredModule, type DefaultedReading, type DiscoveredCustomUnit, type DiscoveredSubUnit, type DiscoveredSubUnitParent, type DiscoveryMatch, type DiscoveryPattern, type EffectArg, type EmptyStage, EnclosingNodes, type ExitKind, type ExtractionConfig, type ExtractionReport, type ExtractorOptions, type FailureDelivery, type GlobalPrefixCall, type HealthCheck, type HealthViolation, type HelperDeclarations, type HelperSearch, type HelperSink, type HelperValue, IdMap, IdSet, type Identified, type InputMappingPattern, type InputRead, type InvocationRecognizer, KeptParses, type LanguageAdapter, type LoweredStatementParts, MAX_ENTRIES, MAX_PATHS, MODULE_SURFACE_RECOGNITION, type ModuleInitOptions, type NodeVisitor, type OpsCarrier, type PackDeclarations, type PackFailure, type PackFunnel, type PackGradient, type PackTally, type ParameterSupplier, type ParsedNode, type PartialPlan, PathBudgetExceeded, type PatternPack, type ProjectHelper, type ProjectHelpers, type RawBranch, type RawCodeStructure, type RawCondition, type RawDeclaredContract, type RawDependencyCall, type RawEffect, type RawParameter, type RawProvenance, type RawTerminal, type Reading, type ReceiverOrigin, type RegistrationHelper, type ResponsePropertyMapping, type ResponsePropertyMeaning, type RootRecord, SKIP_CHILDREN, type SettledModule, type SourceRange, type SourceSpelling, type StatedSlot, type StatementBlock, type StructuredPathConditionsInput, type StructuredPathConditionsResult, type StructuredStatement, type TerminalExtraction, type TerminalMatch, type TerminalPattern, type TestCaseMatch, type Timer, type TimingReport, type TransparentWrapper, type UnitRecord, UnmodeledFlow, type UnsettledName, type ValueEntry, type ValueOps, type WalkEnd, type WalkableNode, type WrapperMethodRegistration, type WrapperOptionRegistration, type WrapperRegistration, absentReading, ambiguousReading, andThenReading, assembleSummary, assessConfidence, buildUngatedExtractionReport, commonDirectoryOf, composeWrappers, computeContentHash, computeDistHashFrom, configuredCallOption, createAdapterStamp, createCacheLayer, createPackTallies, createTimer, detectGaps, effectToIR, emptyTally, enumerateOrDegrade, enumerateStructuredPaths, evaluatePackHealth, extractionConfigStamp, firstWrittenReading, formatPackHealth, guardsHoldOn, httpRouteDiscovery, isListedTestFile, makeTransitionId, mapReading, markReturnsAsExitCode, matchesTestFileName, moduleInitStructure, moduleOfFile, noopTimer, packGradients, paramToInput, projectFileStamp, rawConditionToPredicate, recordPackFailure, registrationHelperDiscovery, routeHelperIndex, runDigest, runsBefore, scopeOption, settleModules, sharedGatingConditions, sourceRefsOf, stampMayMissAWrite, stampModuleImports, stampModules, storageSystemOption, summaryCountsByPack, tallyUnit, terminalToOutput, unreadableReading, unwrapJsonStringify, valueToReadFurtherFrom, walkDescendants, wrapperDiscovery, writtenReading };
+export { type AccessRecognizer, type AdapterCodeStamp, type AdapterStamp, type ArgumentParser, type AstCapableOps, type BindingExtraction, type BodyContent, type CacheAttribution, type CacheDiagnostic, type CacheInput, type CacheLayer, type CacheLookup, type CallOps, type CaseGroup, type ChannelSource, type ChildrenOf, type ChosenReading, type ClassOps, type ConditionHandle, type ConditionInfo, type ConditionSource, type ConstructedFrom, type ContractPattern, type DeclaredBinding, type DeclaredBy, type DeclaredMatch, type DeclaredModule, type DeclaredStatusDecorators, type DefaultedReading, type DiscoveredCustomUnit, type DiscoveredSubUnit, type DiscoveredSubUnitParent, type DiscoveryMatch, type DiscoveryPattern, type EffectArg, type EmptyStage, EnclosingNodes, type ExitKind, type ExtractionConfig, type ExtractionReport, type ExtractorOptions, type FailureDelivery, type GlobalPrefixCall, type HandOffSite, type HealthCheck, type HealthViolation, type HelperDeclarations, type HelperSearch, type HelperSink, type HelperValue, IdMap, IdSet, type Identified, type InputMappingPattern, type InputRead, type InvocationRecognizer, type KeepsArms, KeptParses, type LanguageAdapter, type LoweredStatementParts, MAX_ENTRIES, MAX_HELPER_PATHS, MAX_PATHS, MODULE_SURFACE_RECOGNITION, type ModuleInitOptions, type NodeVisitor, type OpsCarrier, type PackDeclarations, type PackFailure, type PackFunnel, type PackGradient, type PackTally, type ParameterSupplier, type ParsedNode, type PartialPlan, PathBudgetExceeded, type PatternPack, type ProjectHelper, type ProjectHelpers, type RawBranch, type RawCodeStructure, type RawCondition, type RawDeclaredContract, type RawDependencyCall, type RawEffect, type RawParameter, type RawProvenance, type RawTerminal, type Reading, type ReceiverOrigin, type RedirectDelivery, type RedirectOption, type RegistrationHelper, type ResponsePropertyMapping, type ResponsePropertyMeaning, type RootRecord, type RouteVersioning, SKIP_CHILDREN, type SettledModule, type SourceRange, type SourceSpelling, type StatedSlot, type StatementBlock, type StructuredPathConditionsInput, type StructuredPathConditionsResult, type StructuredStatement, type TerminalExtraction, type TerminalMatch, type TerminalPattern, type TestCaseMatch, type Timer, type TimingReport, type TransparentWrapper, type UnitRecord, UnmodeledFlow, type UnsettledName, type ValueEntry, type ValueOps, type VersionPlacement, type WalkEnd, type WrapperMethodRegistration, type WrapperOptionRegistration, type WrapperRegistration, absentReading, ambiguousReading, andThenReading, assembleSummary, assessConfidence, buildUngatedExtractionReport, commonDirectoryOf, composeWrappers, computeContentHash, computeDistHashFrom, configuredCallOption, createAdapterStamp, createCacheLayer, createPackTallies, createTimer, detectGaps, effectToIR, emptyTally, enumerateOrDegrade, enumerateStructuredPaths, evaluatePackHealth, extractionConfigStamp, firstWrittenReading, formatPackHealth, guardsHoldOn, helperPathsOnVariables, httpRouteDiscovery, isListedTestFile, makeIgnoredDirectory, makeTransitionId, mapReading, markReturnsAsExitCode, matchesTestFileName, mergeReadShapes, moduleInitStructure, moduleOfFile, noopTimer, packGradients, paramToInput, projectFileStamp, rawConditionToPredicate, recordPackFailure, redirectDeliveryWhenSet, registrationHelperDiscovery, routeHelperIndex, runDigest, runsBefore, scopeOption, settleModules, sharedGatingConditions, sourceRefsOf, splitAtHandOffs, stampMayMissAWrite, stampModuleImports, stampModules, storageSystemOption, summaryCountsByPack, tallyUnit, terminalToOutput, throughHelper, unreadableReading, unwrapJsonStringify, valueToReadFurtherFrom, walkDescendants, wrapperDiscovery, writtenReading };