@warlock.js/core 5.30.0 → 5.31.0

package/esm/tooling/check/changed-files.mjs

@@ -0,0 +1,73 @@
+import { createProblem } from "../problem.mjs";
+import path from "node:path";
+import { existsSync } from "node:fs";
+import { execFile } from "node:child_process";
+
+//#region ../../packages/core/src/tooling/check/changed-files.ts
+/** The default {@link GitRunner}: the `git` on PATH. */
+const runGit = (args, cwd) => new Promise((resolve) => {
+	execFile("git", [...args], {
+		cwd,
+		encoding: "utf8",
+		windowsHide: true,
+		maxBuffer: 16 * 1024 * 1024
+	}, (error, stdout, stderr) => {
+		resolve({
+			code: error === null ? 0 : typeof error.code === "number" ? error.code : 127,
+			stdout,
+			stderr: stderr || (error?.message ?? "")
+		});
+	});
+});
+/** Files `warlock check --changed` considers: JavaScript and TypeScript sources. */
+const SOURCE_FILE = /\.(?:[cm]?[jt]sx?)$/i;
+function lines(output) {
+	return output.split(/\r?\n/).map((line) => line.trim()).filter((line) => line.length > 0);
+}
+function gitProblem(message) {
+	return createProblem({
+		code: "WL8006",
+		source: "environment",
+		message
+	});
+}
+/**
+* The source files changed in the working tree — tracked changes against
+* `base` (or HEAD) plus untracked files — relative to `cwd`, existing only.
+*
+* With `base`, the comparison point is `git merge-base <base> HEAD`, so a
+* branch is compared with where it left `base` rather than with `base`'s tip.
+* A git failure is a `WL8006` environment problem.
+*/
+async function listChangedFiles(options) {
+	const git = options.git ?? runGit;
+	let ref = "HEAD";
+	if (options.base) {
+		const mergeBase = await git([
+			"merge-base",
+			options.base,
+			"HEAD"
+		], options.cwd);
+		if (mergeBase.code !== 0) return { problem: gitProblem(`git merge-base ${options.base} HEAD failed: ${mergeBase.stderr.trim() || `exit ${mergeBase.code}`}`) };
+		ref = mergeBase.stdout.trim();
+	}
+	const diff = await git([
+		"diff",
+		"--name-only",
+		"--relative",
+		"--diff-filter=ACMR",
+		ref
+	], options.cwd);
+	if (diff.code !== 0) return { problem: gitProblem(`git diff against ${ref} failed: ${diff.stderr.trim() || `exit ${diff.code}`}`) };
+	const untracked = await git([
+		"ls-files",
+		"--others",
+		"--exclude-standard"
+	], options.cwd);
+	if (untracked.code !== 0) return { problem: gitProblem(`git ls-files failed: ${untracked.stderr.trim() || `exit ${untracked.code}`}`) };
+	return { files: [...new Set([...lines(diff.stdout), ...lines(untracked.stdout)])].map((file) => file.split(path.sep).join("/")).filter((file) => SOURCE_FILE.test(file) && existsSync(path.join(options.cwd, file))).sort() };
+}
+
+//#endregion
+export { listChangedFiles, runGit };
+//# sourceMappingURL=changed-files.mjs.map

package/esm/tooling/check/changed-files.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"changed-files.mjs","names":[],"sources":["../../../../../../../../../packages/core/src/tooling/check/changed-files.ts"],"sourcesContent":["import { execFile } from \"node:child_process\";\nimport { existsSync } from \"node:fs\";\nimport path from \"node:path\";\nimport { createProblem, type ToolingProblem } from \"../problem\";\n\n/** The result of one git invocation. */\nexport type GitResult = { code: number; stdout: string; stderr: string };\n\n/** Runs `git <args>` in `cwd`. Injectable so tests need no repository. */\nexport type GitRunner = (args: readonly string[], cwd: string) => Promise<GitResult>;\n\n/** The default {@link GitRunner}: the `git` on PATH. */\nexport const runGit: GitRunner = (args, cwd) =>\n  new Promise((resolve) => {\n    execFile(\n      \"git\",\n      [...args],\n      { cwd, encoding: \"utf8\", windowsHide: true, maxBuffer: 16 * 1024 * 1024 },\n      (error, stdout, stderr) => {\n        const code = error === null ? 0 : typeof error.code === \"number\" ? error.code : 127;\n\n        resolve({ code, stdout, stderr: stderr || (error?.message ?? \"\") });\n      },\n    );\n  });\n\n/** Files `warlock check --changed` considers: JavaScript and TypeScript sources. */\nconst SOURCE_FILE = /\\.(?:[cm]?[jt]sx?)$/i;\n\nfunction lines(output: string): string[] {\n  return output\n    .split(/\\r?\\n/)\n    .map((line) => line.trim())\n    .filter((line) => line.length > 0);\n}\n\nfunction gitProblem(message: string): ToolingProblem {\n  return createProblem({ code: \"WL8006\", source: \"environment\", message });\n}\n\n/**\n * The source files changed in the working tree — tracked changes against\n * `base` (or HEAD) plus untracked files — relative to `cwd`, existing only.\n *\n * With `base`, the comparison point is `git merge-base <base> HEAD`, so a\n * branch is compared with where it left `base` rather than with `base`'s tip.\n * A git failure is a `WL8006` environment problem.\n */\nexport async function listChangedFiles(options: {\n  cwd: string;\n  base?: string;\n  git?: GitRunner;\n}): Promise<{ files: string[] } | { problem: ToolingProblem }> {\n  const git = options.git ?? runGit;\n  let ref = \"HEAD\";\n\n  if (options.base) {\n    const mergeBase = await git([\"merge-base\", options.base, \"HEAD\"], options.cwd);\n\n    if (mergeBase.code !== 0) {\n      return {\n        problem: gitProblem(\n          `git merge-base ${options.base} HEAD failed: ${mergeBase.stderr.trim() || `exit ${mergeBase.code}`}`,\n        ),\n      };\n    }\n\n    ref = mergeBase.stdout.trim();\n  }\n\n  // `--relative` makes the paths relative to cwd and limits them to it.\n  const diff = await git(\n    [\"diff\", \"--name-only\", \"--relative\", \"--diff-filter=ACMR\", ref],\n    options.cwd,\n  );\n\n  if (diff.code !== 0) {\n    return {\n      problem: gitProblem(\n        `git diff against ${ref} failed: ${diff.stderr.trim() || `exit ${diff.code}`}`,\n      ),\n    };\n  }\n\n  const untracked = await git([\"ls-files\", \"--others\", \"--exclude-standard\"], options.cwd);\n\n  if (untracked.code !== 0) {\n    return {\n      problem: gitProblem(\n        `git ls-files failed: ${untracked.stderr.trim() || `exit ${untracked.code}`}`,\n      ),\n    };\n  }\n\n  const files = [...new Set([...lines(diff.stdout), ...lines(untracked.stdout)])]\n    .map((file) => file.split(path.sep).join(\"/\"))\n    .filter((file) => SOURCE_FILE.test(file) && existsSync(path.join(options.cwd, file)))\n    .sort();\n\n  return { files };\n}\n"],"mappings":";;;;;;;AAYA,MAAa,UAAqB,MAAM,QACtC,IAAI,SAAS,YAAY;CACvB,SACE,OACA,CAAC,GAAG,IAAI,GACR;EAAE;EAAK,UAAU;EAAQ,aAAa;EAAM,WAAW,KAAK,OAAO;CAAK,IACvE,OAAO,QAAQ,WAAW;EAGzB,QAAQ;GAAE,MAFG,UAAU,OAAO,IAAI,OAAO,MAAM,SAAS,WAAW,MAAM,OAAO;GAEhE;GAAQ,QAAQ,WAAW,OAAO,WAAW;EAAI,CAAC;CACpE,CACF;AACF,CAAC;;AAGH,MAAM,cAAc;AAEpB,SAAS,MAAM,QAA0B;CACvC,OAAO,OACJ,MAAM,OAAO,CAAC,CACd,KAAK,SAAS,KAAK,KAAK,CAAC,CAAC,CAC1B,QAAQ,SAAS,KAAK,SAAS,CAAC;AACrC;AAEA,SAAS,WAAW,SAAiC;CACnD,OAAO,cAAc;EAAE,MAAM;EAAU,QAAQ;EAAe;CAAQ,CAAC;AACzE;;;;;;;;;AAUA,eAAsB,iBAAiB,SAIwB;CAC7D,MAAM,MAAM,QAAQ,OAAO;CAC3B,IAAI,MAAM;CAEV,IAAI,QAAQ,MAAM;EAChB,MAAM,YAAY,MAAM,IAAI;GAAC;GAAc,QAAQ;GAAM;EAAM,GAAG,QAAQ,GAAG;EAE7E,IAAI,UAAU,SAAS,GACrB,OAAO,EACL,SAAS,WACP,kBAAkB,QAAQ,KAAK,gBAAgB,UAAU,OAAO,KAAK,KAAK,QAAQ,UAAU,QAC9F,EACF;EAGF,MAAM,UAAU,OAAO,KAAK;CAC9B;CAGA,MAAM,OAAO,MAAM,IACjB;EAAC;EAAQ;EAAe;EAAc;EAAsB;CAAG,GAC/D,QAAQ,GACV;CAEA,IAAI,KAAK,SAAS,GAChB,OAAO,EACL,SAAS,WACP,oBAAoB,IAAI,WAAW,KAAK,OAAO,KAAK,KAAK,QAAQ,KAAK,QACxE,EACF;CAGF,MAAM,YAAY,MAAM,IAAI;EAAC;EAAY;EAAY;CAAoB,GAAG,QAAQ,GAAG;CAEvF,IAAI,UAAU,SAAS,GACrB,OAAO,EACL,SAAS,WACP,wBAAwB,UAAU,OAAO,KAAK,KAAK,QAAQ,UAAU,QACvE,EACF;CAQF,OAAO,EAAE,OALK,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,MAAM,KAAK,MAAM,GAAG,GAAG,MAAM,UAAU,MAAM,CAAC,CAAC,CAAC,CAAC,CAC5E,KAAK,SAAS,KAAK,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,CAC7C,QAAQ,SAAS,YAAY,KAAK,IAAI,KAAK,WAAW,KAAK,KAAK,QAAQ,KAAK,IAAI,CAAC,CAAC,CAAC,CACpF,KAEU,EAAE;AACjB"}

