@suss/adapter-typescript 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,537 @@
+import { FunctionDeclaration, FunctionExpression, ArrowFunction, MethodDeclaration, Node, CallExpression, SourceFile, Project, Expression } from 'ts-morph';
+import { RawCondition, DiscoveryPattern, PatternPack, ExtractorOptions, InvocationRecognizer, AccessRecognizer, RawCodeStructure, TerminalPattern, RawBranch, RawDeclaredContract, ContractPattern, ResponsePropertyMapping, RawTerminal } from '@suss/extractor';
+import { BehavioralSummary, BoundaryBinding, Predicate, TypeShape, ValueRef } from '@suss/behavioral-ir';
+
+/**
+ * Reported by `lookup`. Surfaces what the cache decided and, for
+ * partial-hits, the file-churn breakdown so callers can render a
+ * diagnostic.
+ */
+interface CacheDiagnostic {
+    kind: "hit" | "partial-hit" | "miss";
+    /** Reason the lookup missed (only set when kind === "miss"). */
+    missReason?: "no-manifest" | "schema-mismatch" | "packs-changed" | "tsconfig-changed";
+    /**
+     * Counts describing the file churn that produced a partial hit.
+     * Only populated when kind === "partial-hit".
+     */
+    partial?: {
+        /** Cached summaries whose location.file is in the unchanged set. */
+        reusedSummaries: number;
+        /** Files the adapter needs to re-extract per-file from. */
+        filesToReExtract: number;
+        /** Files added to the include set since the cached run. */
+        addedFiles: number;
+        /** Files removed from the include set since the cached run. */
+        removedFiles: number;
+        /** Files whose mtime/size differs (excludes added/removed). */
+        changedFiles: number;
+    };
+}
+/**
+ * Result of a cache lookup. The adapter dispatches on `kind`:
+ *
+ *   - "hit"          — the entire summary set is valid; return it
+ *                      verbatim, skip extraction.
+ *   - "partial-hit"  — `kept` is correct as far as their location.file
+ *                      went; re-extract `filesToExtract` per-file and
+ *                      re-run the closure / rethrow passes over the
+ *                      merged set.
+ *   - "miss"         — manifest absent or coarse keys (schema, packs,
+ *                      tsconfig) changed; full re-extract.
+ */
+type CacheLookup = {
+    kind: "hit";
+    summaries: BehavioralSummary[];
+    diagnostic: CacheDiagnostic;
+} | {
+    kind: "partial-hit";
+    kept: BehavioralSummary[];
+    filesToExtract: string[];
+    diagnostic: CacheDiagnostic;
+} | {
+    kind: "miss";
+    diagnostic: CacheDiagnostic;
+};
+
+/** One pack's path through the funnel. */
+interface PackFunnel {
+    pack: string;
+    /**
+     * Import specifiers that make a file relevant to this pack. Empty
+     * for an ungated pack, which walks every file.
+     */
+    gates: string[];
+    /**
+     * Gate specifiers that do not resolve from the tsconfig. Non-empty
+     * here usually means the target project's dependencies are not
+     * installed, which stops symbol-resolution packs while leaving
+     * textual-gate packs working, so the run half-succeeds in a way
+     * nothing else surfaces.
+     */
+    unresolvedGates: string[];
+    /** Files the pre-filter selected for this pack. */
+    candidateFiles: number;
+    /** Units discovered across those files. */
+    unitsDiscovered: number;
+    /** Summaries built from those units. */
+    summariesProduced: number;
+}
+interface ExtractionReport {
+    /** Files in the tsconfig include set, or null when the caller supplied a Project. */
+    filesInProject: number | null;
+    /** Files the bootstrap loaded and the extract walked. */
+    filesWalked: number;
+    packs: PackFunnel[];
+    summaries: number;
+    /**
+     * The first stage whose count was zero, when the run produced
+     * nothing. Null when the run produced summaries.
+     */
+    emptyStage: EmptyStage | null;
+}
+type EmptyStage = "tsconfig" | "gateResolution" | "candidateFiles" | "discovery" | "assembly";
+
+type FunctionRoot = FunctionDeclaration | FunctionExpression | ArrowFunction | MethodDeclaration;
+/**
+ * Public API — returns RawCondition[] with structured: null.
+ * Use collectAncestorConditionInfos when you need the Expression nodes.
+ */
+declare function collectAncestorBranches(terminalNode: Node, functionRoot: FunctionRoot): RawCondition[];
+/**
+ * Public API — returns RawCondition[] with structured: null.
+ * Use collectEarlyReturnConditionInfos when you need the Expression nodes.
+ */
+declare function collectEarlyReturns(terminalNode: Node, functionRoot: FunctionRoot): RawCondition[];
+
+interface ClientCallSite {
+    callExpression: CallExpression;
+    /** Method name on the client object (e.g. "getUser"), null for bare calls like fetch() */
+    methodName: string | null;
+}
+interface DiscoveredUnit {
+    func: FunctionRoot;
+    kind: string;
+    name: string;
+    callSite?: ClientCallSite;
+    /** The discovery pattern that produced this unit. Set by discoverUnits. */
+    pattern?: DiscoveryPattern;
+    /**
+     * Populated by `resolverMap`-style discovery (GraphQL code-first).
+     * The adapter uses it to build a `graphql-resolver` binding directly,
+     * without running this through the REST-shaped bindingExtraction
+     * path.
+     *
+     * `schemaSdl` is the typeDefs string captured from the same
+     * ApolloServer config object the resolver map came from, when
+     * we can statically resolve it (string literal or gql-tagged
+     * template, inline or const-bound). Surfaced on the summary so
+     * the checker's nested-selection pairing can look up return-type
+     * fields without needing a separate schema provenance.
+     */
+    resolverInfo?: {
+        typeName: string;
+        fieldName: string;
+        schemaSdl?: string;
+    };
+    /**
+     * Populated by `graphqlHookCall` discovery (GraphQL consumer side).
+     * Carries the operation shape the adapter uses to build a
+     * `graphql-operation` binding. `operationName` is absent for
+     * anonymous operations (`gql\`query { ... }\``, no identifier).
+     *
+     * `document` is the raw GraphQL document source (the inner text of
+     * the gql-tagged template literal, backticks stripped). Kept
+     * alongside the parsed shape so downstream tools can re-parse if
+     * they need additional detail beyond what we surface here. Absent
+     * when the document body wasn't statically readable and the header
+     * was recovered from `TypedDocumentNode` type arguments — a
+     * cross-module codegen reference to a document produced by a helper.
+     *
+     * `variables` list the `$name: Type` declarations at the operation
+     * header. Each becomes an `Input` on the resulting summary so
+     * pairing layers can match against resolver args. Empty when the
+     * document body wasn't read.
+     *
+     * `rootFields` is the list of root-level selection names — the
+     * fields the operation actually selects under Query / Mutation /
+     * Subscription. Used by the checker's pairing pass. Empty when the
+     * document body wasn't read.
+     *
+     * `unresolved` is set when the argument was recognized as a GraphQL
+     * document reference but the header couldn't be fully read. The unit
+     * is still emitted (operation type comes from the call shape) and the
+     * gap surfaces on the summary as `metadata.graphql.unresolvedDocument`
+     * so nothing is silently dropped.
+     */
+    operationInfo?: {
+        operationType: "query" | "mutation" | "subscription";
+        operationName?: string;
+        document?: string;
+        variables: Array<{
+            name: string;
+            type: string;
+            required: boolean;
+        }>;
+        rootFields: string[];
+        unresolved?: {
+            reference: string;
+            reason: string;
+        };
+    };
+    /**
+     * Populated by `packageExports` discovery. Carries the package
+     * identity the adapter uses to build a `function-call` binding
+     * with `package` + `exportPath` fields — i.e. a provider summary
+     * for a publicly-exported library function.
+     */
+    packageExportInfo?: {
+        packageName: string;
+        exportPath: string[];
+    };
+    /**
+     * Populated by `decoratedRoute` discovery (NestJS-style REST
+     * controllers). The adapter uses it to build a `rest` binding
+     * with `(method, path)` directly, bypassing the
+     * `bindingExtraction` config used by Express / Fastify (which
+     * extract from `app.get(...)` registration calls — the wrong
+     * shape for decorator-driven controllers).
+     */
+    routeInfo?: {
+        method: string;
+        path: string;
+    };
+    /**
+     * Metadata merged onto the assembled summary's `metadata` field.
+     * Populated when a pack's `discoverUnits` callback stamps provenance
+     * on the units it returns (the discovery-layer sibling of the
+     * per-sub-unit `metadata` the `subUnits` hook carries).
+     */
+    metadata?: Record<string, unknown>;
+}
+
+/**
+ * Discover code units in `sourceFile` by running all patterns.
+ * Deduplicates entries with the same function node and kind.
+ */
+declare function discoverUnits(sourceFile: SourceFile, patterns: DiscoveryPattern[]): DiscoveredUnit[];
+
+interface TimingReport {
+    totalMs: number;
+    phases: Array<{
+        label: string;
+        durationMs: number;
+        calls: number;
+    }>;
+}
+interface Timer {
+    /** Run `fn`, accumulate wall time under `label`, return its result. */
+    time<T>(label: string, fn: () => T): T;
+    /** Async variant — same accumulation rule. */
+    timeAsync<T>(label: string, fn: () => Promise<T>): Promise<T>;
+    /** Snapshot of all accumulated phases, ordered by total time descending. */
+    report(): TimingReport;
+}
+
+/**
+ * Nested function nodes a pack claimed as sub-units. The unit-body
+ * walkers stop at these so the sub-unit's behavior isn't double-counted
+ * on the parent.
+ */
+type DescentBarriers = ReadonlySet<Node>;
+
+declare function extractCodeStructure(unit: DiscoveredUnit, pack: PatternPack, filePath: string, invocationRecognizers?: InvocationRecognizer[], accessRecognizers?: AccessRecognizer[], barriers?: DescentBarriers): RawCodeStructure;
+interface TypeScriptAdapterConfig {
+    tsConfigFilePath?: string;
+    project?: Project;
+    frameworks: PatternPack[];
+    extractorOptions?: ExtractorOptions;
+    /**
+     * Include library summaries for every function reachable through a
+     * static call edge from a pack-discovered unit. Defaults to `true` —
+     * internal orchestrators, helpers, and utilities that frameworks
+     * don't recognise become `library`-kind summaries with
+     * `recognition: "reachable"` so readers can see their behaviour.
+     * Set to `false` for pack-only extraction (smaller output; only the
+     * units packs explicitly claim).
+     */
+    includeReachable?: boolean;
+    /**
+     * Called once at the end of each `extractAll` / `extractFromFiles`
+     * with the wall-clock breakdown of the major extraction phases.
+     * Always-on instrumentation cost is negligible (millisecond-scale
+     * `performance.now()` calls); the callback is the opt-in for
+     * surfacing it. CLI uses this to render the per-extract summary
+     * line and the `--timing` breakdown.
+     */
+    onTiming?: (report: TimingReport) => void;
+    /**
+     * Called once per extract with the cache hit/miss decision and the
+     * partial-reuse diagnostic — counts of cached summaries that fine-
+     * grained invalidation would have salvaged on a coarse miss.
+     * Phase 4a uses this to validate the dep-tracking model before
+     * activating partial-reuse.
+     */
+    onCacheDiagnostic?: (diagnostic: CacheDiagnostic) => void;
+    /**
+     * Called once per `extractAll` with the funnel: files in the
+     * tsconfig, files walked, and per-pack gate / candidate / unit /
+     * summary counts. The CLI renders it when a run produces nothing,
+     * so "wrote 0 summaries" can say which stage the count died at
+     * instead of leaving the user to guess.
+     *
+     * Not called on a cache hit, where no stage ran.
+     */
+    onExtractionReport?: (report: ExtractionReport) => void;
+    /**
+     * On-disk cache directory for the coarse-key extraction cache.
+     * Pass an absolute path; defaults to `.suss/cache/` next to the
+     * tsconfig (or under cwd when no tsconfig path is supplied).
+     * Pass `null` to disable caching entirely. The cache stores one
+     * `manifest.json` keyed against (adapter version, pack versions,
+     * sorted file mtime/size stamps); on a warm run with no changes
+     * the lookup is stat-only and skips extraction.
+     */
+    cacheDir?: string | null;
+}
+interface TypeScriptAdapter {
+    project: Project;
+    /**
+     * Extract summaries from a specific list of files. Returns a
+     * Promise so the implementation can do concurrent I/O during
+     * the pre-filter / lazy-load phases without bottlenecking on
+     * sync `fs.readFileSync`.
+     */
+    extractFromFiles(filePaths: string[]): Promise<BehavioralSummary[]>;
+    /** Extract summaries from every (non-declaration) file the Project knows about. */
+    extractAll(): Promise<BehavioralSummary[]>;
+}
+declare function createTypeScriptAdapter(config: TypeScriptAdapterConfig): TypeScriptAdapter;
+
+/**
+ * Extract all raw branches from a function, composing:
+ *   1. findTerminals — locate terminal nodes
+ *   2. collectEarlyReturnConditionInfos — prior guard clauses
+ *   3. collectAncestorConditionInfos — enclosing branch conditions
+ *   4. parseConditionExpression — Expression → Predicate
+ *   5. extractInvocationEffects — bare expression-statement calls
+ *      (Phase 1.5b — attaches to the default branch so handler /
+ *      useEffect bodies carry their side-effect set)
+ *
+ * `isDefault` is true when the branch has no conditions, or all
+ * conditions come from early returns/throws.
+ */
+declare function extractRawBranches(func: FunctionRoot, terminalPatterns: TerminalPattern[], invocationRecognizers?: InvocationRecognizer[], accessRecognizers?: AccessRecognizer[], barriers?: DescentBarriers): RawBranch[];
+
+/**
+ * A Project covering `rootDir`, for a codebase with no tsconfig to read.
+ * Returns the project and the files it loaded.
+ */
+declare function createProjectWithoutTsconfig(rootDir: string): {
+    project: Project;
+    files: string[];
+};
+/** The nearest tsconfig or jsconfig at or above `startDir`, or null. */
+declare function findNearestTsconfig(startDir: string): string | null;
+
+interface ContractReadResult {
+    declaredContract: RawDeclaredContract;
+    boundaryBinding: BoundaryBinding | null;
+}
+/**
+ * Read the declared contract for a discovered handler unit.
+ *
+ * Traces from the handler's registration site (e.g., `s.router(contract, { ... })`)
+ * back to the contract definition, then extracts the declared responses for
+ * this specific endpoint.
+ *
+ * Returns null if the handler wasn't registered with a contract or the contract
+ * can't be resolved.
+ */
+declare function readContract(unit: DiscoveredUnit, pattern: ContractPattern): ContractReadResult | null;
+/**
+ * Resolve the contract for a consumer call site.
+ *
+ * Given `client.getUser(...)`, traces back to the `initClient(contract, ...)`
+ * call to find the contract, then extracts the endpoint definition for the
+ * matched method name (e.g. "getUser").
+ */
+declare function readContractForClientCall(callExpression: Node, methodName: string, pattern: ContractPattern): ContractReadResult | null;
+
+interface TsDiscoveryContext {
+    /** Full filesystem path of the source file. Useful for excluding
+     *  test / story files via the pack's own regex. */
+    getFilePath(sourceFile: SourceFile): string;
+    /**
+     * Yield every export from the source file whose declaration is a
+     * function — function declarations, arrow / function-expression
+     * variable initializers, and re-exports of either. Skips
+     * non-function exports (constants, classes, types).
+     *
+     * Each entry carries the exported name (the binding the consumer
+     * uses), the function root, and whether the export is the file's
+     * default export. `default` is included; the pack decides whether
+     * to handle it (typically the data-driven `namedExport(["default"])`
+     * already does, and the callback skips to avoid duplicates).
+     */
+    exportedFunctions(sourceFile: SourceFile): Array<{
+        name: string;
+        func: FunctionRoot;
+        isDefault: boolean;
+    }>;
+    /**
+     * Walk a function's body for return statements whose value is a
+     * JSX element / fragment / self-closing tag. Returns true on the
+     * first match; false otherwise. Skips into nested function bodies
+     * — nested arrow returning JSX is its own component, not part of
+     * this function's output.
+     *
+     * Concise-arrow bodies (`() => <X/>`) are handled — the body IS
+     * the implicit return.
+     */
+    hasJsxReturn(func: FunctionRoot): boolean;
+}
+declare function createTsDiscoveryContext(): TsDiscoveryContext;
+
+/**
+ * Parse a ts-morph Expression into a structured Predicate.
+ * Returns null when the expression can't be decomposed cleanly.
+ * The caller wraps null into { type: "opaque", sourceText, reason: "complexExpression" }.
+ *
+ * Call expressions are resolved recursively: if the callee is a local
+ * function with a single-expression body, the body is parsed as a
+ * predicate and parameter references are substituted with the call-site
+ * arguments. This reduces opaqueness for patterns like `if (isActive(user))`.
+ */
+declare function parseConditionExpression(expr: Expression, depth?: number): Predicate | null;
+
+interface BranchFieldAccesses {
+    /** Terminal location (start, end lines) — used to match back to transitions */
+    terminalLocation: {
+        start: number;
+        end: number;
+    };
+    /** The shape of fields the consumer reads from the response in this branch */
+    expectedInput: TypeShape | null;
+}
+/**
+ * For a client function, collect the fields accessed on the response variable
+ * within each branch. Returns one entry per branch (matched by terminal location).
+ *
+ * @param callExpr The API call expression (fetch(), client.getUser())
+ * @param func The enclosing function
+ * @param branchLocations Terminal locations from the extracted branches
+ * @param responseSemantics Optional response property mappings from the pack —
+ *   used to filter non-body properties instead of a hardcoded list
+ */
+declare function collectClientFieldAccesses(callExpr: CallExpression, func: Node, branchLocations: Array<{
+    start: number;
+    end: number;
+}>, responseSemantics?: ResponsePropertyMapping[]): BranchFieldAccesses[];
+
+/**
+ * Resolve a ts-morph Expression node to a structured ValueRef.
+ * Uses only expr.getSymbol()?.getDeclarations()[0] for symbol lookup —
+ * never findReferencesAsNodes() which is project-wide and quadratic.
+ *
+ * Follows intermediate variable assignments (const data = result.body)
+ * so that property chains through temporaries resolve to their origin.
+ * Depth-bounded to prevent infinite recursion on cyclic references.
+ */
+declare function resolveSubject(expr: Expression, depth?: number): ValueRef;
+
+/**
+ * The context the TypeScript adapter passes to a pack's `subUnits`
+ * hook. Covers JSX-attribute-walking and call-expression-walking plus
+ * the resolution helpers packs need to map AST nodes back to function
+ * bodies and source text.
+ *
+ * All walks are scoped to the parent function and deliberately do NOT
+ * recurse into nested function bodies — sub-units of nested functions
+ * belong to those functions' summaries, not to the enclosing parent.
+ */
+interface TsSubUnitContext {
+    /**
+     * Yield every JSX attribute on every JSX element / self-closing
+     * element in the parent's body, excluding any inside nested
+     * function bodies. The tag is the source text of the element's
+     * tag-name node.
+     */
+    findJsxAttributes(parent: FunctionRoot): TsJsxAttributeLocation[];
+    /**
+     * Yield every call expression matching `name` (bare identifier
+     * callee only — e.g. `useEffect(...)`, not `React.useEffect(...)`).
+     * Nested function bodies are skipped.
+     */
+    findCallExpressionsByName(parent: FunctionRoot, name: string): CallExpression[];
+    /**
+     * Resolve a JSX attribute's value to a function body, if the value
+     * is (a) an inline arrow or function expression or (b) an
+     * identifier referring to a function declared inside the parent.
+     * Returns null for prop-delegating references (`props.onClick`),
+     * identifiers that resolve outside the parent's scope, or any
+     * non-function expression.
+     */
+    resolveAttributeValueFunction(attr: TsJsxAttributeLocation, parent: FunctionRoot): {
+        func: FunctionRoot;
+        localName: string | null;
+    } | null;
+    /**
+     * Return the Nth argument of a call as a function body, if it's an
+     * inline arrow or function expression. Returns null for identifier
+     * references, property accesses, or non-function values.
+     */
+    getCallArgumentFunction(call: CallExpression, position: number): FunctionRoot | null;
+    /**
+     * Return the Nth argument raw node (or null if absent).
+     */
+    getCallArgument(call: CallExpression, position: number): Node | null;
+    /**
+     * If `node` is an array literal expression, return each element's
+     * source text. If it's some other expression, return a single entry
+     * with the node's full text. Null means no deps argument was given.
+     */
+    readArrayLiteralText(node: Node | null): string[] | null;
+}
+/**
+ * A located JSX attribute: which element it's on, its name, and the
+ * expression node supplying its value (null for boolean-shorthand
+ * attributes like `<input disabled>`).
+ */
+interface TsJsxAttributeLocation {
+    tag: string;
+    name: string;
+    valueExpression: Node | null;
+}
+declare function createTsSubUnitContext(): TsSubUnitContext;
+
+interface FoundTerminal {
+    node: Node;
+    terminal: RawTerminal;
+}
+
+/**
+ * Walk every descendant of `func` and try each pattern in order (first match
+ * wins per node). Returns all matched terminals across the whole function.
+ *
+ * Descends into nested function expressions / arrows so a unit whose
+ * terminal output is produced inside a Promise executor or `.then`
+ * callback (`res.json(data)` on the unit's own `res` parameter) is still
+ * discovered. Inside a nested function only escaping terminals are
+ * matched — see `NESTED_ESCAPING_MATCH_TYPES`.
+ */
+declare function findTerminals(func: FunctionRoot, patterns: TerminalPattern[], barriers?: DescentBarriers): FoundTerminal[];
+
+declare const ADAPTER_VERSION = "0.1.0";
+/**
+ * Compute a cache-friendly identity for an adapter+packs combination.
+ * Stable across processes given the same inputs; bumps when any pack
+ * declares a new version, the adapter version changes, or the loaded
+ * adapter dist file changes (dev-mode rebuild auto-invalidation).
+ */
+declare function computeAdapterPacksDigest(packVersions: ReadonlyArray<{
+    name: string;
+    version?: string;
+}>): string;
+
+export { ADAPTER_VERSION, type CacheDiagnostic, type CacheLookup, type ClientCallSite, type ContractReadResult, type DiscoveredUnit, type EmptyStage, type ExtractionReport, type FoundTerminal, type FunctionRoot, type PackFunnel, type Timer, type TimingReport, type TsDiscoveryContext, type TsJsxAttributeLocation, type TsSubUnitContext, type TypeScriptAdapter, type TypeScriptAdapterConfig, collectAncestorBranches, collectClientFieldAccesses, collectEarlyReturns, computeAdapterPacksDigest, createProjectWithoutTsconfig, createTsDiscoveryContext, createTsSubUnitContext, createTypeScriptAdapter, discoverUnits, extractCodeStructure, extractRawBranches, findNearestTsconfig, findTerminals, parseConditionExpression, readContract, readContractForClientCall, resolveSubject };