@warlock.js/core 5.34.3 → 5.36.0

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

@@ -1 +1 @@
-{"version":3,"file":"run-check.mjs","names":[],"sources":["../../../../../../../../../packages/core/src/tooling/check/run-check.ts"],"sourcesContent":["import path from \"node:path\";\nimport { createProblem, type ToolingProblem } from \"../problem\";\nimport {\n  runTypecheck,\n  type TypecheckOptions,\n  type TypecheckResult,\n} from \"../typecheck/run-typecheck\";\nimport { type GitRunner, listChangedFiles } from \"./changed-files\";\nimport {\n  CHECK_STEPS,\n  type CheckReport,\n  type CheckStep,\n  type CheckStepName,\n  type CheckStepStatus,\n  checkExitCode,\n} from \"./check-report.types\";\nimport { runConventions } from \"./conventions-step\";\nimport { checkNodeVersion } from \"./environment-step\";\nimport { runLint } from \"./lint-step\";\nimport { listSourceFiles, listTestFiles } from \"./source-files\";\nimport {\n  findVitest,\n  parseVitestReport,\n  runVitest,\n  type VitestRunner,\n  vitestArguments,\n  vitestRunFailure,\n} from \"./tests-step\";\n\n/** Runs the typecheck step. The CLI swaps in a child process so a heap overflow cannot end `check`. */\nexport type TypecheckRunner = (\n  options: TypecheckOptions,\n) => Promise<TypecheckResult> | TypecheckResult;\n\n/** Inputs of {@link runCheck}. */\nexport type CheckOptions = {\n  /** Project root. Default: `process.cwd()`. */\n  cwd?: string;\n  /** Oxlint is the only supported linter. */\n  lint?: \"oxlint\";\n  /** Limit every step to the files changed against `base` (default HEAD) plus untracked files. */\n  changed?: boolean;\n  /** Compare with `git merge-base <base> HEAD` instead of HEAD. Implies `changed`. */\n  base?: string;\n  /** Steps not to run. */\n  skip?: readonly CheckStepName[];\n  /** tsconfig path, relative to `cwd`. Default: `tsconfig.json`. */\n  project?: string;\n  /** How git is run. */\n  git?: GitRunner;\n  /** How the typecheck runs. Default: in this process. */\n  typecheck?: TypecheckRunner;\n  /** How vitest runs. */\n  vitest?: VitestRunner;\n  /** Where the app's vitest CLI is. Default: resolved from the app root. */\n  vitestBinary?: string | null;\n  /** The Node.js version to check. Default: the running one. */\n  nodeVersion?: string;\n};\n\nfunction errorMessage(error: unknown): string {\n  return error instanceof Error ? error.message : String(error);\n}\n\nfunction statusOf(problems: readonly ToolingProblem[]): CheckStepStatus {\n  const errors = problems.filter((problem) => problem.severity === \"error\");\n\n  if (errors.some((problem) => problem.category === \"environment\")) return \"blocked\";\n\n  return errors.length > 0 ? \"failed\" : \"passed\";\n}\n\n/** Bundles one step's timing, status and problems. */\ntype StepOutcome = { status?: CheckStepStatus; detail: string | null; problems: ToolingProblem[] };\n\n/**\n * The single verify command: typecheck, lint, the tests affected by the\n * change, and the framework's convention checks, as one report with one entry\n * per problem and an exit code that tells \"your code\" (1) from \"this machine\"\n * (2).\n *\n * Every step runs even when an earlier one failed, so one run lists every\n * problem. The only exception: with `changed`, a git failure leaves no file\n * list, and every step after `environment` is `blocked`.\n */\nexport async function runCheck(options: CheckOptions = {}): Promise<CheckReport> {\n  const selection: unknown = options.lint;\n  if (selection !== undefined && selection !== \"oxlint\")\n    throw new Error(\n      \"ESLint support was removed in 5.34.0. Oxlint/Oxfmt is the default; run npx warlock upgrade --from 5.33 --to 5.34.0.\",\n    );\n  const cwd = path.resolve(options.cwd ?? process.cwd());\n  const changed = options.changed === true || options.base !== undefined;\n  const skip = new Set(options.skip ?? []);\n  const steps: CheckStep[] = [];\n  const problems: ToolingProblem[] = [];\n  let files: string[] | null = null;\n  let filesBlocked = false;\n\n  const run = async (name: CheckStepName, body: () => Promise<StepOutcome> | StepOutcome) => {\n    const startedAt = Date.now();\n\n    if (skip.has(name)) {\n      steps.push({ name, status: \"skipped\", durationMs: 0, detail: \"skipped with --skip\" });\n      return;\n    }\n\n    if (filesBlocked && name !== \"environment\") {\n      steps.push({\n        name,\n        status: \"blocked\",\n        durationMs: 0,\n        detail: \"the changed files could not be listed\",\n      });\n      return;\n    }\n\n    let outcome: StepOutcome;\n\n    try {\n      outcome = await body();\n    } catch (error) {\n      outcome = {\n        detail: null,\n        problems: [\n          createProblem({\n            code: \"WL8007\",\n            source: \"environment\",\n            message: `The ${name} step crashed: ${errorMessage(error)}`,\n          }),\n        ],\n      };\n    }\n\n    problems.push(...outcome.problems);\n    steps.push({\n      name,\n      status: outcome.status ?? statusOf(outcome.problems),\n      durationMs: Date.now() - startedAt,\n      detail: outcome.detail,\n    });\n  };\n\n  await run(\"environment\", async () => {\n    const found = checkNodeVersion(cwd, options.nodeVersion);\n\n    if (changed) {\n      const listed = await listChangedFiles({ cwd, base: options.base, git: options.git });\n\n      if (\"problem\" in listed) {\n        filesBlocked = true;\n        found.push(listed.problem);\n      } else {\n        files = listed.files;\n      }\n    }\n\n    return {\n      detail: `Node ${options.nodeVersion ?? process.versions.node}${files ? `, ${files.length} changed file(s)` : \"\"}`,\n      problems: found,\n    };\n  });\n\n  const targets = async (): Promise<string[]> => files ?? (await listSourceFiles(cwd));\n\n  await run(\"typecheck\", async () => {\n    if (files !== null && files.length === 0) {\n      return { status: \"skipped\", detail: \"no changed files\", problems: [] };\n    }\n\n    const typecheck = options.typecheck ?? runTypecheck;\n    const result = await typecheck({\n      cwd,\n      project: options.project,\n      ...(files !== null ? { files } : {}),\n    });\n\n    return {\n      detail: `${result.checkedFiles} file(s) checked in ${result.durationMs}ms`,\n      problems: result.problems,\n    };\n  });\n\n  await run(\"lint\", async () => {\n    const lintFiles = await targets();\n\n    if (lintFiles.length === 0) {\n      return { status: \"skipped\", detail: \"no files to lint\", problems: [] };\n    }\n\n    const { linters, problems: found } = await runLint(cwd, lintFiles);\n\n    if (linters.length === 0) {\n      return {\n        status: \"skipped\",\n        detail: \"no Oxlint config\",\n        problems: [],\n      };\n    }\n\n    return { detail: `${linters.join(\" + \")} over ${lintFiles.length} file(s)`, problems: found };\n  });\n\n  await run(\"tests\", async () => {\n    if (files !== null && files.length === 0) {\n      return { status: \"skipped\", detail: \"no changed files\", problems: [] };\n    }\n\n    const binary = options.vitestBinary === undefined ? findVitest(cwd) : options.vitestBinary;\n\n    if (!binary) {\n      if ((await listTestFiles(cwd)).length === 0) {\n        return { status: \"skipped\", detail: \"no test files\", problems: [] };\n      }\n\n      return {\n        detail: null,\n        problems: [\n          createProblem({\n            code: \"WL8002\",\n            source: \"environment\",\n            message: \"The project has test files but vitest is not installed in the app.\",\n          }),\n        ],\n      };\n    }\n\n    const vitest = options.vitest ?? runVitest;\n    const outcome = await vitest(binary, vitestArguments(files), cwd);\n    const found =\n      outcome.report === undefined\n        ? vitestRunFailure(outcome)\n        : parseVitestReport(outcome.report, cwd);\n    const total =\n      typeof outcome.report === \"object\" && outcome.report !== null\n        ? Reflect.get(outcome.report, \"numTotalTests\")\n        : undefined;\n\n    return {\n      detail: typeof total === \"number\" ? `${total} test(s) ran` : null,\n      problems: found,\n    };\n  });\n\n  await run(\"conventions\", async () => {\n    const conventionFiles = await targets();\n\n    return {\n      detail: `${conventionFiles.length} file(s) checked`,\n      problems: runConventions(cwd, conventionFiles, options.project),\n    };\n  });\n\n  // Keep the declared order even if a future step is added out of sequence.\n  steps.sort((first, second) => CHECK_STEPS.indexOf(first.name) - CHECK_STEPS.indexOf(second.name));\n\n  const exitCode = checkExitCode(problems);\n  const errors = problems.filter((problem) => problem.severity === \"error\");\n\n  return {\n    schemaVersion: 1,\n    ok: exitCode === 0,\n    exitCode,\n    changed,\n    files,\n    steps,\n    problems,\n    summary: {\n      errors: errors.length,\n      warnings: problems.length - errors.length,\n      code: errors.filter((problem) => problem.category === \"code\").length,\n      environment: errors.filter((problem) => problem.category === \"environment\").length,\n    },\n  };\n}\n"],"mappings":"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"}
+{"version":3,"file":"run-check.mjs","names":[],"sources":["../../../../../../../../../packages/core/src/tooling/check/run-check.ts"],"sourcesContent":["import { affectedFiles } from \"./affected-files\";\nimport { applyConventionFixes } from \"./fixes\";\nimport path from \"node:path\";\nimport { createProblem, type ToolingProblem } from \"../problem\";\nimport {\n  runTypecheck,\n  type TypecheckOptions,\n  type TypecheckResult,\n} from \"../typecheck/run-typecheck\";\nimport { type GitRunner, listChangedFiles } from \"./changed-files\";\nimport {\n  CHECK_STEPS,\n  type CheckReport,\n  type CheckStep,\n  type CheckStepName,\n  type CheckStepStatus,\n  checkExitCode,\n} from \"./check-report.types\";\nimport { runConventions } from \"./conventions-step\";\nimport { collectApiRouteFacts } from \"./api-route-references\";\nimport { checkNodeVersion } from \"./environment-step\";\nimport { runLint } from \"./lint-step\";\nimport { listSourceFiles, listTestFiles } from \"./source-files\";\nimport {\n  findVitest,\n  parseVitestReport,\n  runVitest,\n  type VitestRunner,\n  vitestArguments,\n  vitestRunFailure,\n} from \"./tests-step\";\n\n/** Runs the typecheck step. The CLI swaps in a child process so a heap overflow cannot end `check`. */\nexport type TypecheckRunner = (\n  options: TypecheckOptions,\n) => Promise<TypecheckResult> | TypecheckResult;\n\n/** Inputs of {@link runCheck}. */\nexport type CheckOptions = {\n  /** Project root. Default: `process.cwd()`. */\n  cwd?: string;\n  /** Oxlint is the only supported linter. */\n  lint?: \"oxlint\";\n  /** Limit every step to the files changed against `base` (default HEAD) plus untracked files. */\n  changed?: boolean;\n  /** Apply safe convention fixes before checking. */\n  fix?: boolean;\n  /** Compare with `git merge-base <base> HEAD` instead of HEAD. Implies `changed`. */\n  base?: string;\n  /** Steps not to run. */\n  skip?: readonly CheckStepName[];\n  /** tsconfig path, relative to `cwd`. Default: `tsconfig.json`. */\n  project?: string;\n  /** How git is run. */\n  git?: GitRunner;\n  /** How the typecheck runs. Default: in this process. */\n  typecheck?: TypecheckRunner;\n  /** How vitest runs. */\n  vitest?: VitestRunner;\n  /** Where the app's vitest CLI is. Default: resolved from the app root. */\n  vitestBinary?: string | null;\n  /** The Node.js version to check. Default: the running one. */\n  nodeVersion?: string;\n};\n\nfunction errorMessage(error: unknown): string {\n  return error instanceof Error ? error.message : String(error);\n}\n\nfunction statusOf(problems: readonly ToolingProblem[]): CheckStepStatus {\n  const errors = problems.filter((problem) => problem.severity === \"error\");\n\n  if (errors.some((problem) => problem.category === \"environment\")) return \"blocked\";\n\n  return errors.length > 0 ? \"failed\" : \"passed\";\n}\n\n/** Bundles one step's timing, status and problems. */\ntype StepOutcome = { status?: CheckStepStatus; detail: string | null; problems: ToolingProblem[] };\n\n/**\n * The single verify command: typecheck, lint, the tests affected by the\n * change, and the framework's convention checks, as one report with one entry\n * per problem and an exit code that tells \"your code\" (1) from \"this machine\"\n * (2).\n *\n * Every step runs even when an earlier one failed, so one run lists every\n * problem. The only exception: with `changed`, a git failure leaves no file\n * list, and every step after `environment` is `blocked`.\n */\nexport async function runCheck(options: CheckOptions = {}): Promise<CheckReport> {\n  const selection: unknown = options.lint;\n  if (selection !== undefined && selection !== \"oxlint\")\n    throw new Error(\n      \"ESLint support was removed in 5.34.0. Oxlint/Oxfmt is the default; run npx warlock upgrade --from 5.33 --to 5.34.0.\",\n    );\n  const cwd = path.resolve(options.cwd ?? process.cwd());\n  const changed = options.changed === true || options.base !== undefined;\n  const skip = new Set(options.skip ?? []);\n  const steps: CheckStep[] = [];\n  const problems: ToolingProblem[] = [];\n  let files: string[] | null = null;\n  let filesBlocked = false;\n\n  const run = async (name: CheckStepName, body: () => Promise<StepOutcome> | StepOutcome) => {\n    const startedAt = Date.now();\n\n    if (skip.has(name)) {\n      steps.push({ name, status: \"skipped\", durationMs: 0, detail: \"skipped with --skip\" });\n      return;\n    }\n\n    if (filesBlocked && name !== \"environment\") {\n      steps.push({\n        name,\n        status: \"blocked\",\n        durationMs: 0,\n        detail: \"the changed files could not be listed\",\n      });\n      return;\n    }\n\n    let outcome: StepOutcome;\n\n    try {\n      outcome = await body();\n    } catch (error) {\n      outcome = {\n        detail: null,\n        problems: [\n          createProblem({\n            code: \"WL8007\",\n            source: \"environment\",\n            message: `The ${name} step crashed: ${errorMessage(error)}`,\n          }),\n        ],\n      };\n    }\n\n    problems.push(...outcome.problems);\n    steps.push({\n      name,\n      status: outcome.status ?? statusOf(outcome.problems),\n      durationMs: Date.now() - startedAt,\n      detail: outcome.detail,\n    });\n  };\n\n  await run(\"environment\", async () => {\n    const found = checkNodeVersion(cwd, options.nodeVersion);\n\n    if (changed) {\n      const listed = await listChangedFiles({\n        cwd,\n        base: options.base,\n        git: options.git,\n        includeDeleted: true,\n      });\n\n      if (\"problem\" in listed) {\n        filesBlocked = true;\n        found.push(listed.problem);\n      } else {\n        filesBlocked = true;\n        files = await affectedFiles(cwd, listed.files, options.project);\n        filesBlocked = false;\n      }\n    }\n\n    return {\n      detail: `Node ${options.nodeVersion ?? process.versions.node}${files ? `, ${files.length} changed file(s)` : \"\"}`,\n      problems: found,\n    };\n  });\n\n  const targets = async (): Promise<string[]> => files ?? (await listSourceFiles(cwd));\n\n  if (options.fix && !filesBlocked && !skip.has(\"conventions\")) {\n    try {\n      const fixTargets = await targets();\n      applyConventionFixes(\n        cwd,\n        runConventions(\n          cwd,\n          fixTargets,\n          options.project,\n          collectApiRouteFacts(cwd, await listSourceFiles(cwd)),\n        ),\n      );\n    } catch (error) {\n      problems.push(\n        createProblem({\n          code: \"WL8007\",\n          source: \"environment\",\n          message: `Could not apply fixes: ${errorMessage(error)}`,\n        }),\n      );\n    }\n  }\n\n  await run(\"typecheck\", async () => {\n    if (files !== null && files.length === 0) {\n      return { status: \"skipped\", detail: \"no changed files\", problems: [] };\n    }\n\n    const typecheck = options.typecheck ?? runTypecheck;\n    const result = await typecheck({\n      cwd,\n      project: options.project,\n      ...(files !== null ? { files } : {}),\n    });\n\n    return {\n      detail: `${result.checkedFiles} file(s) checked in ${result.durationMs}ms`,\n      problems: result.problems,\n    };\n  });\n\n  await run(\"lint\", async () => {\n    const lintFiles = await targets();\n\n    if (lintFiles.length === 0) {\n      return { status: \"skipped\", detail: \"no files to lint\", problems: [] };\n    }\n\n    const { linters, problems: found } = await runLint(cwd, lintFiles);\n\n    if (linters.length === 0) {\n      return {\n        status: \"skipped\",\n        detail: \"no Oxlint config\",\n        problems: [],\n      };\n    }\n\n    return { detail: `${linters.join(\" + \")} over ${lintFiles.length} file(s)`, problems: found };\n  });\n\n  await run(\"tests\", async () => {\n    if (files !== null && files.length === 0) {\n      return { status: \"skipped\", detail: \"no changed files\", problems: [] };\n    }\n\n    const binary = options.vitestBinary === undefined ? findVitest(cwd) : options.vitestBinary;\n\n    if (!binary) {\n      if ((await listTestFiles(cwd)).length === 0) {\n        return { status: \"skipped\", detail: \"no test files\", problems: [] };\n      }\n\n      return {\n        detail: null,\n        problems: [\n          createProblem({\n            code: \"WL8002\",\n            source: \"environment\",\n            message: \"The project has test files but vitest is not installed in the app.\",\n          }),\n        ],\n      };\n    }\n\n    const vitest = options.vitest ?? runVitest;\n    const outcome = await vitest(binary, vitestArguments(files), cwd);\n    const found =\n      outcome.report === undefined\n        ? vitestRunFailure(outcome)\n        : parseVitestReport(outcome.report, cwd);\n    const total =\n      typeof outcome.report === \"object\" && outcome.report !== null\n        ? Reflect.get(outcome.report, \"numTotalTests\")\n        : undefined;\n\n    return {\n      detail: typeof total === \"number\" ? `${total} test(s) ran` : null,\n      problems: found,\n    };\n  });\n\n  await run(\"conventions\", async () => {\n    const conventionFiles = await targets();\n\n    return {\n      detail: `${conventionFiles.length} file(s) checked`,\n      // Facts come from the whole project even when only changed files are checked:\n      // a route registered in one file may be referenced from another.\n      problems: runConventions(\n        cwd,\n        conventionFiles,\n        options.project,\n        collectApiRouteFacts(cwd, await listSourceFiles(cwd)),\n      ),\n    };\n  });\n\n  // Keep the declared order even if a future step is added out of sequence.\n  steps.sort((first, second) => CHECK_STEPS.indexOf(first.name) - CHECK_STEPS.indexOf(second.name));\n\n  const exitCode = checkExitCode(problems);\n  const errors = problems.filter((problem) => problem.severity === \"error\");\n\n  return {\n    schemaVersion: 1,\n    ok: exitCode === 0,\n    exitCode,\n    changed,\n    files,\n    steps,\n    problems,\n    summary: {\n      errors: errors.length,\n      warnings: problems.length - errors.length,\n      code: errors.filter((problem) => problem.category === \"code\").length,\n      environment: errors.filter((problem) => problem.category === \"environment\").length,\n    },\n  };\n}\n"],"mappings":"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"}

