feat: ship doxy verify v0.1

Author: thrishank007

README.md

@@ -24,7 +24,7 @@
 
 ---
 
-Think of doxy as **"caniuse for npm packages"** — it reads your lockfile versions and curated API data to find mismatches at lint time, with zero runtime cost.
+Think of doxy as **"caniuse for npm packages"** — it reads your installed or declared dependency versions and curated API data to find mismatches at lint time, with zero runtime cost.
 
 ```
 $ doxy verify
@@ -57,11 +57,10 @@ $ doxy verify
 - **Removed API detection** — errors when you use APIs removed in your installed version
 - **Future API detection** — errors when you use APIs that require a newer version than installed
 - **Wrong arity detection** — errors when you call functions with the wrong number of arguments
-- **Incremental analysis** — only re-analyzes changed files using git diff + content hashing
 - **Inline suppression** — silence specific findings with `// doxy-ignore` comments
 - **Config-level suppression** — suppress patterns project-wide with glob-based rules
-- **Multiple output formats** — human-readable, JSON, JSONL, SARIF
-- **Framework-aware** — understands React/Next.js import patterns and re-exports
+- **Multiple output formats** — human-readable, JSON, JSONL
+- **Framework-aware** — understands React import patterns and ReactDOM subpaths
 - **Fast** — powered by SWC for parsing (~100x faster than TypeScript compiler)
 
 ## Installation
@@ -86,14 +85,11 @@ yarn add -D doxy
 # Run verification on your project
 npx doxy verify
 
-# Only check changed files (great for CI)
-npx doxy verify --changed
-
 # Output as JSON for tooling integration
 npx doxy verify --json
 
-# Get detailed info about a specific finding
-npx doxy explain dxy_a1b2c3d4
+# Output as JSONL for agent or streaming workflows
+npx doxy verify --jsonl
 ```
 
 ## CLI Reference
@@ -103,32 +99,14 @@ npx doxy explain dxy_a1b2c3d4
 | Command | Description |
 |---|---|
 | `doxy verify [files...]` | Run verification (default command) |
-| `doxy init` | Initialize doxy in your project |
-| `doxy explain <finding-id>` | Detailed explanation of a finding |
-| `doxy cache status` | Show cache statistics |
-| `doxy cache clear` | Delete cached data |
-| `doxy authority list` | List loaded authority packages |
-| `doxy authority update` | Pull latest authority data |
-| `doxy authority show <pkg> [export]` | Inspect authority data for a package |
-| `doxy fix [files...]` | Apply auto-fixes |
 
 ### Verify Flags
 
 | Flag | Description |
 |---|---|
 | `--json` | Output findings as JSON |
 | `--jsonl` | Output findings as newline-delimited JSON |
-| `--sarif` | Output findings in SARIF format |
-| `--severity <level>` | Minimum severity to report (default: `warning`) |
-| `--fail-on <level>` | Exit non-zero threshold (default: `error`) |
-| `--changed` | Only analyze changed files |
-| `--base <ref>` | Git ref for diff base |
-| `--no-cache` | Disable caching |
-| `--framework <name@version>` | Override framework detection |
-| `--save-baseline` | Save current findings as baseline |
-| `--update-baseline` | Update baseline to current findings |
-| `--include-baseline` | Show baseline findings in output |
-| `--include-suppressed` | Show suppressed findings in output |
+| `[files...]` | Optional explicit files to analyze instead of config globs |
 
 ### Exit Codes
 
@@ -217,7 +195,7 @@ Lockfile ─────┘       │              │                      │
 3. **Query** — Each symbol is checked against curated authority data for your installed version
 4. **Emit** — Findings are generated with severity, messages, and fix suggestions
 5. **Filter** — Inline and config-level suppressions are applied
-6. **Cache** — Results are cached per-file with smart invalidation
+6. **Report** — Findings are emitted in human, JSON, or JSONL format
 
 doxy never executes your code. It reads your lockfile for installed versions and uses curated API specifications to detect issues statically.
 
@@ -226,9 +204,8 @@ doxy never executes your code. It reads your lockfile for installed versions and
 | Framework | Status | Packages |
 |---|---|---|
 | React | Supported | `react`, `react-dom` |
-| Next.js | Planned | `next` |
 
-Authority data currently covers **27 API specs** across React and ReactDOM, including hooks, lifecycle methods, rendering APIs, and more.
+Authority data currently covers React and ReactDOM APIs, including hooks, lifecycle methods, rendering APIs, and deprecation timelines.
 
 ## Finding Kinds
 
@@ -238,7 +215,6 @@ Authority data currently covers **27 API specs** across React and ReactDOM, incl
 | `removed-api` | error | API was removed in your installed version |
 | `future-api` | error | API requires a newer version than installed |
 | `wrong-arity` | error | Function called with wrong number of arguments |
-| `wrong-param` | error | Function called with wrong parameter names |
 | `unknown-export` | info | Export not found in authority data |
 
 ## CI Integration
@@ -249,12 +225,6 @@ Authority data currently covers **27 API specs** across React and ReactDOM, incl
   run: npx doxy verify --fail-on error
 ```
 
