@warlock.js/core 5.30.0 → 5.31.0

package/esm/tooling/trace/trace-report.types.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace-report.types.mjs","names":[],"sources":["../../../../../../../../../packages/core/src/tooling/trace/trace-report.types.ts"],"sourcesContent":["import type { DevtoolsPhaseRecord } from \"../devtools/devtools-client\";\n\n/** The `schemaVersion` of {@link TraceReport}. Fields are only added within a version. */\nexport const TRACE_SCHEMA_VERSION = 1;\n\n/** One middleware run, in the order it ran. */\nexport type TraceMiddleware = {\n  name: string | null;\n  index: number | null;\n  durationMs: number;\n};\n\n/** What the route's validation did. */\nexport type TraceValidation = {\n  /** Whether a validation phase ran (the route declares a schema or a `validate` function). */\n  ran: boolean;\n  durationMs: number | null;\n  /**\n   * `true` when validation ran and the handler ran after it (or the response\n   * succeeded); `false` when it ran, the handler did not, and the response is\n   * an error; `null` when validation did not run.\n   */\n  passed: boolean | null;\n  /** The response body's `errors` (or the whole body) when validation failed; otherwise `null`. */\n  errors: unknown;\n};\n\n/** One recorded query, with its N+1 flag. */\nexport type TraceQuery = Record<string, unknown> & {\n  /** `true` when the query's shape is one devtools reported as an N+1. */\n  nPlusOne: boolean;\n};\n\n/** What `warlock trace --json` prints and `traceRequest()` returns. */\nexport type TraceReport = {\n  schemaVersion: typeof TRACE_SCHEMA_VERSION;\n  /** The request id the server used (the `x-request-id` it echoed). */\n  requestId: string;\n  /** The dev server origin the request went to. */\n  server: string;\n  request: {\n    method: string;\n    url: string;\n    /** Sent headers; `authorization`, `cookie` and `proxy-authorization` values read `[redacted]`. */\n    headers: Record<string, string>;\n    body: unknown;\n  };\n  response: {\n    status: number;\n    headers: Record<string, string>;\n    /** Parsed JSON when the content type is JSON, else text; `null` for an empty body. */\n    body: unknown;\n    /** Whether `body` was cut to the first 64 KiB. */\n    truncated: boolean;\n  };\n  /** The matched route pattern, e.g. `/posts/:id`, or `null`. */\n  route: string | null;\n  /** The error devtools recorded for the request, or `null`. */\n  error: string | null;\n  timeline: {\n    /** Every recorded phase in the order it was recorded. */\n    phases: DevtoolsPhaseRecord[];\n    routeMatch: { durationMs: number } | null;\n    middleware: TraceMiddleware[];\n    validation: TraceValidation;\n    handler: { durationMs: number } | null;\n  };\n  queries: TraceQuery[];\n  /** Devtools warnings for the request (`{ type: \"n+1\", message, shape, count, caller }`). */\n  warnings: Record<string, unknown>[];\n  logs: Record<string, unknown>[];\n  cache: Record<string, unknown>[];\n  /** Ids of mails captured during the request. */\n  mails: string[];\n  timings: {\n    /** The server-side duration devtools measured, or `null` while unsettled. */\n    totalMs: number | null;\n    /** The round trip measured by the client. */\n    clientMs: number;\n    /** Total time per phase name. */\n    phasesMs: Record<string, number>;\n  };\n};\n"],"mappings":";;AAGA,MAAa,uBAAuB"}

package/esm/tooling/trace/trace-request.d.mts

@@ -0,0 +1,83 @@
+import { DevtoolsFetch, DevtoolsRequestRecord } from "../devtools/devtools-client.mjs";
+import { TraceReport } from "./trace-report.types.mjs";
+
+//#region ../../packages/core/src/tooling/trace/trace-request.d.ts
+/** The correlation header core reads and echoes by default (`http.requestId.header`). */
+declare const TRACE_REQUEST_ID_HEADER = "x-request-id";
+/** Response bodies longer than this are cut in the report. */
+declare const TRACE_BODY_LIMIT: number;
+/** Inputs of {@link traceRequest}. */
+type TraceRequestOptions = {
+  /** HTTP method, any case. */method: string; /** A path on the dev server (`/posts?page=2`) or an absolute URL. */
+  url: string;
+  /**
+   * The request body. A string is sent as-is; anything else is sent as JSON
+   * with `content-type: application/json` unless `headers` sets a content type.
+   */
+  body?: unknown; /** Extra request headers. */
+  headers?: Record<string, string>; /** Project root, where `.warlock/dev-server.json` is read. Default: `process.cwd()`. */
+  cwd?: string; /** The dev server origin; overrides the recorded one. */
+  serverUrl?: string; /** The devtools mount; overrides the recorded one (default `/__warlock`). */
+  devtoolsPath?: string;
+  fetch?: DevtoolsFetch; /** How long to wait for devtools to settle the request record. Default 5000 ms. */
+  timeoutMs?: number; /** Poll interval while waiting for the record. Default 50 ms. */
+  intervalMs?: number;
+  /**
+   * The correlation header the app reads and echoes (`http.requestId.header`).
+   * Default `x-request-id`.
+   */
+  requestIdHeader?: string;
+};
+/** The HTTP response as the report needs it. */
+type TracedResponse = {
+  status: number;
+  headers: Record<string, string>; /** The raw response text. */
+  text: string;
+};
+/** Inputs of {@link buildTraceReport}. */
+type BuildTraceReportInput = {
+  requestId: string;
+  server: string;
+  request: {
+    method: string;
+    url: string;
+    headers: Record<string, string>;
+    body: unknown;
+  };
+  response: TracedResponse;
+  record: DevtoolsRequestRecord;
+  clientMs: number;
+};
+/** Headers with credential values replaced by `[redacted]`. */
+declare function redactHeaders(headers: Record<string, string>): Record<string, string>;
+/** The response body as the report prints it: parsed JSON, else text, cut at the limit. */
+declare function readResponseBody(text: string, contentType: string | undefined): {
+  body: unknown;
+  truncated: boolean;
+};
+/**
+ * Assemble a {@link TraceReport} from the HTTP response and the devtools
+ * record of the same request. Pure: no I/O, so it is testable on its own.
+ */
+declare function buildTraceReport(input: BuildTraceReportInput): TraceReport;
+/** The absolute URL a trace sends to: `url` as-is when absolute, else joined to the server origin. */
+declare function resolveTraceUrl(server: string, url: string): string;
+/**
+ * Send one request to the running dev server and return its devtools
+ * timeline: middleware, validation result, handler, queries (with N+1 flags),
+ * logs, cache operations, captured mails, the response and the timings.
+ *
+ * Devtools is reached first, so a missing dev server (`WL8008`) or devtools
+ * (`WL8009`) fails before anything is sent. The request carries an
+ * `x-request-id` (unless the caller set one), which core adopts as
+ * `request.id` and echoes back; that id is how the devtools record is found.
+ * Throws `WL5004` when devtools never recorded the request.
+ *
+ * @example
+ * const report = await traceRequest({ method: "POST", url: "/posts", body: { title: "Hi" } });
+ * report.timeline.validation.passed; // false when the body was refused
+ */
+declare function traceRequest(options: TraceRequestOptions): Promise<TraceReport>;
+//#endregion
+export { BuildTraceReportInput, TRACE_BODY_LIMIT, TRACE_REQUEST_ID_HEADER, TraceRequestOptions, TracedResponse, buildTraceReport, readResponseBody, redactHeaders, resolveTraceUrl, traceRequest };
+//# sourceMappingURL=trace-request.d.mts.map

