objectstack-ai
diff --git a/‎.changeset/18432-docs-step-line-reports-count.md‎
Lines changed: 17 additions & 0 deletions b/‎.changeset/18432-docs-step-line-reports-count.md‎
Lines changed: 17 additions & 0 deletions
diff --git a/‎content/docs/deployment/cli.mdx‎
Lines changed: 8 additions & 2 deletions b/‎content/docs/deployment/cli.mdx‎
Lines changed: 8 additions & 2 deletions
diff --git a/‎packages/cli/src/commands/compile.ts‎
Lines changed: 10 additions & 1 deletion b/‎packages/cli/src/commands/compile.ts‎
Lines changed: 10 additions & 1 deletion
diff --git a/‎packages/cli/test/build-docs-step-count.e2e.test.ts‎
Lines changed: 215 additions & 0 deletions b/‎packages/cli/test/build-docs-step-count.e2e.test.ts‎
Lines changed: 215 additions & 0 deletions
@@ -0,0 +1,17 @@
+---
+"@objectstack/cli": patch
+---
+
+`os build` / `os compile` — the package-docs step line is printed **after** the collection it announces and carries the count, so a build that collected nothing no longer reads identically to one that collected four documents (#18432).
+
+```
+  → Collecting package docs (ADR-0046)...              ← before: every run
+  → Collecting package docs (ADR-0046)... 0 collected  ← after: this run found none
+  → Collecting package docs (ADR-0046)... 4 collected
+```
+
+The sentence was unconditional and was emitted **before** `collectAndLintDocs` ran, so the reassurance it offers — the docs step ran, and it found your docs — was true of every run including the ones that found nothing at all. This is the reassurance half of #18170: an exit-0 build carrying the usual progress line is the shape every reader trusts. #18428 landed the audible half, where an uncollected docs directory speaks for itself.
+
+- **The docs step now reports what it collected, not what it attempted.** A project whose `src/docs/` is empty, or whose docs directory moved into a package under an ADR-0130 layout, prints `0 collected` here instead of the same sentence a successful collection prints.
+- **The printed number is the artifact's `docs` set**, the same `docsResult.docs` the build writes into `dist/objectstack.json` — pinned from both ends (absent directory, empty directory, two docs) in `packages/cli/test/build-docs-step-count.e2e.test.ts`, because a test that only asserted the sentence was printed passes on the defective tree.
+- **`--json` is unchanged**: the line has always lived behind `if (!flags.json)` and the machine face still emits one JSON document with no step text.
@@ -591,7 +591,7 @@ os compile --json                    # JSON output for CI pipelines
   → Validating protocol compliance...
   → Running author-time rules (45)...
   → Checking capability providers (#3366)...
-  → Collecting package docs (ADR-0046)...
+  → Collecting package docs (ADR-0046)... 0 collected
   → Writing artifact...
 
   ✓ Build complete (74ms)
@@ -604,7 +604,13 @@ os compile --json                    # JSON output for CI pipelines
 ```
 
 Those counts are from a sample project, named in full under [`os info`](#os-info)
-below — the same fixture backs both output examples.
+below — the same fixture backs both output examples. It ships no `src/docs/`
+directory, which is why the docs step reads `0 collected`.
+
+The docs step reports what it collected, not what it attempted — a project whose
+`src/docs/` is empty, or whose docs directory moved into a package under an
+ADR-0130 layout, prints `0 collected` here instead of the same sentence a
+successful collection prints.
 
 The resulting `dist/objectstack.json` is a **portable, self-describing deployment unit** —
 you can hand it to `os start` (locally or on a server), publish it to a CDN, or fetch it
 
@@ -649,8 +649,17 @@ export default class Compile extends Command {
       //
       //     Not a registry rule: it reads `src/docs/` off disk, and the docs it
       //     collects there are an INPUT to the artifact, not just a check.
-      if (!flags.json) printStep('Collecting package docs (ADR-0046)...');
+      //
+      // [#18432] The step line is printed AFTER the call and carries the count.
+      //     Printed before it, the line announced a collection the build had
+      //     not performed yet, so a run that collected NOTHING — an empty or
+      //     absent `src/docs/`, or a docs directory that moved into a package
+      //     under an ADR-0130 layout — emitted the same reassuring sentence as
+      //     a run that collected four documents. Reporting the count is what
+      //     makes the two runs distinguishable; the ordering is what makes the
+      //     count available to report.
       const docsResult = collectAndLintDocs(absolutePath, result.data as Record<string, unknown>);
+      if (!flags.json) printStep(`Collecting package docs (ADR-0046)... ${docsResult.docs.length} collected`);
       const docErrors = docsResult.issues.filter((i) => i.severity === 'error');
       // [#11727] Consumed by BOTH faces — the text block below and the `--json`
       //     payload. Only the text block read it before, so the advisories were
 
@@ -0,0 +1,215 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * #18432 — `os build`'s package-docs step line was printed BEFORE the call it
+ * announces, so a build that collected nothing read identically to one that
+ * collected four documents.
+ *
+ *     if (!flags.json) printStep('Collecting package docs (ADR-0046)...');
+ *     const docsResult = collectAndLintDocs(...)
+ *
+ * The sentence was unconditional and carried no count, so the reassurance it
+ * offers — "the docs step ran, and it found your docs" — was true of every run
+ * including the ones that found nothing at all. That is the reassurance half of
+ * #18170: an exit-0 build with the usual progress line is the shape every
+ * reader trusts. #18428 landed the audible half (an uncollected docs directory
+ * now speaks); this is the other half.
+ *
+ * ## WHAT THESE PINS ASSERT — the PAIR, not the sentence
+ *
+ * A test that only checked "the step line is printed" passes on the defective
+ * tree and pins nothing: the defective tree printed it unconditionally. So the
+ * behaviour is pinned from both ends over fixtures that differ in exactly one
+ * respect — whether `src/docs/` holds anything:
+ *
+ *   - absent `src/docs/`   -> `0 collected`
+ *   - empty  `src/docs/`   -> `0 collected`
+ *   - two docs            -> `2 collected`
+ *
+ * Only the count tells the three runs apart, and only a line printed AFTER the
+ * collection can carry one — which is why this is the assertion that would have
+ * caught the original defect rather than a restatement of it.
+ *
+ * ## The count is the ARTIFACT's docs, not a decoration
+ *
+ * `compile.ts` writes `finalBundle.docs = docsResult.docs` from the same value
+ * it now prints, so each run's printed count is compared against the emitted
+ * artifact. A number that drifted away from the set it describes would be a
+ * second silent-reassurance defect wearing the fix's clothes; asserting only
+ * the text could not see it.
+ *
+ * ## `--json` carries no step line, and that is pinned too
+ *
+ * The printed line lives behind `if (!flags.json)`. The template literal is new
+ * and the `--json` face must stay one JSON document, so the machine face is
+ * asserted to parse and to carry no step text at all.
+ *
+ * ALTITUDE: this spawns the CLI (`bin/run-dev.js` through tsx) rather than
+ * calling a helper, because the defect is in the ORDER of two statements inside
+ * the command body — there is no seam below the process that can observe it.
+ * Same spawn shape and the same `childEnv()` as
+ * `build-json-advisory-parity.e2e.test.ts`, so nothing here is a new pattern.
+ */
+
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { execFile } from 'node:child_process';
+import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { childEnv } from './helpers/serve-process.js';
+
+const HERE = resolve(fileURLToPath(import.meta.url), '..');
+const CLI = resolve(HERE, '../bin/run-dev.js');
+const TSX = resolve(HERE, '../../../node_modules/.bin/tsx');
+
+interface Run {
+  code: number;
+  stdout: string;
+  stderr: string;
+}
+
+function runCli(args: string[], cwd: string): Promise<Run> {
+  return new Promise((resolvePromise) => {
+    execFile(
+      TSX,
+      [CLI, ...args],
+      { cwd, maxBuffer: 16 * 1024 * 1024, env: childEnv({ NO_COLOR: '1' }) },
+      (err, stdout, stderr) => {
+        resolvePromise({
+          code: err ? (typeof (err as { code?: unknown }).code === 'number' ? (err as unknown as { code: number }).code : 1) : 0,
+          stdout: String(stdout),
+          stderr: String(stderr),
+        });
+      },
+    );
+  });
+}
+
+/** The step line, matched so the COUNT is captured and nothing else is assumed. */
+const STEP_LINE = /Collecting package docs \(ADR-0046\)\.\.\.\s*(\d+) collected/;
+
+/** The sentence with NO count — the pre-fix spelling, asserted absent. */
+const COUNTLESS_STEP_LINE = /Collecting package docs \(ADR-0046\)\.\.\.\s*$/m;
+
+/** What the step line reported on this run, or `null` when it was not printed. */
+function printedCount(run: Run): number | null {
+  const m = STEP_LINE.exec(run.stdout);
+  return m ? Number(m[1]) : null;
+}
+
+/** How many docs the emitted artifact actually carries. */
+function artifactDocCount(dir: string): number {
+  const raw = readFileSync(join(dir, 'dist', 'objectstack.json'), 'utf8');
+  const parsed = JSON.parse(raw) as { docs?: unknown };
+  return Array.isArray(parsed.docs) ? parsed.docs.length : 0;
+}
+
+/**
+ * A stack that builds cleanly. The namespace is a parameter because ADR-0046
+ * lints doc names for the package's namespace prefix — a fixture whose docs did
+ * not carry it would fail the build and every count below would be reading an
+ * aborted run.
+ */
+const config = (ns: string) => `
+export default {
+  manifest: { id: 'com.example.${ns}', name: '${ns}', version: '1.0.0', type: 'app', namespace: '${ns}' },
+  requires: [],
+  objects: [
+    {
+      name: '${ns}_thing',
+      label: 'Thing',
+      sharingModel: 'private',
+      fields: { title: { type: 'text', label: 'Title' } },
+    },
+  ],
+};
+`;
+
+const doc = (title: string) => `---
+title: ${title}
+---
+
+# ${title}
+
+Body text.
+`;
+
+/** `absent` has no `src/docs/` at all; `empty` has the directory and no files. */
+const dirs: Record<'absent' | 'empty' | 'two', string> = { absent: '', empty: '', two: '' };
+let root = '';
+
+beforeAll(() => {
+  root = mkdtempSync(join(tmpdir(), 'os-docs-step-'));
+
+  dirs.absent = join(root, 'absent');
+  mkdirSync(join(dirs.absent, 'src'), { recursive: true });
+  writeFileSync(join(dirs.absent, 'objectstack.config.ts'), config('dsabsent'));
+
+  dirs.empty = join(root, 'empty');
+  mkdirSync(join(dirs.empty, 'src', 'docs'), { recursive: true });
+  writeFileSync(join(dirs.empty, 'objectstack.config.ts'), config('dsempty'));
+
+  dirs.two = join(root, 'two');
+  mkdirSync(join(dirs.two, 'src', 'docs'), { recursive: true });
+  writeFileSync(join(dirs.two, 'objectstack.config.ts'), config('dstwo'));
+  writeFileSync(join(dirs.two, 'src', 'docs', 'dstwo_intro.md'), doc('Intro'));
+  writeFileSync(join(dirs.two, 'src', 'docs', 'dstwo_guide.md'), doc('Guide'));
+});
+
+afterAll(() => {
+  if (root) rmSync(root, { recursive: true, force: true });
+});
+
+describe('[#18432] the package-docs step line reports what it collected', () => {
+  it('ABSENT `src/docs/`: the step line reads `0 collected`, and the artifact carries no docs', async () => {
+    const run = await runCli(['build'], dirs.absent);
+    // Asserted first: a non-zero exit would make every claim below vacuous.
+    expect(run.code, `stdout:\n${run.stdout}\nstderr:\n${run.stderr}`).toBe(0);
+
+    expect(printedCount(run)).toBe(0);
+    expect(artifactDocCount(dirs.absent)).toBe(0);
+
+    // The pre-fix spelling — the sentence with nothing after the ellipsis — is
+    // the shape this card exists to remove. Pinned as absent so a revert of the
+    // ordering shows up here rather than in a customer's build log.
+    expect(COUNTLESS_STEP_LINE.test(run.stdout)).toBe(false);
+  }, 120_000);
+
+  it('EMPTY `src/docs/`: also `0 collected` — a present-but-empty directory is not a collection', async () => {
+    const run = await runCli(['build'], dirs.empty);
+    expect(run.code, `stdout:\n${run.stdout}\nstderr:\n${run.stderr}`).toBe(0);
+
+    expect(printedCount(run)).toBe(0);
+    expect(artifactDocCount(dirs.empty)).toBe(0);
+  }, 120_000);
+
+  it('TWO docs: the step line reads `2 collected` — the other end of the pair', async () => {
+    const run = await runCli(['build'], dirs.two);
+    expect(run.code, `stdout:\n${run.stdout}\nstderr:\n${run.stderr}`).toBe(0);
+
+    expect(printedCount(run)).toBe(2);
+    // The printed number IS the set the artifact receives, not a tally kept
+    // beside it.
+    expect(artifactDocCount(dirs.two)).toBe(2);
+  }, 120_000);
+
+  it('the three runs are DISTINGUISHABLE — the defect was that they were not', async () => {
+    // The whole card in one assertion. On the defective tree all three runs
+    // printed the identical sentence; the only thing that separates them is the
+    // count, and the count is only available after the collection has happened.
+    const [absent, empty, two] = await Promise.all([
+      runCli(['build'], dirs.absent),
+      runCli(['build'], dirs.empty),
+      runCli(['build'], dirs.two),
+    ]);
+    expect([printedCount(absent), printedCount(empty), printedCount(two)]).toEqual([0, 0, 2]);
+  }, 180_000);
+
+  it('`--json` prints no step line at all and stays one JSON document', async () => {
+    const run = await runCli(['build', '--json'], dirs.two);
+    expect(run.code, `stdout:\n${run.stdout}\nstderr:\n${run.stderr}`).toBe(0);
+    expect(() => JSON.parse(run.stdout)).not.toThrow();
+    expect(run.stdout).not.toMatch(/Collecting package docs/);
+  }, 120_000);
+});