@warlock.js/core 5.30.0 → 5.32.0

package/esm/tooling/mcp/start-mcp-server.mjs

@@ -0,0 +1,126 @@
+import { WarlockError } from "../../errors/warlock-error.mjs";
+import { loadAiToolsServe } from "./load-ai-tools.mjs";
+import { toStandardSchema, validateToolInput } from "./tool-input.mjs";
+import { createWarlockMcpTools, describeToolError } from "./mcp-tools.mjs";
+
+//#region ../../packages/core/src/tooling/mcp/start-mcp-server.ts
+const LOOPBACK_HOSTS = /* @__PURE__ */ new Set([
+	"127.0.0.1",
+	"::1",
+	"[::1]",
+	"localhost"
+]);
+/** Whether a bind host is loopback-only. */
+function isLoopbackHost(host) {
+	return LOOPBACK_HOSTS.has(host.trim().toLowerCase());
+}
+/** Resolve the transport, refusing a non-loopback bind without a token (`WL7004`). */
+function resolveMcpTransport(transport = { type: "stdio" }) {
+	if (transport.type === "stdio") return { type: "stdio" };
+	const host = transport.host ?? "127.0.0.1";
+	const token = transport.token?.trim();
+	if (!isLoopbackHost(host) && !token) throw new WarlockError("WL7004", `warlock mcp --http refuses to listen on ${host} without a token: anything that can reach that address could call the tools. Pass --token or set WARLOCK_MCP_TOKEN.`);
+	return {
+		type: "http",
+		host,
+		port: transport.port ?? 0,
+		path: transport.path ?? "/mcp",
+		...token ? { auth: { bearer: token } } : {}
+	};
+}
+const EMPTY_USAGE = {
+	input: 0,
+	output: 0,
+	total: 0
+};
+function report(name, status, startedAt) {
+	const endedAt = /* @__PURE__ */ new Date();
+	return {
+		runId: `warlock-mcp-${startedAt.getTime()}`,
+		name,
+		type: "tool",
+		status,
+		startedAt: startedAt.toISOString(),
+		endedAt: endedAt.toISOString(),
+		duration: endedAt.getTime() - startedAt.getTime(),
+		usage: EMPTY_USAGE,
+		children: []
+	};
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+* Turn a Warlock tool into the contract `ai.mcp.serve` runs: arguments are
+* prechecked (a write on a read-only server), validated against the advertised
+* schema, then run; a failure becomes an `isError` result carrying the WL code
+* and its fix, never a crashed server.
+*/
+function toServeContract(tool) {
+	return {
+		name: tool.name,
+		description: tool.description,
+		input: toStandardSchema(tool.input),
+		execute: (input) => tool.run(input),
+		async invoke(raw) {
+			const startedAt = /* @__PURE__ */ new Date();
+			const input = isRecord(raw) ? raw : {};
+			const refusal = tool.precheck?.(input) ?? null;
+			const issues = refusal ? [refusal] : validateToolInput(tool.input, raw);
+			if (issues.length > 0) return {
+				error: /* @__PURE__ */ new Error(`Invalid arguments for ${tool.name}: ${issues.join("; ")}`),
+				usage: EMPTY_USAGE,
+				report: report(tool.name, "failed", startedAt)
+			};
+			try {
+				return {
+					data: await tool.run(input),
+					usage: EMPTY_USAGE,
+					report: report(tool.name, "completed", startedAt)
+				};
+			} catch (error) {
+				return {
+					error: new Error(describeToolError(error)),
+					usage: EMPTY_USAGE,
+					report: report(tool.name, "failed", startedAt)
+				};
+			}
+		}
+	};
+}
+/**
+* Serve the app's tools over MCP — stdio by default, or Streamable HTTP
+* through `@warlock.js/ai-tools` (loopback by default; a token is required off
+* loopback). Read-only unless `context.allowWrites`.
+*
+* @example
+* const server = await startWarlockMcpServer({
+*   context,
+*   transport: { type: "http", token: process.env.WARLOCK_MCP_TOKEN },
+* });
+* console.error(`MCP at ${server.url}`);
+* await server.close();
+*/
+async function startWarlockMcpServer(options) {
+	const transport = resolveMcpTransport(options.transport);
+	const module = await (options.loadServe ?? (() => loadAiToolsServe(options.context.cwd)))();
+	const tools = createWarlockMcpTools(options.context);
+	const server = module.serve(tools.map(toServeContract), {
+		name: options.name ?? "warlock",
+		version: options.version,
+		transport
+	});
+	const handle = await server.start();
+	return {
+		...handle.url ? { url: handle.url } : {},
+		tools: tools.map((tool) => tool.name),
+		close: async () => {
+			await handle.close();
+			await server.stop();
+		}
+	};
+}
+
+//#endregion
+export { isLoopbackHost, resolveMcpTransport, startWarlockMcpServer, toServeContract };
+//# sourceMappingURL=start-mcp-server.mjs.map

package/esm/tooling/mcp/start-mcp-server.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"start-mcp-server.mjs","names":[],"sources":["../../../../../../../../../packages/core/src/tooling/mcp/start-mcp-server.ts"],"sourcesContent":["import { WarlockError } from \"../../errors/warlock-error\";\nimport {\n  type AiToolsServeModule,\n  loadAiToolsServe,\n  type ServeToolContract,\n  type ServeTransportOptions,\n} from \"./load-ai-tools\";\nimport {\n  createWarlockMcpTools,\n  describeToolError,\n  type WarlockMcpContext,\n  type WarlockMcpTool,\n} from \"./mcp-tools\";\nimport { toStandardSchema, validateToolInput } from \"./tool-input\";\n\n/** Where the server listens. */\nexport type WarlockMcpTransport =\n  | { type: \"stdio\" }\n  | {\n      type: \"http\";\n      /** Default `127.0.0.1`. Any other host requires `token`. */\n      host?: string;\n      /** Default `0` (a free port; read it from the returned `url`). */\n      port?: number;\n      /** Default `/mcp`. */\n      path?: string;\n      /** Bearer token clients must send (`Authorization: Bearer <token>`). */\n      token?: string;\n    };\n\n/** Options of {@link startWarlockMcpServer}. */\nexport type StartWarlockMcpServerOptions = {\n  context: WarlockMcpContext;\n  /** Default `{ type: \"stdio\" }`. */\n  transport?: WarlockMcpTransport;\n  /** Advertised in `initialize`. Default `\"warlock\"`. */\n  name?: string;\n  version?: string;\n  /** How `@warlock.js/ai-tools` is loaded (tests inject it). */\n  loadServe?: () => Promise<AiToolsServeModule>;\n};\n\n/** A running server. */\nexport type WarlockMcpServerHandle = {\n  /** The endpoint (HTTP only), e.g. `http://127.0.0.1:53211/mcp`. */\n  url?: string;\n  /** The exposed tool names. */\n  tools: string[];\n  close(): Promise<void>;\n};\n\nconst LOOPBACK_HOSTS = new Set([\"127.0.0.1\", \"::1\", \"[::1]\", \"localhost\"]);\n\n/** Whether a bind host is loopback-only. */\nexport function isLoopbackHost(host: string): boolean {\n  return LOOPBACK_HOSTS.has(host.trim().toLowerCase());\n}\n\n/** Resolve the transport, refusing a non-loopback bind without a token (`WL7004`). */\nexport function resolveMcpTransport(\n  transport: WarlockMcpTransport = { type: \"stdio\" },\n): ServeTransportOptions {\n  if (transport.type === \"stdio\") return { type: \"stdio\" };\n\n  const host = transport.host ?? \"127.0.0.1\";\n  const token = transport.token?.trim();\n\n  if (!isLoopbackHost(host) && !token) {\n    throw new WarlockError(\n      \"WL7004\",\n      `warlock mcp --http refuses to listen on ${host} without a token: anything that can reach that address could call the tools. Pass --token or set WARLOCK_MCP_TOKEN.`,\n    );\n  }\n\n  return {\n    type: \"http\",\n    host,\n    port: transport.port ?? 0,\n    path: transport.path ?? \"/mcp\",\n    ...(token ? { auth: { bearer: token } } : {}),\n  };\n}\n\nconst EMPTY_USAGE = { input: 0, output: 0, total: 0 };\n\nfunction report(name: string, status: \"completed\" | \"failed\", startedAt: Date) {\n  const endedAt = new Date();\n\n  return {\n    runId: `warlock-mcp-${startedAt.getTime()}`,\n    name,\n    type: \"tool\",\n    status,\n    startedAt: startedAt.toISOString(),\n    endedAt: endedAt.toISOString(),\n    duration: endedAt.getTime() - startedAt.getTime(),\n    usage: EMPTY_USAGE,\n    children: [],\n  };\n}\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n  return typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n\n/**\n * Turn a Warlock tool into the contract `ai.mcp.serve` runs: arguments are\n * prechecked (a write on a read-only server), validated against the advertised\n * schema, then run; a failure becomes an `isError` result carrying the WL code\n * and its fix, never a crashed server.\n */\nexport function toServeContract(tool: WarlockMcpTool): ServeToolContract {\n  return {\n    name: tool.name,\n    description: tool.description,\n    input: toStandardSchema(tool.input),\n    execute: (input) => tool.run(input),\n    async invoke(raw) {\n      const startedAt = new Date();\n      const input = isRecord(raw) ? raw : {};\n      const refusal = tool.precheck?.(input) ?? null;\n      const issues = refusal ? [refusal] : validateToolInput(tool.input, raw);\n\n      if (issues.length > 0) {\n        return {\n          error: new Error(`Invalid arguments for ${tool.name}: ${issues.join(\"; \")}`),\n          usage: EMPTY_USAGE,\n          report: report(tool.name, \"failed\", startedAt),\n        };\n      }\n\n      try {\n        const data = await tool.run(input);\n\n        return { data, usage: EMPTY_USAGE, report: report(tool.name, \"completed\", startedAt) };\n      } catch (error) {\n        return {\n          error: new Error(describeToolError(error)),\n          usage: EMPTY_USAGE,\n          report: report(tool.name, \"failed\", startedAt),\n        };\n      }\n    },\n  };\n}\n\n/**\n * Serve the app's tools over MCP — stdio by default, or Streamable HTTP\n * through `@warlock.js/ai-tools` (loopback by default; a token is required off\n * loopback). Read-only unless `context.allowWrites`.\n *\n * @example\n * const server = await startWarlockMcpServer({\n *   context,\n *   transport: { type: \"http\", token: process.env.WARLOCK_MCP_TOKEN },\n * });\n * console.error(`MCP at ${server.url}`);\n * await server.close();\n */\nexport async function startWarlockMcpServer(\n  options: StartWarlockMcpServerOptions,\n): Promise<WarlockMcpServerHandle> {\n  const transport = resolveMcpTransport(options.transport);\n  const module = await (options.loadServe ?? (() => loadAiToolsServe(options.context.cwd)))();\n  const tools = createWarlockMcpTools(options.context);\n  const server = module.serve(tools.map(toServeContract), {\n    name: options.name ?? \"warlock\",\n    version: options.version,\n    transport,\n  });\n  const handle = await server.start();\n\n  return {\n    ...(handle.url ? { url: handle.url } : {}),\n    tools: tools.map((tool) => tool.name),\n    close: async () => {\n      await handle.close();\n      await server.stop();\n    },\n  };\n}\n"],"mappings":"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"}