-```yaml
-# With JSON output for annotations
-- name: Check API compatibility
-  run: npx doxy verify --json > doxy-results.json
-```
-
 doxy writes **findings to stdout** and **everything else to stderr**, making it easy to pipe and parse output in CI pipelines.
 
 ## Contributing
@@ -273,17 +243,17 @@ npm run check    # typecheck + lint + test
 ```
 doxy/
 ├── src/
-│   ├── cli/                 CLI entry point + commands
+│   ├── cli/                 `verify` command + reporters
 │   ├── core/                Pure analysis logic
 │   │   ├── types/           All shared type definitions
 │   │   ├── repo-context/    Version detection from manifests
+│   │   ├── files/           File discovery from config globs
 │   │   ├── import-resolver/ Import → package/export mapping
+│   │   ├── analyzer/        Per-file analysis orchestration
 │   │   ├── suppression/     Inline + config suppression
-│   │   └── analyzer/        Per-file analysis orchestration
 │   ├── authority/           Authority data store
 │   ├── adapters/            Framework-specific adapters
 │   ├── parser/              SWC-based AST parsing
-│   └── incremental/         Git diff + caching
 ├── authority-data/          Curated API spec datasets
 └── fixtures/                Test fixture mini-projects
 ```

fixtures/react-18-wrong-arity/expected-findings.json