package/esm/tooling/check/run-tests.mjs

@@ -1,7 +1,7 @@
 import { checkExitCode } from "./check-report.types.mjs";
 import { createProblem } from "../problem.mjs";
-import { listChangedFiles } from "./changed-files.mjs";
 import { listTestFiles } from "./source-files.mjs";
+import { listChangedFiles } from "./changed-files.mjs";
 import { findVitest, parseVitestReport, runVitest, vitestArguments, vitestRunFailure } from "./tests-step.mjs";
 import path from "node:path";
 

package/esm/tooling/check/source-ast.d.mts

@@ -0,0 +1 @@
+import "../syntax/ast.mjs";

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

@@ -0,0 +1,32 @@
+import { scanTranslationSource } from "../../localization/translation-usage.mjs";
+import { createProblem } from "../problem.mjs";
+
+//#region ../../packages/core/src/tooling/check/translation-conventions.ts
+/** Application code that renders on the client: everything under `src/web` except setup and test files. */
+const WEB_CLIENT_FILE = /^src\/web\/.+\.[cm]?[jt]sx?$/;
+const SETUP_OR_TEST_FILE = /\.(?:setup|test|spec)\.[cm]?[jt]sx?$/i;
+/**
+* `WL9104`: a translation lookup whose key is only known at runtime.
+*
+* A page ships the translation keys its client code can reach, found by
+* reading the code. A key computed at runtime (`trans(key)`, a translator
+* passed on as a value) defeats that reading, so the page falls back to every
+* group. The fix is a `config.translations` declaration in the page's setup
+* file, which this rule points at.
+*/
+function translationProblems(relativePath, source) {
+	if (!WEB_CLIENT_FILE.test(relativePath) || SETUP_OR_TEST_FILE.test(relativePath)) return [];
+	return scanTranslationSource(relativePath, source).usage.dynamicSites.map((site) => createProblem({
+		code: "WL9104",
+		source: "convention",
+		severity: "warning",
+		message: `Translation key \`${site.text}\` is computed at runtime, so a page that renders it ships every translation group. Declare the keys it uses with \`config.translations\` in the page's setup file.`,
+		file: relativePath,
+		line: site.line,
+		column: site.column
+	}));
+}
+
+//#endregion
+export { translationProblems };
+//# sourceMappingURL=translation-conventions.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"translation-conventions.mjs","names":[],"sources":["../../../../../../../../../packages/core/src/tooling/check/translation-conventions.ts"],"sourcesContent":["import { scanTranslationSource } from \"../../localization/translation-usage\";\nimport { createProblem, type ToolingProblem } from \"../problem\";\n\n/** Application code that renders on the client: everything under `src/web` except setup and test files. */\nconst WEB_CLIENT_FILE = /^src\\/web\\/.+\\.[cm]?[jt]sx?$/;\nconst SETUP_OR_TEST_FILE = /\\.(?:setup|test|spec)\\.[cm]?[jt]sx?$/i;\n\n/**\n * `WL9104`: a translation lookup whose key is only known at runtime.\n *\n * A page ships the translation keys its client code can reach, found by\n * reading the code. A key computed at runtime (`trans(key)`, a translator\n * passed on as a value) defeats that reading, so the page falls back to every\n * group. The fix is a `config.translations` declaration in the page's setup\n * file, which this rule points at.\n */\nexport function translationProblems(relativePath: string, source: string): ToolingProblem[] {\n  if (!WEB_CLIENT_FILE.test(relativePath) || SETUP_OR_TEST_FILE.test(relativePath)) return [];\n\n  return scanTranslationSource(relativePath, source).usage.dynamicSites.map((site) =>\n    createProblem({\n      code: \"WL9104\",\n      source: \"convention\",\n      severity: \"warning\",\n      message:\n        `Translation key \\`${site.text}\\` is computed at runtime, so a page that renders it ships every ` +\n        \"translation group. Declare the keys it uses with `config.translations` in the page's setup file.\",\n      file: relativePath,\n      line: site.line,\n      column: site.column,\n    }),\n  );\n}\n"],"mappings":";;;;;AAIA,MAAM,kBAAkB;AACxB,MAAM,qBAAqB;;;;;;;;;;AAW3B,SAAgB,oBAAoB,cAAsB,QAAkC;CAC1F,IAAI,CAAC,gBAAgB,KAAK,YAAY,KAAK,mBAAmB,KAAK,YAAY,GAAG,OAAO,CAAC;CAE1F,OAAO,sBAAsB,cAAc,MAAM,CAAC,CAAC,MAAM,aAAa,KAAK,SACzE,cAAc;EACZ,MAAM;EACN,QAAQ;EACR,UAAU;EACV,SACE,qBAAqB,KAAK,KAAK;EAEjC,MAAM;EACN,MAAM,KAAK;EACX,QAAQ,KAAK;CACf,CAAC,CACH;AACF"}

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