package/esm/tooling/trace/trace-request.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace-request.d.mts","names":[],"sources":["../../../../../../../../../packages/core/src/tooling/trace/trace-request.ts"],"mappings":";;;;;cAgBa,uBAAA;AAAb;AAAA,cAGa,gBAAA;;KAMD,mBAAA;EATwB,6BAWlC,MAAA,UARuC;EAUvC,GAAA;EAVuC;AAAA;AAMzC;;EASE,IAAA,YASqB;EAPrB,OAAA,GAAU,MAAA,kBAPV;EASA,GAAA,WAFA;EAIA,SAAA,WAFA;EAIA,YAAA;EACA,KAAA,GAAQ,aAAa,EAArB;EAEA,SAAA;EAEA,UAAA;EAKA;;AAAe;AAIjB;EAJE,eAAA;AAAA;;KAIU,cAAA;EACV,MAAA;EACA,OAAA,EAAS,MAAM,kBAEf;EAAA,IAAA;AAAA;AAIF;AAAA,KAAY,qBAAA;EACV,SAAA;EACA,MAAA;EACA,OAAA;IAAW,MAAA;IAAgB,GAAA;IAAa,OAAA,EAAS,MAAA;IAAwB,IAAA;EAAA;EACzE,QAAA,EAAU,cAAA;EACV,MAAA,EAAQ,qBAAA;EACR,QAAA;AAAA;;iBAkBc,aAAA,CAAc,OAAA,EAAS,MAAA,mBAAyB,MAAM;;iBAWtD,gBAAA,CACd,IAAA,UACA,WAAA;EACG,IAAA;EAAe,SAAA;AAAA;;AAhCV;AAkBV;;iBA2EgB,gBAAA,CAAiB,KAAA,EAAO,qBAAA,GAAwB,WAAW;;iBAoE3D,eAAA,CAAgB,MAAA,UAAgB,GAAW;;;;AA/IW;AAWtE;;;;;;;;;AAG6B;AA6D7B;iBA+GsB,YAAA,CAAa,OAAA,EAAS,mBAAA,GAAsB,OAAA,CAAQ,WAAA"}

package/esm/tooling/trace/trace-request.mjs