package/esm/tooling/mcp/tool-input.d.mts

@@ -0,0 +1,75 @@
+//#region ../../packages/core/src/tooling/mcp/tool-input.d.ts
+/**
+ * The input schemas of the `warlock mcp` tools, and the small validator that
+ * checks arguments against them.
+ *
+ * The tools only take flat objects of strings, numbers, booleans, string
+ * enums and string arrays, so a JSON Schema subset is enough and core needs no
+ * validator dependency. The same object is what `tools/list` advertises.
+ */
+/** One property of a tool input. */
+export type McpInputProperty = {
+  type: "string";
+  description: string;
+  enum?: readonly string[];
+} | {
+  type: "integer";
+  description: string;
+  minimum?: number;
+  maximum?: number;
+} | {
+  type: "boolean";
+  description: string;
+} | {
+  type: "array";
+  description: string;
+  items: {
+    type: "string";
+    enum?: readonly string[];
+  };
+};
+/** A tool's input schema: a closed object. */
+export type McpInputSchema = {
+  type: "object";
+  properties: Record<string, McpInputProperty>;
+  required?: readonly string[];
+  additionalProperties: false;
+};
+/** Build an {@link McpInputSchema}. */
+export declare function inputSchema(properties: Record<string, McpInputProperty>, required?: readonly string[]): McpInputSchema;
+/**
+ * Check arguments against a schema. Returns the problems (empty when valid).
+ * `undefined` / `null` arguments are read as `{}`.
+ */
+export declare function validateToolInput(schema: McpInputSchema, input: unknown): string[];
+/** The Standard Schema result shape (spec v1). */
+type StandardResult = {
+  value: Record<string, unknown>;
+} | {
+  issues: {
+    message: string;
+  }[];
+};
+/**
+ * The input as a Standard Schema (v1) with the Standard JSON Schema extension,
+ * which is what `@warlock.js/ai` tools take: `~standard.validate` checks the
+ * arguments, `~standard.jsonSchema.input()` returns the schema `tools/list`
+ * advertises.
+ */
+export type StandardInputSchema = {
+  "~standard": {
+    version: 1;
+    vendor: string;
+    validate(value: unknown): StandardResult;
+    jsonSchema: {
+      input(options?: {
+        target?: string;
+      }): McpInputSchema;
+    };
+  };
+};
+/** Wrap a schema as a {@link StandardInputSchema}. */
+export declare function toStandardSchema(schema: McpInputSchema): StandardInputSchema;
+//#endregion
+export {};
+//# sourceMappingURL=tool-input.d.mts.map