@@ -0,0 +1,10 @@
+import { WarlockErrorCode } from "../../errors/error-codes.mjs";
+import "../syntax/ast.mjs";
+import "./source-ast.mjs";
+//#region ../../packages/core/src/tooling/check/web-conventions.d.ts
+export type ConventionOptions = {
+  componentLineLimit?: number;
+  rules?: Partial<Record<WarlockErrorCode, "off" | "warning" | "error">>;
+};
+//#endregion
+//# sourceMappingURL=web-conventions.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"web-conventions.d.mts","names":["_$______errors_error_codes0.WarlockErrorCode"],"sources":["../../../../../../../../../packages/core/src/tooling/check/web-conventions.ts"],"mappings":";;;;YAaY;EACV;EACA,QAAQ,QACN,OAHQA"}

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

@@ -0,0 +1,126 @@
+import { parentOf, textOf } from "../syntax/ast.mjs";
+import { ancestors, calleeName, isFunctionLike, keyName, literalString, memberName, unwrap, walk } from "./source-ast.mjs";
+
+//#region ../../packages/core/src/tooling/check/web-conventions.ts
+/** JSX-returning functions are components; helpers and hook files are not. */
+function webFindings(source, options = {}) {
+	if (!/^src\/web\/.*\.tsx$/.test(source.fileName)) return [];
+	const findings = [];
+	const hooks = /* @__PURE__ */ new Set([
+		"useState",
+		"useReducer",
+		"useEffect",
+		"useLayoutEffect"
+	]);
+	for (const statement of source.body) if (statement.type === "ImportDeclaration" && statement.source.value === "react") {
+		for (const specifier of statement.specifiers) if (specifier.type === "ImportSpecifier" && hooks.has(keyName(specifier.imported) ?? "")) hooks.add(specifier.local.name);
+	}
+	const components = [];
+	walk(source, (node) => {
+		if (!isFunctionLike(node) || !node.body || ancestors(node).some(isFunctionLike)) return;
+		const parent = parentOf(node);
+		const name = node.id?.name ?? (parent?.type === "VariableDeclarator" ? keyName(parent.id) : void 0);
+		if (name && !/^[A-Z]/.test(name)) return;
+		let jsx = false;
+		walk(node.body, (child) => {
+			if (child.type === "JSXElement" || child.type === "JSXFragment") jsx = true;
+		});
+		if (jsx) components.push(node);
+	}, true);
+	const add = (code, node, message) => findings.push({
+		code,
+		node,
+		message,
+		severity: "warning"
+	});
+	const limit = options.componentLineLimit ?? 150;
+	if (components.length && source.text.replace(/\r?\n$/, "").split(/\r?\n/).length > limit) add("WL9013", components[0] ?? source, `Component file exceeds ${limit} lines. Split it into smaller components and use-*.ts hooks.`);
+	for (const component of components.slice(1)) add("WL9014", component, "More than one component in this file. Move each component to its own file.");
+	for (const component of components) {
+		if (!isFunctionLike(component) || !component.body) continue;
+		const eventNames = /* @__PURE__ */ new Set();
+		walk(component.body, (node) => {
+			if (node.type === "JSXAttribute" && /^on[A-Z]/.test(keyName(node.name) ?? "") && node.value?.type === "JSXExpressionContainer" && node.value.expression.type === "Identifier") eventNames.add(node.value.expression.name);
+		});
+		walk(component.body, (node) => {
+			if (node.type === "CallExpression" && hooks.has(calleeName(node) ?? "")) add("WL9015", node, "Move component state and effects to a use-*.ts hook file.");
+			if (isFunctionLike(node)) {
+				const parent = parentOf(node);
+				const name = node.id?.name ?? (parent?.type === "VariableDeclarator" ? keyName(parent.id) : void 0);
+				const attribute = parent?.type === "JSXExpressionContainer" ? parentOf(parent) : void 0;
+				if (/^(?:handle|on)[A-Z]/.test(name ?? "") || eventNames.has(name ?? "") || attribute?.type === "JSXAttribute" && /^on[A-Z]/.test(keyName(attribute.name) ?? "")) add("WL9015", node, "Move this event-handler function to a use-*.ts hook file.");
+			}
+		});
+	}
+	walk(source, (node) => {
+		if (node.type !== "JSXOpeningElement" || node.name.type !== "JSXIdentifier") return;
+		const tag = node.name.name;
+		if (![
+			"input",
+			"textarea",
+			"select"
+		].includes(tag)) return;
+		const attributes = node.attributes.filter((attribute) => attribute.type === "JSXAttribute");
+		const value = (attribute) => attribute.value?.type === "JSXExpressionContainer" ? literalString(attribute.value.expression) : literalString(attribute.value);
+		const inputType = attributes.find((attribute) => keyName(attribute.name) === "type");
+		const type = inputType ? value(inputType) : void 0;
+		if (!source.fileName.startsWith("src/web/design-system/") && (tag === "select" || tag === "input" && [
+			"checkbox",
+			"radio",
+			"date",
+			"time",
+			"datetime-local"
+		].includes(type ?? ""))) add("WL9016", node, "Use a design-system control instead of this native form control.");
+		for (const attribute of attributes) {
+			const name = keyName(attribute.name);
+			if ([
+				"required",
+				"pattern",
+				"min",
+				"max",
+				"minLength",
+				"maxLength"
+			].includes(name ?? "") || tag === "input" && name === "type" && type === "email") add("WL9017", attribute, "Move native validation to the shared validation schema and display field errors through the design-system control.");
+		}
+	}, true);
+	return findings;
+}
+/** RequestHandler exports declare their contract through a static responseSchema. */
+function responseSchemaFindings(source) {
+	if (!/^src\/app\/.+\/controllers\/.+\.[cm]?tsx?$/.test(source.fileName)) return [];
+	const handlerTypes = /* @__PURE__ */ new Set(["RequestHandler"]);
+	for (const statement of source.body) if (statement.type === "ImportDeclaration") {
+		for (const specifier of statement.specifiers) if (specifier.type === "ImportSpecifier" && keyName(specifier.imported) === "RequestHandler") handlerTypes.add(specifier.local.name);
+	}
+	const exports = /* @__PURE__ */ new Set();
+	const schemas = /* @__PURE__ */ new Set();
+	const handlers = [];
+	walk(source, (node) => {
+		if (node.type === "ExportNamedDeclaration") for (const specifier of node.specifiers) exports.add(keyName(specifier.local) ?? "");
+		if (node.type === "ExportDefaultDeclaration" && node.declaration.type === "Identifier") exports.add(node.declaration.name);
+		if (ancestors(node).some(isFunctionLike)) return;
+		if (node.type === "AssignmentExpression" && node.operator === "=") {
+			const left = unwrap(node.left);
+			if (left.type === "MemberExpression" && memberName(left) === "responseSchema" && left.object.type === "Identifier" && !["undefined", "null"].includes(textOf(node.right))) schemas.add(left.object.name);
+		}
+		if (node.type !== "VariableDeclarator" || node.id.type !== "Identifier") return;
+		const annotation = node.id.typeAnnotation?.typeAnnotation;
+		const initializer = node.init;
+		const satisfied = initializer?.type === "TSSatisfiesExpression" ? initializer.typeAnnotation : void 0;
+		const type = annotation ?? satisfied;
+		if (type?.type !== "TSTypeReference" || !handlerTypes.has(keyName(type.typeName) ?? "")) return;
+		handlers.push(node);
+		if (initializer?.type === "CallExpression" && initializer.callee.type === "MemberExpression" && initializer.callee.object.type === "Identifier" && initializer.callee.object.name === "Object" && keyName(initializer.callee.property) === "assign" && initializer.arguments.slice(1).some((argument) => argument.type === "ObjectExpression" && argument.properties.some((property) => property.type === "Property" && keyName(property.key) === "responseSchema"))) schemas.add(node.id.name);
+		if (ancestors(node).some((parent) => parent.type === "ExportNamedDeclaration")) exports.add(node.id.name);
+	}, true);
+	return handlers.filter((node) => node.id.type === "Identifier" && exports.has(node.id.name) && !schemas.has(node.id.name)).map((node) => ({
+		code: "WL9018",
+		node: node.id,
+		severity: "warning",
+		message: "Exported RequestHandler has no responseSchema. Declare the response body contract for each returned status code."
+	}));
+}
+
+//#endregion
+export { responseSchemaFindings, webFindings };
+//# sourceMappingURL=web-conventions.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"web-conventions.mjs","names":["ast.parentOf","ast.textOf"],"sources":["../../../../../../../../../packages/core/src/tooling/check/web-conventions.ts"],"sourcesContent":["import * as ast from \"../syntax/ast\";\nimport {\n  ancestors,\n  calleeName,\n  isFunctionLike,\n  keyName,\n  literalString,\n  memberName,\n  unwrap,\n  walk,\n  type SourceFinding,\n} from \"./source-ast\";\n\nexport type ConventionOptions = {\n  componentLineLimit?: number;\n  rules?: Partial<\n    Record<import(\"../../errors/error-codes\").WarlockErrorCode, \"off\" | \"warning\" | \"error\">\n  >;\n};\n\n/** JSX-returning functions are components; helpers and hook files are not. */\nexport function webFindings(\n  source: ast.SourceFile,\n  options: ConventionOptions = {},\n): SourceFinding[] {\n  if (!/^src\\/web\\/.*\\.tsx$/.test(source.fileName)) return [];\n  const findings: SourceFinding[] = [];\n  const hooks = new Set([\"useState\", \"useReducer\", \"useEffect\", \"useLayoutEffect\"]);\n  for (const statement of source.body)\n    if (statement.type === \"ImportDeclaration\" && statement.source.value === \"react\") {\n      for (const specifier of statement.specifiers)\n        if (specifier.type === \"ImportSpecifier\" && hooks.has(keyName(specifier.imported) ?? \"\"))\n          hooks.add(specifier.local.name);\n    }\n  const components: ast.Node[] = [];\n  walk(\n    source,\n    (node) => {\n      if (!isFunctionLike(node) || !node.body || ancestors(node).some(isFunctionLike)) return;\n      const parent = ast.parentOf(node);\n      const name =\n        node.id?.name ?? (parent?.type === \"VariableDeclarator\" ? keyName(parent.id) : undefined);\n      if (name && !/^[A-Z]/.test(name)) return;\n      let jsx = false;\n      walk(node.body, (child) => {\n        if (child.type === \"JSXElement\" || child.type === \"JSXFragment\") jsx = true;\n      });\n      if (jsx) components.push(node);\n    },\n    true,\n  );\n  const add = (code: SourceFinding[\"code\"], node: ast.Node, message: string) =>\n    findings.push({ code, node, message, severity: \"warning\" });\n  const limit = options.componentLineLimit ?? 150;\n  if (components.length && source.text.replace(/\\r?\\n$/, \"\").split(/\\r?\\n/).length > limit)\n    add(\n      \"WL9013\",\n      components[0] ?? source,\n      `Component file exceeds ${limit} lines. Split it into smaller components and use-*.ts hooks.`,\n    );\n  for (const component of components.slice(1))\n    add(\n      \"WL9014\",\n      component,\n      \"More than one component in this file. Move each component to its own file.\",\n    );\n  for (const component of components) {\n    if (!isFunctionLike(component) || !component.body) continue;\n    const eventNames = new Set<string>();\n    walk(component.body, (node) => {\n      if (\n        node.type === \"JSXAttribute\" &&\n        /^on[A-Z]/.test(keyName(node.name) ?? \"\") &&\n        node.value?.type === \"JSXExpressionContainer\" &&\n        node.value.expression.type === \"Identifier\"\n      )\n        eventNames.add(node.value.expression.name);\n    });\n    walk(component.body, (node) => {\n      if (node.type === \"CallExpression\" && hooks.has(calleeName(node) ?? \"\"))\n        add(\"WL9015\", node, \"Move component state and effects to a use-*.ts hook file.\");\n      if (isFunctionLike(node)) {\n        const parent = ast.parentOf(node);\n        const name =\n          node.id?.name ?? (parent?.type === \"VariableDeclarator\" ? keyName(parent.id) : undefined);\n        const attribute =\n          parent?.type === \"JSXExpressionContainer\" ? ast.parentOf(parent) : undefined;\n        if (\n          /^(?:handle|on)[A-Z]/.test(name ?? \"\") ||\n          eventNames.has(name ?? \"\") ||\n          (attribute?.type === \"JSXAttribute\" && /^on[A-Z]/.test(keyName(attribute.name) ?? \"\"))\n        )\n          add(\"WL9015\", node, \"Move this event-handler function to a use-*.ts hook file.\");\n      }\n    });\n  }\n  walk(\n    source,\n    (node) => {\n      if (node.type !== \"JSXOpeningElement\" || node.name.type !== \"JSXIdentifier\") return;\n      const tag = node.name.name;\n      if (![\"input\", \"textarea\", \"select\"].includes(tag)) return;\n      const attributes = node.attributes.filter((attribute) => attribute.type === \"JSXAttribute\");\n      const value = (attribute: ast.JSXAttribute) =>\n        attribute.value?.type === \"JSXExpressionContainer\"\n          ? literalString(attribute.value.expression)\n          : literalString(attribute.value);\n      const inputType = attributes.find((attribute) => keyName(attribute.name) === \"type\");\n      const type = inputType ? value(inputType) : undefined;\n      if (\n        !source.fileName.startsWith(\"src/web/design-system/\") &&\n        (tag === \"select\" ||\n          (tag === \"input\" &&\n            [\"checkbox\", \"radio\", \"date\", \"time\", \"datetime-local\"].includes(type ?? \"\")))\n      )\n        add(\"WL9016\", node, \"Use a design-system control instead of this native form control.\");\n      for (const attribute of attributes) {\n        const name = keyName(attribute.name);\n        if (\n          [\"required\", \"pattern\", \"min\", \"max\", \"minLength\", \"maxLength\"].includes(name ?? \"\") ||\n          (tag === \"input\" && name === \"type\" && type === \"email\")\n        )\n          add(\n            \"WL9017\",\n            attribute,\n            \"Move native validation to the shared validation schema and display field errors through the design-system control.\",\n          );\n      }\n    },\n    true,\n  );\n  return findings;\n}\n\n/** RequestHandler exports declare their contract through a static responseSchema. */\nexport function responseSchemaFindings(source: ast.SourceFile): SourceFinding[] {\n  if (!/^src\\/app\\/.+\\/controllers\\/.+\\.[cm]?tsx?$/.test(source.fileName)) return [];\n  const handlerTypes = new Set([\"RequestHandler\"]);\n  for (const statement of source.body)\n    if (statement.type === \"ImportDeclaration\")\n      for (const specifier of statement.specifiers)\n        if (\n          specifier.type === \"ImportSpecifier\" &&\n          keyName(specifier.imported) === \"RequestHandler\"\n        )\n          handlerTypes.add(specifier.local.name);\n  const exports = new Set<string>();\n  const schemas = new Set<string>();\n  const handlers: ast.VariableDeclarator[] = [];\n  walk(\n    source,\n    (node) => {\n      if (node.type === \"ExportNamedDeclaration\")\n        for (const specifier of node.specifiers) exports.add(keyName(specifier.local) ?? \"\");\n      if (node.type === \"ExportDefaultDeclaration\" && node.declaration.type === \"Identifier\")\n        exports.add(node.declaration.name);\n      if (ancestors(node).some(isFunctionLike)) return;\n      if (node.type === \"AssignmentExpression\" && node.operator === \"=\") {\n        const left = unwrap(node.left);\n        if (\n          left.type === \"MemberExpression\" &&\n          memberName(left) === \"responseSchema\" &&\n          left.object.type === \"Identifier\" &&\n          ![\"undefined\", \"null\"].includes(ast.textOf(node.right))\n        )\n          schemas.add(left.object.name);\n      }\n      if (node.type !== \"VariableDeclarator\" || node.id.type !== \"Identifier\") return;\n      const annotation = node.id.typeAnnotation?.typeAnnotation;\n      const initializer = node.init;\n      const satisfied =\n        initializer?.type === \"TSSatisfiesExpression\" ? initializer.typeAnnotation : undefined;\n      const type = annotation ?? satisfied;\n      if (type?.type !== \"TSTypeReference\" || !handlerTypes.has(keyName(type.typeName) ?? \"\"))\n        return;\n      handlers.push(node);\n      if (\n        initializer?.type === \"CallExpression\" &&\n        initializer.callee.type === \"MemberExpression\" &&\n        initializer.callee.object.type === \"Identifier\" &&\n        initializer.callee.object.name === \"Object\" &&\n        keyName(initializer.callee.property) === \"assign\" &&\n        initializer.arguments\n          .slice(1)\n          .some(\n            (argument) =>\n              argument.type === \"ObjectExpression\" &&\n              argument.properties.some(\n                (property) =>\n                  property.type === \"Property\" && keyName(property.key) === \"responseSchema\",\n              ),\n          )\n      )\n        schemas.add(node.id.name);\n      if (ancestors(node).some((parent) => parent.type === \"ExportNamedDeclaration\"))\n        exports.add(node.id.name);\n    },\n    true,\n  );\n  return handlers\n    .filter(\n      (node) =>\n        node.id.type === \"Identifier\" && exports.has(node.id.name) && !schemas.has(node.id.name),\n    )\n    .map<SourceFinding>((node) => ({\n      code: \"WL9018\",\n      node: node.id,\n      severity: \"warning\",\n      message:\n        \"Exported RequestHandler has no responseSchema. Declare the response body contract for each returned status code.\",\n    }));\n}\n"],"mappings":"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"}