package/esm/tooling/check/check-report.types.d.mts

@@ -0,0 +1,62 @@
+import { ToolingProblem } from "../problem.mjs";
+
+//#region ../../packages/core/src/tooling/check/check-report.types.d.ts
+/** The steps `warlock check` runs, in order. */
+declare const CHECK_STEPS: readonly ["environment", "typecheck", "lint", "tests", "conventions"];
+/** One step name. */
+type CheckStepName = (typeof CHECK_STEPS)[number];
+/**
+ * - `passed`: ran and found no error.
+ * - `failed`: ran and found at least one error-severity problem.
+ * - `skipped`: does not apply (no lint config, no tests, nothing changed, `--skip`).
+ * - `blocked`: could not run because of this machine; an environment problem says why.
+ */
+type CheckStepStatus = "passed" | "failed" | "skipped" | "blocked";
+/** One step of the report. */
+type CheckStep = {
+  name: CheckStepName;
+  status: CheckStepStatus;
+  durationMs: number; /** One line on what the step did or why it did not run, or `null`. */
+  detail: string | null;
+};
+/**
+ * Exit codes of `warlock check` and `warlock typecheck`:
+ *
+ * | Code | Meaning                                                                    |
+ * | ---- | -------------------------------------------------------------------------- |
+ * | 0    | no error-severity problem (warnings are allowed)                           |
+ * | 1    | problems in your code only: type, lint, test or convention errors          |
+ * | 2    | this machine: Node version, missing tool, unreachable service, busy port,  |
+ * |      | git unavailable, a tool that crashed — the run is incomplete               |
+ *
+ * 2 wins over 1: when the machine kept a step from running, the run did not
+ * check everything, so "only your code is wrong" cannot be claimed.
+ */
+declare const CHECK_EXIT_CODES: {
+  readonly ok: 0;
+  readonly code: 1;
+  readonly environment: 2;
+};
+/** One of {@link CHECK_EXIT_CODES}. */
+type CheckExitCode = (typeof CHECK_EXIT_CODES)[keyof typeof CHECK_EXIT_CODES];
+/** The exit code for a set of problems; see {@link CHECK_EXIT_CODES}. */
+declare function checkExitCode(problems: readonly ToolingProblem[]): CheckExitCode;
+/** What `warlock check --json` prints. */
+type CheckReport = {
+  schemaVersion: 1; /** `true` when the exit code is 0. */
+  ok: boolean;
+  exitCode: CheckExitCode; /** Whether the run was limited to changed files. */
+  changed: boolean; /** The changed files the run was limited to (project-relative), or `null` for a full run. */
+  files: string[] | null;
+  steps: CheckStep[]; /** One entry per problem, in step order. */
+  problems: ToolingProblem[];
+  summary: {
+    errors: number;
+    warnings: number; /** Error-severity problems in the code. */
+    code: number; /** Error-severity problems with the machine. */
+    environment: number;
+  };
+};
+//#endregion
+export { CHECK_EXIT_CODES, CHECK_STEPS, CheckExitCode, CheckReport, CheckStep, CheckStepName, CheckStepStatus, checkExitCode };
+//# sourceMappingURL=check-report.types.d.mts.map