package/esm/tooling/mcp/tool-input.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-input.d.mts","names":[],"sources":["../../../../../../../../../packages/core/src/tooling/mcp/tool-input.ts"],"mappings":";;;;;;;;;;YAUY;EACN;EAAgB;EAAqB;;EACrC;EAAiB;EAAqB;EAAkB;;EACxD;EAAiB;;EAEjB;EACA;EACA;IAAS;IAAgB;;;;YAInB;EACV;EACA,YAAY,eAAe;EAC3B;EACA;;;wBAIc,YACd,YAAY,eAAe,mBAC3B,+BACC;;;;;wBAqDa,kBAAkB,QAAQ,gBAAgB;;KA8BrD;EAAmB,OAAO;;EAA8B;IAAU;;;;;;;;;YAQ3D;EACV;IACE;IACA;IACA,SAAS,iBAAiB;IAC1B;MAAc,MAAM;QAAY;UAAoB;;;;;wBAKxC,iBAAiB,QAAQ,iBAAiB"}

package/esm/tooling/mcp/tool-input.mjs

@@ -0,0 +1,72 @@
+//#region ../../packages/core/src/tooling/mcp/tool-input.ts
+/** Build an {@link McpInputSchema}. */
+function inputSchema(properties, required = []) {
+	return {
+		type: "object",
+		properties,
+		...required.length > 0 ? { required } : {},
+		additionalProperties: false
+	};
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function checkProperty(name, property, value) {
+	switch (property.type) {
+		case "string":
+			if (typeof value !== "string") return `"${name}" must be a string`;
+			if (property.enum && !property.enum.includes(value)) return `"${name}" must be one of: ${property.enum.join(", ")}`;
+			return null;
+		case "integer":
+			if (typeof value !== "number" || !Number.isInteger(value)) return `"${name}" must be an integer`;
+			if (property.minimum !== void 0 && value < property.minimum) return `"${name}" must be at least ${property.minimum}`;
+			if (property.maximum !== void 0 && value > property.maximum) return `"${name}" must be at most ${property.maximum}`;
+			return null;
+		case "boolean": return typeof value === "boolean" ? null : `"${name}" must be a boolean`;
+		case "array":
+			if (!Array.isArray(value)) return `"${name}" must be an array of strings`;
+			for (const item of value) {
+				if (typeof item !== "string") return `"${name}" must be an array of strings`;
+				if (property.items.enum && !property.items.enum.includes(item)) return `"${name}" items must be one of: ${property.items.enum.join(", ")}`;
+			}
+			return null;
+	}
+}
+/**
+* Check arguments against a schema. Returns the problems (empty when valid).
+* `undefined` / `null` arguments are read as `{}`.
+*/
+function validateToolInput(schema, input) {
+	const value = input === void 0 || input === null ? {} : input;
+	if (!isRecord(value)) return ["arguments must be an object"];
+	const issues = [];
+	for (const name of schema.required ?? []) if (value[name] === void 0) issues.push(`"${name}" is required`);
+	for (const [name, item] of Object.entries(value)) {
+		const property = schema.properties[name];
+		if (!property) {
+			issues.push(`unknown argument "${name}"`);
+			continue;
+		}
+		if (item === void 0) continue;
+		const issue = checkProperty(name, property, item);
+		if (issue) issues.push(issue);
+	}
+	return issues;
+}
+/** Wrap a schema as a {@link StandardInputSchema}. */
+function toStandardSchema(schema) {
+	return { "~standard": {
+		version: 1,
+		vendor: "warlock-mcp",
+		validate(value) {
+			const issues = validateToolInput(schema, value);
+			if (issues.length > 0) return { issues: issues.map((message) => ({ message })) };
+			return { value: isRecord(value) ? value : {} };
+		},
+		jsonSchema: { input: () => schema }
+	} };
+}
+
+//#endregion
+export { inputSchema, toStandardSchema, validateToolInput };
+//# sourceMappingURL=tool-input.mjs.map

package/esm/tooling/mcp/tool-input.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-input.mjs","names":[],"sources":["../../../../../../../../../packages/core/src/tooling/mcp/tool-input.ts"],"sourcesContent":["/**\n * The input schemas of the `warlock mcp` tools, and the small validator that\n * checks arguments against them.\n *\n * The tools only take flat objects of strings, numbers, booleans, string\n * enums and string arrays, so a JSON Schema subset is enough and core needs no\n * validator dependency. The same object is what `tools/list` advertises.\n */\n\n/** One property of a tool input. */\nexport type McpInputProperty =\n  | { type: \"string\"; description: string; enum?: readonly string[] }\n  | { type: \"integer\"; description: string; minimum?: number; maximum?: number }\n  | { type: \"boolean\"; description: string }\n  | {\n      type: \"array\";\n      description: string;\n      items: { type: \"string\"; enum?: readonly string[] };\n    };\n\n/** A tool's input schema: a closed object. */\nexport type McpInputSchema = {\n  type: \"object\";\n  properties: Record<string, McpInputProperty>;\n  required?: readonly string[];\n  additionalProperties: false;\n};\n\n/** Build an {@link McpInputSchema}. */\nexport function inputSchema(\n  properties: Record<string, McpInputProperty>,\n  required: readonly string[] = [],\n): McpInputSchema {\n  return {\n    type: \"object\",\n    properties,\n    ...(required.length > 0 ? { required } : {}),\n    additionalProperties: false,\n  };\n}\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n  return typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n\nfunction checkProperty(name: string, property: McpInputProperty, value: unknown): string | null {\n  switch (property.type) {\n    case \"string\":\n      if (typeof value !== \"string\") return `\"${name}\" must be a string`;\n      if (property.enum && !property.enum.includes(value)) {\n        return `\"${name}\" must be one of: ${property.enum.join(\", \")}`;\n      }\n      return null;\n    case \"integer\":\n      if (typeof value !== \"number\" || !Number.isInteger(value)) {\n        return `\"${name}\" must be an integer`;\n      }\n      if (property.minimum !== undefined && value < property.minimum) {\n        return `\"${name}\" must be at least ${property.minimum}`;\n      }\n      if (property.maximum !== undefined && value > property.maximum) {\n        return `\"${name}\" must be at most ${property.maximum}`;\n      }\n      return null;\n    case \"boolean\":\n      return typeof value === \"boolean\" ? null : `\"${name}\" must be a boolean`;\n    case \"array\": {\n      if (!Array.isArray(value)) return `\"${name}\" must be an array of strings`;\n\n      for (const item of value) {\n        if (typeof item !== \"string\") return `\"${name}\" must be an array of strings`;\n        if (property.items.enum && !property.items.enum.includes(item)) {\n          return `\"${name}\" items must be one of: ${property.items.enum.join(\", \")}`;\n        }\n      }\n\n      return null;\n    }\n  }\n}\n\n/**\n * Check arguments against a schema. Returns the problems (empty when valid).\n * `undefined` / `null` arguments are read as `{}`.\n */\nexport function validateToolInput(schema: McpInputSchema, input: unknown): string[] {\n  const value = input === undefined || input === null ? {} : input;\n\n  if (!isRecord(value)) return [\"arguments must be an object\"];\n\n  const issues: string[] = [];\n\n  for (const name of schema.required ?? []) {\n    if (value[name] === undefined) issues.push(`\"${name}\" is required`);\n  }\n\n  for (const [name, item] of Object.entries(value)) {\n    const property = schema.properties[name];\n\n    if (!property) {\n      issues.push(`unknown argument \"${name}\"`);\n      continue;\n    }\n\n    if (item === undefined) continue;\n\n    const issue = checkProperty(name, property, item);\n\n    if (issue) issues.push(issue);\n  }\n\n  return issues;\n}\n\n/** The Standard Schema result shape (spec v1). */\ntype StandardResult = { value: Record<string, unknown> } | { issues: { message: string }[] };\n\n/**\n * The input as a Standard Schema (v1) with the Standard JSON Schema extension,\n * which is what `@warlock.js/ai` tools take: `~standard.validate` checks the\n * arguments, `~standard.jsonSchema.input()` returns the schema `tools/list`\n * advertises.\n */\nexport type StandardInputSchema = {\n  \"~standard\": {\n    version: 1;\n    vendor: string;\n    validate(value: unknown): StandardResult;\n    jsonSchema: { input(options?: { target?: string }): McpInputSchema };\n  };\n};\n\n/** Wrap a schema as a {@link StandardInputSchema}. */\nexport function toStandardSchema(schema: McpInputSchema): StandardInputSchema {\n  return {\n    \"~standard\": {\n      version: 1,\n      vendor: \"warlock-mcp\",\n      validate(value) {\n        const issues = validateToolInput(schema, value);\n\n        if (issues.length > 0) return { issues: issues.map((message) => ({ message })) };\n\n        return { value: isRecord(value) ? value : {} };\n      },\n      jsonSchema: { input: () => schema },\n    },\n  };\n}\n"],"mappings":";;AA6BA,SAAgB,YACd,YACA,WAA8B,CAAC,GACf;CAChB,OAAO;EACL,MAAM;EACN;EACA,GAAI,SAAS,SAAS,IAAI,EAAE,SAAS,IAAI,CAAC;EAC1C,sBAAsB;CACxB;AACF;AAEA,SAAS,SAAS,OAAkD;CAClE,OAAO,OAAO,UAAU,YAAY,UAAU,QAAQ,CAAC,MAAM,QAAQ,KAAK;AAC5E;AAEA,SAAS,cAAc,MAAc,UAA4B,OAA+B;CAC9F,QAAQ,SAAS,MAAjB;EACE,KAAK;GACH,IAAI,OAAO,UAAU,UAAU,OAAO,IAAI,KAAK;GAC/C,IAAI,SAAS,QAAQ,CAAC,SAAS,KAAK,SAAS,KAAK,GAChD,OAAO,IAAI,KAAK,oBAAoB,SAAS,KAAK,KAAK,IAAI;GAE7D,OAAO;EACT,KAAK;GACH,IAAI,OAAO,UAAU,YAAY,CAAC,OAAO,UAAU,KAAK,GACtD,OAAO,IAAI,KAAK;GAElB,IAAI,SAAS,YAAY,UAAa,QAAQ,SAAS,SACrD,OAAO,IAAI,KAAK,qBAAqB,SAAS;GAEhD,IAAI,SAAS,YAAY,UAAa,QAAQ,SAAS,SACrD,OAAO,IAAI,KAAK,oBAAoB,SAAS;GAE/C,OAAO;EACT,KAAK,WACH,OAAO,OAAO,UAAU,YAAY,OAAO,IAAI,KAAK;EACtD,KAAK;GACH,IAAI,CAAC,MAAM,QAAQ,KAAK,GAAG,OAAO,IAAI,KAAK;GAE3C,KAAK,MAAM,QAAQ,OAAO;IACxB,IAAI,OAAO,SAAS,UAAU,OAAO,IAAI,KAAK;IAC9C,IAAI,SAAS,MAAM,QAAQ,CAAC,SAAS,MAAM,KAAK,SAAS,IAAI,GAC3D,OAAO,IAAI,KAAK,0BAA0B,SAAS,MAAM,KAAK,KAAK,IAAI;GAE3E;GAEA,OAAO;CAEX;AACF;;;;;AAMA,SAAgB,kBAAkB,QAAwB,OAA0B;CAClF,MAAM,QAAQ,UAAU,UAAa,UAAU,OAAO,CAAC,IAAI;CAE3D,IAAI,CAAC,SAAS,KAAK,GAAG,OAAO,CAAC,6BAA6B;CAE3D,MAAM,SAAmB,CAAC;CAE1B,KAAK,MAAM,QAAQ,OAAO,YAAY,CAAC,GACrC,IAAI,MAAM,UAAU,QAAW,OAAO,KAAK,IAAI,KAAK,cAAc;CAGpE,KAAK,MAAM,CAAC,MAAM,SAAS,OAAO,QAAQ,KAAK,GAAG;EAChD,MAAM,WAAW,OAAO,WAAW;EAEnC,IAAI,CAAC,UAAU;GACb,OAAO,KAAK,qBAAqB,KAAK,EAAE;GACxC;EACF;EAEA,IAAI,SAAS,QAAW;EAExB,MAAM,QAAQ,cAAc,MAAM,UAAU,IAAI;EAEhD,IAAI,OAAO,OAAO,KAAK,KAAK;CAC9B;CAEA,OAAO;AACT;;AAqBA,SAAgB,iBAAiB,QAA6C;CAC5E,OAAO,EACL,aAAa;EACX,SAAS;EACT,QAAQ;EACR,SAAS,OAAO;GACd,MAAM,SAAS,kBAAkB,QAAQ,KAAK;GAE9C,IAAI,OAAO,SAAS,GAAG,OAAO,EAAE,QAAQ,OAAO,KAAK,aAAa,EAAE,QAAQ,EAAE,EAAE;GAE/E,OAAO,EAAE,OAAO,SAAS,KAAK,IAAI,QAAQ,CAAC,EAAE;EAC/C;EACA,YAAY,EAAE,aAAa,OAAO;CACpC,EACF;AACF"}

