@geoql/doctor-core 1.1.0 → 1.2.0

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+import { z } from "zod";
+
 //#region src/score.d.ts
 interface ScoreBreakdownEntry {
   ruleId: string;
@@ -139,46 +141,102 @@ declare function checkBuildQuality(projectInfo: ProjectInfo): Promise<Diagnostic
 //#region src/check-deps.d.ts
 declare function checkDeps(projectInfo: ProjectInfo): Promise<Diagnostic[]>;
 //#endregion
+//#region src/config/schema.d.ts
+/**
+ * A rule severity level as accepted in user config. `off` disables a rule
+ * (removing it from the resolved preset base); the other three mirror the
+ * internal {@link import('../types.js').Severity} vocabulary.
+ */
+declare const LevelSchema: z.ZodEnum<{
+  error: "error";
+  warn: "warn";
+  info: "info";
+  off: "off";
+}>;
+/**
+ * The accepted shape of a single `rules` entry. Doctor config only ever takes
+ * a bare severity string (no `[level, options]` tuple, no `{ level }` object) —
+ * this matches the historical hand-rolled validator exactly.
+ */
+declare const RuleEntrySchema: z.ZodEnum<{
+  error: "error";
+  warn: "warn";
+  info: "info";
+  off: "off";
+}>;
+/**
+ * The single source of truth for doctor config validation. Wraps the base
+ * object in a `superRefine` that rejects any unknown rule id with a
+ * `rules.<id>` path, so a typo'd rule surfaces as an `InvalidConfigError`
+ * rather than silently doing nothing.
+ */
+declare const DoctorUserConfigSchema: z.ZodObject<{
+  $schema: z.ZodOptional<z.ZodString>;
+  rootDir: z.ZodOptional<z.ZodString>;
+  include: z.ZodOptional<z.ZodArray<z.ZodString>>;
+  exclude: z.ZodOptional<z.ZodArray<z.ZodString>>;
+  failOn: z.ZodOptional<z.ZodEnum<{
+    error: "error";
+    warn: "warn";
+    none: "none";
+  }>>;
+  threshold: z.ZodOptional<z.ZodInt>;
+  preset: z.ZodOptional<z.ZodEnum<{
+    minimal: "minimal";
+    recommended: "recommended";
+    strict: "strict";
+    all: "all";
+  }>>;
+  extends: z.ZodOptional<z.ZodArray<z.ZodString>>;
+  fixExcludes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+  rules: z.ZodOptional<z.ZodObject<{
+    [x: string]: z.ZodOptional<z.ZodEnum<{
+      error: "error";
+      warn: "warn";
+      info: "info";
+      off: "off";
+    }>>;
+  }, z.core.$catchall<z.ZodOptional<z.ZodEnum<{
+    error: "error";
+    warn: "warn";
+    info: "info";
+    off: "off";
+  }>>>>>;
+}, z.core.$loose>;
+/** The inferred user-config type — the single source of truth for the shape. */
+type DoctorUserConfigInput = z.infer<typeof DoctorUserConfigSchema>;
+/**
+ * Generate the JSON Schema for the user config. Built from the base object
+ * (not the refined wrapper) so `z.toJSONSchema` emits the full property set,
+ * including every enumerated rule id. The result is what gets written to
+ * `schema.json` and served from the docs site.
+ */
+declare function buildJsonSchema(): Record<string, unknown>;
+//#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[];
-  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[];
-}
+type ConfigSource = 'flag' | 'ts' | 'mjs' | 'js' | 'json' | 'jsonc' | 'package.json' | 'built-in';
+/**
+ * User-authored config shape, inferred from {@link DoctorUserConfigSchema} so
+ * the zod schema is the single source of truth for the accepted fields.
+ */
+type DoctorUserConfig = DoctorUserConfigInput;
 /**
- * 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.
+ * Resolved + normalized config that audit consumes. `failOn` and `preset` are
+ * narrowed from the schema-derived user shape; `rules` is the merged effective
+ * severity map (preset base + user overrides minus explicit offs), so it never
+ * carries `'off'`.
  */
 interface ResolvedDoctorConfig {
   rootDir: string;
   include: string[];
   exclude: string[];
-  failOn: 'error' | 'warn' | 'none';
+  failOn: NonNullable<DoctorUserConfig['failOn']>;
   threshold: number;
   rules: Record<string, Severity>;
-  preset: 'minimal' | 'recommended' | 'strict' | 'all';
+  preset: NonNullable<DoctorUserConfig['preset']>;
   source: ConfigSource;
   configFile?: string;
+  fixExcludes?: string[];
 }
 //#endregion
 //#region src/dead-code/dedupe.d.ts