package/esm/tooling/check/check-report.types.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"check-report.types.d.mts","names":[],"sources":["../../../../../../../../../packages/core/src/tooling/check/check-report.types.ts"],"mappings":";;;;cAGa,WAAA;AAAb;AAAA,KAGY,aAAA,WAAwB,WAAW;;;AAHiD;AAGhG;;;KAQY,eAAA;AARmC;AAAA,KAWnC,SAAA;EACV,IAAA,EAAM,aAAA;EACN,MAAA,EAAQ,eAAe;EACvB,UAAA,UANyB;EAQzB,MAAA;AAAA;;;;;;;;;;AAAM;AAgBR;;;cAAa,gBAAA;EAAA;;;;;KAOD,aAAA,WAAwB,gBAAA,eAA+B,gBAAgB;;iBAGnE,aAAA,CAAc,QAAA,WAAmB,cAAA,KAAmB,aAAa;;KAWrE,WAAA;EACV,aAAA,KAZ2B;EAc3B,EAAA;EACA,QAAA,EAAU,aAAA,EAfqC;EAiB/C,OAAA,WAjBkE;EAmBlE,KAAA;EACA,KAAA,EAAO,SAAA,IATG;EAWV,QAAA,EAAU,cAAA;EACV,OAAA;IACE,MAAA;IACA,QAAA,UAHQ;IAKR,IAAA,UALsB;IAOtB,WAAA;EAAA;AAAA"}

package/esm/tooling/check/check-report.types.mjs

@@ -0,0 +1,37 @@
+//#region ../../packages/core/src/tooling/check/check-report.types.ts
+/** The steps `warlock check` runs, in order. */
+const CHECK_STEPS = [
+	"environment",
+	"typecheck",
+	"lint",
+	"tests",
+	"conventions"
+];
+/**
+* Exit codes of `warlock check` and `warlock typecheck`:
+*
+* | Code | Meaning                                                                    |
+* | ---- | -------------------------------------------------------------------------- |
+* | 0    | no error-severity problem (warnings are allowed)                           |
+* | 1    | problems in your code only: type, lint, test or convention errors          |
+* | 2    | this machine: Node version, missing tool, unreachable service, busy port,  |
+* |      | git unavailable, a tool that crashed — the run is incomplete               |
+*
+* 2 wins over 1: when the machine kept a step from running, the run did not
+* check everything, so "only your code is wrong" cannot be claimed.
+*/
+const CHECK_EXIT_CODES = {
+	ok: 0,
+	code: 1,
+	environment: 2
+};
+/** The exit code for a set of problems; see {@link CHECK_EXIT_CODES}. */
+function checkExitCode(problems) {
+	const errors = problems.filter((problem) => problem.severity === "error");
+	if (errors.some((problem) => problem.category === "environment")) return CHECK_EXIT_CODES.environment;
+	return errors.length > 0 ? CHECK_EXIT_CODES.code : CHECK_EXIT_CODES.ok;
+}
+
+//#endregion
+export { CHECK_EXIT_CODES, CHECK_STEPS, checkExitCode };
+//# sourceMappingURL=check-report.types.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"check-report.types.mjs","names":[],"sources":["../../../../../../../../../packages/core/src/tooling/check/check-report.types.ts"],"sourcesContent":["import type { ToolingProblem } from \"../problem\";\n\n/** The steps `warlock check` runs, in order. */\nexport const CHECK_STEPS = [\"environment\", \"typecheck\", \"lint\", \"tests\", \"conventions\"] as const;\n\n/** One step name. */\nexport type CheckStepName = (typeof CHECK_STEPS)[number];\n\n/**\n * - `passed`: ran and found no error.\n * - `failed`: ran and found at least one error-severity problem.\n * - `skipped`: does not apply (no lint config, no tests, nothing changed, `--skip`).\n * - `blocked`: could not run because of this machine; an environment problem says why.\n */\nexport type CheckStepStatus = \"passed\" | \"failed\" | \"skipped\" | \"blocked\";\n\n/** One step of the report. */\nexport type CheckStep = {\n  name: CheckStepName;\n  status: CheckStepStatus;\n  durationMs: number;\n  /** One line on what the step did or why it did not run, or `null`. */\n  detail: string | null;\n};\n\n/**\n * Exit codes of `warlock check` and `warlock typecheck`:\n *\n * | Code | Meaning                                                                    |\n * | ---- | -------------------------------------------------------------------------- |\n * | 0    | no error-severity problem (warnings are allowed)                           |\n * | 1    | problems in your code only: type, lint, test or convention errors          |\n * | 2    | this machine: Node version, missing tool, unreachable service, busy port,  |\n * |      | git unavailable, a tool that crashed — the run is incomplete               |\n *\n * 2 wins over 1: when the machine kept a step from running, the run did not\n * check everything, so \"only your code is wrong\" cannot be claimed.\n */\nexport const CHECK_EXIT_CODES = {\n  ok: 0,\n  code: 1,\n  environment: 2,\n} as const;\n\n/** One of {@link CHECK_EXIT_CODES}. */\nexport type CheckExitCode = (typeof CHECK_EXIT_CODES)[keyof typeof CHECK_EXIT_CODES];\n\n/** The exit code for a set of problems; see {@link CHECK_EXIT_CODES}. */\nexport function checkExitCode(problems: readonly ToolingProblem[]): CheckExitCode {\n  const errors = problems.filter((problem) => problem.severity === \"error\");\n\n  if (errors.some((problem) => problem.category === \"environment\")) {\n    return CHECK_EXIT_CODES.environment;\n  }\n\n  return errors.length > 0 ? CHECK_EXIT_CODES.code : CHECK_EXIT_CODES.ok;\n}\n\n/** What `warlock check --json` prints. */\nexport type CheckReport = {\n  schemaVersion: 1;\n  /** `true` when the exit code is 0. */\n  ok: boolean;\n  exitCode: CheckExitCode;\n  /** Whether the run was limited to changed files. */\n  changed: boolean;\n  /** The changed files the run was limited to (project-relative), or `null` for a full run. */\n  files: string[] | null;\n  steps: CheckStep[];\n  /** One entry per problem, in step order. */\n  problems: ToolingProblem[];\n  summary: {\n    errors: number;\n    warnings: number;\n    /** Error-severity problems in the code. */\n    code: number;\n    /** Error-severity problems with the machine. */\n    environment: number;\n  };\n};\n"],"mappings":";;AAGA,MAAa,cAAc;CAAC;CAAe;CAAa;CAAQ;CAAS;AAAa;;;;;;;;;;;;;;AAmCtF,MAAa,mBAAmB;CAC9B,IAAI;CACJ,MAAM;CACN,aAAa;AACf;;AAMA,SAAgB,cAAc,UAAoD;CAChF,MAAM,SAAS,SAAS,QAAQ,YAAY,QAAQ,aAAa,OAAO;CAExE,IAAI,OAAO,MAAM,YAAY,QAAQ,aAAa,aAAa,GAC7D,OAAO,iBAAiB;CAG1B,OAAO,OAAO,SAAS,IAAI,iBAAiB,OAAO,iBAAiB;AACtE"}

