fix(core): relativize pushed finding paths + point docs urls at docs.the-doctor.report

Two dashboard-facing bugs in the findings push pipeline:

1. stripFindings forwarded the auditor's absolute file paths, so the
   SaaS dashboard rendered CI runner internals like
   /home/runner/work/v-clappr/v-clappr/src/… for every finding.
   stripFindings now takes the project rootDir and relativizes
   absolute paths against it (paths outside rootDir stay untouched
   rather than escaping via ../). Both CLIs pass rootDir through.

2. docsUrl still pointed at the dead docs.doctor.geoql.in domain
   (DNS no longer resolves) — the dashboard's per-rule docs links
   404'd before even reaching the docs site. Now
   docs.the-doctor.report, matching the live docs deployment.

Signed-off-by: Vinayak Kulkarni <19776877+vinayakkulkarni@users.noreply.github.com>

Author: vinayakkulkarni

README.md

@@ -2,49 +2,104 @@
 
 > Your agent writes bad Vue/Nuxt. This catches it.
 
-A pair of CLIs and oxlint plugins that audit Vue 3 + Nuxt 4 apps for performance, correctness, security, and AI-agent anti-patterns. It does not scaffold or generate — it _critiques_ the code your agent just wrote and gives it a deterministic health score.
+[![npm](https://img.shields.io/npm/v/@geoql/vue-doctor?label=vue-doctor)](https://www.npmjs.com/package/@geoql/vue-doctor)
+[![npm](https://img.shields.io/npm/v/@geoql/nuxt-doctor?label=nuxt-doctor)](https://www.npmjs.com/package/@geoql/nuxt-doctor)
+[![JSR](https://jsr.io/badges/@geoql/vue-doctor)](https://jsr.io/@geoql/vue-doctor)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
 
-**Documentation:** [docs.the-doctor.report](https://docs.the-doctor.report)
+## What is this?
+
+A pnpm monorepo of CLIs and oxlint plugins that audit Vue 3 and Nuxt 4 apps for performance, correctness, security, and AI-agent anti-patterns. It does not scaffold or generate. It critiques the code your agent just wrote and gives it a deterministic 0-100 health score. The audit runs fully local and offline: same code in, same score out.
+
+Full docs, rule reference, config, and scoring live at [docs.the-doctor.report](https://docs.the-doctor.report).
+
+## Ecosystem
+
+| Repo                       | What                            | Link                                                                     |
+| -------------------------- | ------------------------------- | ------------------------------------------------------------------------ |
+| `geoql/doctor` (this repo) | OSS CLIs + oxlint rule plugins  | [github.com/geoql/doctor](https://github.com/geoql/doctor)               |
+| `geoql/doctor-action`      | GitHub Action wrapper           | [github.com/geoql/doctor-action](https://github.com/geoql/doctor-action) |
+| `the-doctor.report`        | Hosted SaaS dashboard (private) | [app.the-doctor.report](https://app.the-doctor.report)                   |
+| Docs                       | Rules, CLI, scoring reference   | [docs.the-doctor.report](https://docs.the-doctor.report)                 |
 
 ## Packages
 
-| Package                                                                  | Description                      | Version                                                                                                                                 |
-| ------------------------------------------------------------------------ | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
-| [`@geoql/doctor-core`](packages/doctor-core)                             | Audit engine, scoring, reporters | [![npm](https://img.shields.io/npm/v/@geoql/doctor-core)](https://www.npmjs.com/package/@geoql/doctor-core)                             |
-| [`@geoql/oxlint-plugin-vue-doctor`](packages/oxlint-plugin-vue-doctor)   | oxlint JS plugin: Vue 3 rules    | [![npm](https://img.shields.io/npm/v/@geoql/oxlint-plugin-vue-doctor)](https://www.npmjs.com/package/@geoql/oxlint-plugin-vue-doctor)   |
-| [`@geoql/oxlint-plugin-nuxt-doctor`](packages/oxlint-plugin-nuxt-doctor) | oxlint JS plugin: Nuxt 4 rules   | [![npm](https://img.shields.io/npm/v/@geoql/oxlint-plugin-nuxt-doctor)](https://www.npmjs.com/package/@geoql/oxlint-plugin-nuxt-doctor) |
-| [`@geoql/vue-doctor`](packages/vue-doctor)                               | CLI: `npx -y @geoql/vue-doctor`  | [![npm](https://img.shields.io/npm/v/@geoql/vue-doctor)](https://www.npmjs.com/package/@geoql/vue-doctor)                               |
-| [`@geoql/nuxt-doctor`](packages/nuxt-doctor)                             | CLI: `npx -y @geoql/nuxt-doctor` | [![npm](https://img.shields.io/npm/v/@geoql/nuxt-doctor)](https://www.npmjs.com/package/@geoql/nuxt-doctor)                             |
+| Package                                                                  | Version                                                                                                                                 | Description                                                |
+| ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
+| [`@geoql/doctor-core`](packages/doctor-core)                             | [![npm](https://img.shields.io/npm/v/@geoql/doctor-core)](https://www.npmjs.com/package/@geoql/doctor-core)                             | Audit engine: scoring, reporters, hybrid two-pass analysis |
+| [`@geoql/vue-doctor`](packages/vue-doctor)                               | [![npm](https://img.shields.io/npm/v/@geoql/vue-doctor)](https://www.npmjs.com/package/@geoql/vue-doctor)                               | CLI for Vue 3 projects                                     |
+| [`@geoql/nuxt-doctor`](packages/nuxt-doctor)                             | [![npm](https://img.shields.io/npm/v/@geoql/nuxt-doctor)](https://www.npmjs.com/package/@geoql/nuxt-doctor)                             | CLI for Nuxt 4 projects                                    |
+| [`@geoql/oxlint-plugin-vue-doctor`](packages/oxlint-plugin-vue-doctor)   | [![npm](https://img.shields.io/npm/v/@geoql/oxlint-plugin-vue-doctor)](https://www.npmjs.com/package/@geoql/oxlint-plugin-vue-doctor)   | oxlint JS plugin: Vue 3 rules                              |
+| [`@geoql/oxlint-plugin-nuxt-doctor`](packages/oxlint-plugin-nuxt-doctor) | [![npm](https://img.shields.io/npm/v/@geoql/oxlint-plugin-nuxt-doctor)](https://www.npmjs.com/package/@geoql/oxlint-plugin-nuxt-doctor) | oxlint JS plugin: Nuxt 4 rules                             |
+
+The two CLIs ship at `1.1.1`, published on [npm](https://www.npmjs.com/org/geoql) and [JSR](https://jsr.io/@geoql) with OIDC provenance.
 
 ## Quick start
 
 ```sh
-# Audit a Vue 3 project
+# Audit a Vue 3 project (npm)
 npx -y @geoql/vue-doctor
 
-# Audit a Nuxt 4 project
+# Audit a Nuxt 4 project (npm)
 npx -y @geoql/nuxt-doctor
+
+# Run from JSR (Deno)
+deno run -A jsr:@geoql/vue-doctor
+deno run -A jsr:@geoql/nuxt-doctor
 ```
 
-## Documentation
+Both CLIs print a health score with grouped diagnostics and exit non-zero when findings breach your `--fail-on` threshold, so they drop straight into CI.
+
+## Monorepo layout
+
+```
+geoql/doctor/
+├── packages/
+│   ├── doctor-core/                  # @geoql/doctor-core — audit engine
+│   ├── vue-doctor/                   # @geoql/vue-doctor — Vue 3 CLI
+│   ├── nuxt-doctor/                  # @geoql/nuxt-doctor — Nuxt 4 CLI
+│   ├── oxlint-plugin-vue-doctor/     # Vue 3 oxlint rules
+│   ├── oxlint-plugin-nuxt-doctor/    # Nuxt 4 oxlint rules
+│   └── benchmark/                    # perf workspace (not published)
+├── apps/docs/                        # docs.the-doctor.report (Nuxt)
+└── docs/SPEC.md                      # the locked spec
+```
+
+## CLI flags
+
+Both `vue-doctor` and `nuxt-doctor` share the same surface. Key flags:
 
-Full docs — rules, CLI reference, config, and scoring — live at **[docs.the-doctor.report](https://docs.the-doctor.report)**.
+| Flag                             | Purpose                                                                                        |
+| -------------------------------- | ---------------------------------------------------------------------------------------------- |
+| `--preset <name>`                | Base preset: `minimal` \| `recommended` \| `strict` \| `all`                                   |
+| `--format <kind>`                | `agent` (default) \| `pretty` \| `json` \| `json-compact` \| `sarif` \| `html` \| `pr-comment` |
+| `--fail-on <level>`              | Exit non-zero on `error` \| `warn` \| `none` (default `error`)                                 |
+| `--threshold <n>`                | Minimum passing score 0-100                                                                    |
+| `--rule <id:level>`              | Override one rule (repeatable), e.g. `--rule a/b:off`                                          |
+| `--fix`                          | Auto-fix oxlint-pass findings in place (full scan only)                                        |
+| `--diff` / `--staged` / `--full` | Scope to changed, staged, or all files                                                         |
+| `--score`                        | Print only the integer score                                                                   |
+| `--output <file>`                | Write the report to a file                                                                     |
+| `--pr-comment`                   | Emit a Markdown PR-comment body                                                                |
+| `--push`                         | POST privacy-stripped findings to the SaaS (needs `--api-key`)                                 |
+| `--push-url <url>`               | Findings endpoint (default `https://app.the-doctor.report/api/v1/findings`)                    |
+| `--api-key <key>`                | the-doctor.report API key (`doc_…`), sent as the `x-api-key` header                            |
+| `--push-project <slug>`          | Dashboard project slug, e.g. `owner/repo` (defaults to the audited dir name)                   |
 
-Both CLIs run a deterministic audit, print a health score (0–100) with grouped
-diagnostics, and exit non-zero when findings breach your `--fail-on` threshold —
-so they drop straight into CI. See the [docs](https://docs.the-doctor.report)
-for flags (`--fix`, `--ci`, `--sarif`, `--json`, presets) and the full rule set.
+Subcommands: `list-rules`, `explain <ruleId>`, `inspect [dir]`, `init [dir]`. Run `vue-doctor --help` for the complete list.
 
-## Status
+## Scoring model
 
-`v0.1.0` — published on [npm](https://www.npmjs.com/org/geoql) and [JSR](https://jsr.io/@geoql) with provenance. See the [v1.0 milestone](https://github.com/geoql/doctor/milestone/3) for the roadmap.
+Internal severities are `error`, `warn`, and `info` with weights `5`, `2`, and `0.5`. The score uses square-root decay: each repeated occurrence of a rule contributes `weight × 1/√(i+1)`, so the first hit costs full weight and repeats cost less. The final score is `max(0, round(100 − penalty))`. `--fail-on` accepts `error`, `warn`, or `none`. An invalid value exits `2`.
 
 ## Development
 
 ```sh
 pnpm install
-pnpm run lint
-pnpm run format
+pnpm run lint        # vp lint
+pnpm run format      # vp fmt
+pnpm run build       # vp pack per package
+pnpm run coverage    # vitest run --coverage (100% gate)
 ```
 
 Requires Node `>=24` and pnpm `11.4.0`.

packages/doctor-core/src/push.ts

@@ -1,3 +1,4 @@
+import { isAbsolute, relative } from 'node:path';
 import { RULE_REGISTRY } from './rule-registry.js';
 import type { Diagnostic, Severity } from './types.js';
 
@@ -37,6 +38,8 @@ export 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;
@@ -58,17 +61,32 @@ function lookupCategory(ruleId: string): string {
   return categoryByRuleId.get(ruleId) ?? 'unknown';
 }
 
+function toRepoRelative(file: string, rootDir: string | undefined): string {
+  if (!rootDir || !isAbsolute(file)) return file;
+  const rel = relative(rootDir, file);
+  // Paths outside rootDir would relativize to ../../… which is more
+  // confusing (and more revealing) than the original — keep those as-is.
+  if (rel.startsWith('..')) return file;
+  return rel;
+}
+
 /**
  * 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>/…`.
  */
-export function stripFindings(diagnostics: Diagnostic[]): PushedFinding[] {
+export function stripFindings(
+  diagnostics: Diagnostic[],
+  rootDir?: string,
+): PushedFinding[] {
   const out: PushedFinding[] = new Array(diagnostics.length);
   for (let i = 0; i < diagnostics.length; i++) {
     const d = diagnostics[i]!;
     out[i] = {
-      file: d.file,
+      file: toRepoRelative(d.file, rootDir),
       line: d.line,
       col: d.column,
       ruleId: d.ruleId,
@@ -119,7 +137,7 @@ export function buildPushPayload(input: PushPayloadInput): PushPayload {
  * exit code is not affected by SaaS downtime.
  */
 export async function pushFindings(opts: PushOptions): Promise<PushResult> {
-  const findings = stripFindings(opts.diagnostics);
+  const findings = stripFindings(opts.diagnostics, opts.rootDir);
   const payload = buildPushPayload({
     project: opts.project,
     score: opts.score,

packages/doctor-core/src/reporters/docs-url.ts

@@ -1,3 +1,3 @@
 export function docsUrl(ruleId: string): string {
-  return `https://docs.doctor.geoql.in/rules/${ruleId}`;
+  return `https://docs.the-doctor.report/rules/${ruleId}`;
 }

packages/doctor-core/src/reporters/pr-comment.ts

@@ -3,7 +3,7 @@ import type { Diagnostic } from '../types.js';
 import { compareStrings } from './render.js';
 import type { ReporterInput } from './types.js';
 
-const DOCS_BASE = 'https://docs.doctor.geoql.in/rules/';
+const DOCS_BASE = 'https://docs.the-doctor.report/rules/';
 const MAX_PER_SECTION = 5;
 
 function binName(toolName: string): string {

packages/doctor-core/tests/docs-url.test.ts

@@ -4,13 +4,13 @@ import { docsUrl } from '../src/reporters/docs-url.js';
 describe('docsUrl', () => {
   it('builds a deterministic docs URL from a ruleId', () => {
     expect(docsUrl('reactivity/no-destructure-reactive')).toBe(
-      'https://docs.doctor.geoql.in/rules/reactivity/no-destructure-reactive',
+      'https://docs.the-doctor.report/rules/reactivity/no-destructure-reactive',
     );
   });
 
   it('is pure: same input yields the same output', () => {
     const id = 'vue-doctor/template/v-for-has-key';
     expect(docsUrl(id)).toBe(docsUrl(id));
-    expect(docsUrl(id)).toBe(`https://docs.doctor.geoql.in/rules/${id}`);
+    expect(docsUrl(id)).toBe(`https://docs.the-doctor.report/rules/${id}`);
   });
 });

packages/doctor-core/tests/pr-comment.test.ts

@@ -141,7 +141,7 @@ describe('prCommentReport', () => {
 
   it('footer links to the docs base and the top finding explain command', () => {
     const out = prCommentReport(makeInput([diag({ severity: 'error' })]));
-    expect(out).toContain('https://docs.doctor.geoql.in/rules/');
+    expect(out).toContain('https://docs.the-doctor.report/rules/');
     expect(out).toContain(
       'Run `vue-doctor explain vue-doctor/template/v-for-has-key`',
     );

packages/doctor-core/tests/push.test.ts

@@ -64,6 +64,34 @@ describe('stripFindings', () => {
     expect(json).not.toContain('SECRET RECOMMENDATION');
   });
 
+  it('relativizes absolute file paths against rootDir (no CI runner paths leak)', () => {
+    const out = stripFindings(
+      [
+        makeDiag({
+          file: '/home/runner/work/v-clappr/v-clappr/src/components/Player.vue',
+        }),
+      ],
+      '/home/runner/work/v-clappr/v-clappr',
+    );
+    expect(out[0]!.file).toBe('src/components/Player.vue');
+  });
+
+  it('leaves already-relative file paths untouched when rootDir is given', () => {
+    const out = stripFindings(
+      [makeDiag({ file: 'src/a.ts' })],
+      '/home/runner/work/v-clappr/v-clappr',
+    );
+    expect(out[0]!.file).toBe('src/a.ts');
+  });
+
+  it('keeps absolute paths outside rootDir relative-safe (no ../ escapes)', () => {
+    const out = stripFindings(
+      [makeDiag({ file: '/tmp/elsewhere/file.ts' })],
+      '/home/runner/work/v-clappr/v-clappr',
+    );
+    expect(out[0]!.file).toBe('/tmp/elsewhere/file.ts');
+  });
+
   it('looks up the category from RULE_REGISTRY (not the ruleId prefix)', () => {
     const out = stripFindings([makeDiag({ ruleId: 'dead-code/unused-file' })]);
     expect(out[0]!.category).toBe('dead-code');

packages/doctor-core/tests/reporters.test.ts

@@ -114,7 +114,7 @@ describe('agent reporter', () => {
         '    code: const { name, age } = props\n' +
         '    fix:  const { name } = toRefs(props)\n' +
         '    why:  Destructuring a reactive object loses reactivity.\n' +
-        '    docs: https://docs.doctor.geoql.in/rules/reactivity/no-destructure-reactive\n' +
+        '    docs: https://docs.the-doctor.report/rules/reactivity/no-destructure-reactive\n' +
         '\n' +
         'NEXT STEPS:\n' +
         '  −5 pts  1× reactivity/no-destructure-reactive\n' +
@@ -256,7 +256,7 @@ describe('agent reporter', () => {
   it('renders the docs URL for the ruleId', () => {
     const out = agentReport(makeInput({ diagnostics: [diag({})] }));
     expect(out).toContain(
-      '    docs: https://docs.doctor.geoql.in/rules/reactivity/no-destructure-reactive\n',
+      '    docs: https://docs.the-doctor.report/rules/reactivity/no-destructure-reactive\n',
     );
   });
 

packages/doctor-core/tests/reporters/html.test.ts

@@ -109,9 +109,9 @@ describe('htmlReport', () => {
     expect(html).toContain('rule/with<brackets>');
   });
 
-  it('includes a docs link per finding pointing at docs.doctor.geoql.in', () => {
+  it('includes a docs link per finding pointing at docs.the-doctor.report', () => {
     const html = htmlReport(makeInput([ERROR_DIAG]));
-    expect(html).toContain('docs.doctor.geoql.in');
+    expect(html).toContain('docs.the-doctor.report');
     expect(html).toContain('rel="noopener"');
   });
 

packages/doctor-core/tests/reporters/sarif.test.ts

@@ -297,14 +297,14 @@ describe('sarifReport', () => {
     expect(new Set(hashes).size).toBe(hashes.length);
   });
 
-  it('emits helpUri on each rule descriptor pointing at docs.doctor.geoql.in', () => {
+  it('emits helpUri on each rule descriptor pointing at docs.the-doctor.report', () => {
     const parsed = JSON.parse(sarifReport(makeInput([ERROR_DIAG]))) as {
       runs: {
         tool: { driver: { rules: { id: string; helpUri: string }[] } };
       }[];
     };
     const rule = parsed.runs[0]!.tool.driver.rules[0]!;
-    expect(rule.helpUri).toContain('docs.doctor.geoql.in');
+    expect(rule.helpUri).toContain('docs.the-doctor.report');
     expect(rule.helpUri).toContain('vue-doctor/template/v-for-has-key');
   });