@geoql/doctor-core 0.1.1 → 1.0.0

package/README.md

@@ -6,7 +6,7 @@ This is the library that does the work. The two CLIs are thin `cac` wrappers; ev
 
 ## What it does
 
-`doctor-core` runs a **hybrid two-pass scan** over a Vue 3 or Nuxt 4 project, as locked in [`docs/ARCHITECTURE.md`](../../docs/ARCHITECTURE.md):
+`doctor-core` runs a **hybrid two-pass scan** over a Vue 3 or Nuxt 4 project, as locked in [`docs/SPEC.md`](../../docs/SPEC.md) §10:
 
 - **Pass 1 — template AST.** Parses `.vue` SFCs with `@vue/compiler-sfc` and walks the template AST in-process. This is the only pass that can see the template, so template-shaped rules (`v-for` missing `:key`, `v-if`/`v-for` on the same node, inline object props in lists) live here.
 - **Pass 2 — script ESTree.** Spawns `oxlint` as a subprocess against a generated `.oxlintrc.json` that turns on oxlint's native `vue` plugin plus the doctor JS plugins (`@geoql/oxlint-plugin-vue-doctor`, `@geoql/oxlint-plugin-nuxt-doctor`). oxlint only hands JS plugins the extracted `<script>`, so all script-level rules run here.