package/esm/tooling/check/code-style-conventions.mjs

@@ -0,0 +1,106 @@
+import { isMemberAccess, keyName, memberName, unwrap } from "./source-ast.mjs";
+import ts from "typescript";
+
+//#region ../../packages/core/src/tooling/check/code-style-conventions.ts
+const AWAITED_LOGGER_NAMES = new Set(["log", "logger"]);
+/** Logger methods that return the logger synchronously since 5.30. */
+const SYNC_LOG_METHODS = new Set([
+	"info",
+	"warn",
+	"error",
+	"debug",
+	"success",
+	"fatal",
+	"log",
+	"assert"
+]);
+function checkAwaitLog(node, findings) {
+	if (!ts.isAwaitExpression(node)) return;
+	const argument = unwrap(node.expression);
+	if (!ts.isCallExpression(argument)) return;
+	const callee = unwrap(argument.expression);
+	if (!isMemberAccess(callee)) return;
+	const owner = unwrap(callee.expression);
+	if (!ts.isIdentifier(owner) || !AWAITED_LOGGER_NAMES.has(owner.text)) return;
+	const method = memberName(callee);
+	if (!method || !SYNC_LOG_METHODS.has(method)) return;
+	findings.push({
+		code: "WL9010",
+		severity: "warning",
+		node,
+		message: `\`${owner.text}.${method}()\` returns the logger synchronously; \`await\` does nothing here. Remove it (use \`await log.flush()\` to wait for delivery).`
+	});
+}
+/** Handler type annotations that mark a constant as a controller. */
+const HANDLER_TYPE_PATTERN = /RequestHandler$/;
+const CONTROLLER_NAME_PATTERN = /Controller$/;
+function hasHandlerType(declaration) {
+	const type = declaration.type;
+	return type !== void 0 && ts.isTypeReferenceNode(type) && ts.isIdentifier(type.typeName) && HANDLER_TYPE_PATTERN.test(type.typeName.text);
+}
+function controllerIdentifiers(statement) {
+	if (ts.isFunctionDeclaration(statement) || ts.isClassDeclaration(statement)) return statement.name && CONTROLLER_NAME_PATTERN.test(statement.name.text) ? [statement.name] : [];
+	if (!ts.isVariableStatement(statement)) return [];
+	const found = [];
+	for (const declaration of statement.declarationList.declarations) {
+		if (!ts.isIdentifier(declaration.name)) continue;
+		if (CONTROLLER_NAME_PATTERN.test(declaration.name.text) || hasHandlerType(declaration)) found.push(declaration.name);
+	}
+	return found;
+}
+function ordinal(position) {
+	if (position === 2) return "2nd";
+	if (position === 3) return "3rd";
+	return `${position}th`;
+}
+function checkOneControllerPerFile(sourceFile, findings) {
+	const controllers = sourceFile.statements.flatMap(controllerIdentifiers);
+	const first = controllers[0];
+	if (!first) return;
+	controllers.slice(1).forEach((identifier, index) => {
+		findings.push({
+			code: "WL9011",
+			severity: "warning",
+			node: identifier,
+			message: `\`${identifier.text}\` is the ${ordinal(index + 2)} controller in this file (after \`${first.text}\`). Move it to its own \`*.controller.ts\` file.`
+		});
+	});
+}
+/** A string/number literal type, or a union made only of them. */
+function isLiteralType(node) {
+	if (!node) return false;
+	if (ts.isLiteralTypeNode(node)) return true;
+	return ts.isUnionTypeNode(node) && node.types.every((member) => ts.isLiteralTypeNode(member));
+}
+function checkKindDiscriminator(node, findings) {
+	if (!ts.isPropertySignature(node) || ts.isComputedPropertyName(node.name)) return;
+	if (keyName(node.name) !== "kind" || !isLiteralType(node.type)) return;
+	findings.push({
+		code: "WL9012",
+		severity: "warning",
+		node: node.name,
+		message: "Name this discriminator `type`, not `kind` (the framework's convention for tagged unions)."
+	});
+}
+/**
+* The code-style conventions in one parsed file, all reported as warnings:
+*
+* - `WL9010` `await` on a synchronous `log.*()` call;
+* - `WL9011` a second (third, …) controller in one file;
+* - `WL9012` a tagged union whose discriminator is `kind` instead of `type`.
+*/
+function codeStyleFindings(sourceFile) {
+	const findings = [];
+	checkOneControllerPerFile(sourceFile, findings);
+	const visit = (node) => {
+		checkAwaitLog(node, findings);
+		checkKindDiscriminator(node, findings);
+		ts.forEachChild(node, visit);
+	};
+	visit(sourceFile);
+	return findings;
+}
+
+//#endregion
+export { codeStyleFindings };
+//# sourceMappingURL=code-style-conventions.mjs.map