package/esm/tooling/index.d.mts

@@ -1,5 +1,5 @@
 import { AGENTS_MD_END, AGENTS_MD_FILE, AGENTS_MD_START, upsertGeneratedSection } from "./agents-md/agents-md-markers.mjs";
-import { INSPECT_SCHEMA_VERSION, INSPECT_SECTIONS, InspectConfigKey, InspectEvent, InspectJob, InspectModel, InspectModelColumn, InspectModelRelation, InspectPackage, InspectPage, InspectParameter, InspectReport, InspectResource, InspectRoute, InspectRouteAuth, InspectRouteLogging, InspectRouteRateLimit, InspectSchedule, InspectSection, InspectWarning, JsonSchema } from "./inspect/inspect-report.types.mjs";
+import { INSPECT_SCHEMA_VERSION, INSPECT_SECTIONS, InspectConfigKey, InspectEvent, InspectFile, InspectJob, InspectModel, InspectModelColumn, InspectModelRelation, InspectPackage, InspectPage, InspectParameter, InspectReport, InspectResource, InspectRoute, InspectRouteAuth, InspectRouteLogging, InspectRouteRateLimit, InspectSchedule, InspectSection, InspectWarning, JsonSchema } from "./inspect/inspect-report.types.mjs";
 import { InstalledSkill, listInstalledSkills, parseSkillFrontMatter, shortSkillLine } from "./agents-md/installed-skills.mjs";
 import { AgentsMdWriteStatus, WriteAgentsMdOptions, WriteAgentsMdResult, writeAgentsMd } from "./agents-md/write-agents-md.mjs";
 import { AgentsMdRefresher, AgentsMdRefresherOptions, createAgentsMdRefresher } from "./agents-md/agents-md-refresher.mjs";