@@ -0,0 +1,241 @@
+import { WarlockError } from "../../errors/warlock-error.mjs";
+import { connectDevtools } from "../devtools/devtools-client.mjs";
+import { TRACE_SCHEMA_VERSION } from "./trace-report.types.mjs";
+import { randomUUID } from "node:crypto";
+
+//#region ../../packages/core/src/tooling/trace/trace-request.ts
+/** The correlation header core reads and echoes by default (`http.requestId.header`). */
+const TRACE_REQUEST_ID_HEADER = "x-request-id";
+/** Response bodies longer than this are cut in the report. */
+const TRACE_BODY_LIMIT = 64 * 1024;
+/** Header values never printed in a report. */
+const REDACTED_HEADERS = new Set([
+	"authorization",
+	"cookie",
+	"proxy-authorization"
+]);
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function lowerCaseKeys(headers) {
+	const result = {};
+	for (const [key, value] of Object.entries(headers)) result[key.toLowerCase()] = value;
+	return result;
+}
+/** Headers with credential values replaced by `[redacted]`. */
+function redactHeaders(headers) {
+	const result = {};
+	for (const [key, value] of Object.entries(headers)) result[key] = REDACTED_HEADERS.has(key.toLowerCase()) ? "[redacted]" : value;
+	return result;
+}
+/** The response body as the report prints it: parsed JSON, else text, cut at the limit. */
+function readResponseBody(text, contentType) {
+	if (text.length === 0) return {
+		body: null,
+		truncated: false
+	};
+	const truncated = text.length > TRACE_BODY_LIMIT;
+	if (!truncated && contentType !== void 0 && /\bjson\b/i.test(contentType)) try {
+		return {
+			body: JSON.parse(text),
+			truncated: false
+		};
+	} catch {}
+	return {
+		body: truncated ? text.slice(0, TRACE_BODY_LIMIT) : text,
+		truncated
+	};
+}
+function attrNumber(attrs, key) {
+	const value = attrs?.[key];
+	return typeof value === "number" ? value : null;
+}
+function attrString(attrs, key) {
+	const value = attrs?.[key];
+	return typeof value === "string" ? value : null;
+}
+function validationOf(record, status, body) {
+	const phases = record.phases.filter((phase) => phase.name === "validation");
+	if (phases.length === 0) return {
+		ran: false,
+		durationMs: null,
+		passed: null,
+		errors: null
+	};
+	const durationMs = phases.reduce((total, phase) => total + phase.durationMs, 0);
+	const passed = record.phases.some((phase) => phase.name === "handler") || status < 400;
+	return {
+		ran: true,
+		durationMs,
+		passed,
+		errors: passed ? null : isRecord(body) && "errors" in body ? body.errors : body
+	};
+}
+function sumPhase(record, name) {
+	const phases = record.phases.filter((phase) => phase.name === name);
+	if (phases.length === 0) return null;
+	return { durationMs: phases.reduce((total, phase) => total + phase.durationMs, 0) };
+}
+/**
+* Assemble a {@link TraceReport} from the HTTP response and the devtools
+* record of the same request. Pure: no I/O, so it is testable on its own.
+*/
+function buildTraceReport(input) {
+	const { record, response } = input;
+	const responseHeaders = lowerCaseKeys(response.headers);
+	const { body, truncated } = readResponseBody(response.text, responseHeaders["content-type"]);
+	const middleware = record.phases.filter((phase) => phase.name === "middleware").map((phase) => ({
+		name: attrString(phase.attrs, "name"),
+		index: attrNumber(phase.attrs, "index"),
+		durationMs: phase.durationMs
+	}));
+	const nPlusOneShapes = new Set(record.warnings.flatMap((warning) => warning.type === "n+1" && typeof warning.shape === "string" ? [warning.shape] : []));
+	const queries = record.queries.map((query) => ({
+		...query,
+		nPlusOne: typeof query.shape === "string" && nPlusOneShapes.has(query.shape)
+	}));
+	const phasesMs = {};
+	for (const phase of record.phases) phasesMs[phase.name] = (phasesMs[phase.name] ?? 0) + phase.durationMs;
+	return {
+		schemaVersion: 1,
+		requestId: input.requestId,
+		server: input.server,
+		request: {
+			method: input.request.method,
+			url: input.request.url,
+			headers: redactHeaders(input.request.headers),
+			body: input.request.body
+		},
+		response: {
+			status: response.status,
+			headers: redactHeaders(responseHeaders),
+			body,
+			truncated
+		},
+		route: record.route ?? null,
+		error: record.error ?? null,
+		timeline: {
+			phases: record.phases,
+			routeMatch: sumPhase(record, "route.match"),
+			middleware,
+			validation: validationOf(record, response.status, body),
+			handler: sumPhase(record, "handler")
+		},
+		queries,
+		warnings: record.warnings,
+		logs: record.logs,
+		cache: record.cache,
+		mails: record.mails,
+		timings: {
+			totalMs: record.durationMs ?? null,
+			clientMs: input.clientMs,
+			phasesMs
+		}
+	};
+}
+/** The absolute URL a trace sends to: `url` as-is when absolute, else joined to the server origin. */
+function resolveTraceUrl(server, url) {
+	if (/^https?:\/\//i.test(url)) return url;
+	return `${server}${url.startsWith("/") ? url : `/${url}`}`;
+}
+/** The body and headers to send for a {@link TraceRequestOptions.body}. */
+function encodeBody(body, headers) {
+	if (body === void 0) return {
+		payload: void 0,
+		headers
+	};
+	if (typeof body === "string") return {
+		payload: body,
+		headers
+	};
+	const hasContentType = Object.keys(headers).some((key) => key.toLowerCase() === "content-type");
+	return {
+		payload: JSON.stringify(body),
+		headers: hasContentType ? headers : {
+			...headers,
+			"content-type": "application/json"
+		}
+	};
+}
+function headerValue(headers, name) {
+	const key = Object.keys(headers).find((candidate) => candidate.toLowerCase() === name);
+	return key === void 0 ? void 0 : headers[key];
+}
+/**
+* Send one request to the running dev server and return its devtools
+* timeline: middleware, validation result, handler, queries (with N+1 flags),
+* logs, cache operations, captured mails, the response and the timings.
+*
+* Devtools is reached first, so a missing dev server (`WL8008`) or devtools
+* (`WL8009`) fails before anything is sent. The request carries an
+* `x-request-id` (unless the caller set one), which core adopts as
+* `request.id` and echoes back; that id is how the devtools record is found.
+* Throws `WL5004` when devtools never recorded the request.
+*
+* @example
+* const report = await traceRequest({ method: "POST", url: "/posts", body: { title: "Hi" } });
+* report.timeline.validation.passed; // false when the body was refused
+*/
+async function traceRequest(options) {
+	const fetcher = options.fetch ?? ((input, init) => fetch(input, init));
+	const devtools = await connectDevtools({
+		cwd: options.cwd,
+		url: options.serverUrl,
+		devtoolsPath: options.devtoolsPath,
+		fetch: fetcher
+	});
+	const method = options.method.toUpperCase();
+	const url = resolveTraceUrl(devtools.url, options.url);
+	const idHeader = (options.requestIdHeader ?? "x-request-id").toLowerCase();
+	const ownId = headerValue(options.headers ?? {}, idHeader);
+	const sentId = ownId ?? randomUUID();
+	const base = ownId === void 0 ? {
+		...options.headers,
+		[idHeader]: sentId
+	} : { ...options.headers };
+	const { payload, headers } = encodeBody(options.body, base);
+	const startedAt = performance.now();
+	let response;
+	try {
+		response = await fetcher(url, {
+			method,
+			headers,
+			body: payload
+		});
+	} catch (error) {
+		throw new WarlockError("WL8008", `The dev server at ${devtools.url} did not answer ${method} ${url}: ${error instanceof Error ? error.message : String(error)}.`, { cause: error });
+	}
+	const text = await response.text();
+	const clientMs = performance.now() - startedAt;
+	const responseHeaders = {};
+	response.headers.forEach((value, key) => {
+		responseHeaders[key] = value;
+	});
+	const requestId = responseHeaders[idHeader] ?? sentId;
+	const record = await devtools.waitForRequest(requestId, {
+		timeoutMs: options.timeoutMs,
+		intervalMs: options.intervalMs
+	});
+	if (!record) throw new WarlockError("WL5004", `Devtools holds no record of request ${requestId} (${method} ${url} answered ${response.status}). Keep http.requestId enabled so the id is echoed; paths under ${devtools.devtoolsPath} are never recorded.`);
+	return buildTraceReport({
+		requestId,
+		server: devtools.url,
+		request: {
+			method,
+			url,
+			headers,
+			body: options.body ?? null
+		},
+		response: {
+			status: response.status,
+			headers: responseHeaders,
+			text
+		},
+		record,
+		clientMs
+	});
+}
+
+//#endregion
+export { TRACE_BODY_LIMIT, TRACE_REQUEST_ID_HEADER, buildTraceReport, readResponseBody, redactHeaders, resolveTraceUrl, traceRequest };
+//# sourceMappingURL=trace-request.mjs.map

package/esm/tooling/trace/trace-request.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace-request.mjs","names":[],"sources":["../../../../../../../../../packages/core/src/tooling/trace/trace-request.ts"],"sourcesContent":["import { randomUUID } from \"node:crypto\";\nimport { WarlockError } from \"../../errors/warlock-error\";\nimport {\n  connectDevtools,\n  type DevtoolsFetch,\n  type DevtoolsRequestRecord,\n} from \"../devtools/devtools-client\";\nimport {\n  TRACE_SCHEMA_VERSION,\n  type TraceMiddleware,\n  type TraceQuery,\n  type TraceReport,\n  type TraceValidation,\n} from \"./trace-report.types\";\n\n/** The correlation header core reads and echoes by default (`http.requestId.header`). */\nexport const TRACE_REQUEST_ID_HEADER = \"x-request-id\";\n\n/** Response bodies longer than this are cut in the report. */\nexport const TRACE_BODY_LIMIT = 64 * 1024;\n\n/** Header values never printed in a report. */\nconst REDACTED_HEADERS = new Set([\"authorization\", \"cookie\", \"proxy-authorization\"]);\n\n/** Inputs of {@link traceRequest}. */\nexport type TraceRequestOptions = {\n  /** HTTP method, any case. */\n  method: string;\n  /** A path on the dev server (`/posts?page=2`) or an absolute URL. */\n  url: string;\n  /**\n   * The request body. A string is sent as-is; anything else is sent as JSON\n   * with `content-type: application/json` unless `headers` sets a content type.\n   */\n  body?: unknown;\n  /** Extra request headers. */\n  headers?: Record<string, string>;\n  /** Project root, where `.warlock/dev-server.json` is read. Default: `process.cwd()`. */\n  cwd?: string;\n  /** The dev server origin; overrides the recorded one. */\n  serverUrl?: string;\n  /** The devtools mount; overrides the recorded one (default `/__warlock`). */\n  devtoolsPath?: string;\n  fetch?: DevtoolsFetch;\n  /** How long to wait for devtools to settle the request record. Default 5000 ms. */\n  timeoutMs?: number;\n  /** Poll interval while waiting for the record. Default 50 ms. */\n  intervalMs?: number;\n  /**\n   * The correlation header the app reads and echoes (`http.requestId.header`).\n   * Default `x-request-id`.\n   */\n  requestIdHeader?: string;\n};\n\n/** The HTTP response as the report needs it. */\nexport type TracedResponse = {\n  status: number;\n  headers: Record<string, string>;\n  /** The raw response text. */\n  text: string;\n};\n\n/** Inputs of {@link buildTraceReport}. */\nexport type BuildTraceReportInput = {\n  requestId: string;\n  server: string;\n  request: { method: string; url: string; headers: Record<string, string>; body: unknown };\n  response: TracedResponse;\n  record: DevtoolsRequestRecord;\n  clientMs: number;\n};\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n  return typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n\nfunction lowerCaseKeys(headers: Record<string, string>): Record<string, string> {\n  const result: Record<string, string> = {};\n\n  for (const [key, value] of Object.entries(headers)) {\n    result[key.toLowerCase()] = value;\n  }\n\n  return result;\n}\n\n/** Headers with credential values replaced by `[redacted]`. */\nexport function redactHeaders(headers: Record<string, string>): Record<string, string> {\n  const result: Record<string, string> = {};\n\n  for (const [key, value] of Object.entries(headers)) {\n    result[key] = REDACTED_HEADERS.has(key.toLowerCase()) ? \"[redacted]\" : value;\n  }\n\n  return result;\n}\n\n/** The response body as the report prints it: parsed JSON, else text, cut at the limit. */\nexport function readResponseBody(\n  text: string,\n  contentType: string | undefined,\n): { body: unknown; truncated: boolean } {\n  if (text.length === 0) return { body: null, truncated: false };\n\n  const truncated = text.length > TRACE_BODY_LIMIT;\n\n  if (!truncated && contentType !== undefined && /\\bjson\\b/i.test(contentType)) {\n    try {\n      return { body: JSON.parse(text), truncated: false };\n    } catch {\n      // Fall through to text: a body that claims JSON and is not is worth seeing as-is.\n    }\n  }\n\n  return { body: truncated ? text.slice(0, TRACE_BODY_LIMIT) : text, truncated };\n}\n\nfunction attrNumber(attrs: Record<string, unknown> | undefined, key: string): number | null {\n  const value = attrs?.[key];\n\n  return typeof value === \"number\" ? value : null;\n}\n\nfunction attrString(attrs: Record<string, unknown> | undefined, key: string): string | null {\n  const value = attrs?.[key];\n\n  return typeof value === \"string\" ? value : null;\n}\n\nfunction validationOf(\n  record: DevtoolsRequestRecord,\n  status: number,\n  body: unknown,\n): TraceValidation {\n  const phases = record.phases.filter((phase) => phase.name === \"validation\");\n\n  if (phases.length === 0) {\n    return { ran: false, durationMs: null, passed: null, errors: null };\n  }\n\n  const durationMs = phases.reduce((total, phase) => total + phase.durationMs, 0);\n  const handlerRan = record.phases.some((phase) => phase.name === \"handler\");\n  // A validation failure answers before the handler runs, with the configured\n  // failure status (422 by default, `validation.response.status`).\n  const passed = handlerRan || status < 400;\n  const errors = passed ? null : isRecord(body) && \"errors\" in body ? body.errors : body;\n\n  return { ran: true, durationMs, passed, errors };\n}\n\nfunction sumPhase(record: DevtoolsRequestRecord, name: string): { durationMs: number } | null {\n  const phases = record.phases.filter((phase) => phase.name === name);\n\n  if (phases.length === 0) return null;\n\n  return { durationMs: phases.reduce((total, phase) => total + phase.durationMs, 0) };\n}\n\n/**\n * Assemble a {@link TraceReport} from the HTTP response and the devtools\n * record of the same request. Pure: no I/O, so it is testable on its own.\n */\nexport function buildTraceReport(input: BuildTraceReportInput): TraceReport {\n  const { record, response } = input;\n  const responseHeaders = lowerCaseKeys(response.headers);\n  const { body, truncated } = readResponseBody(response.text, responseHeaders[\"content-type\"]);\n\n  const middleware: TraceMiddleware[] = record.phases\n    .filter((phase) => phase.name === \"middleware\")\n    .map((phase) => ({\n      name: attrString(phase.attrs, \"name\"),\n      index: attrNumber(phase.attrs, \"index\"),\n      durationMs: phase.durationMs,\n    }));\n\n  const nPlusOneShapes = new Set(\n    record.warnings.flatMap((warning) =>\n      warning.type === \"n+1\" && typeof warning.shape === \"string\" ? [warning.shape] : [],\n    ),\n  );\n  const queries: TraceQuery[] = record.queries.map((query) => ({\n    ...query,\n    nPlusOne: typeof query.shape === \"string\" && nPlusOneShapes.has(query.shape),\n  }));\n\n  const phasesMs: Record<string, number> = {};\n\n  for (const phase of record.phases) {\n    phasesMs[phase.name] = (phasesMs[phase.name] ?? 0) + phase.durationMs;\n  }\n\n  return {\n    schemaVersion: TRACE_SCHEMA_VERSION,\n    requestId: input.requestId,\n    server: input.server,\n    request: {\n      method: input.request.method,\n      url: input.request.url,\n      headers: redactHeaders(input.request.headers),\n      body: input.request.body,\n    },\n    response: {\n      status: response.status,\n      headers: redactHeaders(responseHeaders),\n      body,\n      truncated,\n    },\n    route: record.route ?? null,\n    error: record.error ?? null,\n    timeline: {\n      phases: record.phases,\n      routeMatch: sumPhase(record, \"route.match\"),\n      middleware,\n      validation: validationOf(record, response.status, body),\n      handler: sumPhase(record, \"handler\"),\n    },\n    queries,\n    warnings: record.warnings,\n    logs: record.logs,\n    cache: record.cache,\n    mails: record.mails,\n    timings: {\n      totalMs: record.durationMs ?? null,\n      clientMs: input.clientMs,\n      phasesMs,\n    },\n  };\n}\n\n/** The absolute URL a trace sends to: `url` as-is when absolute, else joined to the server origin. */\nexport function resolveTraceUrl(server: string, url: string): string {\n  if (/^https?:\\/\\//i.test(url)) return url;\n\n  return `${server}${url.startsWith(\"/\") ? url : `/${url}`}`;\n}\n\n/** The body and headers to send for a {@link TraceRequestOptions.body}. */\nfunction encodeBody(\n  body: unknown,\n  headers: Record<string, string>,\n): { payload: string | undefined; headers: Record<string, string> } {\n  if (body === undefined) return { payload: undefined, headers };\n  if (typeof body === \"string\") return { payload: body, headers };\n\n  const hasContentType = Object.keys(headers).some((key) => key.toLowerCase() === \"content-type\");\n\n  return {\n    payload: JSON.stringify(body),\n    headers: hasContentType ? headers : { ...headers, \"content-type\": \"application/json\" },\n  };\n}\n\nfunction headerValue(headers: Record<string, string>, name: string): string | undefined {\n  const key = Object.keys(headers).find((candidate) => candidate.toLowerCase() === name);\n\n  return key === undefined ? undefined : headers[key];\n}\n\n/**\n * Send one request to the running dev server and return its devtools\n * timeline: middleware, validation result, handler, queries (with N+1 flags),\n * logs, cache operations, captured mails, the response and the timings.\n *\n * Devtools is reached first, so a missing dev server (`WL8008`) or devtools\n * (`WL8009`) fails before anything is sent. The request carries an\n * `x-request-id` (unless the caller set one), which core adopts as\n * `request.id` and echoes back; that id is how the devtools record is found.\n * Throws `WL5004` when devtools never recorded the request.\n *\n * @example\n * const report = await traceRequest({ method: \"POST\", url: \"/posts\", body: { title: \"Hi\" } });\n * report.timeline.validation.passed; // false when the body was refused\n */\nexport async function traceRequest(options: TraceRequestOptions): Promise<TraceReport> {\n  const fetcher: DevtoolsFetch = options.fetch ?? ((input, init) => fetch(input, init));\n  const devtools = await connectDevtools({\n    cwd: options.cwd,\n    url: options.serverUrl,\n    devtoolsPath: options.devtoolsPath,\n    fetch: fetcher,\n  });\n\n  const method = options.method.toUpperCase();\n  const url = resolveTraceUrl(devtools.url, options.url);\n  const idHeader = (options.requestIdHeader ?? TRACE_REQUEST_ID_HEADER).toLowerCase();\n  const ownId = headerValue(options.headers ?? {}, idHeader);\n  const sentId = ownId ?? randomUUID();\n  const base =\n    ownId === undefined ? { ...options.headers, [idHeader]: sentId } : { ...options.headers };\n  const { payload, headers } = encodeBody(options.body, base);\n\n  const startedAt = performance.now();\n  let response: Response;\n\n  try {\n    response = await fetcher(url, { method, headers, body: payload });\n  } catch (error) {\n    throw new WarlockError(\n      \"WL8008\",\n      `The dev server at ${devtools.url} did not answer ${method} ${url}: ${error instanceof Error ? error.message : String(error)}.`,\n      { cause: error },\n    );\n  }\n\n  const text = await response.text();\n  const clientMs = performance.now() - startedAt;\n  const responseHeaders: Record<string, string> = {};\n\n  response.headers.forEach((value, key) => {\n    responseHeaders[key] = value;\n  });\n\n  const requestId = responseHeaders[idHeader] ?? sentId;\n  const record = await devtools.waitForRequest(requestId, {\n    timeoutMs: options.timeoutMs,\n    intervalMs: options.intervalMs,\n  });\n\n  if (!record) {\n    throw new WarlockError(\n      \"WL5004\",\n      `Devtools holds no record of request ${requestId} (${method} ${url} answered ${response.status}). Keep http.requestId enabled so the id is echoed; paths under ${devtools.devtoolsPath} are never recorded.`,\n    );\n  }\n\n  return buildTraceReport({\n    requestId,\n    server: devtools.url,\n    request: { method, url, headers, body: options.body ?? null },\n    response: { status: response.status, headers: responseHeaders, text },\n    record,\n    clientMs,\n  });\n}\n"],"mappings":"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"}