package/esm/tooling/check/code-style-conventions.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"code-style-conventions.mjs","names":[],"sources":["../../../../../../../../../packages/core/src/tooling/check/code-style-conventions.ts"],"sourcesContent":["import ts from \"typescript\";\nimport { isMemberAccess, keyName, memberName, type SourceFinding, unwrap } from \"./source-ast\";\n\n// ── WL9010: await on a synchronous log call ─────────────────────────────────\n\nconst AWAITED_LOGGER_NAMES: ReadonlySet<string> = new Set([\"log\", \"logger\"]);\n\n/** Logger methods that return the logger synchronously since 5.30. */\nconst SYNC_LOG_METHODS: ReadonlySet<string> = new Set([\n  \"info\",\n  \"warn\",\n  \"error\",\n  \"debug\",\n  \"success\",\n  \"fatal\",\n  \"log\",\n  \"assert\",\n]);\n\nfunction checkAwaitLog(node: ts.Node, findings: SourceFinding[]): void {\n  if (!ts.isAwaitExpression(node)) return;\n\n  const argument = unwrap(node.expression);\n\n  if (!ts.isCallExpression(argument)) return;\n\n  const callee = unwrap(argument.expression);\n\n  if (!isMemberAccess(callee)) return;\n\n  const owner = unwrap(callee.expression);\n\n  if (!ts.isIdentifier(owner) || !AWAITED_LOGGER_NAMES.has(owner.text)) return;\n\n  const method = memberName(callee);\n\n  if (!method || !SYNC_LOG_METHODS.has(method)) return;\n\n  findings.push({\n    code: \"WL9010\",\n    severity: \"warning\",\n    node,\n    message: `\\`${owner.text}.${method}()\\` returns the logger synchronously; \\`await\\` does nothing here. Remove it (use \\`await log.flush()\\` to wait for delivery).`,\n  });\n}\n\n// ── WL9011: more than one controller in a file ──────────────────────────────\n\n/** Handler type annotations that mark a constant as a controller. */\nconst HANDLER_TYPE_PATTERN = /RequestHandler$/;\n\nconst CONTROLLER_NAME_PATTERN = /Controller$/;\n\nfunction hasHandlerType(declaration: ts.VariableDeclaration): boolean {\n  const type = declaration.type;\n\n  return (\n    type !== undefined &&\n    ts.isTypeReferenceNode(type) &&\n    ts.isIdentifier(type.typeName) &&\n    HANDLER_TYPE_PATTERN.test(type.typeName.text)\n  );\n}\n\nfunction controllerIdentifiers(statement: ts.Statement): ts.Identifier[] {\n  if (ts.isFunctionDeclaration(statement) || ts.isClassDeclaration(statement)) {\n    return statement.name && CONTROLLER_NAME_PATTERN.test(statement.name.text)\n      ? [statement.name]\n      : [];\n  }\n\n  if (!ts.isVariableStatement(statement)) return [];\n\n  const found: ts.Identifier[] = [];\n\n  for (const declaration of statement.declarationList.declarations) {\n    if (!ts.isIdentifier(declaration.name)) continue;\n\n    if (CONTROLLER_NAME_PATTERN.test(declaration.name.text) || hasHandlerType(declaration)) {\n      found.push(declaration.name);\n    }\n  }\n\n  return found;\n}\n\nfunction ordinal(position: number): string {\n  if (position === 2) return \"2nd\";\n  if (position === 3) return \"3rd\";\n\n  return `${position}th`;\n}\n\nfunction checkOneControllerPerFile(sourceFile: ts.SourceFile, findings: SourceFinding[]): void {\n  const controllers = sourceFile.statements.flatMap(controllerIdentifiers);\n  const first = controllers[0];\n\n  if (!first) return;\n\n  controllers.slice(1).forEach((identifier, index) => {\n    findings.push({\n      code: \"WL9011\",\n      severity: \"warning\",\n      node: identifier,\n      message: `\\`${identifier.text}\\` is the ${ordinal(index + 2)} controller in this file (after \\`${first.text}\\`). Move it to its own \\`*.controller.ts\\` file.`,\n    });\n  });\n}\n\n// ── WL9012: a union discriminator named `kind` ──────────────────────────────\n\n/** A string/number literal type, or a union made only of them. */\nfunction isLiteralType(node: ts.TypeNode | undefined): boolean {\n  if (!node) return false;\n  if (ts.isLiteralTypeNode(node)) return true;\n\n  return ts.isUnionTypeNode(node) && node.types.every((member) => ts.isLiteralTypeNode(member));\n}\n\nfunction checkKindDiscriminator(node: ts.Node, findings: SourceFinding[]): void {\n  if (!ts.isPropertySignature(node) || ts.isComputedPropertyName(node.name)) return;\n  if (keyName(node.name) !== \"kind\" || !isLiteralType(node.type)) return;\n\n  findings.push({\n    code: \"WL9012\",\n    severity: \"warning\",\n    node: node.name,\n    message:\n      \"Name this discriminator `type`, not `kind` (the framework's convention for tagged unions).\",\n  });\n}\n\n/**\n * The code-style conventions in one parsed file, all reported as warnings:\n *\n * - `WL9010` `await` on a synchronous `log.*()` call;\n * - `WL9011` a second (third, …) controller in one file;\n * - `WL9012` a tagged union whose discriminator is `kind` instead of `type`.\n */\nexport function codeStyleFindings(sourceFile: ts.SourceFile): SourceFinding[] {\n  const findings: SourceFinding[] = [];\n\n  checkOneControllerPerFile(sourceFile, findings);\n\n  // Every node, type nodes included: discriminators live in type literals and interfaces.\n  const visit = (node: ts.Node): void => {\n    checkAwaitLog(node, findings);\n    checkKindDiscriminator(node, findings);\n    ts.forEachChild(node, visit);\n  };\n\n  visit(sourceFile);\n\n  return findings;\n}\n"],"mappings":"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"}

package/esm/tooling/check/conventions-step.d.mts

@@ -0,0 +1,34 @@
+import { ToolingProblem } from "../problem.mjs";
+
+//#region ../../packages/core/src/tooling/check/conventions-step.d.ts
+/** Matches a project-relative path of a file the framework loads by itself. */
+declare function isAutoLoadedFile(relativePath: string): boolean;
+/**
+ * The convention problems in one source file, in source order:
+ *
+ * - `WL9001` an import of a file the framework loads by itself (`routes.ts`,
+ *   `main.ts`, `worker.ts`, `events/*`) — importing it registers it twice;
+ * - `WL9002` a relative import ending in `.js`;
+ * - `WL9003` a relative import from one `src/app/<module>` into another, which
+ *   should use the `app/<module>/...` alias;
+ * - `WL9005`–`WL9009` the security conventions (see `securityFindings`):
+ *   `request.all()` into a query or service, a mutating route with no guard
+ *   and no `public: true`, a redirect target from request input, sensitive
+ *   values in logs, unbounded regexes on request input;
+ * - `WL9010`–`WL9012` warnings: `await log.*()`, a second controller in one
+ *   file, a `kind` discriminator.
+ *
+ * A `// warlock-check-ignore WL9006` comment on the problem's line or the line
+ * above silences that code there; without codes it silences every one.
+ */
+declare function checkFileConventions(relativePath: string, source: string, cwd: string): ToolingProblem[];
+/** `WL9004` when the project tsconfig turns on legacy decorators. */
+declare function checkTsconfigConventions(cwd: string, project?: string): ToolingProblem[];
+/**
+ * Run every convention check over `files` (project-relative) plus the
+ * project tsconfig.
+ */
+declare function runConventions(cwd: string, files: readonly string[], project?: string): ToolingProblem[];
+//#endregion
+export { checkFileConventions, checkTsconfigConventions, isAutoLoadedFile, runConventions };
+//# sourceMappingURL=conventions-step.d.mts.map

package/esm/tooling/check/conventions-step.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conventions-step.d.mts","names":[],"sources":["../../../../../../../../../packages/core/src/tooling/check/conventions-step.ts"],"mappings":";;;;iBAegB,gBAAA,CAAiB,YAAoB;AAArD;;;;AAAqD;AAwLrD;;;;;;;;;AAIiB;AAmBjB;;;AA/MA,iBAwLgB,oBAAA,CACd,YAAA,UACA,MAAA,UACA,GAAA,WACC,cAAc;;iBAmBD,wBAAA,CAAyB,GAAA,UAAa,OAAA,YAA4B,cAAc;;;AAAA;AAyChG;iBAAgB,cAAA,CACd,GAAA,UACA,KAAA,qBACA,OAAA,YACC,cAAc"}

package/esm/tooling/check/conventions-step.mjs

