@geoql/doctor-core

中文文档
1.9.0发布于 2026/11/04MITTypeScriptES Module构建来源已验证近 30 天下载 7906

Audit engine for @geoql/vue-doctor and @geoql/nuxt-doctor. Hybrid two-pass: @vue/compiler-sfc template AST + oxlint subprocess. TypeScript, ESM.

原始使用文档
文档目录7 节
  1. What it does
  2. Install
  3. API
  4. Key exports
  5. Scope
  6. Architecture
  7. License

@geoql/doctor-core

The audit engine behind @geoql/vue-doctor and @geoql/nuxt-doctor.

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.

What it does

doctor-core runs a hybrid two-pass scan over a Vue 3 or Nuxt 4 project, as locked in 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.

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

npm i @geoql/doctor-core

Published on npm and JSR 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.

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 d of report.diagnostics) {
  console.log(
    `${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',
  ),
);

Severity is error | warn | info throughout. failOn accepts error | warn | none.

Key exports

ExportPurpose
auditRun the two-pass scan and return the full report.
formatRender a report as agent, pretty, json, json-compact, sarif, or html.
loadDoctorConfig, defineConfig, mergeCliOverridesLoad doctor.config.ts (via c12) and layer CLI overrides on top.
detectProjectDetect framework, versions, and capability tokens used to gate rules.
listRules, RULE_REGISTRY, loadRuleDocInspect the rule registry and per-rule docs.
scoreDiagnosticsDeterministic 0–100 scoring with the breakdown.
listChangedFilesResolve diff/staged file scopes for incremental runs.
encodeAnnotationsEmit 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 §10 for the full two-pass design, the empirical oxlint findings that shaped it, and the canonical Diagnostic shape.

License

MIT © Vinayak Kulkarni

版本与发布记录

@geoql/doctor-core 共发布 25 个版本,首次发布于 2026/05/29;过去 12 个月发布了 25 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
1.9.0latest2026/11/0412 天前
1.8.42026/11/0412 天前
1.8.32026/10/2818 天前
1.8.22026/09/122 个月前
1.8.12026/07/283 个月前
1.8.02026/07/273 个月前

其他发布通道:alpha → 0.2.0-alpha.0。

关于 @geoql/doctor-core 的常见问题

@geoql/doctor-core 是什么?

Audit engine for @geoql/vue-doctor and @geoql/nuxt-doctor. Hybrid two-pass: @vue/compiler-sfc template AST + oxlint subprocess. TypeScript, ESM.

如何安装 @geoql/doctor-core?

在项目目录运行 npm install @geoql/doctor-core,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:knip(^6.14.2)、oxlint(^1.66.0)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@geoql/doctor-core 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@geoql/doctor-core 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@geoql/doctor-core 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >=24。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@geoql/doctor-core 可以商用吗?

@geoql/doctor-core 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@geoql/doctor-core 的下载量有多少?

根据 npm 官方下载统计,@geoql/doctor-core 在 2026/10/16 – 2026/11/14 这 30 天内被下载 7,906 次,日均约 264 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@geoql/doctor-core 还在维护吗?

最新版本 1.9.0 发布于 2026/11/04(12 天前);至今共发布 25 个版本,其中过去 12 个月发布了 25 个;首次发布于 2026/05/29。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。