package/esm/tooling/typecheck/index.d.mts

@@ -0,0 +1 @@
+import { DEFAULT_TYPECHECK_BUILD_INFO, TypecheckOptions, TypecheckResult, diagnosticToProblem, directImporters, runTypecheck } from "./run-typecheck.mjs";

package/esm/tooling/typecheck/index.mjs

@@ -0,0 +1,3 @@
+import { DEFAULT_TYPECHECK_BUILD_INFO, diagnosticToProblem, directImporters, runTypecheck } from "./run-typecheck.mjs";
+
+export {  };

package/esm/tooling/typecheck/run-typecheck.d.mts

@@ -0,0 +1,59 @@
+import { ToolingProblem } from "../problem.mjs";
+import ts from "typescript";
+
+//#region ../../packages/core/src/tooling/typecheck/run-typecheck.d.ts
+/** Inputs of {@link runTypecheck}. */
+type TypecheckOptions = {
+  /** Project root. Default: `process.cwd()`. */cwd?: string; /** tsconfig path, relative to `cwd`. Default: `tsconfig.json`. */
+  project?: string;
+  /**
+   * Limit diagnostics to these files (relative to `cwd` or absolute) and the
+   * project files that import them directly. Omit for the whole program.
+   */
+  files?: readonly string[]; /** Where the incremental state is kept. Default: `.warlock/cache/typecheck.tsbuildinfo`. */
+  buildInfoFile?: string;
+};
+/** The outcome of {@link runTypecheck}. */
+type TypecheckResult = {
+  /** `true` when no error-severity problem was found. */ok: boolean; /** `program` = every file; `files` = the given files and their direct importers. */
+  mode: "program" | "files"; /** Project-relative files whose diagnostics were collected in `files` mode, else `null`. */
+  files: string[] | null; /** Number of source files checked. */
+  checkedFiles: number;
+  problems: ToolingProblem[];
+  durationMs: number; /** Absolute path of the incremental state file, or `null` when nothing was written. */
+  buildInfoFile: string | null;
+};
+/** Default location of the incremental state, under the framework's own folder. */
+declare const DEFAULT_TYPECHECK_BUILD_INFO: string;
+/** Map one TypeScript diagnostic to a problem (`WL7101`, `rule: "TS<code>"`). */
+declare function diagnosticToProblem(diagnostic: ts.Diagnostic, cwd: string, code?: "WL7101" | "WL7102"): ToolingProblem | undefined;
+/**
+ * The project files that import any of `targets` directly.
+ *
+ * Read from each file's import list (`ts.preProcessFile`) resolved with the
+ * program's own options and a shared resolution cache, rather than through the
+ * builder's transitive dependency graph: a change to a widely used file would
+ * otherwise pull in nearly the whole project, and `--changed` exists to keep
+ * the loop small. A full `warlock typecheck` (incremental, so cheap after the
+ * first run) still checks everything.
+ */
+declare function directImporters(program: ts.Program, targets: ReadonlySet<string>, root: string): Set<string>;
+/**
+ * Typecheck the project with the TypeScript compiler API, incrementally.
+ *
+ * The program is built with `incremental` and `noEmit`, and its state is kept
+ * in {@link DEFAULT_TYPECHECK_BUILD_INFO}, so a second run re-checks only what
+ * changed. With `files`, diagnostics are collected only for those files and
+ * their direct importers — the checker is lazy, so files nobody asks about are
+ * parsed and bound but not checked, which is most of the memory a full check
+ * costs.
+ *
+ * Never throws for a project problem: a missing or invalid tsconfig is a
+ * `WL7102` problem, a type error a `WL7101` problem. A compiler crash is
+ * re-thrown for the caller to classify (`warlock check` reports it as
+ * `WL8007`).
+ */
+declare function runTypecheck(options?: TypecheckOptions): TypecheckResult;
+//#endregion
+export { DEFAULT_TYPECHECK_BUILD_INFO, TypecheckOptions, TypecheckResult, diagnosticToProblem, directImporters, runTypecheck };
+//# sourceMappingURL=run-typecheck.d.mts.map

