@geoql/doctor-core 0.2.0-alpha.0 → 1.0.0

package/README.md

@@ -1,34 +1,94 @@
 # `@geoql/doctor-core`
 
-> Audit engine shared by [`@geoql/vue-doctor`](../vue-doctor) and (future) `@geoql/nuxt-doctor`.
+> The audit engine behind [`@geoql/vue-doctor`](../vue-doctor) and [`@geoql/nuxt-doctor`](../nuxt-doctor).
 
-Implements the **hybrid two-pass design** locked in [`docs/ARCHITECTURE.md`](../../docs/ARCHITECTURE.md):
+This is the library that does the work. The two CLIs are thin `cac` wrappers; everything real lives here: the hybrid scan, scoring, reporters, config loading, and project detection. You usually depend on a CLI, not on this package directly. Reach for `doctor-core` only when you're embedding the audit into your own tool.
 
-1. **Template pass** — parses `.vue` SFCs with `@vue/compiler-sfc` and walks the template AST for rules that need template-level context (e.g. `v-for` missing `:key`).
-2. **Script pass** — spawns `oxlint` as a subprocess with a generated `.oxlintrc.json` that activates oxlint's built-in `vue` plugin AND a custom `jsPlugins` entry (`@geoql/oxlint-plugin-vue-doctor`).
+## What it does
 
-Diagnostics from both passes are merged, deduped, and fed into a deterministic 0–100 score.
+`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:
 
-## Usage (programmatic)
+- **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.
+
+Diagnostics from both passes are merged and deduped on `(file, line, column, ruleId)`, then collapsed into a deterministic 0–100 score. Scoring uses fixed severity weights (`error` = 5, `warn` = 2, `info` = 0.5) with √-decay on repeat offenders so one noisy rule can't tank the whole score. Same code in, same score out: no randomness, no config-tunable weights.
+
+It also owns the pieces the CLIs surface: the config loader (`doctor.config.ts` via `c12`), project/capability detection used to gate rules, the rule registry, and every reporter format.
+
+## Install
+
+```sh
+npm i @geoql/doctor-core
+```
+
+Published on [npm](https://www.npmjs.com/package/@geoql/doctor-core) and [JSR](https://jsr.io/@geoql/doctor-core) at `v0.1.0` with provenance. ESM-only. `knip` and `oxlint` are peer dependencies (the dead-code and script passes shell out to them).
+
+## API
+
+The main entry is `audit()`. It returns a report carrying diagnostics, the numeric score, the score breakdown, detected project info, and a process exit code.
 
 ```ts
-import { audit } from '@geoql/doctor-core';
+import { audit, format } from '@geoql/doctor-core';
 
 const report = await audit({
   rootDir: process.cwd(),
   include: ['**/*.vue', '**/*.ts'],
+  exclude: ['node_modules', 'dist', '.nuxt', '.output'],
   failOn: 'error',
 });
 
