vouchington-tooling 0.32.0 → 0.34.0

package/README.md

@@ -8,11 +8,16 @@ GitHub Actions policy checks and compiler host freshness with bounded build sett
 [`config-inventory`](../../docs/config-inventory.md) collects environment, dynamic-configuration,
 and package-manager evidence using caller-owned file roles and policies.
 
+[`finite-enum-ripple`](../../docs/finite-enum-ripple.md) compares finite TypeScript declarations,
+route configuration, routed pages, and factory calls. Consumers supply every tracked-file role,
+declaration name, route label, factory pattern, and exception.
+
 ```bash
 npm install vouchington-tooling
 # optional, only if you import vouchington-tooling/sql-ast
 npm install @libpg-query/parser
-# optional, only if you import vouchington-tooling/contract-schema
+# optional, if you import vouchington-tooling/contract-schema, finite-enum-ripple,
+# or post-publication-inventory
 # (classic compiler API; typescript@7's package root is version-only)
 npm install @typescript/typescript6
 # optional, only if you use the Vitest reporter export
@@ -366,6 +371,31 @@ summaries and quoted attributes; it is not a general HTML validator or sanitizer
 the input or infers semantic relevance, cost, schema conformance, or failure causes. The existing
 `markdownSectionBetweenHeadings` API retains its original boundary behavior.
 
+`hasUncheckedMarkdownTask` reports parsed unchecked GFM task items, ignoring code and non-task text.
+`markdownLiteralSpans` returns source-backed `{ kind, position, value }` facts for fenced or indented
+code, inline code, and raw HTML. `markdownHtmlFacts` distinguishes inline HTML from block HTML and
+labels CommonMark block types 1–7; `markdownHtmlBlocks` selects block types 1, 6, and 7, retaining
+the parser's source bounds, including type 1 blocks through their matching closer or end of input.
+Positions use 1-indexed line/column coordinates and JavaScript string offsets, including CRLF and
+Unicode source text. These APIs return facts rather than mdast nodes so callers can apply their own
+content policy without binding it to parser internals.
+
+```ts
+import {
+  hasUncheckedMarkdownTask,
+  markdownHtmlBlocks,
+  markdownLiteralSpans,
+} from 'vouchington-tooling/markdown'
+
+const hasOpenTask = hasUncheckedMarkdownTask(body)
+const literalSpans = markdownLiteralSpans(body)
+const blockHtml = markdownHtmlBlocks(body)
+```
+
+`markdownHtmlBlocks` reports CommonMark types 1, 6, and 7; inline tags do not appear in that result.
+Use `markdownHtmlFacts` when inline/block classification and other CommonMark HTML block types are
+also needed.
+
 Machine-wide agent configuration now belongs to [vouchington-machines](https://github.com/vouchington/vouchington-machines/blob/main/docs/agent-config.md).
 Use its `configure-agents.sh` and `diagnose-agents.sh`; project hooks and MCP configuration remain in their checkouts.
 
@@ -449,6 +479,138 @@ aliases; `options.onRouteError` enables lenient response and request extraction.
 does not cache programs or depend on the caller's repository layout. OpenAPI document assembly
 remains a separate `openapi-document` call.
 
+`options.onAmbiguousAttribution` optionally emits facts for response calls lexically inside handler
+functions registered to multiple routes, plus inline response calls within those handlers. Facts
+are delivered after discovery succeeds, ordered by normalized source location; each callback gets
+its own copy of the sorted route list. It recognizes direct property handlers on `const`
+object-literal receivers, shorthand properties, immutable aliases, and inline handlers. Mutable
+receivers whose properties may be reassigned, variable receivers without object-literal initializers,
+and non-identifier receiver expressions fail closed for attribution.
+Direct identifier assignment, identifier writes through array/object destructuring or loop targets,
+identifier updates, and dot-property assignment or updates make that binding ineligible for attribution.
+Computed receiver-property writes, `delete`, runtime reflection, and other indirect mutation are not
+analyzed. Named helper calls are not followed transitively: for example, an
+emission inside `emit(ctx)` is not attributed when a registered `shared(ctx)` handler calls
+`emit(ctx)`. The callback does not change the discovered contract result.
+
+Query contracts (`apiQuery`) carry requiredness. A top-level parameter descriptor type may include
+`required: true` (inline or through an intersection such as `{ readonly required: true }`); the
+extracted descriptor then has `required: true` and the OpenAPI parameter emits `required: true`,
+otherwise `required: false`. `required` must be the literal `true`; `false`, `boolean`, optional, or
+non-literal values fail as a malformed query parameter, as do `required` together with `default` and
+`required` on `csv-array` `items`.
+
+`discoverRequestValidationFacts({ program, sourceFiles, validators, factories, executedCallbacks })`
+reports, per registered route (`METHOD:/template`), the route `kind` and `source`, every configured
+validator call its handlers reach (`validatorSites`), every configured handler-factory call
+(`factorySites`), and the raw request carriers the handlers read (`carrierReads`). It reports
+facts only; which routes must validate and what counts as covered stay with the caller.
+
+```ts
+import { discoverRequestValidationFacts } from 'vouchington-tooling/api-contract-discovery'
+
+const facts = discoverRequestValidationFacts({
+  program,
+  sourceFiles,
+  validators: [
+    {
+      module: 'lib/validation.ts', // resolved declaration path suffix, or a package specifier
+      exportName: 'validateInput',
+      operationArgument: 1,
+      carriers: { kind: 'input-object', argument: 2 }, // or { kind: 'fixed', carriers, optionCarriers }
+    },
+  ],
+  factories: [
+    {
+      module: 'lib/factory.ts',
+      exportName: 'createThingHandler',
+      optionsArgument: 0,
+      operationProperty: 'operation',
+      carriers: ['path', 'body'],
+    },
+  ],
+  executedCallbacks: [
+    {
+      module: 'lib/admit.ts',
+      exportName: 'admitWork',
+      argument: 0,
+      properties: ['beforeCapacity'],
+    },
+  ],
+})
+```
+
+A call matches only when its callee resolves, through aliases, re-exports and path mappings, to the
+configured export of a declaration file matching `module` (`.d.ts`, `.d.mts` and `.d.cts` suffixes
+are ignored when comparing, and the configured `module` may be written with or without a `.ts`,
+`.mts`, `.cts`, `.js`, `.mjs` or `.cjs` extension, so `lib/validation.js` matches `lib/validation.ts`
+and `lib/validation.d.ts`); import specifier text and same-named local functions never match.
+Operation keys resolve through literals, `const`s (including imported ones), `as const`,
+`satisfies`, helper parameters bound to static arguments, and, for factories, the option property
+including spread `const` objects; anything else, including a name with no symbol, gives
+`operation: null` with `unresolvedReason`. Each validated carrier reports `origins`, the request
+carriers (`path`, `query`, `body`, `header`) its value derives from, traced through calls, followed
+helper returns, branches, logical operands, spreads and earlier assignments; `unresolved` is set
+when part of the value depends on an unbound parameter. An unconditional reassignment of the
+identifier itself earlier in the same function body (not inside a branch, loop or `try`) replaces
+the earlier origins, conditional reassignments merge, and property writes such as `x.limit = n`
+always add; an assignment on a statically dead path (`if (false)`) is ignored. A destructured
+local traces only the property or element it binds (`const { chosen } = pair`), resolved through
+object and array literals, `const`s and followed helper returns (also awaited), and falls back to the
+whole initializer when it cannot be selected (rest, computed key, spread, unknown source).
+A destructured handler context parameter (`({ query, params, request }) => ...`) binds each member
+to its carrier. A helper parameter that is reassigned is not trusted as the bound operation key:
+only a lone unconditional reassignment is used, anything else gives `operation: null`.
+Generator functions are not followed, because calling one does not run its body.
+Fixed-carrier validators report the carrier itself as their origin.
+
+An input-object validator's input is resolved through `const` objects and spreads with
+last-write-wins semantics, like the factory option resolver. When it cannot be fully resolved (a
+non-literal input, a spread of something that is not a resolvable `const` object, a cyclic spread,
+or a computed property name), `carriers` lists what was found and the site sets
+`unresolvedCarriers` to the reason, so a consumer must not treat `carriers` as complete. A `const`
+object (input or factory options) with a property write before the use (`o.p = x`, `o[k] = x`,
+`delete o.p`, `o.n++`, `Object.assign(o, ...)`) is unresolvable too, and a factory then reports
+`operation: null`.
+
+`conditional` is true under `if`/ternary branches, the right of `&&`/`||`/`??`, `switch` cases,
+loop bodies, `catch` and `finally`. Handlers are walked into function declarations and `const`
+function expressions in `sourceFiles`, and only through bindings that are never reassigned (`let`
+and reassigned bindings are not trusted as handlers). A callback passed to a followed helper is
+followed only when the helper runs it, and is conditional unless it is invoked directly from the
+helper's own body outside any condition. Known limit: the invocations of an inline callback are
+found only in the callback's own source file, so a callback passed to a helper declared in another
+file (`withTx(ctx, async () => { validateInput(...) })`) is not walked. Inline callback properties of an `executedCallbacks` host,
+written as identifiers or string literals, are walked as executed and take only the condition of
+the call to the configured host, never how its implementation invokes them. Configured validator
+and factory implementations are never entered, but their callee and arguments are still walked for
+nested validator sites and reads; only reads that build a validator's input are left out, including
+reads inside a followed helper that only prepares that input. Validators evaluated while a handler is
+built (registration time) are not sites: only the walk of the handler reports validators. A handler a
+helper returns under a runtime branch (`if (flag) return ctx => ...`) reports `conditional: true`. Factory
+sites are reported for factory calls whose returned handler is a registration-time value (a route
+registration argument, a module `const` used as one, or a helper-returned handler); a factory call
+inside a handler body, such as a discarded `createThingHandler(options);`, is not a factory site.
+A factory site is also found through a module `const` initialized by a factory call that a handler
+calls (`const handler = createThingHandler({...})`, then `handler(ctx)`). Like validator sites,
+`FactorySite.conditional` is true when the site is reached only under a condition, and a site
+reached both ways is reported unconditional. A template-literal operation key folds to a string
+when every substitution resolves (literals, `const`s, bound parameters); otherwise it is `null`.
+
+Pass the `program` you already built: the function uses it as given and never builds its own.
+Helpers are followed only within `sourceFiles`, so pass every file that declares a followed helper,
+not just the route files; a helper declared elsewhere is not entered, which silently yields empty
+`origins` rather than an error. An omitted optional or defaulted helper argument contributes no
+origin and is not `unresolved`; an omitted required argument is `unresolved`. Per-call caches make
+repeated helpers cheap, so a 700-route program completes in seconds once the program exists.
+
+Each `carrierReads` entry has `access`: `key` for a static key (`ctx.query.limit`, destructured
+names, a resolvable `ctx.query[name]`), `computed` for a non-static key (`ctx.query[name]`, a
+computed destructuring key; `key: null`), and `whole` for the carrier used as a value
+(`consume(ctx.query)`, `{ ...ctx.params }`, `return ctx.headers`, a rest element) or a body read
+such as `ctx.request.json()` (`key: null`). A `const` alias of a carrier is not itself a read; its
+uses are.
+
 Version one recognizes literal-key `apiResponse`, `apiNoContent`, `apiOpenApiRawResponse`,
 `apiRequest`, `apiRequestContract`, `apiNoRequestBody`, `apiQuery`, and `apiHeaders` markers inside
 `app.route(...).get/post/put/patch/delete(...)` handlers. It also inspects unmarked `ctx.json`,
@@ -504,13 +666,19 @@ Caller-owned `apiOpenApiHttpResponse(key, response)` markers bind a constant opa
 carrying optional readonly `apiHttpResponseVariants` metadata. Each concrete union variant has
 `status` and `bodyKind`; content variants also have `mediaType` and `body`. Discovery associates
 the marked variable's status and body emissions without reading or replacing response bytes.
+Feasible assignments, deletions, or updates to its body or status, including cast and constant
+aliases, invalidate the selected contracts because their metadata no longer proves the dispatch.
 A status setter must dominate each body emission, including separate branches; constant context
 aliases are followed, assigned mutable context aliases and object-literal context wrappers fail closed,
 and helper parameters must resolve to the registered caller's unchanged response context.
 Helper-owned contracts also account for response emissions in their proven caller scopes.
+Opaque callees receiving the canonical HTTP context or its response object invalidate its contract;
+implemented helpers and consumed callbacks retain their proven dispatch behavior.
 Feasible assignments or deletions of response methods through canonical context aliases invalidate
 that dispatch evidence; dead, ignored, or unrelated method mutations preserve the contract.
 Indirect response `call`, `apply`, and `bind` forms fail closed, including borrowed context receivers.
+Compiler-resolved standard `Reflect.apply` uses its target and actual receiver to reject unrepresented
+HTTP emissions; project implementations, unrelated contexts, and non-executed calls are preserved.
 SSE frames and branded content variants reject body-forbidden 1xx, 204, 205, and 304 statuses.
 Literal bracket response methods have the same emission checks as property methods. Unrelated raw emissions
 remain unavailable. Separate branded response branches are checked together, and the nearest
@@ -548,6 +716,29 @@ the dedicated process group to exit after the direct child closes so descendants
 `isProcessGroupAlive` and `waitForProcessGroupExit` are also available when callers need the same
 process-group probe and bounded-drain semantics outside a browser session.
 
+### Contract schema type queries
+
+`getExportedTypeFacts` and `getCallRowTypeFacts` use an existing TypeScript `Program` from the
+`contract-schema` subpath. Every request must also pass `typescript`, the same TypeScript compiler
+API instance that created that `Program`. The source-file recognition check is a compatibility
+guard, and callers remain responsible for pairing the same compiler instance; the query uses the
+supplied API for compiler operations. Pass the exact `SourceFile.fileName`, an exported name or exact call
+expression text, and only the property names and exported comparison types the consumer needs.
+Facts include the displayed type, whether it is `any`, requested property displays, and requested
+assignability booleans. `defaultTypeParameterIndex` selects an exported generic default;
+direct defaults and direct references to preceding defaults are supported. Dependent composite
+defaults and uninstantiated generic type declarations used as assignability targets fail with an
+instruction to export and select a named instantiated type. Generic function values remain valid
+compiler-backed comparison targets. Default lookup uses an outer class, interface, or type-alias
+parameter list when present; otherwise it uses the first checker-visible call or construct
+signature, never a hidden implementation or a later overload.
+`rowSource: 'typeArgument'` selects a call's explicit type argument, while
+`rowSource: 'awaitedRows'` selects `Awaited<ReturnType>.rows[number]`.
+Call results are source ordered and include one-based line and column. An absent call returns an
+empty array so the consumer can enforce its own cardinality; a selected call missing its requested
+row type fails with a descriptive error. The package does not choose source files, expected
+properties, or contract policy.
+
 ## Workflow skills outside plugins
 
 The package ships a flat union of canonical workflow, testing, and database skills at
@@ -679,3 +870,30 @@ block, escaped and length-bounded like CI failures, and other entries are ignore
 `Status: none observed` or `Status: events observed`, each followed by
 `(journal entries only; no friction log observed)`; a truncated scan reports
 `unavailable (journal scan incomplete)` with the entries read so far.
+
+## Basic Auth exemption facts
+
+`vouchington-tooling/basic-auth-doc-sync` extracts literal exemption collections from
+TypeScript and route rows from Markdown. Callers configure declaration names and
+runbook headings, then compare the returned data using their own route policy.
+See the [API contract](docs/basic-auth-doc-sync.md).
+
+## Publication writer inventory facts
+
+`vouchington-tooling/post-publication-inventory` exports
+`analyzePostPublicationWriterSource(source, fileName, options)`. It returns five booleans for an
+approved capture-helper call, a capture opt-out, writes through a configured entity table,
+generated relation writes, and eligibility-table writes. Consumers supply every module, symbol,
+property, receiver, and table name through `PostPublicationWriterSourceOptions` and retain their
+inventory schema, tracked files, exceptions, and diagnostics.
+
+This preserves source-inventory heuristics, rather than proving runtime execution or SQL safety.
+Capture imports/calls are name-based and order-independent; relation-variable appends are
+order-sensitive. DML recognition examines literal/template text. Static table matching lowercases
+the extracted name; dynamic literal table matching preserves case. Malformed TypeScript uses the
+compiler's recovery tree. An argument-free append returns no relation fact.
+Pass TypeScript source (`.ts` or `.mts`); the parser uses TypeScript mode even if the file name ends
+in `.tsx`. Template expressions join their static fragments for DML matching, while DML prefixes
+for generated-table facts come from templates rather than ordinary quoted strings. Dynamic
+eligibility-table matching expects an unquoted literal immediately after the DML prefix and does
+not recognize `DELETE FROM ONLY`.

package/dist/api-contract-discovery/index.d.mts

@@ -27,5 +27,8 @@ export type { BackendRequestContract } from './request-contract-types.mts';
 export type { BackendQueryContract, BackendQueryContractRegistry } from './query-contract-types.mts';
 export type { HeaderContract, HeaderContractRegistry } from './header-contract-types.mts';
 export type { RegisteredRoute } from './registered-route-catalog.mts';
-export type { RouteDiscoveryError, DiscoverApiResponseContractsOptions, } from './response-contract-lenient.mts';
+export type { AmbiguousAttributionFact, RouteDiscoveryError, DiscoverApiResponseContractsOptions, } from './response-contract-lenient.mts';
 export type { DiscoverApiRequestContractsOptions } from './request-contract-lenient.mts';
+export { discoverRequestValidationFacts } from './request-validation-facts.mts';
+export type { RequestValidationFactsInput } from './request-validation-facts.mts';
+export type { Carrier, CarrierRead, ExecutedCallbackConfig, FactoryConfig, FactorySite, RouteValidationFacts, ValidatorConfig, ValidatorSite, ValidatorSiteCarrier, } from './request-validation-types.mts';

package/dist/api-contract-discovery/index.mjs

@@ -24,3 +24,4 @@ export { discoverApiQueryContracts } from './query-contract-registry.mjs';
 export { discoverApiHeaderContracts } from './header-contract-registry.mjs';
 export { discoverRegisteredRoutes, routeShape } from './registered-route-catalog.mjs';
 export { responseStatusCodesForContract } from './response-contract-status.mjs';
+export { discoverRequestValidationFacts } from './request-validation-facts.mjs';

package/dist/api-contract-discovery/protocol-analysis-cache.d.mts

@@ -0,0 +1,21 @@
+import ts from '../contract-schema/typescript-api.mts';
+export type Assignment = {
+    node: ts.BinaryExpression;
+    direct: boolean;
+    start: number;
+};
+/**
+ * Memoized protocol-proof results for one analysis run. Nodes are immutable, so every entry stays
+ * valid for the run; callers create one per run and drop it afterwards.
+ */
+export type ProtocolCache = {
+    /** Plain assignments per owning function (or source file), grouped by the symbol they write. */
+    assignments: Map<ts.Node, Map<ts.Symbol, Assignment[]>>;
+    /** Symbols written (assigned, updated, or looped over) anywhere in a source file. */
+    writtenSymbols: Map<ts.SourceFile, Set<ts.Symbol | undefined>>;
+    /** Whether a function is a supported protocol callback. */
+    supported: Map<ts.Node, boolean>;
+    /** Executable call expressions of a source file. */
+    calls: Map<ts.SourceFile, ts.CallExpression[]>;
+};
+export declare const createProtocolCache: () => ProtocolCache;

package/dist/api-contract-discovery/protocol-analysis-cache.mjs

@@ -0,0 +1,7 @@
+import ts from '../contract-schema/typescript-api.mjs';
+export const createProtocolCache = () => ({
+    assignments: new Map(),
+    writtenSymbols: new Map(),
+    supported: new Map(),
+    calls: new Map(),
+});

package/dist/api-contract-discovery/protocol-callback-invocation.d.mts

@@ -1,5 +1,6 @@
 import ts from '../contract-schema/typescript-api.mts';
+import type { ProtocolCache } from './protocol-analysis-cache.mts';
 type FunctionNode = ts.FunctionLikeDeclaration;
 /** Proves callback consumption through concrete helper bodies, without executing nested closures. */
-export declare function isSupportedProtocolCallback(fn: FunctionNode, checker: ts.TypeChecker): boolean;
+export declare function isSupportedProtocolCallback(fn: FunctionNode, checker: ts.TypeChecker, cache?: ProtocolCache): boolean;
 export {};

package/dist/api-contract-discovery/protocol-callback-invocation.mjs

@@ -7,8 +7,16 @@ import { callbackBindingReplaced, callbackOptionsEscape } from './protocol-callb
 import { enclosingFunction } from './protocol-marker-analysis.mjs';
 import { createProtocolCallbackValueResolver, isProtocolCallbackFunction as functionNode, protocolCallbackSourceCalls, protocolCallbackHasWrittenBindings, } from './protocol-callback-values.mjs';
 /** Proves callback consumption through concrete helper bodies, without executing nested closures. */
-export function isSupportedProtocolCallback(fn, checker) {
-    if (!fn.body || fn.asteriskToken || protocolCallbackHasWrittenBindings(fn, checker))
+export function isSupportedProtocolCallback(fn, checker, cache) {
+    const known = cache?.supported.get(fn);
+    if (known !== undefined)
+        return known;
+    const supported = proveProtocolCallback(fn, checker, cache);
+    cache?.supported.set(fn, supported);
+    return supported;
+}
+function proveProtocolCallback(fn, checker, cache) {
+    if (!fn.body || fn.asteriskToken || protocolCallbackHasWrittenBindings(fn, checker, cache))
         return false;
     const resolver = createProtocolCallbackValueResolver(checker);
     const { resolve, symbol } = resolver;
@@ -20,7 +28,7 @@ export function isSupportedProtocolCallback(fn, checker) {
             invalidated ||= callbackOptionsEscape(call, env, fn, resolver);
             return false;
         }
-        if (protocolCallbackHasWrittenBindings(callee.node, checker)) {
+        if (protocolCallbackHasWrittenBindings(callee.node, checker, cache)) {
             invalidated = true;
             return false;
         }
@@ -86,7 +94,7 @@ export function isSupportedProtocolCallback(fn, checker) {
     const call = argument.parent;
     if (!ts.isCallExpression(call) && !ts.isNewExpression(call)) {
         const owner = enclosingFunction(fn);
-        if (owner && isSupportedProtocolCallback(owner, checker))
+        if (owner && isSupportedProtocolCallback(owner, checker, cache))
             return body(owner.body, new Map(), new Set([owner]), false);
         return protocolCallbackSourceCalls(fn).some((candidate) => potentiallyExecuted(candidate) &&
             ((registeredHandler(candidate) &&

package/dist/api-contract-discovery/protocol-callback-values.d.mts

@@ -1,4 +1,5 @@
 import ts from '../contract-schema/typescript-api.mts';
+import type { ProtocolCache } from './protocol-analysis-cache.mts';
 type FunctionNode = ts.FunctionLikeDeclaration;
 export type CallbackValue = {
     node: ts.Node;
@@ -13,5 +14,5 @@ export declare function createProtocolCallbackValueResolver(checker: ts.TypeChec
     symbol: (node: ts.Node) => ts.Symbol | undefined;
     property: (value: CallbackValue | undefined, name: string, seen: Set<ts.Node>) => CallbackValue | undefined;
 };
-export declare function protocolCallbackHasWrittenBindings(fn: FunctionNode, checker: ts.TypeChecker): boolean;
+export declare function protocolCallbackHasWrittenBindings(fn: FunctionNode, checker: ts.TypeChecker, cache?: ProtocolCache): boolean;
 export {};

package/dist/api-contract-discovery/protocol-callback-values.mjs

@@ -108,7 +108,7 @@ export function createProtocolCallbackValueResolver(checker) {
     }
     return { resolve, symbol, property };
 }
-export function protocolCallbackHasWrittenBindings(fn, checker) {
-    return ((ts.isFunctionDeclaration(fn) && hasBindingWrite(fn, checker)) ||
-        runtimeParameters(fn).some((parameter) => hasBindingWrite(parameter, checker)));
+export function protocolCallbackHasWrittenBindings(fn, checker, cache) {
+    return ((ts.isFunctionDeclaration(fn) && hasBindingWrite(fn, checker, cache)) ||
+        runtimeParameters(fn).some((parameter) => hasBindingWrite(parameter, checker, cache)));
 }

package/dist/api-contract-discovery/protocol-execution-path.d.mts

@@ -1,3 +1,4 @@
 import ts from '../contract-schema/typescript-api.mts';
+import type { ProtocolCache } from './protocol-analysis-cache.mts';
 /** Proves execution up to an optional handler whose registered binding is already established. */
-export declare function executableProtocolPath(node: ts.Node, checker: ts.TypeChecker, boundHandler?: ts.Node): boolean;
+export declare function executableProtocolPath(node: ts.Node, checker: ts.TypeChecker, boundHandler?: ts.Node, cache?: ProtocolCache): boolean;

package/dist/api-contract-discovery/protocol-execution-path.mjs

@@ -3,12 +3,12 @@ import { isSupportedProtocolCallback } from './protocol-callback-invocation.mjs'
 import { potentiallyExecuted } from './protocol-executable-path.mjs';
 import { enclosingFunction } from './protocol-marker-analysis.mjs';
 /** Proves execution up to an optional handler whose registered binding is already established. */
-export function executableProtocolPath(node, checker, boundHandler) {
+export function executableProtocolPath(node, checker, boundHandler, cache) {
     if (!potentiallyExecuted(node))
         return false;
     let fn = enclosingFunction(node);
     while (fn && fn !== boundHandler) {
-        if (!potentiallyExecuted(fn) || !isSupportedProtocolCallback(fn, checker))
+        if (!potentiallyExecuted(fn) || !isSupportedProtocolCallback(fn, checker, cache))
             return false;
         fn = enclosingFunction(fn);
     }

package/dist/api-contract-discovery/protocol-http-association.mjs

@@ -10,6 +10,8 @@ import { visit } from './response-contract-route-analysis.mjs';
 import { isSupportedProtocolCallback } from './protocol-callback-invocation.mjs';
 import { mutatesHttpResponseMethod } from './protocol-http-method-mutations.mjs';
 import { opaqueProtocolCallbackPath } from './protocol-opaque-callback.mjs';
+import { opaqueHttpContextArgument } from './protocol-http-context-escapes.mjs';
+import { mutatedHttpResponse } from './protocol-http-response-mutations.mjs';
 const responseMethods = new Set([
     'setStatus',
     'pipeline',
@@ -27,6 +29,10 @@ export function associateHttpResponse(call, response, checker, siblings) {
     const emissions = new Map();
     for (const [scope, context] of httpContextScopes(handler, checker))
         visit(scope, (node) => {
+            if (mutatedHttpResponse(node, response, checker))
+                throw new Error('HTTP branded response body or status is mutated');
+            if (ts.isCallExpression(node) && opaqueHttpContextArgument(node, checker, context))
+                throw new Error('HTTP response context escapes through an opaque argument');
             if (mutatesHttpResponseMethod(node, context, checker))
                 throw new Error('HTTP response context method is mutated');
             if (ts.isCallExpression(node) &&
@@ -68,6 +74,8 @@ export function associateHttpResponse(call, response, checker, siblings) {
 }
 /** Opaque callbacks may emit through an independently proven handler's context. */
 export function opaqueHttpResponse(call, checker, context) {
+    if (opaqueHttpContextArgument(call, checker, context))
+        return true;
     if (context)
         return (responseMethods.has(contextResponseMethod(call.expression, context, checker, true) ??
             indirectHttpResponseMethod(call, context, checker) ??

package/dist/api-contract-discovery/protocol-http-context-callers.d.mts

@@ -1,6 +1,7 @@
 import ts from '../contract-schema/typescript-api.mts';
+import type { ProtocolCache } from './protocol-analysis-cache.mts';
 /** Use the same actual invocation sites for context admission and caller emission coverage. */
-export declare function httpContextInvocations(fn: ts.FunctionLikeDeclaration, checker: ts.TypeChecker): {
+export declare function httpContextInvocations(fn: ts.FunctionLikeDeclaration, checker: ts.TypeChecker, cache?: ProtocolCache): {
     registered: boolean;
     callers: ts.CallExpression[];
 };

package/dist/api-contract-discovery/protocol-http-context-callers.mjs

@@ -5,15 +5,21 @@ import { registeredHandler } from './protocol-callback-registration.mjs';
 import { executableProtocolPath } from './protocol-execution-path.mjs';
 import { enclosingFunction } from './protocol-marker-analysis.mjs';
 /** Use the same actual invocation sites for context admission and caller emission coverage. */
-export function httpContextInvocations(fn, checker) {
+export function httpContextInvocations(fn, checker, cache) {
     const resolver = createProtocolCallbackValueResolver(checker);
-    const calls = [];
-    function visit(node) {
-        if (ts.isCallExpression(node) && executableProtocolPath(node, checker))
-            calls.push(node);
-        ts.forEachChild(node, visit);
+    const sourceFile = fn.getSourceFile();
+    let calls = cache?.calls.get(sourceFile);
+    if (!calls) {
+        const found = [];
+        const visit = (node) => {
+            if (ts.isCallExpression(node) && executableProtocolPath(node, checker, undefined, cache))
+                found.push(node);
+            ts.forEachChild(node, visit);
+        };
+        visit(sourceFile);
+        calls = found;
+        cache?.calls.set(sourceFile, calls);
     }
-    visit(fn.getSourceFile());
     const registered = calls.some((call) => registeredHandler(call) &&
         call.arguments.some((argument) => resolver.resolve(argument, new Map())?.node === fn));
     const callers = calls.filter((call) => {

package/dist/api-contract-discovery/protocol-http-context-escapes.d.mts

@@ -0,0 +1,3 @@
+import ts from '../contract-schema/typescript-api.mts';
+/** Opaque consumers of the canonical context may emit undocumented status or bodies. */
+export declare function opaqueHttpContextArgument(call: ts.CallExpression, checker: ts.TypeChecker, context?: ts.Symbol, active?: Set<ts.FunctionLikeDeclaration>): boolean;

package/dist/api-contract-discovery/protocol-http-context-escapes.mjs

@@ -0,0 +1,95 @@
+import ts from '../contract-schema/typescript-api.mjs';
+import { expressionReceiver } from './protocol-write-receiver.mjs';
+import { httpHandlerContext, contextResponseMethod } from './protocol-http-context.mjs';
+import { httpContextInvocations } from './protocol-http-context-callers.mjs';
+import { callbackArgumentBindings } from './protocol-callback-argument-bindings.mjs';
+import { runtimeParameters } from './registered-route-runtime-parameters.mjs';
+import { enclosingFunction, unwrapExpression } from './protocol-marker-analysis.mjs';
+import { executableProtocolPath } from './protocol-execution-path.mjs';
+import { opaqueProtocolCallbackPath } from './protocol-opaque-callback.mjs';
+import { visit } from './response-contract-route-analysis.mjs';
+import { standardReflectApply } from './protocol-http-reflect.mjs';
+import { createProtocolCallbackValueResolver, isProtocolCallbackFunction, } from './protocol-callback-values.mjs';
+/** Opaque consumers of the canonical context may emit undocumented status or bodies. */
+export function opaqueHttpContextArgument(call, checker, context, active = new Set()) {
+    const matches = (symbol) => call.arguments.some((argument) => contextArgument(argument, symbol, checker));
+    if (context && !matches(context))
+        return false;
+    if (!(executableProtocolPath(call, checker) || opaqueProtocolCallbackPath(call, checker)))
+        return false;
+    if (context)
+        return !implementedCallee(call, context, checker, active);
+    for (let owner = enclosingFunction(call); owner; owner = enclosingFunction(owner)) {
+        const name = runtimeParameters(owner)[0]?.name;
+        const symbol = name && ts.isIdentifier(name) ? checker.getSymbolAtLocation(name) : undefined;
+        if (symbol && matches(symbol) && httpHandlerContext(owner, checker) === symbol)
+            return !implementedCallee(call, symbol, checker, active);
+    }
+    return false;
+}
+function contextArgument(expression, context, checker) {
+    const receiver = expressionReceiver(expression, checker);
+    return ((receiver?.root === context &&
+        (receiver.path.length === 0 ||
+            (receiver.path.length === 1 && receiver.path[0] === 'response'))) ||
+        contextResponseMethod(unwrapExpression(expression), context, checker, true) === 'response');
+}
+/** Actual caller bindings retain the concrete implementations of consumed callback parameters. */
+function implementedCallee(call, context, checker, active) {
+    const resolver = createProtocolCallbackValueResolver(checker);
+    if (standardReflectApply(call, checker)) {
+        const target = call.arguments[0] && resolver.resolve(call.arguments[0], new Map());
+        return !!(target &&
+            isProtocolCallbackFunction(target.node) &&
+            target.node.body &&
+            ts.isBlock(target.node.body) &&
+            target.node.body.statements.length === 0);
+    }
+    const implemented = (env) => {
+        const target = resolver.resolve(call.expression, env);
+        return !!(target &&
+            isProtocolCallbackFunction(target.node) &&
+            target.node.body &&
+            !calleeEscapes(target.node, call, context, checker, active));
+    };
+    if (implemented(new Map()))
+        return true;
+    const expression = unwrapExpression(call.expression);
+    const declaration = ts.isIdentifier(expression)
+        ? checker.getSymbolAtLocation(expression)?.valueDeclaration
+        : undefined;
+    const owner = declaration && ts.isParameter(declaration) ? enclosingFunction(declaration) : undefined;
+    if (!owner || !runtimeParameters(owner).includes(declaration))
+        return false;
+    const callers = httpContextInvocations(owner, checker).callers;
+    return (callers.length > 0 &&
+        callers.every((invocation) => {
+            const target = resolver.resolve(invocation.expression, new Map());
+            if (target?.node !== owner)
+                return false;
+            const env = callbackArgumentBindings(owner, invocation, new Map(), target.env, checker, resolver);
+            return !!env && implemented(env);
+        }));
+}
+/** The current proven call binds canonical arguments; other foreign callers do not hide escapes. */
+function calleeEscapes(fn, call, context, checker, active) {
+    if (active.has(fn))
+        return true;
+    const next = new Set(active).add(fn);
+    const contexts = [context];
+    for (const [index, parameter] of runtimeParameters(fn).entries()) {
+        const argument = call.arguments[index];
+        if (!argument || !contextArgument(argument, context, checker))
+            continue;
+        if (!ts.isIdentifier(parameter.name))
+            return true;
+        contexts.push(checker.getSymbolAtLocation(parameter.name));
+    }
+    let escaped = false;
+    visit(fn.body, (node) => {
+        if (ts.isCallExpression(node) &&
+            contexts.some((symbol) => opaqueHttpContextArgument(node, checker, symbol, next)))
+            escaped = true;
+    });
+    return escaped;
+}

package/dist/api-contract-discovery/protocol-http-context.d.mts

@@ -1,8 +1,7 @@
 import ts from '../contract-schema/typescript-api.mts';
+export { contextResponseMethod } from './protocol-http-method-access.mts';
 /** A helper parameter is a response context only when every executable caller passes one. */
 export declare function httpHandlerContext(fn: ts.FunctionLikeDeclaration, checker: ts.TypeChecker, active?: Set<ts.FunctionLikeDeclaration>): ts.Symbol | undefined;
-/** Literal bracket access is equivalent to property access for response methods. */
-export declare function contextResponseMethod(expression: ts.Expression, context: ts.Symbol, checker: ts.TypeChecker, allowMutable?: boolean): string | undefined;
 /** Follow only caller contexts already admitted by the actual-argument proof. */
 export declare function httpContextScopes(fn: ts.FunctionLikeDeclaration, checker: ts.TypeChecker): Map<ts.FunctionLikeDeclaration, ts.Symbol>;
 /** Indirect methods cannot prove the declared status or body, including borrowed this receivers. */