package/esm/tooling/typecheck/run-typecheck.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-typecheck.d.mts","names":[],"sources":["../../../../../../../../../packages/core/src/tooling/typecheck/run-typecheck.ts"],"mappings":";;;;;KAMY,gBAAA;EAAA,8CAEV,GAAA;EAEA,OAAA;EAFA;;;;EAOA,KAAA,sBAEa;EAAb,aAAA;AAAA;;KAIU,eAAA;EAEV,uDAAA,EAAA,WAIA;EAFA,IAAA,uBAKA;EAHA,KAAA,mBAIA;EAFA,YAAA;EACA,QAAA,EAAU,cAAc;EACxB,UAAA,UAMW;EAJX,aAAA;AAAA;;cAIW,4BAAA;AAkBb;AAAA,iBAAgB,mBAAA,CACd,UAAA,EAAY,EAAA,CAAG,UAAA,EACf,GAAA,UACA,IAAA,yBACC,cAAc;;;;;;;;;;AAAA;iBAuDD,eAAA,CACd,OAAA,EAAS,EAAA,CAAG,OAAA,EACZ,OAAA,EAAS,WAAA,UACT,IAAA,WACC,GAAA;;;;;;;;;;;;;;;;iBAyCa,YAAA,CAAa,OAAA,GAAS,gBAAA,GAAwB,eAAe"}