package/esm/tooling/problem.d.mts

@@ -0,0 +1,55 @@
+import { ErrorCodeCategory, WarlockErrorCode } from "../errors/error-codes.mjs";
+//#region ../../packages/core/src/tooling/problem.d.ts
+/** The tool that found a problem. */
+export type ProblemSource = "typescript" | "eslint" | "oxlint" | "vitest" | "convention" | "environment" | "doctor";
+/**
+ * One problem, in the shape every machine-readable command prints
+ * (`warlock check --json`, `warlock typecheck --json`, `warlock doctor --json`).
+ *
+ * Every key is always present, so a consumer never has to test for one:
+ * `file`, `line` and `column` are `null` when the problem has no position.
+ */
+export type ToolingProblem = {
+  /** Stable Warlock error code; `warlock explain <code>` prints the fix. */
+  code: WarlockErrorCode;
+  /** `code` = fix the project; `environment` = fix this machine. */
+  category: ErrorCodeCategory;
+  /** `error` fails the run; `warning` is reported and does not. */
+  severity: "error" | "warning";
+  /** The tool that reported it. */
+  source: ProblemSource;
+  /** Project-relative POSIX path, or `null`. */
+  file: string | null;
+  /** 1-based line, or `null`. */
+  line: number | null;
+  /** 1-based column, or `null`. */
+  column: number | null;
+  /** What is wrong, in the reporting tool's words. */
+  message: string;
+  /** One line on what to do, from the code registry. */
+  hint: string;
+  /** Slug of the skill that explains the fix. */
+  skill: string;
+  /** Docs URL of the code. */
+  docs: string;
+  /** The tool's own rule or code (`TS2345`, `no-unused-vars`, a test name), or `null`. */
+  rule: string | null;
+};
+/** The fields a reporter supplies; the rest come from the registry. */
+export type ProblemInput = {
+  code: WarlockErrorCode;
+  source: ProblemSource;
+  message: string;
+  severity?: "error" | "warning";
+  file?: string | null;
+  line?: number | null;
+  column?: number | null;
+  rule?: string | null;
+};
+/**
+ * Build a {@link ToolingProblem}, filling `category`, `hint`, `skill` and `docs`
+ * from the code registry so every reporter describes a code the same way.
+ */
+export declare function createProblem(input: ProblemInput): ToolingProblem;
+//#endregion
+//# sourceMappingURL=problem.d.mts.map