@@ -1,12 +1,12 @@
 [
   {
-    "longId": "dxy:react/useState:src/App.tsx:5:32",
+    "longId": "dxy:react/useState:src/App.tsx:5:29",
     "kind": "wrong-arity",
     "severity": "error",
     "message": "react.useState expects 0-1 arguments, but was called with 2."
   },
   {
-    "longId": "dxy:react/useReducer:src/App.tsx:8:36",
+    "longId": "dxy:react/useReducer:src/App.tsx:8:29",
     "kind": "wrong-arity",
     "severity": "error",
     "message": "react.useReducer expects 2-3 arguments, but was called with 0."

fixtures/react-19-removed/expected-findings.json

@@ -12,7 +12,7 @@
     "message": "react-dom.findDOMNode was removed in 19.0.0. Use refs instead."
   },
   {
-    "longId": "dxy:react/PropTypes:src/App.tsx:21:14",
+    "longId": "dxy:react/PropTypes:src/App.tsx:21:12",
     "kind": "removed-api",
     "severity": "error",
     "message": "react.PropTypes was removed in 19.0.0. Use the 'prop-types' package instead."

package-lock.json

@@ -32,12 +32,14 @@
   "dependencies": {
     "@swc/core": "^1.10.0",
     "citty": "^0.1.6",
+    "picomatch": "^4.0.4",
     "semver": "^7.6.0",
     "simple-git": "^3.27.0",
     "zod": "^3.24.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
+    "@types/picomatch": "^4.0.3",
     "@types/semver": "^7.5.0",
     "eslint": "^9.0.0",
     "typescript": "^5.7.0",

package.json

@@ -0,0 +1,29 @@
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import {
+  DEFAULT_CONFIG,
+  DoxyConfigSchema,
+  type DoxyConfig,
+} from "../core/types/index.js";
+
+export async function loadConfig(root: string): Promise<DoxyConfig> {
+  const configPath = resolve(root, "doxy.config.json");
+
+  try {
+    const raw = await readFile(configPath, "utf-8");
+    return DoxyConfigSchema.parse(JSON.parse(raw));
+  } catch (error) {
+    if (isMissingFile(error)) {
+      return DEFAULT_CONFIG;
+    }
+    throw error;
+  }
+}
+
+function isMissingFile(error: unknown): boolean {
+  return (
+    error instanceof Error &&
+    "code" in error &&
+    error.code === "ENOENT"
+  );
+}

src/cli/config.ts

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+
+import { ExitCode } from "../core/types/index.js";
+import { runVerify } from "./verify.js";
+
+type ReportFormat = "human" | "json" | "jsonl";
+
+async function main(): Promise<void> {
+  const rawArgs = process.argv.slice(2);
+  const args = rawArgs[0] === "verify" ? rawArgs.slice(1) : rawArgs;
+
+  let format: ReportFormat = "human";
+  const files: string[] = [];
+
+  for (const arg of args) {
+    if (arg === "--json") {
+      format = "json";
+      continue;
+    }
+    if (arg === "--jsonl") {
+      format = "jsonl";
+      continue;
+    }
+    files.push(arg);
+  }
+
+  if (args.includes("--json") && args.includes("--jsonl")) {
+    process.stderr.write("Choose either --json or --jsonl, not both.\n");
+    process.exitCode = ExitCode.CONFIG_ERROR;
+    return;
+  }
+
+  const result = await runVerify({
+    root: process.cwd(),
+    files,
+    format,
+  });
+
+  if (result.stdout) {
+    process.stdout.write(result.stdout);
+  }
+  if (result.stderr) {
+    process.stderr.write(result.stderr);
+  }
+
+  process.exitCode = result.exitCode;
+}
+
+await main();

src/cli/index.ts

@@ -0,0 +1,83 @@
+import type { Finding } from "../core/types/index.js";
+
+export type ReportFormat = "human" | "json" | "jsonl";
+
+export interface ReportSummary {
+  total: number;
+  errors: number;
+  warnings: number;
+  info: number;
+}
+
+export function summarizeFindings(findings: Finding[]): ReportSummary {
+  return {
+    total: findings.length,
+    errors: findings.filter((finding) => finding.severity === "error").length,
+    warnings: findings.filter((finding) => finding.severity === "warning").length,
+    info: findings.filter((finding) => finding.severity === "info").length,
+  };
+}
+
+export function renderReport(
+  findings: Finding[],
+  format: ReportFormat,
+): string {
+  const summary = summarizeFindings(findings);
+
+  switch (format) {
+    case "json":
+      return JSON.stringify(
+        {
+          tool: "doxy",
+          version: "0.1.0",
+          findings,
+          summary,
+        },
+        null,
+        2,
+      );
+    case "jsonl":
+      return [
+        ...findings.map((finding) => JSON.stringify({ type: "finding", finding })),
+        JSON.stringify({ type: "summary", summary }),
+      ].join("\n");
+    case "human":
+    default:
+      return renderHuman(findings, summary);
+  }
+}
+
+function renderHuman(findings: Finding[], summary: ReportSummary): string {
+  if (findings.length === 0) {
+    return "0 findings\n";
+  }
+
+  const lines: string[] = [];
+  let currentFile: string | undefined;
+
+  for (const finding of findings) {
+    if (finding.location.file !== currentFile) {
+      if (currentFile) {
+        lines.push("");
+      }
+      currentFile = finding.location.file;
+      lines.push(currentFile);
+    }
+
+    lines.push(
+      `  ${finding.location.line}:${finding.location.column}  ${finding.severity}  ${finding.message}  ${finding.kind}  ${finding.id}`,
+    );
+
+    const bestFix = finding.fixes[0];
+    if (bestFix?.description) {
+      lines.push(`             ${bestFix.description}`);
+    }
+  }
+
+  lines.push("");
+  lines.push(
+    `${summary.total} findings (${summary.errors} errors, ${summary.warnings} warnings, ${summary.info} info)`,
+  );
+
+  return `${lines.join("\n")}\n`;
+}