package/esm/tooling/typecheck/run-typecheck.mjs

@@ -0,0 +1,153 @@
+import { createProblem } from "../problem.mjs";
+import path from "node:path";
+import { existsSync, mkdirSync } from "node:fs";
+import ts from "typescript";
+
+//#region ../../packages/core/src/tooling/typecheck/run-typecheck.ts
+/** Default location of the incremental state, under the framework's own folder. */
+const DEFAULT_TYPECHECK_BUILD_INFO = path.join(".warlock", "cache", "typecheck.tsbuildinfo");
+function toPosix(file) {
+	return file.split(path.sep).join("/");
+}
+/** Whether a program file belongs to the project (under the root, outside node_modules). */
+function isProjectFile(fileName, root, declarations = true) {
+	const normalized = path.resolve(fileName);
+	return normalized.startsWith(root + path.sep) && !normalized.split(path.sep).includes("node_modules") && (declarations || !normalized.endsWith(".d.ts"));
+}
+/** Map one TypeScript diagnostic to a problem (`WL7101`, `rule: "TS<code>"`). */
+function diagnosticToProblem(diagnostic, cwd, code = "WL7101") {
+	if (diagnostic.category !== ts.DiagnosticCategory.Error && diagnostic.category !== ts.DiagnosticCategory.Warning) return;
+	let file = null;
+	let line = null;
+	let column = null;
+	if (diagnostic.file) {
+		file = toPosix(path.relative(cwd, diagnostic.file.fileName));
+		if (diagnostic.start !== void 0) {
+			const position = diagnostic.file.getLineAndCharacterOfPosition(diagnostic.start);
+			line = position.line + 1;
+			column = position.character + 1;
+		}
+	}
+	return createProblem({
+		code,
+		source: "typescript",
+		severity: diagnostic.category === ts.DiagnosticCategory.Error ? "error" : "warning",
+		message: ts.flattenDiagnosticMessageText(diagnostic.messageText, "\n"),
+		file,
+		line,
+		column,
+		rule: `TS${diagnostic.code}`
+	});
+}
+function collect(diagnostics, cwd, code) {
+	return diagnostics.map((diagnostic) => diagnosticToProblem(diagnostic, cwd, code)).filter((problem) => problem !== void 0);
+}
+/**
+* The project files that import any of `targets` directly.
+*
+* Read from each file's import list (`ts.preProcessFile`) resolved with the
+* program's own options and a shared resolution cache, rather than through the
+* builder's transitive dependency graph: a change to a widely used file would
+* otherwise pull in nearly the whole project, and `--changed` exists to keep
+* the loop small. A full `warlock typecheck` (incremental, so cheap after the
+* first run) still checks everything.
+*/
+function directImporters(program, targets, root) {
+	const options = program.getCompilerOptions();
+	const cache = ts.createModuleResolutionCache(root, (name) => name, options);
+	const importers = /* @__PURE__ */ new Set();
+	for (const sourceFile of program.getSourceFiles()) {
+		const fileName = path.resolve(sourceFile.fileName);
+		if (!isProjectFile(fileName, root, false) || targets.has(fileName)) continue;
+		const { importedFiles } = ts.preProcessFile(sourceFile.text, true, true);
+		for (const imported of importedFiles) {
+			const resolved = ts.resolveModuleName(imported.fileName, fileName, options, ts.sys, cache).resolvedModule?.resolvedFileName;
+			if (resolved && targets.has(path.resolve(resolved))) {
+				importers.add(fileName);
+				break;
+			}
+		}
+	}
+	return importers;
+}
+/**
+* Typecheck the project with the TypeScript compiler API, incrementally.
+*
+* The program is built with `incremental` and `noEmit`, and its state is kept
+* in {@link DEFAULT_TYPECHECK_BUILD_INFO}, so a second run re-checks only what
+* changed. With `files`, diagnostics are collected only for those files and
+* their direct importers — the checker is lazy, so files nobody asks about are
+* parsed and bound but not checked, which is most of the memory a full check
+* costs.
+*
+* Never throws for a project problem: a missing or invalid tsconfig is a
+* `WL7102` problem, a type error a `WL7101` problem. A compiler crash is
+* re-thrown for the caller to classify (`warlock check` reports it as
+* `WL8007`).
+*/
+function runTypecheck(options = {}) {
+	const startedAt = Date.now();
+	const cwd = path.resolve(options.cwd ?? process.cwd());
+	const configPath = path.resolve(cwd, options.project ?? "tsconfig.json");
+	const result = (problems, rest = {}) => ({
+		ok: !problems.some((problem) => problem.severity === "error"),
+		mode: options.files ? "files" : "program",
+		files: null,
+		checkedFiles: 0,
+		problems,
+		durationMs: Date.now() - startedAt,
+		buildInfoFile: null,
+		...rest
+	});
+	if (!existsSync(configPath)) return result([createProblem({
+		code: "WL7102",
+		source: "typescript",
+		message: `No TypeScript config at ${toPosix(path.relative(cwd, configPath)) || configPath}.`,
+		file: toPosix(path.relative(cwd, configPath))
+	})]);
+	const read = ts.readConfigFile(configPath, ts.sys.readFile);
+	if (read.error) return result(collect([read.error], cwd, "WL7102"));
+	const parsed = ts.parseJsonConfigFileContent(read.config, ts.sys, path.dirname(configPath), void 0, configPath);
+	const buildInfoFile = path.resolve(cwd, options.buildInfoFile ?? DEFAULT_TYPECHECK_BUILD_INFO);
+	mkdirSync(path.dirname(buildInfoFile), { recursive: true });
+	const compilerOptions = {
+		...parsed.options,
+		noEmit: true,
+		incremental: true,
+		tsBuildInfoFile: buildInfoFile,
+		composite: false,
+		emitDeclarationOnly: false
+	};
+	const builder = ts.createIncrementalProgram({
+		rootNames: parsed.fileNames,
+		options: compilerOptions,
+		projectReferences: parsed.projectReferences,
+		configFileParsingDiagnostics: ts.getConfigFileParsingDiagnostics(parsed),
+		host: ts.createIncrementalCompilerHost(compilerOptions)
+	});
+	const problems = [
+		...collect(builder.getConfigFileParsingDiagnostics(), cwd, "WL7102"),
+		...collect(builder.getOptionsDiagnostics(), cwd, "WL7102"),
+		...collect(builder.getGlobalDiagnostics(), cwd, "WL7101")
+	];
+	let checked;
+	let files = null;
+	if (options.files) {
+		const targets = new Set(options.files.map((file) => path.resolve(cwd, file)));
+		const program = builder.getProgram();
+		const wanted = new Set([...targets, ...directImporters(program, targets, cwd)]);
+		checked = builder.getSourceFiles().filter((sourceFile) => wanted.has(path.resolve(sourceFile.fileName)));
+		files = checked.map((sourceFile) => toPosix(path.relative(cwd, sourceFile.fileName))).sort();
+	} else checked = builder.getSourceFiles().filter((sourceFile) => isProjectFile(sourceFile.fileName, cwd));
+	for (const sourceFile of checked) problems.push(...collect(builder.getSyntacticDiagnostics(sourceFile), cwd, "WL7101"), ...collect(builder.getSemanticDiagnostics(sourceFile), cwd, "WL7101"));
+	builder.emit();
+	return result(problems, {
+		files,
+		checkedFiles: checked.length,
+		buildInfoFile: existsSync(buildInfoFile) ? buildInfoFile : null
+	});
+}
+
+//#endregion
+export { DEFAULT_TYPECHECK_BUILD_INFO, diagnosticToProblem, directImporters, runTypecheck };
+//# sourceMappingURL=run-typecheck.mjs.map