package/esm/tooling/problem.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"problem.d.mts","names":[],"sources":["../../../../../../../../packages/core/src/tooling/problem.ts"],"mappings":";;;YAQY;;;;;;;;YAgBA;;EAEV,MAAM;;EAEN,UAAU;;EAEV;;EAEA,QAAQ;;EAER;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA;;;YAIU;EACV,MAAM;EACN,QAAQ;EACR;EACA;EACA;EACA;EACA;EACA;;;;;;wBAOc,cAAc,OAAO,eAAe"}

package/esm/tooling/problem.mjs

@@ -0,0 +1,28 @@
+import { ERROR_CODES, errorCodeDocsUrl } from "../errors/error-codes.mjs";
+
+//#region ../../packages/core/src/tooling/problem.ts
+/**
+* Build a {@link ToolingProblem}, filling `category`, `hint`, `skill` and `docs`
+* from the code registry so every reporter describes a code the same way.
+*/
+function createProblem(input) {
+	const definition = ERROR_CODES[input.code];
+	return {
+		code: input.code,
+		category: definition.category,
+		severity: input.severity ?? "error",
+		source: input.source,
+		file: input.file ?? null,
+		line: input.line ?? null,
+		column: input.column ?? null,
+		message: input.message,
+		hint: definition.fix,
+		skill: definition.skill,
+		docs: errorCodeDocsUrl(input.code),
+		rule: input.rule ?? null
+	};
+}
+
+//#endregion
+export { createProblem };
+//# sourceMappingURL=problem.mjs.map