@@ -7,9 +7,11 @@ import { RenderAgentsMdOptions, listAppModules, renderAgentsMdSection } from "./
 import { BOARD_DIRECTORY, BOARD_STATES, BOARD_TRANSITIONS, BOARD_VERDICT_LINES, BoardHistoryEntry, BoardInbox, BoardItem, BoardMessage, BoardState, BoardStatus, BoardVerdict, isBoardState, isBoardVerdict } from "./board/board.types.mjs";
 import { AddBoardItemInput, InitBoardResult, MoveBoardItemOptions, SendBoardMessageInput, SendBoardMessageResult, WatchBoardOptions, WatchBoardResult, addBoardItem, assertAgentName, assertBoardTransition, boardSlug, gitignoreCoversBoard, initBoard, listBoardItems, listBoardMessages, moveBoardItem, nextBoardStates, readBoardCursor, readBoardItem, readBoardStatus, sendBoardMessage, watchBoard, writeBoardCursor } from "./board/board.mjs";
 import { BoardMessageFields, ParsedBoardMessage, formatBoardMessage, parseBoardMessage } from "./board/board-message.mjs";
+import { ProblemFix } from "./check/fixes.mjs";
 import { ProblemInput, ProblemSource, ToolingProblem, createProblem } from "./problem.mjs";
 import { GitResult, GitRunner, listChangedFiles, runGit } from "./check/changed-files.mjs";
 import { CHECK_EXIT_CODES, CHECK_STEPS, CheckExitCode, CheckReport, CheckStep, CheckStepName, CheckStepStatus, checkExitCode } from "./check/check-report.types.mjs";
+import { ConventionOptions } from "./check/web-conventions.mjs";
 import { checkFileConventions, checkTsconfigConventions, isAutoLoadedFile, runConventions } from "./check/conventions-step.mjs";
 import { MIN_NODE_VERSION, checkNodeVersion } from "./check/environment-step.mjs";
 import { LintOutcome, runLint } from "./check/lint-step.mjs";
