fix(cli): withhold doctor's ✓ over a tree it never examined (#10679) (#10799)

`findMissingTests()` and `findDeprecatedUsages()` both walk
`<cwd>/packages/spec/src`, a path present in this monorepo and in no
application. Both returned `[]` for "that directory is not here" — the same
value they return for "I walked it and found nothing wrong" — so every stock
scaffold printed `✓ Test coverage` and `✓ Deprecations` about files doctor
never opened, exiting 0 either way.

Whether the tree was examined is now a fact in the return type
(`MonorepoTreeScan`), the shape #5413 used for the installed-package ledger,
so the print site cannot reach the `✓` from the unexamined arm. An unexamined
tree prints an informational skip naming the reason, with the resolved
directory under `--verbose`. It is deliberately not a warning: withholding a
false ✓ must not manufacture a false ⚠.

The adjacent `⚠ @objectstack/spec  Not built` probe is gated on the workspace
existing — outside the monorepo it warned about an absent package and
prescribed a command that cannot succeed there. Inside it, unchanged.

Two control assertions that pinned `Environment is functional but has some
warnings` held only because of that phantom warning; they now assert the claim
they actually make (doctor reached its summary and did not call the
environment broken).


Claude-Session: https://claude.ai/code/session_019bmVFqoQPq63zhKrxdYG1r

Co-authored-by: Claude <noreply@anthropic.com>

Author: Elon Musk

.changeset/doctor-withholds-checks-over-unexamined-tree.md

@@ -0,0 +1,54 @@
+---
+"@objectstack/cli": patch
+---
+
+`os doctor` no longer prints `✓ Test coverage` / `✓ Deprecations` about a tree it
+never examined, and no longer warns `@objectstack/spec  Not built` about a
+workspace that is not part of the tree (#10679).
+
+`findMissingTests()` and `findDeprecatedUsages()` both walk
+`<cwd>/packages/spec/src` — a path that exists in this monorepo and in no
+application built with the framework. Both answered "that directory is not here"
+with the same value they return for "I walked it and found nothing wrong" (an
+empty array), so in a stock `create-objectstack -t blank` scaffold every run
+printed, verbatim:
+
+```
+  ✓ Test coverage         All *.zod.ts files have matching tests
+  ✓ Deprecations          No @deprecated tags found
+```
+
+about files doctor never opened. The command exits 0 either way, so "no problems
+found" and "I never looked" were byte-identical to every downstream reader.
+
+Doctor already refuses to do this one screen down: the ADR-0120 D5e advisory's
+`✓ Unique scope` is withheld unless `ledgerReadingIsComplete()` says the ledger
+half was read in full. These two checks escaped that discipline; this restores
+it, in the same shape #5413 used for the ledger — whether the tree was examined
+is now a fact in the return type rather than an absence, so the print site
+cannot reach the `✓` from the unexamined arm. Where the tree is absent doctor
+prints an informational, named-reason skip instead:
+
+```
+  ℹ Test coverage         Skipped — no packages/spec/src in this directory (monorepo-only check)
+  ℹ Deprecations          Skipped — no packages/spec/src in this directory (monorepo-only check)
+```
+
+`--verbose` adds the resolved directory it looked for. The skip is deliberately
+not a warning: nothing is wrong in an application that has no
+`packages/spec/src`, and withholding a false `✓` must not manufacture a false
+`⚠`.
+
+The adjacent `⚠ @objectstack/spec  Not built` probe read `<cwd>/packages/spec/dist`
+with no check that the workspace it names exists, so in an application it warned
+about an absent package and prescribed `pnpm --filter @objectstack/spec build`, a
+command that cannot succeed there. It is now gated on `packages/spec/package.json`
+being present. Inside the monorepo the row is unchanged; outside it there is no
+row, and an application's spec dependency stays covered by the `Dependencies`
+check and by the spec-version-gap advisory.
+
+Exit codes are untouched — 1 exactly when an error row exists, warnings never
+flip it. One visible consequence: a stock scaffold with no other findings now
+ends on `✅ Environment is healthy and ready for development!` instead of
+`⚠️  Environment is functional but has some warnings`, because the warning it
+used to carry was about a workspace that was never there.

packages/cli/src/commands/doctor-env-provenance.test.ts

@@ -447,7 +447,18 @@ describe('os doctor, end to end, against a posture that only exists in .env', ()
     const healthy = await runDoctor();
 
     expect(healthy.exitCode).toBeUndefined();
-    expect(healthy.out).toContain('Environment is functional');
+    // #10679 — this used to read `toContain('Environment is functional')`, and
+    // it passed for a reason that had nothing to do with #5387: the temp cwd
+    // has no `packages/spec`, and doctor warned `@objectstack/spec Not built`
+    // about that absent workspace on every run. Removing that phantom warning
+    // leaves this cwd with no findings at all, so the summary is now the
+    // healthy one. What the control actually claims — doctor reached its
+    // summary and did NOT refuse to call this environment usable — is what the
+    // matcher says instead, and it still cannot pass for the broken leg below
+    // (that one prints `Some critical issues found`).
+    expect(healthy.out).toMatch(
+      /Environment is (healthy and ready for development|functional but has some warnings)/,
+    );
     expect(healthy.out).not.toContain('Tenancy posture');
     // The report says what it read even when everything is fine — that is the
     // "not a silent merge" half, and it is only observable on a healthy run.

packages/cli/src/commands/doctor-tenancy-posture-report.test.ts

@@ -295,8 +295,19 @@ describe('os doctor reports an unrecognized posture and exits non-zero', () => {
 
     // Doctor completes normally. This is the sentence #5382 quoted, and here it
     // is CORRECT: this environment really can start.
+    //
+    // #10679 — the matcher accepts either non-error summary. The control used
+    // to pin `Environment is functional but has some warnings` literally, and
+    // it held only because the temp cwd has no `packages/spec` and doctor
+    // warned `@objectstack/spec Not built` about that absent workspace every
+    // time. With that phantom warning gone this cwd has no findings, so the
+    // summary is the healthy one. Either sentence proves the control's actual
+    // claim; neither can be produced by the broken leg below, which prints
+    // `Some critical issues found` and exits 1.
     expect(healthy.exitCode).toBeUndefined();
-    expect(healthy.out).toContain('Environment is functional');
+    expect(healthy.out).toMatch(
+      /Environment is (healthy and ready for development|functional but has some warnings)/,
+    );
     expect(healthy.out).not.toContain('Tenancy posture');
 
     // ── The case: one character changed ──────────────────────────────────