package/esm/tooling/problem.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"problem.mjs","names":[],"sources":["../../../../../../../../packages/core/src/tooling/problem.ts"],"sourcesContent":["import {\n  ERROR_CODES,\n  errorCodeDocsUrl,\n  type ErrorCodeCategory,\n  type WarlockErrorCode,\n} from \"../errors/error-codes\";\n\n/** The tool that found a problem. */\nexport type ProblemSource =\n  | \"typescript\"\n  | \"eslint\"\n  | \"oxlint\"\n  | \"vitest\"\n  | \"convention\"\n  | \"environment\"\n  | \"doctor\";\n\n/**\n * One problem, in the shape every machine-readable command prints\n * (`warlock check --json`, `warlock typecheck --json`, `warlock doctor --json`).\n *\n * Every key is always present, so a consumer never has to test for one:\n * `file`, `line` and `column` are `null` when the problem has no position.\n */\nexport type ToolingProblem = {\n  /** Stable Warlock error code; `warlock explain <code>` prints the fix. */\n  code: WarlockErrorCode;\n  /** `code` = fix the project; `environment` = fix this machine. */\n  category: ErrorCodeCategory;\n  /** `error` fails the run; `warning` is reported and does not. */\n  severity: \"error\" | \"warning\";\n  /** The tool that reported it. */\n  source: ProblemSource;\n  /** Project-relative POSIX path, or `null`. */\n  file: string | null;\n  /** 1-based line, or `null`. */\n  line: number | null;\n  /** 1-based column, or `null`. */\n  column: number | null;\n  /** What is wrong, in the reporting tool's words. */\n  message: string;\n  /** One line on what to do, from the code registry. */\n  hint: string;\n  /** Slug of the skill that explains the fix. */\n  skill: string;\n  /** Docs URL of the code. */\n  docs: string;\n  /** The tool's own rule or code (`TS2345`, `no-unused-vars`, a test name), or `null`. */\n  rule: string | null;\n};\n\n/** The fields a reporter supplies; the rest come from the registry. */\nexport type ProblemInput = {\n  code: WarlockErrorCode;\n  source: ProblemSource;\n  message: string;\n  severity?: \"error\" | \"warning\";\n  file?: string | null;\n  line?: number | null;\n  column?: number | null;\n  rule?: string | null;\n};\n\n/**\n * Build a {@link ToolingProblem}, filling `category`, `hint`, `skill` and `docs`\n * from the code registry so every reporter describes a code the same way.\n */\nexport function createProblem(input: ProblemInput): ToolingProblem {\n  const definition = ERROR_CODES[input.code];\n\n  return {\n    code: input.code,\n    category: definition.category,\n    severity: input.severity ?? \"error\",\n    source: input.source,\n    file: input.file ?? null,\n    line: input.line ?? null,\n    column: input.column ?? null,\n    message: input.message,\n    hint: definition.fix,\n    skill: definition.skill,\n    docs: errorCodeDocsUrl(input.code),\n    rule: input.rule ?? null,\n  };\n}\n"],"mappings":";;;;;;;AAmEA,SAAgB,cAAc,OAAqC;CACjE,MAAM,aAAa,YAAY,MAAM;CAErC,OAAO;EACL,MAAM,MAAM;EACZ,UAAU,WAAW;EACrB,UAAU,MAAM,YAAY;EAC5B,QAAQ,MAAM;EACd,MAAM,MAAM,QAAQ;EACpB,MAAM,MAAM,QAAQ;EACpB,QAAQ,MAAM,UAAU;EACxB,SAAS,MAAM;EACf,MAAM,WAAW;EACjB,OAAO,WAAW;EAClB,MAAM,iBAAiB,MAAM,IAAI;EACjC,MAAM,MAAM,QAAQ;CACtB;AACF"}