@@ -17,6 +19,8 @@ import { DEFAULT_TYPECHECK_BUILD_INFO, TypecheckOptions, TypecheckResult, diagno
 import { VitestRun, VitestRunner, findVitest, parseVitestReport, runVitest } from "./check/tests-step.mjs";
 import { CheckOptions, TypecheckRunner, runCheck } from "./check/run-check.mjs";
 import { RunTestsOptions, TestRunReport, runTests, testRunArguments } from "./check/run-tests.mjs";
+import { affectedFiles } from "./check/affected-files.mjs";
+import "./check/index.mjs";
 import { DEV_SERVER_STATE_FILE, DevServerState, parseDevServerState, readDevServerState, removeDevServerState, updateDevServerState, writeDevServerState } from "./dev-state/dev-server-state.mjs";
 import { ConnectDevtoolsOptions, DEFAULT_DEVTOOLS_PATH, DevtoolsClient, DevtoolsEndpoint, DevtoolsFetch, DevtoolsPhaseRecord, DevtoolsRequestRecord, DevtoolsRequestSummaryRecord, connectDevtools, parseRequestRecord, parseRequestSummary, resolveDevServerEndpoint } from "./devtools/devtools-client.mjs";
 import { GeneratorArgsOptions, GeneratorSpec, MAKE_GENERATORS, MAKE_GENERATOR_FLAGS, MakeGenerator, buildGeneratorArgs, isMakeGenerator } from "./generate/generator-spec.mjs";
@@ -29,6 +33,7 @@ import { AppModuleImporter } from "./inspect/collect-packages.mjs";
 import { InspectOptions, inspectApp, isInspectSection, parseInspectSections } from "./inspect/inspect-app.mjs";
 import { InspectBootResult, bootForInspect, inspectOptionsFromBoot } from "./inspect/boot-for-inspect.mjs";
 import { INSPECT_REPORT_JSON_SCHEMA } from "./inspect/inspect-report.schema.mjs";
+import { ExplainedFile, explainFile } from "./inspect/explain-file.mjs";
 import "./inspect/index.mjs";
 import { DbSchema, DbSchemaColumn, DbSchemaTable, buildDbSchema } from "./mcp/db-schema.mjs";
 import { DOCS_CORPUS_GLOBS, DocsCorpus, DocsSearchHit, DocsSection, loadDocsCorpus, readDocsFile, searchDocs, searchTerms, splitSections } from "./mcp/docs-search.mjs";
@@ -39,4 +44,4 @@ import { AiToolsServeModule, MCP_INSTALL_HINT, ServeToolContract, isAiToolsServe
 import { StartWarlockMcpServerOptions, WarlockMcpServerHandle, WarlockMcpTransport, isLoopbackHost, resolveMcpTransport, startWarlockMcpServer, toServeContract } from "./mcp/start-mcp-server.mjs";
 import { TRACE_SCHEMA_VERSION, TraceMiddleware, TraceQuery, TraceReport, TraceValidation } from "./trace/trace-report.types.mjs";
 import { BuildTraceReportInput, TRACE_BODY_LIMIT, TRACE_REQUEST_ID_HEADER, TraceRequestOptions, TracedResponse, buildTraceReport, readResponseBody, redactHeaders, resolveTraceUrl, traceRequest } from "./trace/trace-request.mjs";
-export { AGENTS_MD_END, AGENTS_MD_FILE, AGENTS_MD_START, type AddBoardItemInput, type AgentsMdRefresher, type AgentsMdRefresherOptions, type AgentsMdWriteStatus, type AiToolsServeModule, type AppModuleImporter, type ApplyGenerationOptions, BOARD_DIRECTORY, BOARD_STATES, BOARD_TRANSITIONS, BOARD_VERDICT_LINES, type BoardHistoryEntry, type BoardInbox, type BoardItem, type BoardMessage, type BoardMessageFields, type BoardState, type BoardStatus, type BoardVerdict, type BuildTraceReportInput, CHECK_EXIT_CODES, CHECK_STEPS, type CheckExitCode, type CheckOptions, type CheckReport, type CheckStep, type CheckStepName, type CheckStepStatus, type CliInvocation, type CliRun, type CliRunner, ConnectDevtoolsOptions, type CreateMcpContextOptions, DEFAULT_DEVTOOLS_PATH, DEFAULT_GENERATION_TIMEOUT_MS, DEFAULT_TYPECHECK_BUILD_INFO, DEV_SERVER_STATE_FILE, DIFF_CONTEXT_LINES, DOCS_CORPUS_GLOBS, type DbSchema, type DbSchemaColumn, type DbSchemaTable, DevServerState, DevtoolsClient, DevtoolsEndpoint, DevtoolsFetch, DevtoolsPhaseRecord, DevtoolsRequestRecord, DevtoolsRequestSummaryRecord, type DocsCorpus, type DocsSearchHit, type DocsSection, EventRecorder, type GeneratedFile, type GenerationBackend, type GenerationPlan, type GenerationPlanOptions, type GeneratorArgsOptions, type GeneratorSpec, type GitResult, type GitRunner, INSPECT_REPORT_JSON_SCHEMA, INSPECT_SCHEMA_VERSION, INSPECT_SECTIONS, type InitBoardResult, type InspectBootResult, InspectConfigKey, InspectEvent, InspectJob, InspectModel, InspectModelColumn, type InspectModelModule, InspectModelRelation, type InspectOptions, InspectPackage, InspectPage, InspectParameter, InspectReport, InspectResource, InspectRoute, InspectRouteAuth, InspectRouteLogging, InspectRouteRateLimit, InspectSchedule, InspectSection, InspectWarning, type InstalledSkill, JsonSchema, type LintOutcome, MAKE_GENERATORS, MAKE_GENERATOR_FLAGS, MAX_FILE_DIFF_BYTES, MCP_INSTALL_HINT, MCP_MAKE_GENERATORS, MIN_NODE_VERSION, type MakeGenerator, type McpInputProperty, type McpInputSchema, type MoveBoardItemOptions, type ParsedBoardMessage, type ProblemInput, type ProblemSource, type RecordedListener, type RenderAgentsMdOptions, type RunTestsOptions, type SandboxBackendOptions, type SendBoardMessageInput, type SendBoardMessageResult, type ServeToolContract, type StartWarlockMcpServerOptions, TRACE_BODY_LIMIT, TRACE_REQUEST_ID_HEADER, TRACE_SCHEMA_VERSION, type TestRunReport, type ToolingProblem, TraceMiddleware, TraceQuery, TraceReport, type TraceRequestOptions, TraceValidation, type TracedResponse, type TypecheckOptions, type TypecheckResult, type TypecheckRunner, type UnifiedDiffInput, type VitestRun, type VitestRunner, type WarlockMcpContext, type WarlockMcpServerHandle, type WarlockMcpTool, type WarlockMcpTransport, type WatchBoardOptions, type WatchBoardResult, type WriteAgentsMdOptions, type WriteAgentsMdResult, addBoardItem, applyGeneration, assertAgentName, assertBoardTransition, boardSlug, bootForInspect, buildDbSchema, buildGeneratorArgs, buildTraceReport, checkExitCode, checkFileConventions, checkNodeVersion, checkTsconfigConventions, connectDevtools, createAgentsMdRefresher, createMcpContext, createProblem, createWarlockMcpTools, describeRun, describeToolError, diagnosticToProblem, directImporters, findVitest, formatBoardMessage, gitignoreCoversBoard, groupListeners, initBoard, inputSchema, inspectApp, inspectOptionsFromBoot, isAiToolsServeModule, isAutoLoadedFile, isBoardState, isBoardVerdict, isInspectSection, isLoopbackHost, isMakeGenerator, listAppModules, listBoardItems, listBoardMessages, listChangedFiles, listInstalledSkills, loadAiToolsServe, loadDocsCorpus, makeSpecFromInput, moveBoardItem, nextBoardStates, parseBoardMessage, parseDevServerState, parseInspectSections, parseRequestRecord, parseRequestSummary, parseSkillFrontMatter, parseVitestReport, readBoardCursor, readBoardItem, readBoardStatus, readDevServerState, readDocsFile, readResponseBody, redactHeaders, removeDevServerState, renderAgentsMdSection, resolveCliEntry, resolveDevServerEndpoint, resolveMcpTransport, resolveTraceUrl, runCheck, runConventions, runGit, runLint, runTests, runTypecheck, runVitest, sandboxBackend, searchDocs, searchTerms, sendBoardMessage, shortSkillLine, spawnCli, splitSections, startWarlockMcpServer, testRunArguments, toServeContract, toStandardSchema, traceRequest, unifiedDiff, updateDevServerState, upsertGeneratedSection, validateToolInput, watchBoard, writeAgentsMd, writeBoardCursor, writeDevServerState };
+export { AGENTS_MD_END, AGENTS_MD_FILE, AGENTS_MD_START, type AddBoardItemInput, type AgentsMdRefresher, type AgentsMdRefresherOptions, type AgentsMdWriteStatus, type AiToolsServeModule, type AppModuleImporter, type ApplyGenerationOptions, BOARD_DIRECTORY, BOARD_STATES, BOARD_TRANSITIONS, BOARD_VERDICT_LINES, type BoardHistoryEntry, type BoardInbox, type BoardItem, type BoardMessage, type BoardMessageFields, type BoardState, type BoardStatus, type BoardVerdict, type BuildTraceReportInput, CHECK_EXIT_CODES, CHECK_STEPS, type CheckExitCode, type CheckOptions, type CheckReport, type CheckStep, type CheckStepName, type CheckStepStatus, type CliInvocation, type CliRun, type CliRunner, ConnectDevtoolsOptions, type ConventionOptions, type CreateMcpContextOptions, DEFAULT_DEVTOOLS_PATH, DEFAULT_GENERATION_TIMEOUT_MS, DEFAULT_TYPECHECK_BUILD_INFO, DEV_SERVER_STATE_FILE, DIFF_CONTEXT_LINES, DOCS_CORPUS_GLOBS, type DbSchema, type DbSchemaColumn, type DbSchemaTable, DevServerState, DevtoolsClient, DevtoolsEndpoint, DevtoolsFetch, DevtoolsPhaseRecord, DevtoolsRequestRecord, DevtoolsRequestSummaryRecord, type DocsCorpus, type DocsSearchHit, type DocsSection, EventRecorder, type ExplainedFile, type GeneratedFile, type GenerationBackend, type GenerationPlan, type GenerationPlanOptions, type GeneratorArgsOptions, type GeneratorSpec, type GitResult, type GitRunner, INSPECT_REPORT_JSON_SCHEMA, INSPECT_SCHEMA_VERSION, INSPECT_SECTIONS, type InitBoardResult, type InspectBootResult, InspectConfigKey, InspectEvent, InspectFile, InspectJob, InspectModel, InspectModelColumn, type InspectModelModule, InspectModelRelation, type InspectOptions, InspectPackage, InspectPage, InspectParameter, InspectReport, InspectResource, InspectRoute, InspectRouteAuth, InspectRouteLogging, InspectRouteRateLimit, InspectSchedule, InspectSection, InspectWarning, type InstalledSkill, JsonSchema, type LintOutcome, MAKE_GENERATORS, MAKE_GENERATOR_FLAGS, MAX_FILE_DIFF_BYTES, MCP_INSTALL_HINT, MCP_MAKE_GENERATORS, MIN_NODE_VERSION, type MakeGenerator, type McpInputProperty, type McpInputSchema, type MoveBoardItemOptions, type ParsedBoardMessage, type ProblemFix, type ProblemInput, type ProblemSource, type RecordedListener, type RenderAgentsMdOptions, type RunTestsOptions, type SandboxBackendOptions, type SendBoardMessageInput, type SendBoardMessageResult, type ServeToolContract, type StartWarlockMcpServerOptions, TRACE_BODY_LIMIT, TRACE_REQUEST_ID_HEADER, TRACE_SCHEMA_VERSION, type TestRunReport, type ToolingProblem, TraceMiddleware, TraceQuery, TraceReport, type TraceRequestOptions, TraceValidation, type TracedResponse, type TypecheckOptions, type TypecheckResult, type TypecheckRunner, type UnifiedDiffInput, type VitestRun, type VitestRunner, type WarlockMcpContext, type WarlockMcpServerHandle, type WarlockMcpTool, type WarlockMcpTransport, type WatchBoardOptions, type WatchBoardResult, type WriteAgentsMdOptions, type WriteAgentsMdResult, addBoardItem, affectedFiles, applyGeneration, assertAgentName, assertBoardTransition, boardSlug, bootForInspect, buildDbSchema, buildGeneratorArgs, buildTraceReport, checkExitCode, checkFileConventions, checkNodeVersion, checkTsconfigConventions, connectDevtools, createAgentsMdRefresher, createMcpContext, createProblem, createWarlockMcpTools, describeRun, describeToolError, diagnosticToProblem, directImporters, explainFile, findVitest, formatBoardMessage, gitignoreCoversBoard, groupListeners, initBoard, inputSchema, inspectApp, inspectOptionsFromBoot, isAiToolsServeModule, isAutoLoadedFile, isBoardState, isBoardVerdict, isInspectSection, isLoopbackHost, isMakeGenerator, listAppModules, listBoardItems, listBoardMessages, listChangedFiles, listInstalledSkills, loadAiToolsServe, loadDocsCorpus, makeSpecFromInput, moveBoardItem, nextBoardStates, parseBoardMessage, parseDevServerState, parseInspectSections, parseRequestRecord, parseRequestSummary, parseSkillFrontMatter, parseVitestReport, readBoardCursor, readBoardItem, readBoardStatus, readDevServerState, readDocsFile, readResponseBody, redactHeaders, removeDevServerState, renderAgentsMdSection, resolveCliEntry, resolveDevServerEndpoint, resolveMcpTransport, resolveTraceUrl, runCheck, runConventions, runGit, runLint, runTests, runTypecheck, runVitest, sandboxBackend, searchDocs, searchTerms, sendBoardMessage, shortSkillLine, spawnCli, splitSections, startWarlockMcpServer, testRunArguments, toServeContract, toStandardSchema, traceRequest, unifiedDiff, updateDevServerState, upsertGeneratedSection, validateToolInput, watchBoard, writeAgentsMd, writeBoardCursor, writeDevServerState };

package/esm/tooling/index.mjs

@@ -11,15 +11,17 @@ import { formatBoardMessage, parseBoardMessage } from "./board/board-message.mjs
 import { addBoardItem, assertAgentName, assertBoardTransition, boardSlug, gitignoreCoversBoard, initBoard, listBoardItems, listBoardMessages, moveBoardItem, nextBoardStates, readBoardCursor, readBoardItem, readBoardStatus, sendBoardMessage, watchBoard, writeBoardCursor } from "./board/board.mjs";
 import { CHECK_EXIT_CODES, CHECK_STEPS, checkExitCode } from "./check/check-report.types.mjs";
 import { createProblem } from "./problem.mjs";
+import { checkFileConventions, checkTsconfigConventions, isAutoLoadedFile, runConventions } from "./check/conventions-step.mjs";
+import { affectedFiles } from "./check/affected-files.mjs";
 import { DEFAULT_TYPECHECK_BUILD_INFO, diagnosticToProblem, directImporters, runTypecheck } from "./typecheck/run-typecheck.mjs";
 import { listChangedFiles, runGit } from "./check/changed-files.mjs";
-import { checkFileConventions, checkTsconfigConventions, isAutoLoadedFile, runConventions } from "./check/conventions-step.mjs";
 import { MIN_NODE_VERSION, checkNodeVersion } from "./check/environment-step.mjs";
 import { runLint } from "./check/lint-step.mjs";
 import { findVitest, parseVitestReport, runVitest } from "./check/tests-step.mjs";
 import { runCheck } from "./check/run-check.mjs";
 import { DEV_SERVER_STATE_FILE, parseDevServerState, readDevServerState, removeDevServerState, updateDevServerState, writeDevServerState } from "./dev-state/dev-server-state.mjs";
 import { DEFAULT_DEVTOOLS_PATH, connectDevtools, parseRequestRecord, parseRequestSummary, resolveDevServerEndpoint } from "./devtools/devtools-client.mjs";
+import { explainFile } from "./inspect/explain-file.mjs";
 import { runTests, testRunArguments } from "./check/run-tests.mjs";
 import { MAKE_GENERATORS, MAKE_GENERATOR_FLAGS, buildGeneratorArgs, isMakeGenerator } from "./generate/generator-spec.mjs";
 import { DEFAULT_GENERATION_TIMEOUT_MS, describeRun, resolveCliEntry, spawnCli } from "./generate/run-cli.mjs";
@@ -42,4 +44,4 @@ import "./inspect/index.mjs";
 import "./mcp/index.mjs";
 import "./typecheck/index.mjs";
 
-export { AGENTS_MD_END, AGENTS_MD_FILE, AGENTS_MD_START, BOARD_DIRECTORY, BOARD_STATES, BOARD_TRANSITIONS, BOARD_VERDICT_LINES, CHECK_EXIT_CODES, CHECK_STEPS, DEFAULT_DEVTOOLS_PATH, DEFAULT_GENERATION_TIMEOUT_MS, DEFAULT_TYPECHECK_BUILD_INFO, DEV_SERVER_STATE_FILE, DIFF_CONTEXT_LINES, DOCS_CORPUS_GLOBS, EventRecorder, INSPECT_REPORT_JSON_SCHEMA, INSPECT_SCHEMA_VERSION, INSPECT_SECTIONS, MAKE_GENERATORS, MAKE_GENERATOR_FLAGS, MAX_FILE_DIFF_BYTES, MCP_INSTALL_HINT, MCP_MAKE_GENERATORS, MIN_NODE_VERSION, TRACE_BODY_LIMIT, TRACE_REQUEST_ID_HEADER, TRACE_SCHEMA_VERSION, addBoardItem, applyGeneration, assertAgentName, assertBoardTransition, boardSlug, bootForInspect, buildDbSchema, buildGeneratorArgs, buildTraceReport, checkExitCode, checkFileConventions, checkNodeVersion, checkTsconfigConventions, connectDevtools, createAgentsMdRefresher, createMcpContext, createProblem, createWarlockMcpTools, describeRun, describeToolError, diagnosticToProblem, directImporters, findVitest, formatBoardMessage, gitignoreCoversBoard, groupListeners, initBoard, inputSchema, inspectApp, inspectOptionsFromBoot, isAiToolsServeModule, isAutoLoadedFile, isBoardState, isBoardVerdict, isInspectSection, isLoopbackHost, isMakeGenerator, listAppModules, listBoardItems, listBoardMessages, listChangedFiles, listInstalledSkills, loadAiToolsServe, loadDocsCorpus, makeSpecFromInput, moveBoardItem, nextBoardStates, parseBoardMessage, parseDevServerState, parseInspectSections, parseRequestRecord, parseRequestSummary, parseSkillFrontMatter, parseVitestReport, readBoardCursor, readBoardItem, readBoardStatus, readDevServerState, readDocsFile, readResponseBody, redactHeaders, removeDevServerState, renderAgentsMdSection, resolveCliEntry, resolveDevServerEndpoint, resolveMcpTransport, resolveTraceUrl, runCheck, runConventions, runGit, runLint, runTests, runTypecheck, runVitest, sandboxBackend, searchDocs, searchTerms, sendBoardMessage, shortSkillLine, spawnCli, splitSections, startWarlockMcpServer, testRunArguments, toServeContract, toStandardSchema, traceRequest, unifiedDiff, updateDevServerState, upsertGeneratedSection, validateToolInput, watchBoard, writeAgentsMd, writeBoardCursor, writeDevServerState };
+export { AGENTS_MD_END, AGENTS_MD_FILE, AGENTS_MD_START, BOARD_DIRECTORY, BOARD_STATES, BOARD_TRANSITIONS, BOARD_VERDICT_LINES, CHECK_EXIT_CODES, CHECK_STEPS, DEFAULT_DEVTOOLS_PATH, DEFAULT_GENERATION_TIMEOUT_MS, DEFAULT_TYPECHECK_BUILD_INFO, DEV_SERVER_STATE_FILE, DIFF_CONTEXT_LINES, DOCS_CORPUS_GLOBS, EventRecorder, INSPECT_REPORT_JSON_SCHEMA, INSPECT_SCHEMA_VERSION, INSPECT_SECTIONS, MAKE_GENERATORS, MAKE_GENERATOR_FLAGS, MAX_FILE_DIFF_BYTES, MCP_INSTALL_HINT, MCP_MAKE_GENERATORS, MIN_NODE_VERSION, TRACE_BODY_LIMIT, TRACE_REQUEST_ID_HEADER, TRACE_SCHEMA_VERSION, addBoardItem, affectedFiles, applyGeneration, assertAgentName, assertBoardTransition, boardSlug, bootForInspect, buildDbSchema, buildGeneratorArgs, buildTraceReport, checkExitCode, checkFileConventions, checkNodeVersion, checkTsconfigConventions, connectDevtools, createAgentsMdRefresher, createMcpContext, createProblem, createWarlockMcpTools, describeRun, describeToolError, diagnosticToProblem, directImporters, explainFile, findVitest, formatBoardMessage, gitignoreCoversBoard, groupListeners, initBoard, inputSchema, inspectApp, inspectOptionsFromBoot, isAiToolsServeModule, isAutoLoadedFile, isBoardState, isBoardVerdict, isInspectSection, isLoopbackHost, isMakeGenerator, listAppModules, listBoardItems, listBoardMessages, listChangedFiles, listInstalledSkills, loadAiToolsServe, loadDocsCorpus, makeSpecFromInput, moveBoardItem, nextBoardStates, parseBoardMessage, parseDevServerState, parseInspectSections, parseRequestRecord, parseRequestSummary, parseSkillFrontMatter, parseVitestReport, readBoardCursor, readBoardItem, readBoardStatus, readDevServerState, readDocsFile, readResponseBody, redactHeaders, removeDevServerState, renderAgentsMdSection, resolveCliEntry, resolveDevServerEndpoint, resolveMcpTransport, resolveTraceUrl, runCheck, runConventions, runGit, runLint, runTests, runTypecheck, runVitest, sandboxBackend, searchDocs, searchTerms, sendBoardMessage, shortSkillLine, spawnCli, splitSections, startWarlockMcpServer, testRunArguments, toServeContract, toStandardSchema, traceRequest, unifiedDiff, updateDevServerState, upsertGeneratedSection, validateToolInput, watchBoard, writeAgentsMd, writeBoardCursor, writeDevServerState };

package/esm/tooling/inspect/collect-files.mjs

@@ -0,0 +1,172 @@
+import { forEachChild } from "../syntax/ast.mjs";
+import { isConfigFile, isEventFile, isLocaleFile, isMainFile, isRouteFile, isWorkerFile } from "../../dev-server/special-file-patterns.mjs";
+import path from "node:path";
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { readTsconfig, resolvePathAlias } from "get-tsconfig";
+import { parseSync } from "oxc-parser";
+
+//#region ../../packages/core/src/tooling/inspect/collect-files.ts
+const CODE = /\.(?:[cm]?[jt]s|[jt]sx)$/;
+const EXTENSIONS = [
+	".ts",
+	".tsx",
+	".mts",
+	".cts",
+	".js",
+	".jsx",
+	".mjs",
+	".cjs",
+	".d.ts"
+];
+function projectFile(cwd, file) {
+	return path.relative(cwd, path.resolve(cwd, file)).split(path.sep).join("/");
+}
+/** Infer a role from file names and the framework's directory conventions. */
+function fileRole(file) {
+	const stem = path.posix.basename(file).replace(CODE, "");
+	if (/(?:^|\.)(?:spec|test)$/.test(stem)) return "spec";
+	if (file.endsWith(".d.ts")) return "type";
+	if (isConfigFile(file)) return "config";
+	if (isRouteFile(file)) return "routes";
+	if (isMainFile(file)) return "main";
+	if (isWorkerFile(file)) return "worker";
+	if (isEventFile(file)) return "event";
+	if (isLocaleFile(file)) return "locale";
+	for (const role of [
+		"routes",
+		"page",
+		"setup",
+		"layout",
+		"root"
+	]) if (stem === role || stem.endsWith(`.${role}`)) return role;
+	for (const role of [
+		"controller",
+		"service",
+		"repository",
+		"model",
+		"migration",
+		"schema",
+		"resource",
+		"hook",
+		"component",
+		"util",
+		"type",
+		"config"
+	]) if (stem.endsWith(`.${role}`) || file.split("/").includes(role === "repository" ? "repositories" : `${role}s`)) return role;
+	if (file.startsWith("src/config/")) return "config";
+	if (file.split("/").includes("utils")) return "util";
+	if (/^use[A-Z]/.test(stem)) return "hook";
+	if (/\.tsx$|\.jsx$/.test(file)) return "component";
+	return "source";
+}
+function bindingNames(node) {
+	if (node.type === "Identifier") return [node.name];
+	if (node.type === "ObjectPattern") return node.properties.flatMap((property) => bindingNames(property.type === "RestElement" ? property.argument : property.value));
+	if (node.type === "ArrayPattern") return node.elements.flatMap((element) => element ? bindingNames(element) : []);
+	if (node.type === "AssignmentPattern") return bindingNames(node.left);
+	if (node.type === "RestElement") return bindingNames(node.argument);
+	return [];
+}
+/** Read each source module once; never import or execute application code. */
+function collectFiles(cwd, warnings = []) {
+	cwd = path.resolve(cwd);
+	const paths = [];
+	const scan = (directory) => {
+		if (!existsSync(directory)) return;
+		try {
+			for (const entry of readdirSync(directory, { withFileTypes: true })) {
+				const file = path.join(directory, entry.name);
+				if (entry.isDirectory()) scan(file);
+				else if (entry.isFile()) paths.push(file);
+			}
+		} catch (error) {
+			warnings.push({
+				code: null,
+				source: projectFile(cwd, directory),
+				message: String(error)
+			});
+		}
+	};
+	scan(path.join(cwd, "src"));
+	paths.sort();
+	const known = new Set(paths);
+	let tsconfig;
+	try {
+		if (existsSync(path.join(cwd, "tsconfig.json"))) tsconfig = readTsconfig(path.join(cwd, "tsconfig.json"), { typescriptVersion: false });
+	} catch (error) {
+		warnings.push({
+			code: null,
+			source: "tsconfig.json",
+			message: String(error)
+		});
+	}
+	const probe = (base) => {
+		const extension = path.extname(base);
+		const stem = /\.[cm]?jsx?$/.test(extension) ? base.slice(0, -extension.length) : base;
+		const candidates = stem !== base ? EXTENSIONS.map((ext) => stem + ext) : [];
+		candidates.push(base, ...EXTENSIONS.map((ext) => base + ext), ...EXTENSIONS.map((ext) => path.join(base, `index${ext}`)));
+		return candidates.find((candidate) => known.has(candidate));
+	};
+	const files = paths.map((absolute) => {
+		const file = projectFile(cwd, absolute);
+		const parts = file.split("/");
+		const record = {
+			file,
+			module: parts[1] === "app" && parts.length > 3 ? parts.slice(0, 3).join("/") : path.posix.dirname(file).split("/").slice(0, 2).join("/"),
+			role: fileRole(file),
+			exports: [],
+			imports: [],
+			importedBy: []
+		};
+		if (!CODE.test(file)) return record;
+		try {
+			const parsed = parseSync(absolute, readFileSync(absolute, "utf8"));
+			for (const error of parsed.errors) warnings.push({
+				code: null,
+				source: file,
+				message: error.message
+			});
+			const exports = /* @__PURE__ */ new Set();
+			const imports = /* @__PURE__ */ new Set();
+			for (const statement of parsed.program.body) {
+				if (statement.type === "ExportDefaultDeclaration") exports.add("default");
+				if (statement.type === "ExportAllDeclaration") exports.add(statement.exported ? statement.exported.type === "Identifier" ? statement.exported.name : String(statement.exported.value) : "*");
+				if (statement.type !== "ExportNamedDeclaration") continue;
+				for (const specifier of statement.specifiers) exports.add(specifier.exported.type === "Identifier" ? specifier.exported.name : String(specifier.exported.value));
+				const declaration = statement.declaration;
+				if (declaration?.type === "VariableDeclaration") for (const item of declaration.declarations) for (const name of bindingNames(item.id)) exports.add(name);
+				else if (declaration && "id" in declaration && declaration.id?.type === "Identifier") exports.add(declaration.id.name);
+			}
+			const visit = (node) => {
+				if ((node.type === "ImportDeclaration" || node.type === "ExportNamedDeclaration" || node.type === "ExportAllDeclaration" || node.type === "TSImportType") && node.source) imports.add(String(node.source.value));
+				if (node.type === "ImportExpression" && node.source.type === "Literal" && typeof node.source.value === "string") imports.add(node.source.value);
+				if (node.type === "TSImportEqualsDeclaration" && node.moduleReference.type === "TSExternalModuleReference" && typeof node.moduleReference.expression.value === "string") imports.add(node.moduleReference.expression.value);
+				forEachChild(node, visit);
+			};
+			visit(parsed.program);
+			record.exports = [...exports].sort();
+			record.imports = [...imports].sort().map((specifier) => {
+				const resolved = (specifier.startsWith(".") ? [path.resolve(path.dirname(absolute), specifier)] : tsconfig ? resolvePathAlias(tsconfig, specifier) : []).map(probe).find((candidate) => candidate !== void 0);
+				return {
+					specifier,
+					file: resolved ? projectFile(cwd, resolved) : null
+				};
+			});
+		} catch (error) {
+			warnings.push({
+				code: null,
+				source: file,
+				message: String(error)
+			});
+		}
+		return record;
+	});
+	const byFile = new Map(files.map((file) => [file.file, file]));
+	for (const file of files) for (const imported of file.imports) if (imported.file) byFile.get(imported.file)?.importedBy.push(file.file);
+	for (const file of files) file.importedBy = [...new Set(file.importedBy)].sort();
+	return files;
+}
+
+//#endregion
+export { collectFiles, fileRole, projectFile };
+//# sourceMappingURL=collect-files.mjs.map

package/esm/tooling/inspect/collect-files.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"collect-files.mjs","names":[],"sources":["../../../../../../../../../packages/core/src/tooling/inspect/collect-files.ts"],"sourcesContent":["import { existsSync, readdirSync, readFileSync } from \"node:fs\";\nimport path from \"node:path\";\nimport { readTsconfig, resolvePathAlias } from \"get-tsconfig\";\nimport { parseSync, type Node } from \"oxc-parser\";\nimport {\n  isConfigFile,\n  isEventFile,\n  isLocaleFile,\n  isMainFile,\n  isRouteFile,\n  isWorkerFile,\n} from \"../../dev-server/special-file-patterns\";\nimport { forEachChild } from \"../syntax/ast\";\nimport type { InspectFile, InspectWarning } from \"./inspect-report.types\";\n\nconst CODE = /\\.(?:[cm]?[jt]s|[jt]sx)$/;\nconst EXTENSIONS = [\".ts\", \".tsx\", \".mts\", \".cts\", \".js\", \".jsx\", \".mjs\", \".cjs\", \".d.ts\"];\n\nexport function projectFile(cwd: string, file: string): string {\n  return path.relative(cwd, path.resolve(cwd, file)).split(path.sep).join(\"/\");\n}\n\n/** Infer a role from file names and the framework's directory conventions. */\nexport function fileRole(file: string): string {\n  const stem = path.posix.basename(file).replace(CODE, \"\");\n  if (/(?:^|\\.)(?:spec|test)$/.test(stem)) return \"spec\";\n  if (file.endsWith(\".d.ts\")) return \"type\";\n  if (isConfigFile(file)) return \"config\";\n  if (isRouteFile(file)) return \"routes\";\n  if (isMainFile(file)) return \"main\";\n  if (isWorkerFile(file)) return \"worker\";\n  if (isEventFile(file)) return \"event\";\n  if (isLocaleFile(file)) return \"locale\";\n  for (const role of [\"routes\", \"page\", \"setup\", \"layout\", \"root\"]) {\n    if (stem === role || stem.endsWith(`.${role}`)) return role;\n  }\n  for (const role of [\n    \"controller\",\n    \"service\",\n    \"repository\",\n    \"model\",\n    \"migration\",\n    \"schema\",\n    \"resource\",\n    \"hook\",\n    \"component\",\n    \"util\",\n    \"type\",\n    \"config\",\n  ]) {\n    if (\n      stem.endsWith(`.${role}`) ||\n      file.split(\"/\").includes(role === \"repository\" ? \"repositories\" : `${role}s`)\n    )\n      return role;\n  }\n  if (file.startsWith(\"src/config/\")) return \"config\";\n  if (file.split(\"/\").includes(\"utils\")) return \"util\";\n  if (/^use[A-Z]/.test(stem)) return \"hook\";\n  if (/\\.tsx$|\\.jsx$/.test(file)) return \"component\";\n  return \"source\";\n}\n\nfunction bindingNames(node: Node): string[] {\n  if (node.type === \"Identifier\") return [node.name];\n  if (node.type === \"ObjectPattern\")\n    return node.properties.flatMap((property) =>\n      bindingNames(property.type === \"RestElement\" ? property.argument : property.value),\n    );\n  if (node.type === \"ArrayPattern\")\n    return node.elements.flatMap((element) => (element ? bindingNames(element) : []));\n  if (node.type === \"AssignmentPattern\") return bindingNames(node.left);\n  if (node.type === \"RestElement\") return bindingNames(node.argument);\n  return [];\n}\n\n/** Read each source module once; never import or execute application code. */\nexport function collectFiles(cwd: string, warnings: InspectWarning[] = []): InspectFile[] {\n  cwd = path.resolve(cwd);\n  const paths: string[] = [];\n  const scan = (directory: string): void => {\n    if (!existsSync(directory)) return;\n    try {\n      for (const entry of readdirSync(directory, { withFileTypes: true })) {\n        const file = path.join(directory, entry.name);\n        if (entry.isDirectory()) scan(file);\n        else if (entry.isFile()) paths.push(file);\n      }\n    } catch (error) {\n      warnings.push({ code: null, source: projectFile(cwd, directory), message: String(error) });\n    }\n  };\n  scan(path.join(cwd, \"src\"));\n  paths.sort();\n  const known = new Set(paths);\n  let tsconfig: ReturnType<typeof readTsconfig> | undefined;\n  try {\n    if (existsSync(path.join(cwd, \"tsconfig.json\")))\n      tsconfig = readTsconfig(path.join(cwd, \"tsconfig.json\"), { typescriptVersion: false });\n  } catch (error) {\n    warnings.push({ code: null, source: \"tsconfig.json\", message: String(error) });\n  }\n  const probe = (base: string): string | undefined => {\n    const extension = path.extname(base);\n    const stem = /\\.[cm]?jsx?$/.test(extension) ? base.slice(0, -extension.length) : base;\n    const candidates = stem !== base ? EXTENSIONS.map((ext) => stem + ext) : [];\n    candidates.push(\n      base,\n      ...EXTENSIONS.map((ext) => base + ext),\n      ...EXTENSIONS.map((ext) => path.join(base, `index${ext}`)),\n    );\n    return candidates.find((candidate) => known.has(candidate));\n  };\n  const files = paths.map((absolute): InspectFile => {\n    const file = projectFile(cwd, absolute);\n    const parts = file.split(\"/\");\n    const record: InspectFile = {\n      file,\n      module:\n        parts[1] === \"app\" && parts.length > 3\n          ? parts.slice(0, 3).join(\"/\")\n          : path.posix.dirname(file).split(\"/\").slice(0, 2).join(\"/\"),\n      role: fileRole(file),\n      exports: [],\n      imports: [],\n      importedBy: [],\n    };\n    if (!CODE.test(file)) return record;\n    try {\n      const parsed = parseSync(absolute, readFileSync(absolute, \"utf8\"));\n      for (const error of parsed.errors)\n        warnings.push({ code: null, source: file, message: error.message });\n      const exports = new Set<string>();\n      const imports = new Set<string>();\n      for (const statement of parsed.program.body) {\n        if (statement.type === \"ExportDefaultDeclaration\") exports.add(\"default\");\n        if (statement.type === \"ExportAllDeclaration\")\n          exports.add(\n            statement.exported\n              ? statement.exported.type === \"Identifier\"\n                ? statement.exported.name\n                : String(statement.exported.value)\n              : \"*\",\n          );\n        if (statement.type !== \"ExportNamedDeclaration\") continue;\n        for (const specifier of statement.specifiers)\n          exports.add(\n            specifier.exported.type === \"Identifier\"\n              ? specifier.exported.name\n              : String(specifier.exported.value),\n          );\n        const declaration = statement.declaration;\n        if (declaration?.type === \"VariableDeclaration\") {\n          for (const item of declaration.declarations)\n            for (const name of bindingNames(item.id)) exports.add(name);\n        } else if (declaration && \"id\" in declaration && declaration.id?.type === \"Identifier\")\n          exports.add(declaration.id.name);\n      }\n      const visit = (node: Node): void => {\n        if (\n          (node.type === \"ImportDeclaration\" ||\n            node.type === \"ExportNamedDeclaration\" ||\n            node.type === \"ExportAllDeclaration\" ||\n            node.type === \"TSImportType\") &&\n          node.source\n        )\n          imports.add(String(node.source.value));\n        if (\n          node.type === \"ImportExpression\" &&\n          node.source.type === \"Literal\" &&\n          typeof node.source.value === \"string\"\n        )\n          imports.add(node.source.value);\n        if (\n          node.type === \"TSImportEqualsDeclaration\" &&\n          node.moduleReference.type === \"TSExternalModuleReference\" &&\n          typeof node.moduleReference.expression.value === \"string\"\n        )\n          imports.add(node.moduleReference.expression.value);\n        forEachChild(node, visit);\n      };\n      visit(parsed.program);\n      record.exports = [...exports].sort();\n      record.imports = [...imports].sort().map((specifier) => {\n        const bases = specifier.startsWith(\".\")\n          ? [path.resolve(path.dirname(absolute), specifier)]\n          : tsconfig\n            ? resolvePathAlias(tsconfig, specifier)\n            : [];\n        const resolved = bases.map(probe).find((candidate) => candidate !== undefined);\n        return { specifier, file: resolved ? projectFile(cwd, resolved) : null };\n      });\n    } catch (error) {\n      warnings.push({ code: null, source: file, message: String(error) });\n    }\n    return record;\n  });\n  const byFile = new Map(files.map((file) => [file.file, file]));\n  for (const file of files)\n    for (const imported of file.imports) {\n      if (imported.file) byFile.get(imported.file)?.importedBy.push(file.file);\n    }\n  for (const file of files) file.importedBy = [...new Set(file.importedBy)].sort();\n  return files;\n}\n"],"mappings":"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"}