@@ -0,0 +1,184 @@
+import { createProblem } from "../problem.mjs";
+import { positionOf } from "./source-ast.mjs";
+import { codeStyleFindings } from "./code-style-conventions.mjs";
+import { securityFindings } from "./security-conventions.mjs";
+import path from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+import ts from "typescript";
+
+//#region ../../packages/core/src/tooling/check/conventions-step.ts
+/** Extensions tried when resolving an extension-less import. */
+const RESOLVE_EXTENSIONS = [
+	".ts",
+	".tsx",
+	".js",
+	".jsx",
+	"/index.ts",
+	"/index.tsx"
+];
+/** Test files may import anything on purpose. */
+const TEST_FILE = /\.(?:test|spec)\.[cm]?[jt]sx?$/i;
+/** Matches a project-relative path of a file the framework loads by itself. */
+function isAutoLoadedFile(relativePath) {
+	return /^src\/app\/main\.tsx?$/.test(relativePath) || /^src\/app\/[^/]+\/(?:routes|main|worker)\.tsx?$/.test(relativePath) || /^src\/app\/.+\/events\/[^/]+\.tsx?$/.test(relativePath);
+}
+/** The module folder (`src/app/<module>`) a project-relative path lives in, if any. */
+function moduleOf(relativePath) {
+	return /^src\/app\/([^/]+)\//.exec(relativePath)?.[1];
+}
+function toPosix(file) {
+	return file.split(path.sep).join("/");
+}
+/** Resolve a relative or `app/...` specifier to a project-relative file, if it exists. */
+function resolveSpecifier(specifier, importer, cwd) {
+	let base;
+	if (specifier.startsWith(".")) base = path.resolve(path.dirname(path.join(cwd, importer)), specifier);
+	else if (specifier.startsWith("app/")) base = path.join(cwd, "src", specifier);
+	else return;
+	const candidates = [base, ...RESOLVE_EXTENSIONS.map((extension) => `${base}${extension}`)];
+	const withoutJs = base.replace(/\.jsx?$/, "");
+	if (withoutJs !== base) candidates.push(...RESOLVE_EXTENSIONS.map((extension) => `${withoutJs}${extension}`));
+	const found = candidates.find((candidate) => existsSync(candidate) && path.extname(candidate) !== "");
+	return found ? toPosix(path.relative(cwd, found)) : void 0;
+}
+/** Every module specifier a source file imports, with its position. */
+function importsOf(sourceFile) {
+	const found = [];
+	const visit = (node) => {
+		if ((ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) && node.moduleSpecifier && ts.isStringLiteral(node.moduleSpecifier)) found.push({
+			specifier: node.moduleSpecifier.text,
+			node: node.moduleSpecifier
+		});
+		else if (ts.isCallExpression(node) && node.expression.kind === ts.SyntaxKind.ImportKeyword && node.arguments[0] && ts.isStringLiteral(node.arguments[0])) found.push({
+			specifier: node.arguments[0].text,
+			node: node.arguments[0]
+		});
+		ts.forEachChild(node, visit);
+	};
+	visit(sourceFile);
+	return found;
+}
+/** `// warlock-check-ignore [WLxxxx …]` on a problem's line or the line above it. */
+const IGNORE_COMMENT = /\/[/*]\s*warlock-check-ignore\b(.*)/;
+/** Whether an ignore comment on `line` (1-based) or the line before covers `code`. */
+function isIgnored(lines, line, code) {
+	for (const text of [lines[line - 1], lines[line - 2]]) {
+		const match = text === void 0 ? null : IGNORE_COMMENT.exec(text);
+		if (!match) continue;
+		const codes = match[1]?.match(/WL\d{4}/g);
+		if (!codes || codes.includes(code)) return true;
+	}
+	return false;
+}
+/** The import conventions (`WL9001`–`WL9003`) of one parsed file. */
+function importProblems(sourceFile, relativePath, cwd) {
+	const problems = [];
+	const importerModule = moduleOf(relativePath);
+	for (const { specifier, node } of importsOf(sourceFile)) {
+		const at = {
+			file: relativePath,
+			...positionOf(sourceFile, node)
+		};
+		if (specifier.startsWith(".") && /\.jsx?$/.test(specifier)) problems.push(createProblem({
+			code: "WL9002",
+			source: "convention",
+			message: `Import "${specifier}" ends in a .js extension.`,
+			...at
+		}));
+		const target = resolveSpecifier(specifier, relativePath, cwd);
+		if (!target) continue;
+		if (!TEST_FILE.test(relativePath) && isAutoLoadedFile(target)) problems.push(createProblem({
+			code: "WL9001",
+			source: "convention",
+			message: `"${specifier}" imports ${target}, which the framework loads by itself.`,
+			...at
+		}));
+		const targetModule = moduleOf(target);
+		if (specifier.startsWith(".") && importerModule !== void 0 && targetModule !== void 0 && importerModule !== targetModule) {
+			const alias = `app/${target.replace(/^src\/app\//, "").replace(/\.[cm]?[jt]sx?$/, "")}`;
+			problems.push(createProblem({
+				code: "WL9003",
+				source: "convention",
+				message: `"${specifier}" reaches from module "${importerModule}" into "${targetModule}"; import "${alias}" instead.`,
+				...at
+			}));
+		}
+	}
+	return problems;
+}
+function findingProblem(sourceFile, relativePath, finding) {
+	return createProblem({
+		code: finding.code,
+		source: "convention",
+		severity: finding.severity ?? "error",
+		message: finding.message,
+		file: relativePath,
+		...positionOf(sourceFile, finding.node)
+	});
+}
+/**
+* The convention problems in one source file, in source order:
+*
+* - `WL9001` an import of a file the framework loads by itself (`routes.ts`,
+*   `main.ts`, `worker.ts`, `events/*`) — importing it registers it twice;
+* - `WL9002` a relative import ending in `.js`;
+* - `WL9003` a relative import from one `src/app/<module>` into another, which
+*   should use the `app/<module>/...` alias;
+* - `WL9005`–`WL9009` the security conventions (see `securityFindings`):
+*   `request.all()` into a query or service, a mutating route with no guard
+*   and no `public: true`, a redirect target from request input, sensitive
+*   values in logs, unbounded regexes on request input;
+* - `WL9010`–`WL9012` warnings: `await log.*()`, a second controller in one
+*   file, a `kind` discriminator.
+*
+* A `// warlock-check-ignore WL9006` comment on the problem's line or the line
+* above silences that code there; without codes it silences every one.
+*/
+function checkFileConventions(relativePath, source, cwd) {
+	const sourceFile = ts.createSourceFile(relativePath, source, ts.ScriptTarget.Latest, true);
+	const problems = [...importProblems(sourceFile, relativePath, cwd), ...[...securityFindings(sourceFile), ...codeStyleFindings(sourceFile)].map((finding) => findingProblem(sourceFile, relativePath, finding))];
+	const lines = source.split(/\r?\n/);
+	return problems.filter((problem) => problem.line === null || !isIgnored(lines, problem.line, problem.code)).sort((first, second) => (first.line ?? 0) - (second.line ?? 0) || (first.column ?? 0) - (second.column ?? 0));
+}
+/** `WL9004` when the project tsconfig turns on legacy decorators. */
+function checkTsconfigConventions(cwd, project = "tsconfig.json") {
+	const file = path.join(cwd, project);
+	if (!existsSync(file)) return [];
+	const text = readFileSync(file, "utf8");
+	const read = ts.parseConfigFileTextToJson(file, text);
+	const options = typeof read.config === "object" && read.config !== null ? Reflect.get(read.config, "compilerOptions") : void 0;
+	if (typeof options !== "object" || options === null || Reflect.get(options, "experimentalDecorators") !== true) return [];
+	const index = text.indexOf("experimentalDecorators");
+	const before = index === -1 ? "" : text.slice(0, index);
+	const line = index === -1 ? null : before.split("\n").length;
+	const column = index === -1 ? null : index - before.lastIndexOf("\n");
+	return [createProblem({
+		code: "WL9004",
+		source: "convention",
+		message: "\"experimentalDecorators\": true switches TypeScript to legacy decorators.",
+		file: toPosix(project),
+		line,
+		column
+	})];
+}
+/**
+* Run every convention check over `files` (project-relative) plus the
+* project tsconfig.
+*/
+function runConventions(cwd, files, project) {
+	const problems = checkTsconfigConventions(cwd, project);
+	for (const file of files) {
+		let source;
+		try {
+			source = readFileSync(path.join(cwd, file), "utf8");
+		} catch {
+			continue;
+		}
+		problems.push(...checkFileConventions(file, source, cwd));
+	}
+	return problems;
+}
+
+//#endregion
+export { checkFileConventions, checkTsconfigConventions, isAutoLoadedFile, runConventions };
+//# sourceMappingURL=conventions-step.mjs.map

package/esm/tooling/check/conventions-step.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"conventions-step.mjs","names":[],"sources":["../../../../../../../../../packages/core/src/tooling/check/conventions-step.ts"],"sourcesContent":["import { existsSync, readFileSync } from \"node:fs\";\nimport path from \"node:path\";\nimport ts from \"typescript\";\nimport { createProblem, type ToolingProblem } from \"../problem\";\nimport { codeStyleFindings } from \"./code-style-conventions\";\nimport { securityFindings } from \"./security-conventions\";\nimport { positionOf, type SourceFinding } from \"./source-ast\";\n\n/** Extensions tried when resolving an extension-less import. */\nconst RESOLVE_EXTENSIONS = [\".ts\", \".tsx\", \".js\", \".jsx\", \"/index.ts\", \"/index.tsx\"];\n\n/** Test files may import anything on purpose. */\nconst TEST_FILE = /\\.(?:test|spec)\\.[cm]?[jt]sx?$/i;\n\n/** Matches a project-relative path of a file the framework loads by itself. */\nexport function isAutoLoadedFile(relativePath: string): boolean {\n  return (\n    /^src\\/app\\/main\\.tsx?$/.test(relativePath) ||\n    /^src\\/app\\/[^/]+\\/(?:routes|main|worker)\\.tsx?$/.test(relativePath) ||\n    /^src\\/app\\/.+\\/events\\/[^/]+\\.tsx?$/.test(relativePath)\n  );\n}\n\n/** The module folder (`src/app/<module>`) a project-relative path lives in, if any. */\nfunction moduleOf(relativePath: string): string | undefined {\n  return /^src\\/app\\/([^/]+)\\//.exec(relativePath)?.[1];\n}\n\nfunction toPosix(file: string): string {\n  return file.split(path.sep).join(\"/\");\n}\n\n/** Resolve a relative or `app/...` specifier to a project-relative file, if it exists. */\nfunction resolveSpecifier(specifier: string, importer: string, cwd: string): string | undefined {\n  let base: string;\n\n  if (specifier.startsWith(\".\")) {\n    base = path.resolve(path.dirname(path.join(cwd, importer)), specifier);\n  } else if (specifier.startsWith(\"app/\")) {\n    base = path.join(cwd, \"src\", specifier);\n  } else {\n    return undefined;\n  }\n\n  const candidates = [base, ...RESOLVE_EXTENSIONS.map((extension) => `${base}${extension}`)];\n  const withoutJs = base.replace(/\\.jsx?$/, \"\");\n\n  if (withoutJs !== base) {\n    candidates.push(...RESOLVE_EXTENSIONS.map((extension) => `${withoutJs}${extension}`));\n  }\n\n  const found = candidates.find(\n    (candidate) => existsSync(candidate) && path.extname(candidate) !== \"\",\n  );\n\n  return found ? toPosix(path.relative(cwd, found)) : undefined;\n}\n\n/** Every module specifier a source file imports, with its position. */\nfunction importsOf(sourceFile: ts.SourceFile): { specifier: string; node: ts.Node }[] {\n  const found: { specifier: string; node: ts.Node }[] = [];\n\n  const visit = (node: ts.Node) => {\n    if (\n      (ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) &&\n      node.moduleSpecifier &&\n      ts.isStringLiteral(node.moduleSpecifier)\n    ) {\n      found.push({ specifier: node.moduleSpecifier.text, node: node.moduleSpecifier });\n    } else if (\n      ts.isCallExpression(node) &&\n      node.expression.kind === ts.SyntaxKind.ImportKeyword &&\n      node.arguments[0] &&\n      ts.isStringLiteral(node.arguments[0])\n    ) {\n      found.push({ specifier: node.arguments[0].text, node: node.arguments[0] });\n    }\n\n    ts.forEachChild(node, visit);\n  };\n\n  visit(sourceFile);\n\n  return found;\n}\n\n/** `// warlock-check-ignore [WLxxxx …]` on a problem's line or the line above it. */\nconst IGNORE_COMMENT = /\\/[/*]\\s*warlock-check-ignore\\b(.*)/;\n\n/** Whether an ignore comment on `line` (1-based) or the line before covers `code`. */\nfunction isIgnored(lines: readonly string[], line: number, code: string): boolean {\n  for (const text of [lines[line - 1], lines[line - 2]]) {\n    const match = text === undefined ? null : IGNORE_COMMENT.exec(text);\n\n    if (!match) continue;\n\n    const codes = match[1]?.match(/WL\\d{4}/g);\n\n    if (!codes || codes.includes(code)) return true;\n  }\n\n  return false;\n}\n\n/** The import conventions (`WL9001`–`WL9003`) of one parsed file. */\nfunction importProblems(\n  sourceFile: ts.SourceFile,\n  relativePath: string,\n  cwd: string,\n): ToolingProblem[] {\n  const problems: ToolingProblem[] = [];\n  const importerModule = moduleOf(relativePath);\n\n  for (const { specifier, node } of importsOf(sourceFile)) {\n    const at = { file: relativePath, ...positionOf(sourceFile, node) };\n\n    if (specifier.startsWith(\".\") && /\\.jsx?$/.test(specifier)) {\n      problems.push(\n        createProblem({\n          code: \"WL9002\",\n          source: \"convention\",\n          message: `Import \"${specifier}\" ends in a .js extension.`,\n          ...at,\n        }),\n      );\n    }\n\n    const target = resolveSpecifier(specifier, relativePath, cwd);\n\n    if (!target) continue;\n\n    if (!TEST_FILE.test(relativePath) && isAutoLoadedFile(target)) {\n      problems.push(\n        createProblem({\n          code: \"WL9001\",\n          source: \"convention\",\n          message: `\"${specifier}\" imports ${target}, which the framework loads by itself.`,\n          ...at,\n        }),\n      );\n    }\n\n    const targetModule = moduleOf(target);\n\n    if (\n      specifier.startsWith(\".\") &&\n      importerModule !== undefined &&\n      targetModule !== undefined &&\n      importerModule !== targetModule\n    ) {\n      const alias = `app/${target.replace(/^src\\/app\\//, \"\").replace(/\\.[cm]?[jt]sx?$/, \"\")}`;\n\n      problems.push(\n        createProblem({\n          code: \"WL9003\",\n          source: \"convention\",\n          message: `\"${specifier}\" reaches from module \"${importerModule}\" into \"${targetModule}\"; import \"${alias}\" instead.`,\n          ...at,\n        }),\n      );\n    }\n  }\n\n  return problems;\n}\n\nfunction findingProblem(\n  sourceFile: ts.SourceFile,\n  relativePath: string,\n  finding: SourceFinding,\n): ToolingProblem {\n  return createProblem({\n    code: finding.code,\n    source: \"convention\",\n    severity: finding.severity ?? \"error\",\n    message: finding.message,\n    file: relativePath,\n    ...positionOf(sourceFile, finding.node),\n  });\n}\n\n/**\n * The convention problems in one source file, in source order:\n *\n * - `WL9001` an import of a file the framework loads by itself (`routes.ts`,\n *   `main.ts`, `worker.ts`, `events/*`) — importing it registers it twice;\n * - `WL9002` a relative import ending in `.js`;\n * - `WL9003` a relative import from one `src/app/<module>` into another, which\n *   should use the `app/<module>/...` alias;\n * - `WL9005`–`WL9009` the security conventions (see `securityFindings`):\n *   `request.all()` into a query or service, a mutating route with no guard\n *   and no `public: true`, a redirect target from request input, sensitive\n *   values in logs, unbounded regexes on request input;\n * - `WL9010`–`WL9012` warnings: `await log.*()`, a second controller in one\n *   file, a `kind` discriminator.\n *\n * A `// warlock-check-ignore WL9006` comment on the problem's line or the line\n * above silences that code there; without codes it silences every one.\n */\nexport function checkFileConventions(\n  relativePath: string,\n  source: string,\n  cwd: string,\n): ToolingProblem[] {\n  const sourceFile = ts.createSourceFile(relativePath, source, ts.ScriptTarget.Latest, true);\n  const problems = [\n    ...importProblems(sourceFile, relativePath, cwd),\n    ...[...securityFindings(sourceFile), ...codeStyleFindings(sourceFile)].map((finding) =>\n      findingProblem(sourceFile, relativePath, finding),\n    ),\n  ];\n  const lines = source.split(/\\r?\\n/);\n\n  return problems\n    .filter((problem) => problem.line === null || !isIgnored(lines, problem.line, problem.code))\n    .sort(\n      (first, second) =>\n        (first.line ?? 0) - (second.line ?? 0) || (first.column ?? 0) - (second.column ?? 0),\n    );\n}\n\n/** `WL9004` when the project tsconfig turns on legacy decorators. */\nexport function checkTsconfigConventions(cwd: string, project = \"tsconfig.json\"): ToolingProblem[] {\n  const file = path.join(cwd, project);\n\n  if (!existsSync(file)) return [];\n\n  const text = readFileSync(file, \"utf8\");\n  const read = ts.parseConfigFileTextToJson(file, text);\n  const options: unknown =\n    typeof read.config === \"object\" && read.config !== null\n      ? Reflect.get(read.config, \"compilerOptions\")\n      : undefined;\n\n  if (\n    typeof options !== \"object\" ||\n    options === null ||\n    Reflect.get(options, \"experimentalDecorators\") !== true\n  ) {\n    return [];\n  }\n\n  const index = text.indexOf(\"experimentalDecorators\");\n  const before = index === -1 ? \"\" : text.slice(0, index);\n  const line = index === -1 ? null : before.split(\"\\n\").length;\n  const column = index === -1 ? null : index - before.lastIndexOf(\"\\n\");\n\n  return [\n    createProblem({\n      code: \"WL9004\",\n      source: \"convention\",\n      message: '\"experimentalDecorators\": true switches TypeScript to legacy decorators.',\n      file: toPosix(project),\n      line,\n      column,\n    }),\n  ];\n}\n\n/**\n * Run every convention check over `files` (project-relative) plus the\n * project tsconfig.\n */\nexport function runConventions(\n  cwd: string,\n  files: readonly string[],\n  project?: string,\n): ToolingProblem[] {\n  const problems = checkTsconfigConventions(cwd, project);\n\n  for (const file of files) {\n    let source: string;\n\n    try {\n      source = readFileSync(path.join(cwd, file), \"utf8\");\n    } catch {\n      continue;\n    }\n\n    problems.push(...checkFileConventions(file, source, cwd));\n  }\n\n  return problems;\n}\n"],"mappings":"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"}