package/esm/tooling/syntax/ast.mjs

@@ -0,0 +1,230 @@
+import { parseSync, visitorKeys } from "oxc-parser";
+
+//#region ../../packages/core/src/tooling/syntax/ast.ts
+const parents = /* @__PURE__ */ new WeakMap();
+const sources = /* @__PURE__ */ new WeakMap();
+function forEachChild(node, visit) {
+	const record = node;
+	for (const key of visitorKeys[node.type] ?? []) {
+		const value = record[key];
+		for (const child of Array.isArray(value) ? value : [value]) if (child && typeof child === "object" && "type" in child) visit(child);
+	}
+}
+function parseSourceFile(fileName, text) {
+	const source = Object.assign(parseSync(fileName, text).program, {
+		fileName,
+		text
+	});
+	const attach = (node) => {
+		sources.set(node, source);
+		forEachChild(node, (child) => {
+			parents.set(child, node);
+			attach(child);
+		});
+	};
+	attach(source);
+	return source;
+}
+function parentOf(node) {
+	return parents.get(node);
+}
+function sourceOf(node) {
+	const source = sources.get(node);
+	if (!source) throw new Error("Node has no source file.");
+	return source;
+}
+function textOf(node) {
+	return node.type === "Identifier" ? node.name : sourceOf(node).text.slice(node.start, node.end);
+}
+function keyName(node) {
+	if (!node) return void 0;
+	const parent = parentOf(node);
+	if (parent && "computed" in parent && parent.computed) return void 0;
+	if (node.type === "Identifier" || node.type === "PrivateIdentifier") return node.name;
+	if (node.type === "JSXIdentifier") return node.name;
+	if (node.type === "Literal" && (typeof node.value === "string" || typeof node.value === "number")) return String(node.value);
+	if (node.type === "TemplateLiteral" && node.expressions.length === 0) return node.quasis[0]?.value.cooked ?? void 0;
+}
+function positionOf(source, node) {
+	const lines = source.text.slice(0, node.start).split("\n");
+	return {
+		line: lines.length,
+		column: (lines.at(-1)?.length ?? 0) + 1
+	};
+}
+function expressionOf(node) {
+	if (node.type === "CallExpression" || node.type === "NewExpression") return node.callee;
+	if (node.type === "MemberExpression") return node.object;
+	if (node.type === "AwaitExpression" || node.type === "SpreadElement") return node.argument;
+	if (node.type === "IfStatement") return node.test;
+	if ("expression" in node && node.expression && typeof node.expression === "object") return node.expression;
+	throw new Error(`No expression on ${node.type}.`);
+}
+function nameNode(node) {
+	if ("id" in node && node.id) return node.id;
+	if ("key" in node) return node.key;
+	if (node.type === "ImportSpecifier" || node.type === "ImportDefaultSpecifier" || node.type === "ImportNamespaceSpecifier") return node.local;
+	if (node.type === "JSXAttribute") return node.name;
+	throw new Error(`No name on ${node.type}.`);
+}
+function declarationName(node) {
+	return "id" in node && node.id?.type === "Identifier" ? node.id.name : void 0;
+}
+function valueText(node) {
+	return keyName(node) ?? (node.type === "Literal" ? node.raw ?? "" : textOf(node));
+}
+function isCallExpression(node) {
+	return node.type === "CallExpression";
+}
+function isNewExpression(node) {
+	return node.type === "NewExpression";
+}
+function isIdentifier(node) {
+	return node.type === "Identifier";
+}
+function isObjectLiteralExpression(node) {
+	return node.type === "ObjectExpression";
+}
+function isVariableDeclaration(node) {
+	return node.type === "VariableDeclarator";
+}
+function isVariableStatement(node) {
+	return node.type === "VariableDeclaration";
+}
+function isImportDeclaration(node) {
+	return node.type === "ImportDeclaration";
+}
+function isPropertyAssignment(node) {
+	return node.type === "Property" && !node.shorthand && !node.method && node.kind === "init";
+}
+function isShorthandPropertyAssignment(node) {
+	return node.type === "Property" && node.shorthand;
+}
+function isPropertyDeclaration(node) {
+	return node.type === "PropertyDefinition";
+}
+function isExportAssignment(node) {
+	return node.type === "ExportDefaultDeclaration";
+}
+function isExportDeclaration(node) {
+	return node.type === "ExportNamedDeclaration";
+}
+function isClassDeclaration(node) {
+	return node.type === "ClassDeclaration";
+}
+function isFunctionDeclaration(node) {
+	return node.type === "FunctionDeclaration";
+}
+function isFunctionExpression(node) {
+	return node.type === "FunctionExpression";
+}
+function isArrowFunction(node) {
+	return node.type === "ArrowFunctionExpression";
+}
+function isInterfaceDeclaration(node) {
+	return node.type === "TSInterfaceDeclaration";
+}
+function isTypeAliasDeclaration(node) {
+	return node.type === "TSTypeAliasDeclaration";
+}
+function isAwaitExpression(node) {
+	return node.type === "AwaitExpression";
+}
+function isArrayLiteralExpression(node) {
+	return node.type === "ArrayExpression";
+}
+function isSpreadElement(node) {
+	return node.type === "SpreadElement";
+}
+function isSpreadAssignment(node) {
+	return node.type === "SpreadElement";
+}
+function isAsExpression(node) {
+	return node.type === "TSAsExpression";
+}
+function isNonNullExpression(node) {
+	return node.type === "TSNonNullExpression";
+}
+function isSatisfiesExpression(node) {
+	return node.type === "TSSatisfiesExpression";
+}
+function isTypeAssertionExpression(node) {
+	return node.type === "TSTypeAssertion";
+}
+function isParenthesizedExpression(node) {
+	return node.type === "ParenthesizedExpression";
+}
+function isJsxAttribute(node) {
+	return node.type === "JSXAttribute";
+}
+function isJsxExpression(node) {
+	return node.type === "JSXExpressionContainer";
+}
+function isJsxOpeningElement(node) {
+	return node.type === "JSXOpeningElement";
+}
+function isJsxSelfClosingElement(node) {
+	return node.type === "JSXOpeningElement" && node.selfClosing;
+}
+function isIfStatement(node) {
+	return node.type === "IfStatement";
+}
+function isConditionalExpression(node) {
+	return node.type === "ConditionalExpression";
+}
+function isTemplateExpression(node) {
+	return node.type === "TemplateLiteral" && node.expressions.length > 0;
+}
+function isPropertySignature(node) {
+	return node.type === "TSPropertySignature";
+}
+function isUnionTypeNode(node) {
+	return node.type === "TSUnionType";
+}
+function isLiteralTypeNode(node) {
+	return node.type === "TSLiteralType";
+}
+function isExpressionStatement(node) {
+	return node.type === "ExpressionStatement";
+}
+function isStringLiteral(node) {
+	return node.type === "Literal" && typeof node.value === "string";
+}
+function isNumericLiteral(node) {
+	return node.type === "Literal" && typeof node.value === "number";
+}
+function isNoSubstitutionTemplateLiteral(node) {
+	return node.type === "TemplateLiteral" && node.expressions.length === 0;
+}
+function isBinaryExpression(node) {
+	return node.type === "BinaryExpression" || node.type === "LogicalExpression" || node.type === "AssignmentExpression";
+}
+function isRegularExpressionLiteral(node) {
+	return node.type === "Literal" && "regex" in node;
+}
+function isElementAccessExpression(node) {
+	return node.type === "MemberExpression" && node.computed;
+}
+function isComputedPropertyName(node) {
+	const parent = parentOf(node);
+	return !!parent && "computed" in parent && parent.computed;
+}
+function isOmittedExpression(node) {
+	return node === null;
+}
+function hasModifier(node, modifier) {
+	const parent = parentOf(node);
+	if (modifier === "export") return parent?.type === "ExportNamedDeclaration" || parent?.type === "ExportDefaultDeclaration";
+	if (modifier === "default") return parent?.type === "ExportDefaultDeclaration";
+	return modifier in node && Reflect.get(node, modifier) === true;
+}
+function topLevelDeclarations(source) {
+	return source.body.map((statement) => (statement.type === "ExportNamedDeclaration" || statement.type === "ExportDefaultDeclaration") && statement.declaration ? statement.declaration : statement);
+}
+function isEnumDeclaration(node) {
+	return node.type === "TSEnumDeclaration";
+}
+
+//#endregion
+export { declarationName, expressionOf, forEachChild, hasModifier, isArrayLiteralExpression, isArrowFunction, isAsExpression, isAwaitExpression, isBinaryExpression, isCallExpression, isClassDeclaration, isComputedPropertyName, isConditionalExpression, isElementAccessExpression, isEnumDeclaration, isExportAssignment, isExportDeclaration, isExpressionStatement, isFunctionDeclaration, isFunctionExpression, isIdentifier, isIfStatement, isImportDeclaration, isInterfaceDeclaration, isJsxAttribute, isJsxExpression, isJsxOpeningElement, isJsxSelfClosingElement, isLiteralTypeNode, isNewExpression, isNoSubstitutionTemplateLiteral, isNonNullExpression, isNumericLiteral, isObjectLiteralExpression, isOmittedExpression, isParenthesizedExpression, isPropertyAssignment, isPropertyDeclaration, isPropertySignature, isRegularExpressionLiteral, isSatisfiesExpression, isShorthandPropertyAssignment, isSpreadAssignment, isSpreadElement, isStringLiteral, isTemplateExpression, isTypeAliasDeclaration, isTypeAssertionExpression, isUnionTypeNode, isVariableDeclaration, isVariableStatement, keyName, nameNode, parentOf, parseSourceFile, positionOf, sourceOf, textOf, topLevelDeclarations, valueText };
+//# sourceMappingURL=ast.mjs.map