@gate-forge/pack-http 0.7.1 → 0.9.0

package/README.md

@@ -10,6 +10,12 @@ classification signals** (dogfood remediation phase 4):
   Fastify and Hono registrations (import-disambiguated, the pack-auth
   convention), and NestJS `@Controller('accounts')` + `@Get/@Post/@Put/
   @Patch/@Delete/@All('…')` decorators.
+  `app`/`server`/`router` are server names by convention; an `api.<verb>()`
+  call counts as a registration **only** where the file imports a server
+  framework (express/fastify/hono), because that is also how an axios
+  instance, a Playwright request context, or an api-client module spells
+  its calls — reading those as routes minted server routes out of test
+  and client call sites.
 - **Frontend API-client calls** (bounded static dataflow, plan phase 3):
   direct literal `fetch`/Axios, `fetch(url, { method })`, Axios config
   objects and instances, configured client symbols (`apiClient.get`),
@@ -22,6 +28,17 @@ classification signals** (dogfood remediation phase 4):
   disappear and never default to GET. A modeled Axios instance creation
   with a proven literal `baseURL` joins that base into the emitted call
   path (see *Instance baseURL joining* below).
+- **The verb of `fetch(url, options)`** comes from a bounded
+  request-options model, never from "the options were not inline": an
+  inline object (`method` read with last-writer-wins, so a spread and
+  the override after it both participate), a module-scope constant
+  naming one, or a call to a scanned function whose body is a single
+  `return <expression>` with its first parameter bound to that argument
+  (so a forwarder resolves through it). Options that provably carry no
+  `method` keep the platform default — GET really is what the call
+  sends. Options the model cannot read yield a typed
+  `HTTP_METHOD_DYNAMIC` entry and **no call fact**: before, such a call
+  was recorded as a GET and joined a route the server never serves.
 
 ## Client-scan configuration
 
@@ -109,6 +126,59 @@ wrapper's paths fully, or use a builder with `base`). The
 `urlBuilders[].base` channel is unchanged: it is configuration-declared,
 so the builder's base is part of the resolved value itself.
 
+### Response field reads (bounded, file-local)
+
+Every frontend-call fact carries `attributes.responseReads`: the fields
+the call site reads off that call's own response, each with the location
+of the read. It is the frontend half of the dropped-response-field proof
+(a merged frontend read `invoice.dueDate` after the FastAPI model had
+dropped it; every test mocked the response and the screen showed
+nothing), and it is collected by the same bounded pass that resolves the
+call target — no execution, no type checker, no cross-file inference.
+
+The model is deliberately small:
+
+- the call's own awaited result is followed through `await` and
+  parentheses; `<result>.data` is the payload (the axios/kit envelope) and
+  `<result>` alone is the envelope, so `res.status`/`res.headers` are not
+  fields;
+- a name bound from either of those (`const r = await call`,
+  `const { data: d } = await call`, `const d = (await call).data`) is
+  followed by name inside the enclosing function-like — nested
+  function-likes included, so a `useEffect` callback still counts;
+- `holder.<field>`, `holder.data.<field>`, `holder.data['<field>']` and
+  `holder['<field>']` are reads, as is every key of an object
+  destructuring of a holder or of `<holder>.data`;
+- a `let` holder (reassigned before the read), a computed key
+  (`d[key]`), and a JavaScript member (`data.map`, `data.length`,
+  `status`) are never reads;
+- a branch that opens on the call's OWN envelope (`ok`, `status`) is read
+  for its POLARITY, and only the failure arm is dropped: the body a
+  failure branch reads (`res.data?.detail`) is the server's ERROR
+  envelope, never the success model. `if (res.ok)`, `if (res.ok ===
+  true)`, `if (res.status >= 400)`, `> 399`, `!== 200`, `!== 201`, `< 400`,
+  `=== 200`, `<= 299` and their `!` negations all decide which arm runs,
+  so the success arm keeps its reads — `if (res.ok) setItems(res.data.
+  items)` is exactly the shape where a dropped field hides. A compound
+  condition (`!res.ok || res.status >= 500`), a comparison this pass
+  cannot read (`>= Math.min(400, limit)`) and a `statusText` test are
+  undecidable, so NEITHER arm is collected. A ternary is the same guard as
+  an `if` — `res.ok ? res.data.items : res.data?.detail` keeps the
+  success arm — and a ternary on anything else is not a guard at all: both
+  arms are ordinary success-path reads. A read after an early-return guard
+  (`if (!res.ok) { throw … }` … then the code) is collected as usual;
+- a read that is one operand of a `||` / `??` chain carries that chain's
+  index, so the check judges the chain as the ONE decision it is:
+  `res.data?.invoice_id || res.data?.invoice?.id` is silent when the
+  model declares `invoice_id`, because `invoice` is its defensive
+  fallback. A chain in which no operand is declared is reported whole.
+
+`gateforge check` compares these reads against the response model the
+joined backend route declares and emits one **non-blocking**
+`RESPONSE_FIELD_MISSING_FROM_MODEL` advisory per undeclared field. A call
+nobody consumes emits no attribute at all, so it stays byte-identical to
+before.
+
 ### Scan scoping (optional, strict, back-compatible)
 
 All scoping keys are OPTIONAL; a config without them scans exactly as

package/dist/client-calls.d.ts

@@ -147,6 +147,25 @@ export declare function clientSymbolActiveIn(config: ClientScanConfig, name: str
  * scope, `<symbol>.<verb>(path, handler)` can only be a router).
  */
 export declare function activeClientSymbolNamesIn(config: ClientScanConfig, file: string): string[];
+/**
+ * One field the call site reads off this call's response: the name
+ * exactly as the code writes it, and where that read happens. Collected
+ * by the same bounded static pass that resolves the call target —
+ * `.data.<field>`, `.data['<field>']`, and destructuring of the awaited
+ * result or of its payload, inside the enclosing function, same file.
+ */
+export interface ResponseRead {
+    field: string;
+    location: Location;
+    /**
+     * Index of the `||` / `??` fallback chain this operand belongs to, in
+     * source order within the call; absent for a read that stands alone.
+     * `res.data?.invoice_id || res.data?.invoice?.id` is one decision about
+     * ONE result, so its operands are judged together by the response-model
+     * check instead of one by one.
+     */
+    chain?: number;
+}
 /** One discovered frontend call (one row per source callsite). */
 export interface ClientCall {
     method: HttpMethod;
@@ -166,6 +185,13 @@ export interface ClientCall {
     /** Producing client, e.g. `fetch`, `axios`, `apiClient`, `apiGet`. */
     framework: string;
     location: Location;
+    /**
+     * Fields this call site reads off the response, in source order.
+     * Absent when the code reads none — the attribute is minted only when
+     * it says something, so a call with no read stays byte-identical to
+     * the pre-feature contract.
+     */
+    responseReads?: ResponseRead[];
 }
 export interface ClientScanUnresolved {
     code: typeof FRONTEND_CALL_TARGET_UNRESOLVED | typeof HTTP_METHOD_DYNAMIC | typeof HTTP_PATH_DYNAMIC;

package/dist/client-calls.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client-calls.d.ts","sourceRoot":"","sources":["../src/client-calls.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"client-calls.d.ts","sourceRoot":"","sources":["../src/client-calls.ts"],"names":[],"mappings":"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"}