veriskit 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.3.0 — 2026-07-10
+
+### Added
+- `veris scan` — import-graph map + untested areas, built from the project's own TypeScript (with a dep-free scanner fallback); writes `.veris/graph.json`.
+- `veris plan` — prioritized recommendations (high-impact untested files, weak verification, risky changes). Analysis only — no code generation.
+
+### Changed
+- `veris affected` / `veris watch` are now graph-based: the unit run is narrowed to only the test files that transitively import your changes, with a conservative full-suite fallback (config/global change, unresolved file, or untested change) so an affected test is never skipped. No new runtime dependencies.
+
 ## 0.2.0 — 2026-07-09
 
 ### Added

package/README.md

@@ -95,6 +95,78 @@ want partial results to pass CI can opt in explicitly with
 | failed   | `1`       | at least one check failed                  |
 | partial  | `2` (`0` with `--partial-ok`) | no failures, but something was skipped |
 
+## Project intelligence
+
+`veris scan` and `veris plan` map your codebase's import graph and turn it
+into recommendations — what to test, where verification is weak, and (with
+`--base`) which of your changes are risky. Both are **read-only analysis**;
+neither generates or writes any code.
+
+### `veris scan`
+
+```bash
+veris scan
+```
+
+`scan` discovers every source and test file in the project, builds an import
+graph between them, and reports the source files with the most dependents
+that no test transitively reaches ("untested, by impact"). It writes the
+graph to `.veris/graph.json` — a derived cache, rebuilt on every run and not
+meant to be committed.
+
+**`scan` always states which resolver built the graph**, because the two
+have very different accuracy:
+
+- **`typescript`** — used when the project has a `tsconfig.json` and its own
+  `typescript` package exposes the classic compiler API
+  (`preProcessFile`/`resolveModuleName`/`readConfigFile`/…). Veris loads
+  *your project's own* TypeScript at run time — **no new dependency is added
+  for this** — and resolves imports the way `tsc` would: `tsconfig` path
+  aliases, extension-mapped specifiers, index resolution, and so on.
+- **`scanner`** — the fallback when there's no TypeScript, no
+  `tsconfig.json`, or the installed `typescript` package is a 7.x
+  native/Go-ported build that doesn't expose the classic compiler API veris
+  needs. The scanner is a dependency-free, **relative-imports-only** reader:
+  it follows `./foo` and `../bar/baz` but does not understand `tsconfig`
+  path aliases or computed (non-string-literal) dynamic imports. On a
+  project that relies on aliases, this can miss real edges and undercount a
+  file's blast radius.
+  `scan` says plainly when this fallback is active — it is never presented
+  as equivalent to the TypeScript-accurate graph.
+
+### `veris plan`
+
+```bash
+veris plan               # recommendations from the current graph
+veris plan --base main   # also factor in changes vs another ref
+```
+
+`plan` reads the same graph and turns it into prioritized recommendations:
+
+- the highest-impact untested files to test first (most dependents, no test
+  reaches them);
+- gaps in your verification setup (e.g. no lint or type-check configured);
+- with `--base <ref>`, which files that changed since that ref are "risky" —
+  high blast radius and either untested or actually changed.
+
+**`plan` only recommends — it never generates or writes any code.** Test
+generation is a separate, later goal (v0.8), not something v0.3 does.
+
+### What's still deferred
+
+- **No framework route/endpoint detection.** The graph understands imports
+  only; it doesn't know a file is an Express route, a Next.js page, or an
+  API handler, so it can't flag "this endpoint has no test" the way it flags
+  "this module has no test." Planned as a v0.3.x follow-up, not v0.3.0.
+- **No test generation.** `plan` recommends what to test; it does not write
+  test files. That's v0.8.
+- **Single tsconfig, single root.** Monorepos with multiple `tsconfig.json`
+  files aren't modeled yet — resolution runs against the root project only.
+- **Plain JS / TS 7.x-native projects degrade to the scanner.** There's no
+  new dependency added to compensate — the classic TypeScript compiler API
+  is what makes the accurate resolver possible, and projects without it get
+  the honestly-labeled, relative-imports-only fallback described above.
+
 ## Developer loop
 
 For fast local iteration, veris can scope checks to what you changed instead
@@ -120,12 +192,34 @@ changed file to the check categories it plausibly touches:
 | docs/assets (`.md`, images, `LICENSE`) | nothing |
 | anything else unrecognized | every available check (safe default) |
 