@@ -88,7 +88,7 @@ Vue 3 and Nuxt 4 only. Nuxt detection expects the `app/` directory layout with `
 
 ## Architecture
 
-See [`docs/ARCHITECTURE.md`](../../docs/ARCHITECTURE.md) for the full two-pass design, the empirical oxlint findings that shaped it, and the canonical `Diagnostic` shape.
+See [`docs/SPEC.md`](../../docs/SPEC.md) §10 for the full two-pass design, the empirical oxlint findings that shaped it, and the canonical `Diagnostic` shape.
 
 ## License
 

package/dist/index.d.ts

@@ -100,6 +100,8 @@ interface AuditConfig {
   threshold?: number;
   scopeFiles?: string[];
   respectInlineDisables?: boolean;
+  fix?: boolean;
+  fixExcludes?: string[];
 }
 interface AuditTimings {
   template: number;
@@ -148,6 +150,19 @@ interface DoctorUserConfig {
   preset?: string;
   rules?: Record<string, Severity | 'off'>;
   extends?: string[];
+  fixExcludes?: string[];
+}
+interface ResolvedDoctorConfig {
+  rootDir: string;
+  include: string[];
+  exclude: string[];
+  failOn: 'error' | 'warn' | 'none';
+  threshold: number;
+  rules: Record<string, Severity>;
+  preset: 'minimal' | 'recommended' | 'strict' | 'all';
+  source: ConfigSource;
+  configFile?: string;
+  fixExcludes?: string[];
 }
 /**
  * Resolved + normalized config that audit consumes.
@@ -201,6 +216,7 @@ interface CliOverrides {
   failOn?: 'error' | 'warn' | 'none';
   threshold?: number;
   rules?: Record<string, Severity | 'off'>;
+  fixExcludes?: string[];
 }
 declare function mergeCliOverrides(resolved: ResolvedDoctorConfig, cli: CliOverrides): ResolvedDoctorConfig;
 //#endregion
@@ -233,6 +249,51 @@ declare function validateConfig(raw: unknown): void;
 //#region src/detect-project.d.ts
 declare function detectProject(rootDirectory: string): Promise<ProjectInfo>;
 //#endregion
+//#region src/init/index.d.ts
+type InitConfigFormat = 'ts' | 'json' | 'package-json';
+type InitPreset = 'recommended' | 'strict' | 'minimal';
+interface RawInitAnswers {
+  target?: InitConfigFormat;
+  preset?: InitPreset;
+  threshold?: number;
+  exclude?: string;
+}
+interface ResolvedInitAnswers {
+  configFormat: InitConfigFormat;
+  preset: InitPreset;
+  threshold: number | undefined;
+  exclude: string[] | undefined;
+}
+interface InitOptions {
+  dir: string;
+  configFormat: InitConfigFormat;
+  preset: InitPreset;
+  threshold: number | undefined;
+  exclude: string[] | undefined;
+  binName: string;
+}
+interface InitFileWrite {
+  path: string;
+  content: string;
+}
+interface InitPlan {
+  writes: InitFileWrite[];
+  conflict: boolean;
+  conflictPath: string | null;
+}
+declare function parseExcludeList(raw: string | undefined): string[] | undefined;
+declare function normalizeInitAnswers(raw: RawInitAnswers): ResolvedInitAnswers;
+declare function renderDetectSummary(project: ProjectInfo, sfcCount: number): string;
+declare function detectSummary(dir: string): Promise<string>;
+declare function planInit(options: InitOptions): Promise<InitPlan>;
+//#endregion
+//#region src/project-info/find-monorepo-root.d.ts
+interface MonorepoResult {
+  root: string;
+  kind: MonorepoKind;
+}
+declare function findMonorepoRoot(rootDirectory: string): Promise<MonorepoResult>;
+//#endregion
 //#region src/disables/apply.d.ts
 interface ApplyInlineDisablesOptions {
   respect: boolean;
@@ -264,6 +325,13 @@ interface GitScopeOptions {
 }
 declare function listChangedFiles(options: GitScopeOptions): Promise<string[]>;
 //#endregion
+//#region src/project-info/list-workspace-packages.d.ts
+interface WorkspacePackage {
+  name: string;
+  dir: string;
+}
+declare function listWorkspacePackages(rootDir: string): Promise<WorkspacePackage[]>;
+//#endregion
 //#region src/nuxt/file-role.d.ts
 /**
  * True when the path points at a Nuxt page component — a `.vue` file under
@@ -315,7 +383,7 @@ interface VerboseTraceOptions {
 declare function renderVerboseTrace(report: AuditReport, options: VerboseTraceOptions): string;
 //#endregion
 //#region src/reporters/index.d.ts
-type ReporterFormat = 'agent' | 'pretty' | 'json' | 'json-compact' | 'sarif' | 'html';
+type ReporterFormat = 'agent' | 'pretty' | 'json' | 'json-compact' | 'sarif' | 'html' | 'pr-comment';
 declare function format(input: ReporterInput, kind?: ReporterFormat, options?: ReporterOptions): string;
 //#endregion
 //#region src/reporters/json.d.ts
@@ -374,6 +442,9 @@ declare function jsonReport(input: ReporterInput): string;
 //#region src/reporters/json-compact.d.ts
 declare function jsonCompactReport(input: ReporterInput): string;
 //#endregion
+//#region src/reporters/pr-comment.d.ts
+declare function prCommentReport(input: ReporterInput): string;
+//#endregion
 //#region src/reporters/pretty.d.ts
 declare function prettyReport(input: ReporterInput, options?: ReporterOptions): string;
 //#endregion
@@ -414,5 +485,5 @@ interface ListRulesFilter {
 }
 declare function listRules(filter?: ListRulesFilter): RegisteredRule[];
 //#endregion
-export { type ApplyInlineDisablesOptions, type AuditConfig, type AuditReport, type AuditTimings, BUILT_IN_RECOMMENDED, type Capability, type CliOverrides, ConfigCycleError, ConfigFileNotFoundError, type ConfigSource, DOCTOR_REPORT_SCHEMA_VERSION, DeadCodeImportFailed, DeadCodeTimeoutError, type Diagnostic, type DiagnosticSource, type DirectiveLine, type DirectiveRange, type DirectiveSet, type DoctorReport, type DoctorUserConfig, type Framework, type GitScopeMode, InvalidConfigError, type ListRulesFilter, type LoadRuleDocOptions, type MonorepoKind, OxlintOutputTooLarge, OxlintSpawnFailed, type ProjectInfo, type ProjectInfoLite, RULE_REGISTRY, type RegisteredRule, type ReporterFormat, type ReporterInput, type ReporterOptions, type ResolvedDoctorConfig, type RuleCategory, type RuleDoc, type RuleSource, type ScoreBreakdownEntry, type ScoreConfig, type ScoreResult, type Severity, type VerboseTraceOptions, agentReport, applyInlineDisables, audit, buildDoctorReport, checkBuildQuality, checkDeadCode, checkDeps, checkNuxtProject, dedupeDeadCodeAgainstLint, defineConfig, detectProject, docsUrl, encodeAnnotation, encodeAnnotations, format, isNuxtLayoutFile, isNuxtPageFile, isNuxtServerFile, jsonCompactReport, jsonReport, listChangedFiles, listRules, loadAllRuleDocs, loadDoctorConfig, loadRuleDoc, mergeCliOverrides, parseDirectives, prettyReport, renderVerboseTrace, runCrossFilePass, sarifReport, scoreDiagnostics, validateConfig };
+export { type ApplyInlineDisablesOptions, type AuditConfig, type AuditReport, type AuditTimings, BUILT_IN_RECOMMENDED, type Capability, type CliOverrides, ConfigCycleError, ConfigFileNotFoundError, type ConfigSource, DOCTOR_REPORT_SCHEMA_VERSION, DeadCodeImportFailed, DeadCodeTimeoutError, type Diagnostic, type DiagnosticSource, type DirectiveLine, type DirectiveRange, type DirectiveSet, type DoctorReport, type DoctorUserConfig, type Framework, type GitScopeMode, type InitConfigFormat, type InitFileWrite, type InitOptions, type InitPlan, type InitPreset, InvalidConfigError, type ListRulesFilter, type LoadRuleDocOptions, type MonorepoKind, type MonorepoResult, OxlintOutputTooLarge, OxlintSpawnFailed, type ProjectInfo, type ProjectInfoLite, RULE_REGISTRY, type RawInitAnswers, type RegisteredRule, type ReporterFormat, type ReporterInput, type ReporterOptions, type ResolvedDoctorConfig, type ResolvedInitAnswers, type RuleCategory, type RuleDoc, type RuleSource, type ScoreBreakdownEntry, type ScoreConfig, type ScoreResult, type Severity, type VerboseTraceOptions, type WorkspacePackage, agentReport, applyInlineDisables, audit, buildDoctorReport, checkBuildQuality, checkDeadCode, checkDeps, checkNuxtProject, dedupeDeadCodeAgainstLint, defineConfig, detectProject, detectSummary, docsUrl, encodeAnnotation, encodeAnnotations, findMonorepoRoot, format, isNuxtLayoutFile, isNuxtPageFile, isNuxtServerFile, jsonCompactReport, jsonReport, listChangedFiles, listRules, listWorkspacePackages, loadAllRuleDocs, loadDoctorConfig, loadRuleDoc, mergeCliOverrides, normalizeInitAnswers, parseDirectives, parseExcludeList, planInit, prCommentReport, prettyReport, renderDetectSummary, renderVerboseTrace, runCrossFilePass, sarifReport, scoreDiagnostics, validateConfig };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -1,4 +1,4 @@
-import { a as listRules, c as InvalidConfigError, i as RULE_REGISTRY, l as BUILT_IN_RECOMMENDED, o as ConfigCycleError, r as validateConfig, s as ConfigFileNotFoundError, t as loadDoctorConfig } from "./load-BGjurxpY.js";
+import { a as listRules, c as InvalidConfigError, i as RULE_REGISTRY, l as BUILT_IN_RECOMMENDED, o as ConfigCycleError, r as validateConfig, s as ConfigFileNotFoundError, t as loadDoctorConfig } from "./load-yXDi-5ti.js";
 import { dirname, join, relative, resolve } from "node:path";
 import { performance } from "node:perf_hooks";
 import { access, mkdir, mkdtemp, readFile, readdir, rm, writeFile } from "node:fs/promises";
@@ -215,6 +215,7 @@ async function checkBuildQuality(projectInfo) {
 //#region src/dead-code/build-knip-config.ts
 function buildKnipConfig(projectInfo, doctorConfig) {
 	const isNuxt = projectInfo.framework === "nuxt";
+	const usesConventionResolution = projectInfo.hasAutoImports || projectInfo.hasComponentsAutoImport || projectInfo.hasVueRouter;
 	const entry = isNuxt ? [
 		"app/**/*.vue",
 		"app/**/*.ts",
@@ -224,7 +225,14 @@ function buildKnipConfig(projectInfo, doctorConfig) {
 		"src/main.{ts,js}",
 		"src/App.vue",
 		"index.html",
-		"vite.config.{ts,js}"
+		"vite.config.{ts,js}",
+		...usesConventionResolution ? [
+			"src/pages/**/*.vue",
+			"src/layouts/**/*.vue",
+			"src/components/**/*.vue",
+			"src/composables/**/*.ts",
+			"src/stores/**/*.ts"
+		] : []
 	];
 	const config = {
 		cwd: projectInfo.rootDirectory,
@@ -381,6 +389,20 @@ const _knipLoader = { load: async () => {
 		run: runModule.run
 	};
 } };
+async function writeKnipConfig(rootDir, config) {
+	const cacheDir = join(rootDir, "node_modules", ".cache", "doctor");
+	await mkdir(cacheDir, { recursive: true });
+	const configPath = join(cacheDir, "knip.json");
+	const knipJson = {
+		entry: config.entry,
+		project: config.project,
+		ignore: config.ignoreFiles,
+		ignoreDependencies: config.ignoreDependencies
+	};
+	if (config.compilers) knipJson.compilers = config.compilers;
+	await writeFile(configPath, JSON.stringify(knipJson, null, 2), "utf8");
+	return configPath;
+}
 async function checkDeadCode(options) {
 	if (!options.enabled) return [];
 	const config = buildKnipConfig(options.projectInfo, options.doctorConfig);
@@ -394,13 +416,10 @@ async function checkDeadCode(options) {
 	} catch (err) {
 		throw new DeadCodeImportFailed(err);
 	}
+	const configPath = await writeKnipConfig(options.projectInfo.rootDirectory, config);
 	const knipOptions = await createOptions({
 		cwd: options.projectInfo.rootDirectory,
-		entry: config.entry,
-		project: config.project,
-		ignoreFiles: config.ignoreFiles,
-		ignoreDependencies: config.ignoreDependencies,
-		...config.compilers ? { compilers: config.compilers } : {}
+		args: { config: configPath }
 	});
 	const diagnostics = flattenKnipIssues((await Promise.race([run(knipOptions), new Promise((_, reject) => setTimeout(() => reject(new DeadCodeTimeoutError(timeoutMs)), timeoutMs))])).results.issues).map((issue) => mapKnipDiagnostic(options.projectInfo.rootDirectory, issue)).filter((d) => d !== null);
 	diagnostics.sort((a, b) => {
@@ -1347,6 +1366,23 @@ function toCanonicalDiagnostics(raws, rootDir) {
 const VUE_DEFAULT_RULES = {
 	"vue/no-export-in-script-setup": "error",
 	"vue/require-typed-ref": "warn",
+	"vue/no-arrow-functions-in-watch": "error",
+	"vue/no-deprecated-data-object-declaration": "error",
+	"vue/no-deprecated-events-api": "error",
+	"vue/no-deprecated-destroyed-lifecycle": "error",
+	"vue/no-deprecated-model-definition": "error",
+	"vue/no-deprecated-delete-set": "error",
+	"vue/no-deprecated-vue-config-keycodes": "error",
+	"vue/no-lifecycle-after-await": "error",
+	"vue/no-this-in-before-route-enter": "error",
+	"vue/return-in-computed-property": "error",
+	"vue/valid-define-emits": "error",
+	"vue/valid-define-props": "error",
+	"vue/no-required-prop-with-default": "warn",
+	"vue/prefer-import-from-vue": "warn",
+	"vue/no-import-compiler-macros": "warn",
+	"vue/no-multiple-slot-args": "warn",
+	"vue/require-default-export": "warn",
 	"vue-doctor/no-em-dash-in-string": "warn",
 	"vue-doctor/no-non-null-assertion-on-ref-value": "warn",
 	"vue-doctor/no-imports-from-vue-when-auto-imported": "warn",
@@ -1369,6 +1405,27 @@ const NUXT_PLUGIN_RULES = {
 const VUE_OXLINT_RULE_IDS = new Set([
 	"vue/no-export-in-script-setup",
 	"vue/require-typed-ref",
+	"vue/no-arrow-functions-in-watch",
+	"vue/no-deprecated-data-object-declaration",
+	"vue/no-deprecated-events-api",
+	"vue/no-deprecated-destroyed-lifecycle",
+	"vue/no-deprecated-model-definition",
+	"vue/no-deprecated-delete-set",
+	"vue/no-deprecated-vue-config-keycodes",
+	"vue/no-lifecycle-after-await",
+	"vue/no-this-in-before-route-enter",
+	"vue/return-in-computed-property",
+	"vue/valid-define-emits",
+	"vue/valid-define-props",
+	"vue/no-required-prop-with-default",
+	"vue/prefer-import-from-vue",
+	"vue/no-import-compiler-macros",
+	"vue/no-multiple-slot-args",
+	"vue/require-default-export",
+	"vue/define-emits-declaration",
+	"vue/define-props-declaration",
+	"vue/define-props-destructuring",
+	"vue/max-props",
 	"vue-doctor/no-em-dash-in-string",
 	"vue-doctor/no-destructure-props-without-to-refs",
 	"vue-doctor/no-destructure-reactive-without-to-refs",
@@ -1543,9 +1600,10 @@ async function runOxlint(opts) {
 			"-c",
 			opts.configPath,
 			"--format",
-			"json",
-			opts.targetPath
+			"json"
 		];
+		if (opts.fix) args.push("--fix");
+		args.push(opts.targetPath);
 		const child = spawn(opts.oxlintBin, args, {
 			cwd: opts.rootDir,
 			stdio: [
@@ -1647,7 +1705,8 @@ async function runScriptPass(opts) {
 			targetPath: opts.targetPath,
 			configPath,
 			oxlintBin,
-			timeoutMs: opts.timeoutMs
+			timeoutMs: opts.timeoutMs,
+			fix: opts.fix
 		});
 		return {
 			diagnostics: toCanonicalDiagnostics(raw.diagnostics, opts.rootDir),
@@ -2618,7 +2677,9 @@ async function audit(config = {}) {
 			rootDir,
 			targetPath: rootDir,
 			ruleOverrides: config.rules,
-			framework: project.framework === "nuxt" ? "nuxt" : "vue"
+			framework: project.framework === "nuxt" ? "nuxt" : "vue",
+			fix: config.fix === true && config.scopeFiles === void 0,
+			fixExcludes: config.fixExcludes
 		});
 		scriptDiagnostics = result.diagnostics;
 		oxlintStderr = result.stderr;
@@ -2632,7 +2693,7 @@ async function audit(config = {}) {
 	if (config.deadCode !== false) {
 		const deadCodeStart = performance.now();
 		try {
-			const { loadDoctorConfig } = await import("./load-BGjurxpY.js").then((n) => n.n);
+			const { loadDoctorConfig } = await import("./load-yXDi-5ti.js").then((n) => n.n);
 			deadCodeDiagnostics = dedupeDeadCodeAgainstLint(await checkDeadCode({
 				projectInfo: project,
 				doctorConfig: await loadDoctorConfig(rootDir),
@@ -2751,7 +2812,111 @@ function mergeCliOverrides(resolved, cli) {
 		threshold: cli.threshold ?? resolved.threshold,
 		rules,
 		source: resolved.source,
-		configFile: resolved.configFile
+		configFile: resolved.configFile,
+		...cli.fixExcludes ?? resolved.fixExcludes ? { fixExcludes: cli.fixExcludes ?? resolved.fixExcludes } : {}
+	};
+}
+//#endregion
+//#region src/init/index.ts
+function parseExcludeList(raw) {
+	if (!raw) return void 0;
+	const parts = raw.split(",").map((entry) => entry.trim()).filter((entry) => entry.length > 0);
+	return parts.length > 0 ? parts : void 0;
+}
+function normalizeInitAnswers(raw) {
+	return {
+		configFormat: raw.target ?? "ts",
+		preset: raw.preset ?? "recommended",
+		threshold: typeof raw.threshold === "number" ? raw.threshold : void 0,
+		exclude: parseExcludeList(raw.exclude)
+	};
+}
+function frameworkLabel(project) {
+	if (project.framework === "nuxt") return `Nuxt ${project.nuxtVersion ?? "unknown"}`;
+	if (project.framework === "vue") return `Vue ${project.vueVersion ?? "unknown"}`;
+	return "unknown project";
+}
+function renderDetectSummary(project, sfcCount) {
+	const ts = project.capabilities.has("typescript") ? " · TS" : "";
+	const noun = sfcCount === 1 ? "SFC" : "SFCs";
+	return `detected: ${frameworkLabel(project)}${ts} · ${sfcCount} ${noun}`;
+}
+async function detectSummary(dir) {
+	return renderDetectSummary(await detectProject(dir), (await listSourceFiles({
+		rootDir: dir,
+		include: ["**/*.vue"],
+		exclude: ["**/node_modules/**"]
+	})).length);
+}
+function buildUserConfig(options) {
+	const config = { preset: options.preset };
+	if (options.threshold !== void 0) config.threshold = options.threshold;
+	if (options.exclude && options.exclude.length > 0) config.exclude = options.exclude;
+	return config;
+}
+function renderTsConfig(options) {
+	const config = buildUserConfig(options);
+	const lines = [
+		"import { defineConfig } from '@geoql/doctor-core';",
+		"",
+		"export default defineConfig({",
+		`  preset: '${config.preset}',`
+	];
+	if (config.threshold !== void 0) lines.push(`  threshold: ${config.threshold},`);
+	if (config.exclude) {
+		const globs = config.exclude.map((glob) => `'${glob}'`).join(", ");
+		lines.push(`  exclude: [${globs}],`);
+	}
+	lines.push("});");
+	return `${lines.join("\n")}\n`;
+}
+function renderJsonConfig(options) {
+	return `${JSON.stringify(buildUserConfig(options), null, 2)}\n`;
+}
+async function readPackageJsonRaw(path) {
+	try {
+		return JSON.parse(await readFile(path, "utf8"));
+	} catch {
+		return null;
+	}
+}
+async function planInit(options) {
+	const writes = [];
+	const packageJsonPath = join(options.dir, "package.json");
+	const pkg = { ...await readPackageJsonRaw(packageJsonPath) ?? {} };
+	let conflict = false;
+	let conflictPath = null;
+	if (options.configFormat === "package-json") {
+		if (pkg.doctor !== void 0) {
+			conflict = true;
+			conflictPath = packageJsonPath;
+		}
+		pkg.doctor = buildUserConfig(options);
+	} else {
+		const fileName = options.configFormat === "ts" ? "doctor.config.ts" : "doctor.config.json";
+		const configPath = join(options.dir, fileName);
+		if (await pathExists(configPath)) {
+			conflict = true;
+			conflictPath = configPath;
+		}
+		const content = options.configFormat === "ts" ? renderTsConfig(options) : renderJsonConfig(options);
+		writes.push({
+			path: configPath,
+			content
+		});
+	}
+	pkg.scripts = {
+		...pkg.scripts ?? {},
+		"doctor:check": options.binName
+	};
+	writes.push({
+		path: packageJsonPath,
+		content: `${JSON.stringify(pkg, null, 2)}\n`
+	});
+	return {
+		writes,
+		conflict,
+		conflictPath
 	};
 }
 //#endregion
@@ -2798,6 +2963,47 @@ async function listChangedFiles(options) {
 	return [...new Set(absolute)].sort();
 }
 //#endregion
+//#region src/project-info/list-workspace-packages.ts
+function parsePackageGlobs(yaml) {
+	const globs = [];
+	let inPackages = false;
+	for (const raw of yaml.split("\n")) {
+		if (!inPackages) {
+			if (/^packages:/.test(raw)) inPackages = true;
+			continue;
+		}
+		const item = raw.match(/^\s*-\s*(.+?)\s*$/);
+		if (item) {
+			globs.push(item[1].replace(/^['"]|['"]$/g, ""));
+			continue;
+		}
+		if (raw.trim() === "") continue;
+		break;
+	}
+	return globs;
+}
+async function listWorkspacePackages(rootDir) {
+	const { root, kind } = await findMonorepoRoot(rootDir);
+	if (kind !== "pnpm") return [];
+	const manifests = await glob(parsePackageGlobs(await readFile(join(root, "pnpm-workspace.yaml"), "utf8")).map((g) => `${g}/package.json`), {
+		cwd: root,
+		absolute: true,
+		onlyFiles: true,
+		dot: false
+	});
+	const packages = [];
+	for (const manifest of manifests) {
+		const dir = dirname(manifest);
+		const pkg = await readPackageJson(dir);
+		if (pkg?.name) packages.push({
+			name: pkg.name,
+			dir
+		});
+	}
+	packages.sort((a, b) => a.name.localeCompare(b.name));
+	return packages;
+}
+//#endregion
 //#region src/reporters/docs-url.ts
 function docsUrl(ruleId) {
 	return `https://docs.doctor.geoql.in/rules/${ruleId}`;