package/esm/tooling/typecheck/run-typecheck.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-typecheck.mjs","names":[],"sources":["../../../../../../../../../packages/core/src/tooling/typecheck/run-typecheck.ts"],"sourcesContent":["import { existsSync, mkdirSync } from \"node:fs\";\nimport path from \"node:path\";\nimport ts from \"typescript\";\nimport { createProblem, type ToolingProblem } from \"../problem\";\n\n/** Inputs of {@link runTypecheck}. */\nexport type TypecheckOptions = {\n  /** Project root. Default: `process.cwd()`. */\n  cwd?: string;\n  /** tsconfig path, relative to `cwd`. Default: `tsconfig.json`. */\n  project?: string;\n  /**\n   * Limit diagnostics to these files (relative to `cwd` or absolute) and the\n   * project files that import them directly. Omit for the whole program.\n   */\n  files?: readonly string[];\n  /** Where the incremental state is kept. Default: `.warlock/cache/typecheck.tsbuildinfo`. */\n  buildInfoFile?: string;\n};\n\n/** The outcome of {@link runTypecheck}. */\nexport type TypecheckResult = {\n  /** `true` when no error-severity problem was found. */\n  ok: boolean;\n  /** `program` = every file; `files` = the given files and their direct importers. */\n  mode: \"program\" | \"files\";\n  /** Project-relative files whose diagnostics were collected in `files` mode, else `null`. */\n  files: string[] | null;\n  /** Number of source files checked. */\n  checkedFiles: number;\n  problems: ToolingProblem[];\n  durationMs: number;\n  /** Absolute path of the incremental state file, or `null` when nothing was written. */\n  buildInfoFile: string | null;\n};\n\n/** Default location of the incremental state, under the framework's own folder. */\nexport const DEFAULT_TYPECHECK_BUILD_INFO = path.join(\".warlock\", \"cache\", \"typecheck.tsbuildinfo\");\n\nfunction toPosix(file: string): string {\n  return file.split(path.sep).join(\"/\");\n}\n\n/** Whether a program file belongs to the project (under the root, outside node_modules). */\nfunction isProjectFile(fileName: string, root: string, declarations = true): boolean {\n  const normalized = path.resolve(fileName);\n\n  return (\n    normalized.startsWith(root + path.sep) &&\n    !normalized.split(path.sep).includes(\"node_modules\") &&\n    (declarations || !normalized.endsWith(\".d.ts\"))\n  );\n}\n\n/** Map one TypeScript diagnostic to a problem (`WL7101`, `rule: \"TS<code>\"`). */\nexport function diagnosticToProblem(\n  diagnostic: ts.Diagnostic,\n  cwd: string,\n  code: \"WL7101\" | \"WL7102\" = \"WL7101\",\n): ToolingProblem | undefined {\n  if (\n    diagnostic.category !== ts.DiagnosticCategory.Error &&\n    diagnostic.category !== ts.DiagnosticCategory.Warning\n  ) {\n    return undefined;\n  }\n\n  let file: string | null = null;\n  let line: number | null = null;\n  let column: number | null = null;\n\n  if (diagnostic.file) {\n    file = toPosix(path.relative(cwd, diagnostic.file.fileName));\n\n    if (diagnostic.start !== undefined) {\n      const position = diagnostic.file.getLineAndCharacterOfPosition(diagnostic.start);\n\n      line = position.line + 1;\n      column = position.character + 1;\n    }\n  }\n\n  return createProblem({\n    code,\n    source: \"typescript\",\n    severity: diagnostic.category === ts.DiagnosticCategory.Error ? \"error\" : \"warning\",\n    message: ts.flattenDiagnosticMessageText(diagnostic.messageText, \"\\n\"),\n    file,\n    line,\n    column,\n    rule: `TS${diagnostic.code}`,\n  });\n}\n\nfunction collect(\n  diagnostics: readonly ts.Diagnostic[],\n  cwd: string,\n  code: \"WL7101\" | \"WL7102\",\n): ToolingProblem[] {\n  return diagnostics\n    .map((diagnostic) => diagnosticToProblem(diagnostic, cwd, code))\n    .filter((problem): problem is ToolingProblem => problem !== undefined);\n}\n\n/**\n * The project files that import any of `targets` directly.\n *\n * Read from each file's import list (`ts.preProcessFile`) resolved with the\n * program's own options and a shared resolution cache, rather than through the\n * builder's transitive dependency graph: a change to a widely used file would\n * otherwise pull in nearly the whole project, and `--changed` exists to keep\n * the loop small. A full `warlock typecheck` (incremental, so cheap after the\n * first run) still checks everything.\n */\nexport function directImporters(\n  program: ts.Program,\n  targets: ReadonlySet<string>,\n  root: string,\n): Set<string> {\n  const options = program.getCompilerOptions();\n  const cache = ts.createModuleResolutionCache(root, (name) => name, options);\n  const importers = new Set<string>();\n\n  for (const sourceFile of program.getSourceFiles()) {\n    const fileName = path.resolve(sourceFile.fileName);\n\n    if (!isProjectFile(fileName, root, false) || targets.has(fileName)) continue;\n\n    const { importedFiles } = ts.preProcessFile(sourceFile.text, true, true);\n\n    for (const imported of importedFiles) {\n      const resolved = ts.resolveModuleName(imported.fileName, fileName, options, ts.sys, cache)\n        .resolvedModule?.resolvedFileName;\n\n      if (resolved && targets.has(path.resolve(resolved))) {\n        importers.add(fileName);\n        break;\n      }\n    }\n  }\n\n  return importers;\n}\n\n/**\n * Typecheck the project with the TypeScript compiler API, incrementally.\n *\n * The program is built with `incremental` and `noEmit`, and its state is kept\n * in {@link DEFAULT_TYPECHECK_BUILD_INFO}, so a second run re-checks only what\n * changed. With `files`, diagnostics are collected only for those files and\n * their direct importers — the checker is lazy, so files nobody asks about are\n * parsed and bound but not checked, which is most of the memory a full check\n * costs.\n *\n * Never throws for a project problem: a missing or invalid tsconfig is a\n * `WL7102` problem, a type error a `WL7101` problem. A compiler crash is\n * re-thrown for the caller to classify (`warlock check` reports it as\n * `WL8007`).\n */\nexport function runTypecheck(options: TypecheckOptions = {}): TypecheckResult {\n  const startedAt = Date.now();\n  const cwd = path.resolve(options.cwd ?? process.cwd());\n  const configPath = path.resolve(cwd, options.project ?? \"tsconfig.json\");\n  const result = (\n    problems: ToolingProblem[],\n    rest: Partial<TypecheckResult> = {},\n  ): TypecheckResult => ({\n    ok: !problems.some((problem) => problem.severity === \"error\"),\n    mode: options.files ? \"files\" : \"program\",\n    files: null,\n    checkedFiles: 0,\n    problems,\n    durationMs: Date.now() - startedAt,\n    buildInfoFile: null,\n    ...rest,\n  });\n\n  if (!existsSync(configPath)) {\n    return result([\n      createProblem({\n        code: \"WL7102\",\n        source: \"typescript\",\n        message: `No TypeScript config at ${toPosix(path.relative(cwd, configPath)) || configPath}.`,\n        file: toPosix(path.relative(cwd, configPath)),\n      }),\n    ]);\n  }\n\n  const read = ts.readConfigFile(configPath, ts.sys.readFile);\n\n  if (read.error) {\n    return result(collect([read.error], cwd, \"WL7102\"));\n  }\n\n  const parsed = ts.parseJsonConfigFileContent(\n    read.config,\n    ts.sys,\n    path.dirname(configPath),\n    undefined,\n    configPath,\n  );\n  const buildInfoFile = path.resolve(cwd, options.buildInfoFile ?? DEFAULT_TYPECHECK_BUILD_INFO);\n\n  mkdirSync(path.dirname(buildInfoFile), { recursive: true });\n\n  const compilerOptions: ts.CompilerOptions = {\n    ...parsed.options,\n    noEmit: true,\n    incremental: true,\n    tsBuildInfoFile: buildInfoFile,\n    // Both require emitting and are refused alongside noEmit.\n    composite: false,\n    emitDeclarationOnly: false,\n  };\n  const builder = ts.createIncrementalProgram({\n    rootNames: parsed.fileNames,\n    options: compilerOptions,\n    projectReferences: parsed.projectReferences,\n    configFileParsingDiagnostics: ts.getConfigFileParsingDiagnostics(parsed),\n    host: ts.createIncrementalCompilerHost(compilerOptions),\n  });\n  const problems: ToolingProblem[] = [\n    ...collect(builder.getConfigFileParsingDiagnostics(), cwd, \"WL7102\"),\n    ...collect(builder.getOptionsDiagnostics(), cwd, \"WL7102\"),\n    ...collect(builder.getGlobalDiagnostics(), cwd, \"WL7101\"),\n  ];\n\n  let checked: ts.SourceFile[];\n  let files: string[] | null = null;\n\n  if (options.files) {\n    const targets = new Set(options.files.map((file) => path.resolve(cwd, file)));\n    const program = builder.getProgram();\n    const wanted = new Set([...targets, ...directImporters(program, targets, cwd)]);\n\n    checked = builder\n      .getSourceFiles()\n      .filter((sourceFile) => wanted.has(path.resolve(sourceFile.fileName)));\n    files = checked.map((sourceFile) => toPosix(path.relative(cwd, sourceFile.fileName))).sort();\n  } else {\n    checked = builder\n      .getSourceFiles()\n      .filter((sourceFile) => isProjectFile(sourceFile.fileName, cwd));\n  }\n\n  for (const sourceFile of checked) {\n    problems.push(\n      ...collect(builder.getSyntacticDiagnostics(sourceFile), cwd, \"WL7101\"),\n      ...collect(builder.getSemanticDiagnostics(sourceFile), cwd, \"WL7101\"),\n    );\n  }\n\n  // With noEmit + incremental, emit writes only the .tsbuildinfo state.\n  builder.emit();\n\n  return result(problems, {\n    files,\n    checkedFiles: checked.length,\n    buildInfoFile: existsSync(buildInfoFile) ? buildInfoFile : null,\n  });\n}\n"],"mappings":"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"}