-for (const diag of report.diagnostics) {
+for (const d of report.diagnostics) {
   console.log(
-    `${diag.file}:${diag.line}:${diag.column} ${diag.severity} ${diag.ruleId}: ${diag.message}`,
+    `${d.file}:${d.line}:${d.column} ${d.severity} ${d.ruleId}: ${d.message}`,
   );
 }
+
 console.log(`Score: ${report.score}/100`);
+console.log(`Exit code: ${report.exitCode}`);
+
+// Render any reporter format. `format()` takes a ReporterInput,
+// which you assemble from the report.
+process.stdout.write(
+  format(
+    {
+      toolName: '@geoql/vue-doctor',
+      toolVersion: '0.1.0',
+      rootDirectory: report.rootDir,
+      analyzedFileCount: report.filesScanned,
+      elapsedMs: report.elapsedMs,
+      diagnostics: report.diagnostics,
+      score: report.scoreResult,
+      projectInfo: report.projectInfo,
+    },
+    'agent',
+  ),
+);
 ```
 
-Most users should depend on `@geoql/vue-doctor` (the CLI) rather than this package directly.
+Severity is `error | warn | info` throughout. `failOn` accepts `error | warn | none`.
+
+### Key exports
+
+| Export                                                  | Purpose                                                                           |
+| ------------------------------------------------------- | --------------------------------------------------------------------------------- |
+| `audit`                                                 | Run the two-pass scan and return the full report.                                 |
+| `format`                                                | Render a report as `agent`, `pretty`, `json`, `json-compact`, `sarif`, or `html`. |
+| `loadDoctorConfig`, `defineConfig`, `mergeCliOverrides` | Load `doctor.config.ts` (via `c12`) and layer CLI overrides on top.               |
+| `detectProject`                                         | Detect framework, versions, and capability tokens used to gate rules.             |
+| `listRules`, `RULE_REGISTRY`, `loadRuleDoc`             | Inspect the rule registry and per-rule docs.                                      |
+| `scoreDiagnostics`                                      | Deterministic 0–100 scoring with the breakdown.                                   |
+| `listChangedFiles`                                      | Resolve diff/staged file scopes for incremental runs.                             |
+| `encodeAnnotations`                                     | Emit GitHub Actions `::error::` / `::warning::` lines.                            |
+
+Types ship alongside (`AuditConfig`, `AuditReport`, `Diagnostic`, `Severity`, `ReporterFormat`, `ProjectInfo`, `ScoreResult`, and more).
+
+## Scope
+
+Vue 3 and Nuxt 4 only. Nuxt detection expects the `app/` directory layout with `compatibilityVersion: 4`.
+
+## Architecture
+
+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

@@ -41,6 +41,12 @@ interface ProjectInfo {
   readonly nitroPreset: string | null;
   readonly nuxtCompatibilityVersion: 3 | 4 | null;
   readonly monorepoKind: MonorepoKind;
+  readonly nuxtConfigPath: string | null;
+  readonly hasAppDir: boolean;
+  readonly appDirPath: string | null;
+  readonly hasServerDir: boolean;
+  readonly hasPagesDir: boolean;
+  readonly hasWranglerConfig: boolean;
   readonly capabilities: ReadonlySet<Capability>;
 }
 //#endregion
@@ -94,6 +100,8 @@ interface AuditConfig {
   threshold?: number;
   scopeFiles?: string[];
   respectInlineDisables?: boolean;
+  fix?: boolean;
+  fixExcludes?: string[];
 }
 interface AuditTimings {
   template: number;
@@ -142,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.
@@ -182,6 +203,9 @@ interface CheckDeadCodeOptions {
 }
 declare function checkDeadCode(options: CheckDeadCodeOptions): Promise<Diagnostic[]>;
 //#endregion
+//#region src/check-nuxt-project.d.ts
+declare function checkNuxtProject(projectInfo: ProjectInfo): Promise<Diagnostic[]>;
+//#endregion
 //#region src/config/built-in.d.ts
 declare const BUILT_IN_RECOMMENDED: Omit<ResolvedDoctorConfig, 'rootDir' | 'source' | 'configFile'>;
 //#endregion
@@ -192,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
@@ -224,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;
@@ -255,6 +325,38 @@ 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
+ * `pages/` (Nuxt 3 layout) or `app/pages/` (Nuxt 4 layout) at the project root.
+ */
+declare function isNuxtPageFile(relPath: string): boolean;
+/**
+ * True when the path points at a Nitro server file — a `.ts` file under the
+ * project-root `server/` directory.
+ */
+declare function isNuxtServerFile(relPath: string): boolean;
+/**
+ * True when the path points at a Nuxt layout component — a `.vue` file under
+ * `layouts/` (Nuxt 3 layout) or `app/layouts/` (Nuxt 4 layout) at the project
+ * root.
+ */
+declare function isNuxtLayoutFile(relPath: string): boolean;
+//#endregion
+//#region src/nuxt/cross-file/run.d.ts
+interface CrossFilePassOptions {
+  files: string[];
+  projectInfo: ProjectInfo;
+}
+declare function runCrossFilePass(opts: CrossFilePassOptions): Promise<Diagnostic[]>;
+//#endregion
 //#region src/oxlint/errors.d.ts
 declare class OxlintSpawnFailed extends Error {
   name: "OxlintSpawnFailed";
@@ -281,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
@@ -340,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
@@ -362,7 +467,7 @@ declare function loadRuleDoc(ruleId: string, options?: LoadRuleDocOptions): Rule
 declare function loadAllRuleDocs(options?: LoadRuleDocOptions): RuleDoc[];
 //#endregion
 //#region src/rule-registry.d.ts
-type RuleCategory = 'ai-slop' | 'reactivity' | 'composition' | 'performance' | 'template' | 'template-perf' | 'build-quality' | 'deps' | 'dead-code' | 'sfc' | 'vue-builtin';
+type RuleCategory = 'ai-slop' | 'reactivity' | 'composition' | 'performance' | 'template' | 'template-perf' | 'build-quality' | 'deps' | 'dead-code' | 'sfc' | 'vue-builtin' | 'structure' | 'modules-deps' | 'nitro' | 'seo' | 'cloudflare' | 'server-routes' | 'hydration' | 'data-fetching';
 type RuleSource = 'doctor' | 'oxlint-builtin' | 'eslint-plugin-vue';
 interface RegisteredRule {
   readonly id: string;
@@ -380,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, dedupeDeadCodeAgainstLint, defineConfig, detectProject, docsUrl, encodeAnnotation, encodeAnnotations, format, jsonCompactReport, jsonReport, listChangedFiles, listRules, loadAllRuleDocs, loadDoctorConfig, loadRuleDoc, mergeCliOverrides, parseDirectives, prettyReport, renderVerboseTrace, 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