package/esm/tooling/check/environment-step.d.mts

@@ -0,0 +1,18 @@
+import { ToolingProblem } from "../problem.mjs";
+
+//#region ../../packages/core/src/tooling/check/environment-step.d.ts
+/**
+ * The oldest Node.js release core supports — `engines.node` in core's
+ * package.json (`>=22.15`). `bin/warlock.js` refuses older versions before
+ * the CLI loads; this check covers programmatic `runCheck()` calls too.
+ */
+declare const MIN_NODE_VERSION = "22.15.0";
+/**
+ * Check the running Node.js against core's minimum and the app's own
+ * `engines.node` (when it is a plain `>=` range). A mismatch is a `WL8001`
+ * environment problem.
+ */
+declare function checkNodeVersion(cwd: string, running?: string): ToolingProblem[];
+//#endregion
+export { MIN_NODE_VERSION, checkNodeVersion };
+//# sourceMappingURL=environment-step.d.mts.map

package/esm/tooling/check/environment-step.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"environment-step.d.mts","names":[],"sources":["../../../../../../../../../packages/core/src/tooling/check/environment-step.ts"],"mappings":";;;;;AASA;;;cAAa,gBAAA;;;;AAoDiF;;iBAA9E,gBAAA,CAAiB,GAAA,UAAa,OAAA,YAAkC,cAAc"}