-This is **coarse — there is no import graph yet**. `affected` maps changed
-*files* to check *categories*, not to the specific modules or tests that
-actually import them; a real dependency-aware "run exactly the tests this
-file affects" is planned for v0.3. Today it will sometimes run more than the
-minimal ideal set (a config change reruns everything), but it never silently
-skips work it can't prove is safe to skip.
+The table above decides *which check categories* run — that part is still a
+coarse, file-extension-based mapping. **What changed in v0.3 is what happens
+inside the `unit` category.** Instead of running every unit test in the
+project, `affected` builds the same import graph that
+[`veris scan`/`veris plan`](#project-intelligence) use and narrows the unit
+run to only the test files that **transitively import** your changed files.
+
+That narrowing is deliberately conservative — it **falls back to running the
+full test suite** rather than ever risk hiding an affected test:
+
+- any changed file matches a config/global pattern (`tsconfig*.json`,
+  `package.json`, a `*.config.*` or `*.setup.*` file, biome/eslint config, …);
+- a changed file isn't a node in the import graph at all (e.g. it's under an
+  ignored directory like `node_modules` or `.veris`, or it's not a
+  recognized code extension);
+- no test file transitively reaches any of the changed files (an untested
+  change).
+
+The output says when a run was narrowed and why it wasn't:
+
+```text
+unit narrowed to 3 of 41 test file(s) via typescript graph
+unit ran in full — global/config change (package.json)
+```
+
+Today it will still sometimes run more than the minimal ideal set (a config
+change reruns everything, an unresolved file falls back to full), but it
+never silently skips work it can't prove is safe to skip.
 
 **The verdict is honestly scoped.** An `affected` run never prints a bare
 "Verified" — the terminal output and report say "Affected checks passed" (or
@@ -151,6 +245,11 @@ isn't supported, or on filesystems (containers, some network mounts) where
 native change events are unreliable, pass `--poll` to fall back to an
 interval-based scan that diffs file mtimes instead.
 
+Every tick after the baseline uses the same graph-based `unit` narrowing (and
+conservative full-suite fallback) described above for `affected` — the graph
+is rebuilt fresh each tick, so it always reflects the file you just saved,
+not a stale snapshot.
+
 Each tick reprints the full check board. A capability that wasn't affected by
 the latest change keeps showing its last real result, marked `⟳ cached` — a
 cached **failure stays a failure** (✗); it is never hidden or silently
@@ -169,7 +268,9 @@ Every `veris verify` run writes:
 
 `.veris/config.json` and `.veris/.gitignore` are meant to be committed;
 `.veris/runs/`, `.veris/reports/`, and `.veris/cache/` are gitignored by
-`veris init`.
+`veris init`. `.veris/graph.json` (written by [`veris scan`](#project-intelligence))
+is a separate derived cache, rebuilt on every scan — treat it the same way
+and don't commit it.
 
 ## Design
 

package/dist/index.js

@@ -231,7 +231,7 @@ var init_store = __esm({
 // src/util/exec.ts
 import { spawn } from "child_process";
 function exec(cmd, args, opts = {}) {
-  return new Promise((resolve) => {
+  return new Promise((resolve2) => {
     const start = performance.now();
     const child = spawn(cmd, args, {
       cwd: opts.cwd,
@@ -249,7 +249,7 @@ function exec(cmd, args, opts = {}) {
     child.stderr.on("data", (d) => stderr += d.toString());
     child.on("close", (code) => {
       if (timer) clearTimeout(timer);
-      resolve({
+      resolve2({
         code: code ?? 1,
         stdout,
         stderr,
@@ -259,7 +259,7 @@ function exec(cmd, args, opts = {}) {
     });
     child.on("error", () => {
       if (timer) clearTimeout(timer);
-      resolve({
+      resolve2({
         code: 127,
         stdout,
         stderr: stderr || `failed to spawn ${cmd}`,
@@ -375,13 +375,13 @@ var init_jest = __esm({
     init_base();
     jestRunner = {
       id: "jest",
-      toCheck(project, _cap) {
+      toCheck(project, _cap, opts) {
         return {
           id: "unit",
           title: "Unit tests",
           runner: "jest",
           cmd: localBin(project.root, "jest"),
-          args: ["--ci"]
+          args: ["--ci", ...opts?.targetFiles ?? []]
         };
       },
       run(check, ctx) {
@@ -459,13 +459,14 @@ var init_vitest = __esm({
     init_base();
     vitestRunner = {
       id: "vitest",
-      toCheck(project, _cap) {
+      toCheck(project, _cap, opts) {
+        const files = opts?.targetFiles ?? [];
         return {
           id: "unit",
           title: "Unit tests",
           runner: "vitest",
           cmd: localBin(project.root, "vitest"),
-          args: ["run", "--reporter=json"]
+          args: ["run", "--reporter=json", ...files]
         };
       },
       run(check, ctx) {
@@ -544,7 +545,7 @@ var init_verdict = __esm({
 });
 
 // src/core/orchestrator.ts
-async function runChecks(project, ids, root) {
+async function runChecks(project, ids, root, opts = {}) {
   const known = new Set(project.capabilities.map((c) => c.id));
   const unknown = ids.filter((id2) => !known.has(id2));
   if (unknown.length > 0) {
@@ -565,7 +566,9 @@ async function runChecks(project, ids, root) {
         summary
       };
     }
-    const check = runner.toCheck(project, cap);
+    const check = runner.toCheck(project, cap, {
+      targetFiles: opts.targetFiles?.[capId]
+    });
     return runner.run(check, ctx);
   });
   const results = await Promise.all(tasks);
@@ -708,7 +711,7 @@ var init_init = __esm({
     "use strict";
     init_detect();
     init_fs_safe();
-    GITIGNORE = ["runs/", "reports/", "cache/", ""].join("\n");
+    GITIGNORE = ["runs/", "reports/", "cache/", "graph.json", ""].join("\n");
   }
 });
 
@@ -940,6 +943,338 @@ var init_changes = __esm({
   }
 });
 
+// src/project-graph/discover.ts
+import { readdirSync as readdirSync2, statSync } from "fs";
+import { join as join7, relative as relative2, sep } from "path";
+function toPosix(p) {
+  return sep === "/" ? p : p.split(sep).join("/");
+}
+function classify(rel) {
+  if (TEST_RE2.test(rel)) return "test";
+  if (CONFIG_RE2.test(rel)) return "config";
+  return "source";
+}
+function discoverFiles(root) {
+  const out = [];
+  const walk = (dir) => {
+    let entries;
+    try {
+      entries = readdirSync2(dir);
+    } catch {
+      return;
+    }
+    for (const name of entries) {
+      const abs = join7(dir, name);
+      const rel = toPosix(relative2(root, abs));
+      if (IGNORE.test(rel)) continue;
+      let st;
+      try {
+        st = statSync(abs);
+      } catch {
+        continue;
+      }
+      if (st.isDirectory()) {
+        walk(abs);
+      } else if (CODE_RE.test(rel)) {
+        out.push({ file: rel, kind: classify(rel) });
+      }
+    }
+  };
+  walk(root);
+  return out.sort((a, b) => a.file.localeCompare(b.file));
+}
+var IGNORE, CODE_RE, TEST_RE2, CONFIG_RE2;
+var init_discover = __esm({
+  "src/project-graph/discover.ts"() {
+    "use strict";
+    IGNORE = /(^|\/)(\.git|\.claude|\.veris|\.agentloop|\.agentflight|node_modules|dist|coverage|build|fixtures|__fixtures__)(\/|$)/;
+    CODE_RE = /\.[cm]?[jt]sx?$/;
+    TEST_RE2 = /(\.(test|spec)\.[cm]?[jt]sx?$)|(^|\/)(test|tests|__tests__)\//;
+    CONFIG_RE2 = /(^|\/)([^/]+\.config\.[cm]?[jt]sx?)$/;
+  }
+});
+
+// src/project-graph/scanner-resolver.ts
+import { existsSync as existsSync3, readFileSync as readFileSync3, statSync as statSync2 } from "fs";
+import { dirname, join as join8, relative as relative3, resolve } from "path";
+function extractSpecifiers(text) {
+  const specs = [];
+  SPEC_RE.lastIndex = 0;
+  let m;
+  m = SPEC_RE.exec(text);
+  while (m !== null) {
+    const s = m[1] ?? m[2] ?? m[3] ?? m[4];
+    if (s) specs.push(s);
+    m = SPEC_RE.exec(text);
+  }
+  return specs;
+}
+function isFile(p) {
+  try {
+    return statSync2(p).isFile();
+  } catch {
+    return false;
+  }
+}
+function resolveRelative(fromDir, spec) {
+  const base = resolve(fromDir, spec);
+  const candidates = [base];
+  for (const ext of EXTS) candidates.push(base + ext);
+  const extMatch = base.match(/\.[cm]?[jt]sx?$/);
+  if (extMatch) {
+    const noExt = base.slice(0, -extMatch[0].length);
+    for (const ext of EXTS) candidates.push(noExt + ext);
+  }
+  for (const ext of EXTS) candidates.push(join8(base, `index${ext}`));
+  for (const c of candidates) {
+    if (existsSync3(c) && isFile(c)) return c;
+  }
+  return null;
+}
+function scannerImports(root, file) {
+  let text;
+  try {
+    text = readFileSync3(join8(root, file), "utf8");
+  } catch {
+    return [];
+  }
+  const dir = dirname(join8(root, file));
+  const out = /* @__PURE__ */ new Set();
+  for (const spec of extractSpecifiers(text)) {
+    if (!spec.startsWith(".")) continue;
+    const resolved = resolveRelative(dir, spec);
+    if (resolved) out.add(toPosix(relative3(root, resolved)));
+  }
+  return [...out];
+}
+var EXTS, SPEC_RE;
+var init_scanner_resolver = __esm({
+  "src/project-graph/scanner-resolver.ts"() {
+    "use strict";
+    init_discover();
+    EXTS = [".ts", ".tsx", ".mts", ".cts", ".js", ".jsx", ".mjs", ".cjs"];
+    SPEC_RE = /(?:import|export)\b[^'"]*?\bfrom\s*['"]([^'"]+)['"]|(?:^|[^.\w])import\s*['"]([^'"]+)['"]|\bimport\(\s*['"]([^'"]+)['"]\s*\)|\brequire\(\s*['"]([^'"]+)['"]\s*\)/g;
+  }
+});
+
+// src/project-graph/ts-resolver.ts
+import { existsSync as existsSync4, readFileSync as readFileSync4 } from "fs";
+import { createRequire } from "module";
+import { join as join9, relative as relative4, sep as sep2 } from "path";
+function hasClassicApi(mod) {
+  const m = mod;
+  return !!m && typeof m.preProcessFile === "function" && typeof m.resolveModuleName === "function" && typeof m.readConfigFile === "function" && typeof m.parseJsonConfigFileContent === "function" && typeof m.sys === "object" && m.sys !== null;
+}
+function loadTypeScript(root) {
+  try {
+    const require2 = createRequire(join9(root, "__veris__.js"));
+    const tsPath = require2.resolve("typescript");
+    const mod = require2(tsPath);
+    return hasClassicApi(mod) ? mod : null;
+  } catch {
+    return null;
+  }
+}
+function loadCompilerOptions(tsmod, root) {
+  const configPath = join9(root, "tsconfig.json");
+  const read = tsmod.readConfigFile(configPath, tsmod.sys.readFile);
+  if (read.error || !read.config) return {};
+  const parsed = tsmod.parseJsonConfigFileContent(read.config, tsmod.sys, root);
+  return parsed.options;
+}
+function tsImports(tsmod, root, options, file) {
+  let text;
+  try {
+    text = readFileSync4(join9(root, file), "utf8");
+  } catch {
+    return [];
+  }
+  const abs = join9(root, file);
+  const out = /* @__PURE__ */ new Set();
+  try {
+    const pre = tsmod.preProcessFile(text, true, true);
+    for (const imp of pre.importedFiles) {
+      const res = tsmod.resolveModuleName(
+        imp.fileName,
+        abs,
+        options,
+        tsmod.sys
+      );
+      const resolved = res.resolvedModule?.resolvedFileName;
+      if (resolved && !resolved.includes("node_modules") && resolved.startsWith(root + sep2)) {
+        out.add(toPosix(relative4(root, resolved)));
+      }
+    }
+  } catch {
+  }
+  return [...out];
+}
+function selectResolver(root) {
+  const tsmod = existsSync4(join9(root, "tsconfig.json")) ? loadTypeScript(root) : null;
+  if (tsmod) {
+    try {
+      const options = loadCompilerOptions(tsmod, root);
+      return {
+        resolver: "typescript",
+        importsOf: (file) => tsImports(tsmod, root, options, file)
+      };
+    } catch {
+    }
+  }
+  return {
+    resolver: "scanner",
+    importsOf: (file) => scannerImports(root, file)
+  };
+}
+var init_ts_resolver = __esm({
+  "src/project-graph/ts-resolver.ts"() {
+    "use strict";
+    init_discover();
+    init_scanner_resolver();
+  }
+});
+
+// src/project-graph/graph.ts
+var graph_exports = {};
+__export(graph_exports, {
+  buildGraph: () => buildGraph
+});
+async function buildGraph(project) {
+  const root = project.root;
+  const files = discoverFiles(root);
+  const known = new Set(files.map((f) => f.file));
+  const { resolver, importsOf } = selectResolver(root);
+  const nodes = {};
+  for (const f of files) {
+    nodes[f.file] = { file: f.file, kind: f.kind, imports: [], importedBy: [] };
+  }
+  for (const f of files) {
+    const imps = importsOf(f.file).filter((i) => known.has(i) && i !== f.file);
+    nodes[f.file].imports = imps;
+    for (const i of imps) nodes[i]?.importedBy.push(f.file);
+  }
+  return {
+    root,
+    resolver,
+    nodes,
+    sourceFiles: files.filter((f) => f.kind === "source").map((f) => f.file),
+    testFiles: files.filter((f) => f.kind === "test").map((f) => f.file)
+  };
+}
+var init_graph = __esm({
+  "src/project-graph/graph.ts"() {
+    "use strict";
+    init_discover();
+    init_ts_resolver();
+  }
+});
+
+// src/project-graph/analyze.ts
+function transitiveDependents(graph, file) {
+  const seen = /* @__PURE__ */ new Set();
+  const stack = [...graph.nodes[file]?.importedBy ?? []];
+  while (stack.length) {
+    const f = stack.pop();
+    if (!f || seen.has(f)) continue;
+    seen.add(f);
+    for (const d of graph.nodes[f]?.importedBy ?? []) stack.push(d);
+  }
+  return seen;
+}
+function reachableFromTests(graph) {
+  const seen = /* @__PURE__ */ new Set();
+  const stack = [...graph.testFiles];
+  while (stack.length) {
+    const f = stack.pop();
+    if (!f || seen.has(f)) continue;
+    seen.add(f);
+    for (const i of graph.nodes[f]?.imports ?? []) stack.push(i);
+  }
+  return seen;
+}
+function analyze(graph, changed = []) {
+  const blastRadius = {};
+  for (const file of Object.keys(graph.nodes)) {
+    blastRadius[file] = transitiveDependents(graph, file).size;
+  }
+  const reached = reachableFromTests(graph);
+  const byBlast = (a, b) => (blastRadius[b] ?? 0) - (blastRadius[a] ?? 0);
+  const untested = graph.sourceFiles.filter((f) => !reached.has(f)).sort(byBlast);
+  const changedSet = new Set(changed);
+  const untestedSet = new Set(untested);
+  const risky = graph.sourceFiles.filter(
+    (f) => (blastRadius[f] ?? 0) > 0 && (untestedSet.has(f) || changedSet.has(f))
+  ).sort(byBlast);
+  return { untested, blastRadius, risky };
+}
+var init_analyze = __esm({
+  "src/project-graph/analyze.ts"() {
+    "use strict";
+  }
+});
+
+// src/affected/select.ts
+var select_exports = {};
+__export(select_exports, {
+  selectAffectedTests: () => selectAffectedTests
+});
+function selectAffectedTests(graph, changed) {
+  if (graph.resolver !== "typescript") {
+    return {
+      mode: "full",
+      testFiles: [],
+      reason: "scanner graph can miss aliased/subpath imports \u2014 running the full suite"
+    };
+  }
+  for (const f of changed) {
+    if (GLOBAL_RE.test(f)) {
+      return {
+        mode: "full",
+        testFiles: [],
+        reason: `global/config change (${f})`
+      };
+    }
+    if (!(f in graph.nodes)) {
+      return {
+        mode: "full",
+        testFiles: [],
+        reason: `unresolved changed file (${f})`
+      };
+    }
+  }
+  const tests = /* @__PURE__ */ new Set();
+  for (const f of changed) {
+    if (graph.nodes[f]?.kind === "test") tests.add(f);
+    for (const dep of transitiveDependents(graph, f)) {
+      if (graph.nodes[dep]?.kind === "test") tests.add(dep);
+    }
+  }
+  if (tests.size === 0) {
+    return {
+      mode: "full",
+      testFiles: [],
+      reason: "no tests reach the changed files"
+    };
+  }
+  const selected = [...tests].sort();
+  if (selected.some((t) => t.startsWith("-"))) {
+    return {
+      mode: "full",
+      testFiles: [],
+      reason: "a reaching test path starts with '-' (unsafe as a CLI argument)"
+    };
+  }
+  return { mode: "graph", testFiles: selected, reason: "" };
+}
+var GLOBAL_RE;
+var init_select = __esm({
+  "src/affected/select.ts"() {
+    "use strict";
+    init_analyze();
+    GLOBAL_RE = /(^|\/)(tsconfig[^/]*\.json|package\.json|biome\.jsonc?|\.eslintrc[^/]*|eslint\.config\.[^/]+|veris\.config\.[^/]+|[^/]+\.config\.[cm]?[jt]sx?|[^/]+\.setup\.[cm]?[jt]sx?)$/;
+  }
+});
+
 // src/cli/commands/affected.ts
 var affected_exports = {};
 __export(affected_exports, {
@@ -956,7 +1291,25 @@ async function runAffected(root, opts = {}) {
     );
     return 0;
   }
-  const run = await runChecks(project, plan.checks, root);
+  let targetFiles;
+  let narrowedNote = "";
+  const unitRunner = project.capabilities.find((c) => c.id === "unit")?.runner;
+  const canNarrow = unitRunner === "vitest" || unitRunner === "jest";
+  if (plan.checks.includes("unit") && canNarrow) {
+    const { buildGraph: buildGraph2 } = await Promise.resolve().then(() => (init_graph(), graph_exports));
+    const { selectAffectedTests: selectAffectedTests2 } = await Promise.resolve().then(() => (init_select(), select_exports));
+    const graph = await buildGraph2(project);
+    const sel = selectAffectedTests2(graph, files);
+    if (sel.mode === "graph") {
+      targetFiles = { unit: sel.testFiles };
+      narrowedNote = `unit narrowed to ${sel.testFiles.length} of ${graph.testFiles.length} test file(s) via ${graph.resolver} graph`;
+    } else {
+      narrowedNote = `unit ran in full \u2014 ${sel.reason}`;
+    }
+  } else if (plan.checks.includes("unit") && unitRunner) {
+    narrowedNote = `unit ran in full \u2014 the ${unitRunner} runner does not support file filtering`;
+  }
+  const run = await runChecks(project, plan.checks, root, { targetFiles });
   run.scope = { kind: "affected", changedCount: files.length };
   const affected = new Set(plan.checks);
   for (const cap of project.capabilities) {
@@ -974,6 +1327,8 @@ async function runAffected(root, opts = {}) {
   const runDir = await createRunDir(root, run.id);
   await writeMetadata(runDir, run);
   process.stdout.write(`${renderRun(run)}
+`);
+  if (narrowedNote) process.stdout.write(`${narrowedNote}
 `);
   return verdictExitCode(run.verdict, opts);
 }
@@ -994,10 +1349,10 @@ var init_affected = __esm({
 // src/watch/watcher.ts
 import {
   watch as fsWatch,
-  readdirSync as readdirSync2,
-  statSync
+  readdirSync as readdirSync3,
+  statSync as statSync3
 } from "fs";
-import { basename, join as join7, relative as relative2 } from "path";
+import { basename, join as join10, relative as relative5 } from "path";
 function watch(root, opts, onBatch) {
   const debounceMs = opts.debounceMs ?? 150;
   const rootBase = basename(root);
@@ -1010,7 +1365,7 @@ function watch(root, opts, onBatch) {
     if (batch.length) onBatch(batch);
   };
   const schedule = (rel) => {
-    if (!rel || rel === rootBase || IGNORE.test(rel)) return;
+    if (!rel || rel === rootBase || IGNORE2.test(rel)) return;
     pending.add(rel);
     if (timer) clearTimeout(timer);
     timer = setTimeout(flush, debounceMs);
@@ -1051,17 +1406,17 @@ function scanMtimes(root) {
   const walk = (dir) => {
     let entries;
     try {
-      entries = readdirSync2(dir);
+      entries = readdirSync3(dir);
     } catch {
       return;
     }
     for (const name of entries) {
-      const abs = join7(dir, name);
-      const rel = relative2(root, abs);
-      if (IGNORE.test(rel)) continue;
+      const abs = join10(dir, name);
+      const rel = relative5(root, abs);
+      if (IGNORE2.test(rel)) continue;
       let st;
       try {
-        st = statSync(abs);
+        st = statSync3(abs);
       } catch {
         continue;
       }
@@ -1072,11 +1427,11 @@ function scanMtimes(root) {
   walk(root);
   return out;
 }
-var IGNORE;
+var IGNORE2;
 var init_watcher = __esm({
   "src/watch/watcher.ts"() {
     "use strict";
-    IGNORE = /(^|\/)(\.git|\.veris|\.agentloop|\.agentflight|node_modules|dist)(\/|$)/;
+    IGNORE2 = /(^|\/)(\.git|\.veris|\.agentloop|\.agentflight|node_modules|dist)(\/|$)/;
   }
 });
 
@@ -1122,9 +1477,29 @@ async function runWatch(root, opts = {}) {
       const project = await detectProject(root);
       const { files } = await changedFiles(root);
       const checks = initial ? availableIds(project) : affectedChecks(files, project).checks;
+      let targetFiles;
+      let narrowedNote = "";
+      const unitRunner = project.capabilities.find(
+        (c) => c.id === "unit"
+      )?.runner;
+      const canNarrow = unitRunner === "vitest" || unitRunner === "jest";
+      if (!initial && checks.includes("unit") && canNarrow) {
+        const { buildGraph: buildGraph2 } = await Promise.resolve().then(() => (init_graph(), graph_exports));
+        const { selectAffectedTests: selectAffectedTests2 } = await Promise.resolve().then(() => (init_select(), select_exports));
+        const graph = await buildGraph2(project);
+        const sel = selectAffectedTests2(graph, files);
+        if (sel.mode === "graph") {
+          targetFiles = { unit: sel.testFiles };
+          narrowedNote = `unit narrowed to ${sel.testFiles.length} of ${graph.testFiles.length} test file(s) via ${graph.resolver} graph`;
+        } else {
+          narrowedNote = `unit ran in full \u2014 ${sel.reason}`;
+        }
+      } else if (!initial && checks.includes("unit") && unitRunner) {
+        narrowedNote = `unit ran in full \u2014 the ${unitRunner} runner does not support file filtering`;
+      }
       let fresh = [];
       if (checks.length) {
-        const r = await runChecks(project, checks, root);
+        const r = await runChecks(project, checks, root, { targetFiles });
         fresh = r.results;
         for (const result of fresh) cache.set(result.checkId, { ...result });
       }
@@ -1149,6 +1524,8 @@ async function runWatch(root, opts = {}) {
         scope: { kind: "watch", changedCount: files.length }
       };
       process.stdout.write(`${renderRun(run)}
+`);
+      if (narrowedNote) process.stdout.write(`${narrowedNote}
 `);
     } finally {
       running = false;
@@ -1156,7 +1533,7 @@ async function runWatch(root, opts = {}) {
   };
   process.stdout.write("veris watch \u2014 press Ctrl-C to stop\n");
   await tick(true);
-  return await new Promise((resolve) => {
+  return await new Promise((resolve2) => {
     let stop;
     try {
       stop = watch(root, { poll: opts.poll }, () => {
@@ -1167,13 +1544,13 @@ async function runWatch(root, opts = {}) {
         `veris: ${err instanceof Error ? err.message : String(err)}
 `
       );
-      resolve(1);
+      resolve2(1);
       return;
     }
     process.on("SIGINT", () => {
       stop();
       process.stdout.write("\nStopped.\n");
-      resolve(0);
+      resolve2(0);
     });
   });
 }
@@ -1190,6 +1567,147 @@ var init_watch = __esm({
   }
 });
 
+// src/cli/commands/scan.ts
+var scan_exports = {};
+__export(scan_exports, {
+  renderScan: () => renderScan,
+  runScan: () => runScan
+});
+import { writeFile as writeFile3 } from "fs/promises";
+import { join as join11 } from "path";
+import pc3 from "picocolors";
+function renderScan(graph, analysis) {
+  const plain = isPlain();
+  const bold = (s) => plain ? s : pc3.bold(s);
+  const dim = (s) => plain ? s : pc3.dim(s);
+  const warn = (s) => plain ? s : pc3.yellow(s);
+  const lines = [];
+  lines.push(bold("Veris \u2014 scan"));
+  lines.push("");
+  lines.push(
+    `Resolver    ${graph.resolver}${graph.resolver === "scanner" ? dim("  (no TypeScript found \u2014 relative imports only)") : ""}`
+  );
+  lines.push(
+    `Modules     ${Object.keys(graph.nodes).length}   \xB7  Source ${graph.sourceFiles.length}  \xB7  Tests ${graph.testFiles.length}`
+  );
+  lines.push("");
+  lines.push("Untested (top by impact)");
+  const top = analysis.untested.slice(0, 10);
+  if (top.length === 0)
+    lines.push(dim("  none \u2014 every source file is reached by a test"));
+  for (const f of top) {
+    lines.push(
+      `  ${warn("!")} ${f}   ${dim(`${analysis.blastRadius[f] ?? 0} dependents`)}`
+    );
+  }
+  return lines.join("\n");
+}
+async function runScan(root) {
+  const project = await detectProject(root);
+  const graph = await buildGraph(project);
+  const analysis = analyze(graph);
+  const dir = join11(root, ".veris");
+  await ensureDir(dir);
+  await writeFile3(
+    join11(dir, "graph.json"),
+    JSON.stringify({ resolver: graph.resolver, nodes: graph.nodes }, null, 2),
+    "utf8"
+  );
+  process.stdout.write(`${renderScan(graph, analysis)}
+`);
+  process.stdout.write(`
+Graph        ${join11(".veris", "graph.json")}
+`);
+  return 0;
+}
+var init_scan = __esm({
+  "src/cli/commands/scan.ts"() {
+    "use strict";
+    init_detect();
+    init_analyze();
+    init_graph();
+    init_fs_safe();
+    init_tty();
+  }
+});
+
+// src/cli/commands/plan.ts
+var plan_exports = {};
+__export(plan_exports, {
+  renderPlan: () => renderPlan,
+  runPlan: () => runPlan
+});
+import pc4 from "picocolors";
+function renderPlan(project, graph, analysis, changed) {
+  const plain = isPlain();
+  const bold = (s) => plain ? s : pc4.bold(s);
+  const dim = (s) => plain ? s : pc4.dim(s);
+  const warn = (s) => plain ? s : pc4.yellow(s);
+  const lines = [];
+  lines.push(bold("Veris \u2014 plan"));
+  lines.push(dim(`(graph via ${graph.resolver})`));
+  lines.push("");
+  lines.push("Test these first (high impact, untested)");
+  const top = analysis.untested.slice(0, 5);
+  if (top.length === 0)
+    lines.push(
+      dim(
+        "  none \u2014 untested files have no dependents or all files are covered"
+      )
+    );
+  top.forEach((f, i) => {
+    lines.push(
+      `  ${i + 1}. ${f}   ${dim(`(${analysis.blastRadius[f] ?? 0} dependents, no test reaches it)`)}`
+    );
+  });
+  lines.push("");
+  lines.push("Verification setup");
+  const weak = project.capabilities.filter(
+    (c) => !c.available && c.id !== "browser"
+  );
+  if (weak.length === 0)
+    lines.push(dim("  \u2713 types, lint, and unit are all configured"));
+  for (const c of weak)
+    lines.push(
+      `  ${warn("\u26A0")} ${c.id} capability unavailable \u2014 ${c.reason ?? "not configured"}`
+    );
+  if (changed.length) {
+    lines.push("");
+    lines.push(`Risky changes (${changed.length} changed file(s))`);
+    if (analysis.risky.length === 0) lines.push(dim("  none flagged"));
+    for (const f of analysis.risky.slice(0, 8)) {
+      const untested = analysis.untested.includes(f) ? ", untested" : "";
+      lines.push(
+        `  ${warn("!")} ${f}   ${dim(`${analysis.blastRadius[f] ?? 0} dependents${untested}`)}`
+      );
+    }
+  }
+  lines.push("");
+  lines.push(
+    dim("Next: `veris affected` runs only the tests that reach your changes.")
+  );
+  return lines.join("\n");
+}
+async function runPlan(root, opts = {}) {
+  const project = await detectProject(root);
+  const graph = await buildGraph(project);
+  const { files } = await changedFiles(root, { base: opts.base });
+  const analysis = analyze(graph, files);
+  process.stdout.write(`${renderPlan(project, graph, analysis, files)}
+`);
+  return 0;
+}
+var init_plan = __esm({
+  "src/cli/commands/plan.ts"() {
+    "use strict";
+    init_detect();
+    init_changes();
+    init_analyze();
+    init_graph();
+    init_tty();
+  }
+});
+
 // src/cli/index.ts
 import { realpathSync } from "fs";
 import { argv } from "process";
@@ -1242,6 +1760,17 @@ function buildCli() {
     const { runWatch: runWatch2 } = await Promise.resolve().then(() => (init_watch(), watch_exports));
     process.exitCode = await runWatch2(process.cwd(), { poll: opts.poll });
   });
+  cli.command("scan", "Map the import graph and untested areas (read-only)").action(async () => {
+    const { runScan: runScan2 } = await Promise.resolve().then(() => (init_scan(), scan_exports));
+    process.exitCode = await runScan2(process.cwd());
+  });
+  cli.command(
+    "plan",
+    "Recommend what to test, from the import graph (read-only)"
+  ).option("--base <ref>", "Also factor in changes vs a git ref").action(async (opts) => {
+    const { runPlan: runPlan2 } = await Promise.resolve().then(() => (init_plan(), plan_exports));
+    process.exitCode = await runPlan2(process.cwd(), { base: opts.base });
+  });
   return { raw: cli, version: VERSION };
 }
 async function main(argv2) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "veriskit",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "The fastest way to prove your software works — a zero-config verification CLI.",
   "scripts": {
     "test": "vitest run",
@@ -34,7 +34,7 @@
     "@biomejs/biome": "^2.5.3",
     "@types/node": "^26.1.1",
     "tsup": "^8.5.1",
-    "typescript": "^7.0.2",
+    "typescript": "^6.0.3",
     "vitest": "^4.1.10"
   },
   "files": [