@geoql/doctor-core 0.1.0-alpha.0 → 0.1.1

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/ARCHITECTURE.md`](../../docs/ARCHITECTURE.md):
 
-## 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/ARCHITECTURE.md`](../../docs/ARCHITECTURE.md) for the full two-pass design, the empirical oxlint findings that shaped it, and the canonical `Diagnostic` shape.
 
 ## License
 

package/dist/index.d.ts

@@ -1,6 +1,81 @@
+//#region src/score.d.ts
+interface ScoreBreakdownEntry {
+  ruleId: string;
+  occurrences: number;
+  weightPerOccurrence: number;
+  penalty: number;
+}
+interface ScoreResult {
+  score: number;
+  passed: boolean;
+  threshold: number;
+  totalFindings: number;
+  errorCount: number;
+  warnCount: number;
+  infoCount: number;
+  breakdown: ScoreBreakdownEntry[];
+}
+interface ScoreConfig {
+  rules?: Record<string, {
+    weight?: number;
+  }>;
+  threshold?: number;
+}
+declare function scoreDiagnostics(diagnostics: Diagnostic[], config?: ScoreConfig): ScoreResult;
+//#endregion
+//#region src/types/project-info.d.ts
+type Framework = 'vue' | 'nuxt' | 'unknown';
+type Capability = string;
+type MonorepoKind = 'pnpm' | 'yarn' | 'npm' | 'turbo' | null;
+interface ProjectInfo {
+  readonly framework: Framework;
+  readonly rootDirectory: string;
+  readonly packageJsonPath: string | null;
+  readonly vueVersion: string | null;
+  readonly nuxtVersion: string | null;
+  readonly typescriptVersion: string | null;
+  readonly hasAutoImports: boolean;
+  readonly hasComponentsAutoImport: boolean;
+  readonly hasPinia: boolean;
+  readonly hasVueRouter: boolean;
+  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
+//#region src/reporters/types.d.ts
+interface ProjectInfoLite {
+  readonly framework: Framework;
+  readonly vueVersion: string | null;
+  readonly nuxtVersion: string | null;
+  readonly capabilities: readonly string[];
+  readonly rootDirectory: string;
+}
+interface ReporterInput {
+  readonly toolName: string;
+  readonly toolVersion: string;
+  readonly rootDirectory: string;
+  readonly analyzedFileCount: number;
+  readonly elapsedMs: number;
+  readonly diagnostics: readonly Diagnostic[];
+  readonly score: ScoreResult;
+  readonly projectInfo: ProjectInfoLite;
+}
+interface ReporterOptions {
+  readonly color?: boolean;
+  readonly quiet?: boolean;
+}
+//#endregion
 //#region src/types.d.ts
-type Severity = 'error' | 'warning';
-type DiagnosticSource = 'template' | 'oxlint';
+type Severity = 'error' | 'warn' | 'info';
+type DiagnosticSource = 'template' | 'oxlint' | 'sfc' | 'dead-code' | 'project' | 'deps';
 interface Diagnostic {
   file: string;
   line: number;
@@ -12,13 +87,26 @@ interface Diagnostic {
   message: string;
   source: DiagnosticSource;
   recommendation?: string;
+  codeSnippet?: string;
 }
 interface AuditConfig {
   rootDir?: string;
   include?: string[];
   exclude?: string[];
   rules?: Record<string, Severity | 'off'>;
-  failOn?: Severity;
+  failOn?: 'error' | 'warn' | 'none';
+  deadCode?: boolean;
+  lint?: boolean;
+  threshold?: number;
+  scopeFiles?: string[];
+  respectInlineDisables?: boolean;
+}
+interface AuditTimings {
+  template: number;
+  sfc: number;
+  script: number;
+  deadCode: number;
+  total: number;
 }
 interface AuditReport {
   rootDir: string;
@@ -26,23 +114,305 @@ interface AuditReport {
   diagnostics: Diagnostic[];
   score: number;
   errorCount: number;
-  warningCount: number;
+  warnCount: number;
+  infoCount: number;
   exitCode: 0 | 1 | 2;
+  scoreResult: ScoreResult;
+  projectInfo: ProjectInfoLite;
+  elapsedMs: number;
+  timings: AuditTimings;
+  ruleCounts: Record<string, number>;
 }
 //#endregion
+//#region src/annotations.d.ts
+declare function encodeAnnotation(diagnostic: Diagnostic): string;
+declare function encodeAnnotations(diagnostics: Diagnostic[]): string;
+//#endregion
 //#region src/audit.d.ts
 declare function audit(config?: AuditConfig): Promise<AuditReport>;
 //#endregion
-//#region src/config.d.ts
-interface LoadedConfig {
-  config: AuditConfig;
+//#region src/check-build-quality.d.ts
+declare function checkBuildQuality(projectInfo: ProjectInfo): Promise<Diagnostic[]>;
+//#endregion
+//#region src/check-deps.d.ts
+declare function checkDeps(projectInfo: ProjectInfo): Promise<Diagnostic[]>;
+//#endregion
+//#region src/config/types.d.ts
+type ConfigSource = 'flag' | 'ts' | 'mjs' | 'js' | 'json' | 'package.json' | 'built-in';
+interface DoctorUserConfig {
+  rootDir?: string;
+  include?: string[];
+  exclude?: string[];
+  failOn?: 'error' | 'warn' | 'none';
+  threshold?: number;
+  preset?: string;
+  rules?: Record<string, Severity | 'off'>;
+  extends?: string[];
+}
+/**
+ * Resolved + normalized config that audit consumes.
+ * - `rules` is the merged effective severity map (preset base + user overrides - explicit offs).
+ * - `preset` is the preset name that was applied as the base.
+ */
+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;
 }
-declare function loadAuditConfig(rootDir: string, explicitPath?: string): Promise<LoadedConfig>;
+//#endregion
+//#region src/dead-code/dedupe.d.ts
+declare function dedupeDeadCodeAgainstLint(deadCode: Diagnostic[], lint: Diagnostic[]): Diagnostic[];
+//#endregion
+//#region src/dead-code/errors.d.ts
+declare class DeadCodeTimeoutError extends Error {
+  name: "DeadCodeTimeoutError";
+  constructor(timeoutMs: number);
+}
+declare class DeadCodeImportFailed extends Error {
+  name: "DeadCodeImportFailed";
+  constructor(cause?: unknown);
+}
+//#endregion
+//#region src/check-dead-code.d.ts
+interface CheckDeadCodeOptions {
+  projectInfo: ProjectInfo;
+  doctorConfig: ResolvedDoctorConfig;
+  enabled: boolean;
+  timeoutMs?: number;
+}
+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
+//#region src/config/merge-cli-overrides.d.ts
+interface CliOverrides {
+  include?: string[];
+  exclude?: string[];
+  failOn?: 'error' | 'warn' | 'none';
+  threshold?: number;
+  rules?: Record<string, Severity | 'off'>;
+}
+declare function mergeCliOverrides(resolved: ResolvedDoctorConfig, cli: CliOverrides): ResolvedDoctorConfig;
+//#endregion
+//#region src/config/errors.d.ts
+declare class ConfigFileNotFoundError extends Error {
+  name: "ConfigFileNotFoundError";
+  constructor(path: string);
+}
+declare class ConfigCycleError extends Error {
+  name: "ConfigCycleError";
+  constructor(chain: string[]);
+}
+declare class InvalidConfigError extends Error {
+  name: "InvalidConfigError";
+}
+//#endregion
+//#region src/config/define-config.d.ts
+declare function defineConfig<T extends DoctorUserConfig>(config: T): T;
+//#endregion
+//#region src/config/load.d.ts
+interface LoadDoctorConfigOptions {
+  readonly explicitPath?: string;
+  readonly presetOverride?: string;
+}
+declare function loadDoctorConfig(rootDir: string, explicitPathOrOptions?: string | LoadDoctorConfigOptions): Promise<ResolvedDoctorConfig>;
+//#endregion
+//#region src/config/validate.d.ts
+declare function validateConfig(raw: unknown): void;
+//#endregion
+//#region src/detect-project.d.ts
+declare function detectProject(rootDirectory: string): Promise<ProjectInfo>;
+//#endregion
+//#region src/disables/apply.d.ts
+interface ApplyInlineDisablesOptions {
+  respect: boolean;
+}
+declare function applyInlineDisables(diags: Diagnostic[], opts: ApplyInlineDisablesOptions): Diagnostic[];
+//#endregion
+//#region src/disables/parse-directives.d.ts
+interface DirectiveRange {
+  start: number;
+  end: number;
+  rules: string[];
+}
+interface DirectiveLine {
+  line: number;
+  rules: string[];
+}
+interface DirectiveSet {
+  blocks: DirectiveRange[];
+  nextLine: DirectiveLine[];
+  sameLine: DirectiveLine[];
+}
+declare function parseDirectives(text: string): DirectiveSet;
+//#endregion
+//#region src/git-scope.d.ts
+type GitScopeMode = 'diff' | 'staged';
+interface GitScopeOptions {
+  rootDir: string;
+  mode: GitScopeMode;
+}
+declare function listChangedFiles(options: GitScopeOptions): Promise<string[]>;
+//#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";
+  constructor(exitCode: number | null, stderr: string);
+}
+declare class OxlintOutputTooLarge extends Error {
+  name: "OxlintOutputTooLarge";
+  constructor(maxBytes: number);
+}
+//#endregion
+//#region src/reporters/agent.d.ts
+declare function agentReport(input: ReporterInput, options?: ReporterOptions): string;
+//#endregion
+//#region src/reporters/docs-url.d.ts
+declare function docsUrl(ruleId: string): string;
+//#endregion
+//#region src/reporters/sarif.d.ts
+declare function sarifReport(input: ReporterInput): string;
+//#endregion
+//#region src/reporters/verbose.d.ts
+interface VerboseTraceOptions {
+  configSource?: ConfigSource;
+}
+declare function renderVerboseTrace(report: AuditReport, options: VerboseTraceOptions): string;
 //#endregion
 //#region src/reporters/index.d.ts
-type ReporterFormat = 'text' | 'json';
-declare function format(report: AuditReport, kind: ReporterFormat): string;
+type ReporterFormat = 'agent' | 'pretty' | 'json' | 'json-compact' | 'sarif' | 'html';
+declare function format(input: ReporterInput, kind?: ReporterFormat, options?: ReporterOptions): string;
+//#endregion
+//#region src/reporters/json.d.ts
+declare const DOCTOR_REPORT_SCHEMA_VERSION = "1";
+interface DoctorReportDiagnostic {
+  file: string;
+  line: number;
+  column: number;
+  endLine?: number;
+  endColumn?: number;
+  ruleId: string;
+  severity: Severity;
+  message: string;
+  source: string;
+  recommendation?: string;
+}
+interface DoctorReportBreakdownEntry {
+  ruleId: string;
+  occurrences: number;
+  weightPerOccurrence: number;
+  penalty: number;
+}
+interface DoctorReport {
+  schemaVersion: string;
+  tool: {
+    name: string;
+    version: string;
+  };
+  projectInfo: {
+    framework: string;
+    vueVersion: string | null;
+    nuxtVersion: string | null;
+    capabilities: string[];
+    rootDirectory: string;
+  };
+  score: {
+    value: number;
+    threshold: number;
+    passed: boolean;
+    bySeverity: {
+      error: number;
+      warn: number;
+      info: number;
+    };
+    breakdown: DoctorReportBreakdownEntry[];
+  };
+  diagnostics: DoctorReportDiagnostic[];
+  timing: {
+    elapsedMs: number;
+    analyzedFileCount: number;
+  };
+}
+declare function buildDoctorReport(input: ReporterInput): DoctorReport;
+declare function jsonReport(input: ReporterInput): string;
+//#endregion
+//#region src/reporters/json-compact.d.ts
+declare function jsonCompactReport(input: ReporterInput): string;
+//#endregion
+//#region src/reporters/pretty.d.ts
+declare function prettyReport(input: ReporterInput, options?: ReporterOptions): string;
+//#endregion
+//#region src/rule-docs.d.ts
+interface RuleDoc {
+  readonly id: string;
+  readonly title: string;
+  readonly severity: string;
+  readonly category: string;
+  readonly recommended: boolean;
+  readonly source: string;
+  readonly helpUri: string;
+  readonly description: string;
+  readonly hasOverride: boolean;
+}
+interface LoadRuleDocOptions {
+  readonly docsRoot?: string;
+}
+declare function loadRuleDoc(ruleId: string, options?: LoadRuleDocOptions): RuleDoc | null;
+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' | 'structure' | 'modules-deps' | 'nitro' | 'seo' | 'cloudflare' | 'server-routes' | 'hydration' | 'data-fetching';
+type RuleSource = 'doctor' | 'oxlint-builtin' | 'eslint-plugin-vue';
+interface RegisteredRule {
+  readonly id: string;
+  readonly severity: Severity;
+  readonly category: RuleCategory;
+  readonly source: RuleSource;
+  readonly recommended: boolean;
+}
+declare const RULE_REGISTRY: readonly RegisteredRule[];
+interface ListRulesFilter {
+  readonly preset?: 'recommended' | 'all';
+  readonly category?: RuleCategory;
+  readonly source?: RuleSource;
+  readonly severity?: Severity;
+}
+declare function listRules(filter?: ListRulesFilter): RegisteredRule[];
 //#endregion
-export { type AuditConfig, type AuditReport, type Diagnostic, type DiagnosticSource, type ReporterFormat, type Severity, audit, format, loadAuditConfig };
+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 };
 //# sourceMappingURL=index.d.ts.map