@@ -3162,6 +3368,53 @@ function jsonCompactReport(input) {
 	return `${JSON.stringify(buildDoctorReport(input))}\n`;
 }
 //#endregion
+//#region src/reporters/pr-comment.ts
+const DOCS_BASE = "https://docs.doctor.geoql.in/rules/";
+const MAX_PER_SECTION = 5;
+function binName(toolName) {
+	return toolName.replace("@geoql/", "");
+}
+function relativeLocation(diag, rootDirectory) {
+	return `${relative(rootDirectory, diag.file).replaceAll("\\", "/")}:${diag.line}`;
+}
+function findingLine(diag, rootDirectory) {
+	return `- \`${relativeLocation(diag, rootDirectory)}\` ${diag.ruleId} — ${diag.message}`;
+}
+function sortBySeverityFilter(diagnostics, severity, rootDirectory) {
+	return diagnostics.filter((d) => d.severity === severity).sort((a, b) => {
+		const byFile = compareStrings(relative(rootDirectory, a.file).replaceAll("\\", "/"), relative(rootDirectory, b.file).replaceAll("\\", "/"));
+		if (byFile !== 0) return byFile;
+		if (a.line !== b.line) return a.line - b.line;
+		if (a.column !== b.column) return a.column - b.column;
+		return compareStrings(a.ruleId, b.ruleId);
+	});
+}
+function section(title, diagnostics, rootDirectory) {
+	if (diagnostics.length === 0) return [];
+	const lines = ["", `### ${title}`];
+	for (const d of diagnostics.slice(0, MAX_PER_SECTION)) lines.push(findingLine(d, rootDirectory));
+	return lines;
+}
+function prCommentReport(input) {
+	const score = input.score.score;
+	const header = `## 🛡 ${input.toolName} — Score: ${score}`;
+	const errors = sortBySeverityFilter(input.diagnostics, "error", input.rootDirectory);
+	const warnings = sortBySeverityFilter(input.diagnostics, "warn", input.rootDirectory);
+	const actionable = errors.length + warnings.length;
+	if (actionable === 0) return `${header}\n\n✓ No actionable findings. Score: ${score}\n`;
+	const topRule = (errors[0] ?? warnings[0]).ruleId;
+	return `${[
+		header,
+		"",
+		`**${actionable} findings** (${errors.length} errors, ${warnings.length} warnings)`,
+		...section("Errors", errors, input.rootDirectory),
+		...section("Warnings", warnings, input.rootDirectory),
+		"",
+		"---",
+		`[View the docs](${DOCS_BASE}) · Run \`${binName(input.toolName)} explain ${topRule}\` for details.`
+	].join("\n")}\n`;
+}
+//#endregion
 //#region src/reporters/pretty.ts
 const colors = pc.createColors(true);
 const colorTheme = {
@@ -3212,9 +3465,10 @@ function format(input, kind = "agent", options) {
 	if (kind === "json-compact") return jsonCompactReport(input);
 	if (kind === "sarif") return sarifReport(input);
 	if (kind === "html") return htmlReport(input);
+	if (kind === "pr-comment") return prCommentReport(input);
 	return agentReport(input, options);
 }
 //#endregion
-export { BUILT_IN_RECOMMENDED, ConfigCycleError, ConfigFileNotFoundError, DOCTOR_REPORT_SCHEMA_VERSION, DeadCodeImportFailed, DeadCodeTimeoutError, InvalidConfigError, OxlintOutputTooLarge, OxlintSpawnFailed, RULE_REGISTRY, agentReport, applyInlineDisables, audit, buildDoctorReport, checkBuildQuality, checkDeadCode, checkDeps, checkNuxtProject, dedupeDeadCodeAgainstLint, defineConfig, detectProject, docsUrl, encodeAnnotation, encodeAnnotations, format, isNuxtLayoutFile, isNuxtPageFile, isNuxtServerFile, jsonCompactReport, jsonReport, listChangedFiles, listRules, loadAllRuleDocs, loadDoctorConfig, loadRuleDoc, mergeCliOverrides, parseDirectives, prettyReport, renderVerboseTrace, runCrossFilePass, sarifReport, scoreDiagnostics, validateConfig };
+export { BUILT_IN_RECOMMENDED, ConfigCycleError, ConfigFileNotFoundError, DOCTOR_REPORT_SCHEMA_VERSION, DeadCodeImportFailed, DeadCodeTimeoutError, InvalidConfigError, OxlintOutputTooLarge, OxlintSpawnFailed, RULE_REGISTRY, agentReport, applyInlineDisables, audit, buildDoctorReport, checkBuildQuality, checkDeadCode, checkDeps, checkNuxtProject, dedupeDeadCodeAgainstLint, defineConfig, detectProject, detectSummary, docsUrl, encodeAnnotation, encodeAnnotations, findMonorepoRoot, format, isNuxtLayoutFile, isNuxtPageFile, isNuxtServerFile, jsonCompactReport, jsonReport, listChangedFiles, listRules, listWorkspacePackages, loadAllRuleDocs, loadDoctorConfig, loadRuleDoc, mergeCliOverrides, normalizeInitAnswers, parseDirectives, parseExcludeList, planInit, prCommentReport, prettyReport, renderDetectSummary, renderVerboseTrace, runCrossFilePass, sarifReport, scoreDiagnostics, validateConfig };
 
 //# sourceMappingURL=index.js.map