@@ -231,6 +289,8 @@ declare class ConfigCycleError extends Error {
 }
 declare class InvalidConfigError extends Error {
   name: "InvalidConfigError";
+  readonly issues: readonly z.core.$ZodIssue[];
+  constructor(message: string, issues?: readonly z.core.$ZodIssue[]);
 }
 //#endregion
 //#region src/config/define-config.d.ts
@@ -244,6 +304,12 @@ interface LoadDoctorConfigOptions {
 declare function loadDoctorConfig(rootDir: string, explicitPathOrOptions?: string | LoadDoctorConfigOptions): Promise<ResolvedDoctorConfig>;
 //#endregion
 //#region src/config/validate.d.ts
+/**
+ * Validate a raw, untrusted config object against the zod schema — the single
+ * source of truth. Throws {@link InvalidConfigError} (carrying the full zod
+ * issue list) on the first failure, mirroring the legacy validator's
+ * throw-on-first-error contract.
+ */
 declare function validateConfig(raw: unknown): void;
 //#endregion
 //#region src/detect-project.d.ts
@@ -466,8 +532,22 @@ interface LoadRuleDocOptions {
 declare function loadRuleDoc(ruleId: string, options?: LoadRuleDocOptions): RuleDoc | null;
 declare function loadAllRuleDocs(options?: LoadRuleDocOptions): RuleDoc[];
 //#endregion
+//#region src/rule-prompt.d.ts
+/**
+ * Render a self-contained "fix + validate" markdown recipe for a single rule.
+ * Returns `null` for an unknown rule id. Pure: derives everything from the
+ * rule's `RuleDoc` (id, severity, category, source, recommended, helpUri).
+ */
+declare function renderRulePrompt(ruleId: string): string | null;
+/**
+ * Render the canonical agent playbook: the scan → filter → triage → fix →
+ * validate loop an AI agent follows when cleaning up doctor diagnostics. Pure
+ * markdown; fetched on demand by the agent skill at runtime.
+ */
+declare function renderAgentPlaybook(): string;
+//#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 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' | 'security' | 'design';
 type RuleSource = 'doctor' | 'oxlint-builtin' | 'eslint-plugin-vue';
 interface RegisteredRule {
   readonly id: string;
@@ -485,6 +565,29 @@ interface ListRulesFilter {
 }
 declare function listRules(filter?: ListRulesFilter): RegisteredRule[];
 //#endregion
+//#region src/audit-filter.d.ts
+/**
+ * Filter `report.diagnostics` to a known set of allowed rule ids, then
+ * recompute `score`, `errorCount`, `warnCount`, `infoCount`, `scoreResult`,
+ * `ruleCounts`, and `exitCode` from the filtered array.
+ *
+ * Why: the CLI layer calls `audit()` and then applies its own
+ * `allowedRuleIds` filter to drop suppressed (`off`) and preset-excluded
+ * (`info` rules not in `recommended`) diagnostics. The audit's own
+ * `score`/`counts` are computed BEFORE the CLI filter, so they still
+ * include the suppressed findings. That desync surfaces to consumers
+ * (the SaaS `--push` payload, the dashboard's counts-but-no-findings bug)
+ * and to the `score` itself (suppressed findings still penalize).
+ *
+ * Invariant enforced here:
+ *   report.errorCount + report.warnCount + report.infoCount === report.diagnostics.length
+ *   report.scoreResult.totalFindings === report.diagnostics.length
+ *
+ * `exitCode=2` (oxlint crash) is preserved verbatim; `exitCode=1` is
+ * recomputed from the surviving counts + the `failOn` gate.
+ */
+declare function filterReportByRules(report: AuditReport, allowedRuleIds: ReadonlySet<string>, failOn?: 'error' | 'warn' | 'none', oxlintStderr?: string): AuditReport;
+//#endregion
 //#region src/push.d.ts
 /**
  * The 6 fields the SaaS receives for each finding.
@@ -519,6 +622,8 @@ interface PushOptions {
   warnCount: number;
   infoCount: number;
   diagnostics: Diagnostic[];
+  /** Project root used to relativize absolute finding file paths. */
+  rootDir?: string;
   url: string;
   apiKey: string;
   fetchImpl?: typeof fetch;
@@ -538,8 +643,11 @@ type PushResult = {
  * Strip a list of Diagnostics down to the 6 allowed push fields.
  * Privacy boundary: this function is the single point of enforcement.
  * If you add a new privacy-sensitive field to Diagnostic, add it to the deny list here.
+ *
+ * Absolute file paths are relativized against rootDir so dashboards show
+ * `src/Foo.vue` rather than the CI runner's `/home/runner/work/<repo>/…`.
  */
-declare function stripFindings(diagnostics: Diagnostic[]): PushedFinding[];
+declare function stripFindings(diagnostics: Diagnostic[], rootDir?: string): PushedFinding[];
 /**
  * Build the top-level POST body. CI fields (commitSha, branch, prNumber) are
  * included ONLY when the matching GITHUB_* env var is set.
@@ -552,5 +660,5 @@ declare function buildPushPayload(input: PushPayloadInput): PushPayload;
  */
 declare function pushFindings(opts: PushOptions): Promise<PushResult>;
 //#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, 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, type PushOptions, type PushPayload, type PushPayloadInput, type PushResult, type PushedFinding, 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, buildPushPayload, 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, pushFindings, renderDetectSummary, renderVerboseTrace, runCrossFilePass, sarifReport, scoreDiagnostics, stripFindings, 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 DoctorUserConfigInput, DoctorUserConfigSchema, type Framework, type GitScopeMode, type InitConfigFormat, type InitFileWrite, type InitOptions, type InitPlan, type InitPreset, InvalidConfigError, LevelSchema, type ListRulesFilter, type LoadRuleDocOptions, type MonorepoKind, type MonorepoResult, OxlintOutputTooLarge, OxlintSpawnFailed, type ProjectInfo, type ProjectInfoLite, type PushOptions, type PushPayload, type PushPayloadInput, type PushResult, type PushedFinding, RULE_REGISTRY, type RawInitAnswers, type RegisteredRule, type ReporterFormat, type ReporterInput, type ReporterOptions, type ResolvedDoctorConfig, type ResolvedInitAnswers, type RuleCategory, type RuleDoc, RuleEntrySchema, type RuleSource, type ScoreBreakdownEntry, type ScoreConfig, type ScoreResult, type Severity, type VerboseTraceOptions, type WorkspacePackage, agentReport, applyInlineDisables, audit, buildDoctorReport, buildJsonSchema, buildPushPayload, checkBuildQuality, checkDeadCode, checkDeps, checkNuxtProject, dedupeDeadCodeAgainstLint, defineConfig, detectProject, detectSummary, docsUrl, encodeAnnotation, encodeAnnotations, filterReportByRules, findMonorepoRoot, format, isNuxtLayoutFile, isNuxtPageFile, isNuxtServerFile, jsonCompactReport, jsonReport, listChangedFiles, listRules, listWorkspacePackages, loadAllRuleDocs, loadDoctorConfig, loadRuleDoc, mergeCliOverrides, normalizeInitAnswers, parseDirectives, parseExcludeList, planInit, prCommentReport, prettyReport, pushFindings, renderAgentPlaybook, renderDetectSummary, renderRulePrompt, renderVerboseTrace, runCrossFilePass, sarifReport, scoreDiagnostics, stripFindings, validateConfig };
 //# sourceMappingURL=index.d.ts.map