[PR #2768] [MERGED] feat(cli): summarize committed reference-source inventories #5377

New issue

Closed

opened 2026-10-31 01:06:10 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-31 01:06:10 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/2768
Author: @To3akaRin
Created: 10/13/2026
Status: ✅ Merged
Merged: 10/13/2026
Merged by: @morluto

Base: main ← Head: codex/reference-source-summary

📝 Commits (1)

85ef6ac feat(cli): summarize committed reference-source inventories

📊 Changes

5 files changed (+461 additions, -2 deletions)

View changed files

📝 docs/cli.md (+28 -0)
📝 src/cli/utilityCommands.ts (+46 -2)
➕ src/domain/referenceSourceSummary.test.ts (+104 -0)
➕ src/domain/referenceSourceSummary.ts (+93 -0)
➕ tests/boundary/cli/referenceSourceSummary.test.ts (+190 -0)

📄 Description

Summary

Fixes #2442.

rea import-reference-source ROOT --detail summary now answers the initial inventory question without printing every committed file hash and relationship. Complete HistoricalSourceGraph output remains the default and is byte-identical to explicit --detail full on the regression fixture.

Problem and expected behavior

Large source imports require callers to consume the full graph just to inspect its inventory, languages, manifests and root structure. The opt-in HistoricalSourceSummary contains the canonical HistoricalSourceManifest, provenance, VCS facts, inventory state, counts, file/directory states, known sizes, exclusions, limitations and a caller-selected outline.

rea import-reference-source /absolute/path/to/source --detail summary --outline-depth 2 --json

--outline-depth accepts a nonnegative safe integer, defaults to 2 for summaries, and requires --detail summary. Depth 1 shows root children; depth 0 hides all outline entries. outline.omitted_entry_count counts inventoried entries hidden by depth, separately from source exclusions and unexamined coverage. Known file bytes use decimal text for exact large totals, with an independent unknown-size count.

Change and scope

Project the already committed graph after successful import and cleanup, using createHistoricalSourceManifest; do not reread source files or reinterpret source evidence.
Preserve canonical Unicode code-point ordering by selecting from the canonical entries. Keep each visible entry's state/limitations; remove individual file hashes from the outline.
Retain original exclusions and graph limitations, report parse-failure counts, and leave full relationships and diagnostic records in the complete graph output. The summary is a presentation view, not a graph accepted by source-to-bundle comparison.
Document options, unknown sizes, outline versus inventory coverage, and output-size limits in the owning CLI guide.

This is an explicit local projection of an existing CLI operation. A new-provider/target-execution maintainer scope decision is not applicable. No upstream implementation or prompt text was copied.

Contract and boundary impact

Semantic owner and earliest changed stage: domain projection of a successfully committed HistoricalSourceGraph, selected by the CLI after resource cleanup.
CLI/MCP: two opt-in CLI options and the distinct HistoricalSourceSummary marker; default graph output and existing failures remain unchanged. No MCP tool/provider/catalog contract change.
Evidence and provenance: canonical root/graph commitments and manifest identity match full output. Inventory state and unknowns are preserved; outline omission does not imply absent source.
Target/authority/cleanup: existing caller-selected local tree and import lifecycle. No new target execution, injection, network access, source mutation or protection recovery.
Package/installation/release: no dependencies, environment variables, installation changes, or generated files committed.

Expected effects:

Read existing files or captured data through the existing importer.

Evidence and regression coverage

Before implementation, the new public CLI suite had 3 failures because the base rejected --detail; 7 negative-input cases passed. After implementation, the new CLI suite passes 11/11:

Default and explicit full output have identical stdout; summary manifests match the full graph at default, zero, shallow and deep outline selections.
Real owned fixtures exercise nested imports, manifest/language indexes, supplementary Unicode paths, exclusions and parse failures.
Public help advertises the options. Invalid detail, negative/fractional/NaN/unsafe depth, and depth with full output fail. Missing-root failure still reports invalid_input.
Domain cases cover graph immutability, unknown inventory/VCS/file size, unknown directories, missing symlinks, and exact byte totals above Number.MAX_SAFE_INTEGER.

Existing import-status, exclusion and committed-graph suites also pass. POSIX permission behavior is exercised; the existing native-Windows cases are skipped on this macOS host.

Output and resource measurements

Compared the unchanged full output with summary depth 2 on this branch's real src/ tree: 1,840 entries (1,721 files, 119 directories), 10,459 relationships, and the same partial inventory and limitation. Summary retains 1,158 outline entries and explicitly omits 682. Every run produced the same root/graph commitment and manifest ID.

Output	JSON bytes	Estimated output tokens (`tokenx` 1.3.0)	First run wall / CPU / peak RSS	Subsequent 3 runs wall / CPU / peak RSS
Full	2,043,760	575,394	4.22 s / 5.39 s / 447.8 MiB	4.37–4.63 s / 5.73–5.83 s / 399.6–459.6 MiB
Summary, depth 2	187,508	53,313	4.07 s / 5.35 s / 445.8 MiB	4.10–5.44 s / 5.52–6.30 s / 459.8–467.6 MiB

Method: alternating full/summary public CLI invocations under /usr/bin/time -l, four runs each, Node compile cache disabled, stdout captured and parsed. Each invocation starts a new Node process; source imports acquire no target/provider subprocesses, so the measured Node process is the workflow process family. First runs are process-cold, not a flushed filesystem-cache experiment; subsequent runs reuse OS filesystem caches. Background host work was not controlled. Tokens are a heuristic estimate of output only, not measured model usage or whole-agent-task cost. No stable elapsed-time, CPU or memory improvement is claimed. The selected output was 90.8% smaller in bytes; shallow trees and large exclusion/limitation lists need not shrink similarly. Depth 0 removes only the outline.

Validation performed

npm run test:focused -- src/domain/referenceSourceSummary.test.ts src/domain/referenceSourceGraph.test.ts tests/boundary/cli/referenceSourceSummary.test.ts tests/boundary/cli/referenceSourceExclusions.test.ts tests/boundary/cli/referenceSourceImportStatus.test.ts — 31 passed, 2 Windows cases skipped before the added help assertion.
npm run test:focused -- tests/boundary/cli/referenceSourceSummary.test.ts — final 11/11 passed, including help.
npm run check — typecheck, lint, format, knip, metadata, module boundaries and architecture guards passed.
npm run docs:check — passed, including the 2 README consistency tests.
npm run verify:test-discovery — all 1,057 test files discovered exactly once.
git diff --check — passed.

Host: macOS arm64, Node.js 24.19.0, npm 11.17.0. The pinned Node.js 24.18.0 was unavailable after TLS/download failures; it was not tested locally. Full CI/coverage and Linux/Windows execution remain unverified locally. This projection uses no native analysis engine; no real-engine claims are made.

Before merge

Concrete problem and linked issue; one focused Conventional Commit outcome.
Final scope and authority are resolved within existing local import boundaries.
Public CLI, uncertainty, ordering, commitment and compatibility coverage.
Owning documentation updated; generated outputs and local planning files excluded.
Representative output/resource comparison with explicit measurement limits.
Final diff checked for secrets, unrelated cleanup and unsupported claims.

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/morluto/rea/pull/2768 **Author:** [@To3akaRin](https://github.com/To3akaRin) **Created:** 10/13/2026 **Status:** ✅ Merged **Merged:** 10/13/2026 **Merged by:** [@morluto](https://github.com/morluto) **Base:** `main` ← **Head:** `codex/reference-source-summary` --- ### 📝 Commits (1) - [`85ef6ac`](https://github.com/morluto/rea/commit/85ef6ac0e2af887c049aef51849f66767e61236d) feat(cli): summarize committed reference-source inventories ### 📊 Changes **5 files changed** (+461 additions, -2 deletions) <details> <summary>View changed files</summary> 📝 `docs/cli.md` (+28 -0) 📝 `src/cli/utilityCommands.ts` (+46 -2) ➕ `src/domain/referenceSourceSummary.test.ts` (+104 -0) ➕ `src/domain/referenceSourceSummary.ts` (+93 -0) ➕ `tests/boundary/cli/referenceSourceSummary.test.ts` (+190 -0) </details> ### 📄 Description ## Summary Fixes #2442. `rea import-reference-source ROOT --detail summary` now answers the initial inventory question without printing every committed file hash and relationship. Complete `HistoricalSourceGraph` output remains the default and is byte-identical to explicit `--detail full` on the regression fixture. ## Problem and expected behavior Large source imports require callers to consume the full graph just to inspect its inventory, languages, manifests and root structure. The opt-in `HistoricalSourceSummary` contains the canonical `HistoricalSourceManifest`, provenance, VCS facts, inventory state, counts, file/directory states, known sizes, exclusions, limitations and a caller-selected outline. ```sh rea import-reference-source /absolute/path/to/source --detail summary --outline-depth 2 --json ``` `--outline-depth` accepts a nonnegative safe integer, defaults to 2 for summaries, and requires `--detail summary`. Depth 1 shows root children; depth 0 hides all outline entries. `outline.omitted_entry_count` counts inventoried entries hidden by depth, separately from source exclusions and unexamined coverage. Known file bytes use decimal text for exact large totals, with an independent unknown-size count. ## Change and scope - Project the already committed graph after successful import and cleanup, using `createHistoricalSourceManifest`; do not reread source files or reinterpret source evidence. - Preserve canonical Unicode code-point ordering by selecting from the canonical entries. Keep each visible entry's state/limitations; remove individual file hashes from the outline. - Retain original exclusions and graph limitations, report parse-failure counts, and leave full relationships and diagnostic records in the complete graph output. The summary is a presentation view, not a graph accepted by source-to-bundle comparison. - Document options, unknown sizes, outline versus inventory coverage, and output-size limits in the owning CLI guide. This is an explicit local projection of an existing CLI operation. A new-provider/target-execution maintainer scope decision is not applicable. No upstream implementation or prompt text was copied. ## Contract and boundary impact - Semantic owner and earliest changed stage: domain projection of a successfully committed `HistoricalSourceGraph`, selected by the CLI after resource cleanup. - CLI/MCP: two opt-in CLI options and the distinct `HistoricalSourceSummary` marker; default graph output and existing failures remain unchanged. No MCP tool/provider/catalog contract change. - Evidence and provenance: canonical root/graph commitments and manifest identity match full output. Inventory state and unknowns are preserved; outline omission does not imply absent source. - Target/authority/cleanup: existing caller-selected local tree and import lifecycle. No new target execution, injection, network access, source mutation or protection recovery. - Package/installation/release: no dependencies, environment variables, installation changes, or generated files committed. Expected effects: - [x] Read existing files or captured data through the existing importer. ## Evidence and regression coverage Before implementation, the new public CLI suite had 3 failures because the base rejected `--detail`; 7 negative-input cases passed. After implementation, the new CLI suite passes 11/11: - Default and explicit full output have identical stdout; summary manifests match the full graph at default, zero, shallow and deep outline selections. - Real owned fixtures exercise nested imports, manifest/language indexes, supplementary Unicode paths, exclusions and parse failures. - Public help advertises the options. Invalid detail, negative/fractional/NaN/unsafe depth, and depth with full output fail. Missing-root failure still reports `invalid_input`. - Domain cases cover graph immutability, unknown inventory/VCS/file size, unknown directories, missing symlinks, and exact byte totals above `Number.MAX_SAFE_INTEGER`. Existing import-status, exclusion and committed-graph suites also pass. POSIX permission behavior is exercised; the existing native-Windows cases are skipped on this macOS host. ## Output and resource measurements Compared the unchanged full output with summary depth 2 on this branch's real `src/` tree: 1,840 entries (1,721 files, 119 directories), 10,459 relationships, and the same partial inventory and limitation. Summary retains 1,158 outline entries and explicitly omits 682. Every run produced the same root/graph commitment and manifest ID. | Output | JSON bytes | Estimated output tokens (`tokenx` 1.3.0) | First run wall / CPU / peak RSS | Subsequent 3 runs wall / CPU / peak RSS | | --- | ---: | ---: | --- | --- | | Full | 2,043,760 | 575,394 | 4.22 s / 5.39 s / 447.8 MiB | 4.37–4.63 s / 5.73–5.83 s / 399.6–459.6 MiB | | Summary, depth 2 | 187,508 | 53,313 | 4.07 s / 5.35 s / 445.8 MiB | 4.10–5.44 s / 5.52–6.30 s / 459.8–467.6 MiB | Method: alternating full/summary public CLI invocations under `/usr/bin/time -l`, four runs each, Node compile cache disabled, stdout captured and parsed. Each invocation starts a new Node process; source imports acquire no target/provider subprocesses, so the measured Node process is the workflow process family. First runs are process-cold, not a flushed filesystem-cache experiment; subsequent runs reuse OS filesystem caches. Background host work was not controlled. Tokens are a heuristic estimate of output only, not measured model usage or whole-agent-task cost. No stable elapsed-time, CPU or memory improvement is claimed. The selected output was 90.8% smaller in bytes; shallow trees and large exclusion/limitation lists need not shrink similarly. Depth 0 removes only the outline. ## Validation performed - `npm run test:focused -- src/domain/referenceSourceSummary.test.ts src/domain/referenceSourceGraph.test.ts tests/boundary/cli/referenceSourceSummary.test.ts tests/boundary/cli/referenceSourceExclusions.test.ts tests/boundary/cli/referenceSourceImportStatus.test.ts` — 31 passed, 2 Windows cases skipped before the added help assertion. - `npm run test:focused -- tests/boundary/cli/referenceSourceSummary.test.ts` — final 11/11 passed, including help. - `npm run check` — typecheck, lint, format, knip, metadata, module boundaries and architecture guards passed. - `npm run docs:check` — passed, including the 2 README consistency tests. - `npm run verify:test-discovery` — all 1,057 test files discovered exactly once. - `git diff --check` — passed. Host: macOS arm64, Node.js 24.19.0, npm 11.17.0. The pinned Node.js 24.18.0 was unavailable after TLS/download failures; it was not tested locally. Full CI/coverage and Linux/Windows execution remain unverified locally. This projection uses no native analysis engine; no real-engine claims are made. ## Before merge - [x] Concrete problem and linked issue; one focused Conventional Commit outcome. - [x] Final scope and authority are resolved within existing local import boundaries. - [x] Public CLI, uncertainty, ordering, commitment and compatibility coverage. - [x] Owning documentation updated; generated outputs and local planning files excluded. - [x] Representative output/resource comparison with explicit measurement limits. - [x] Final diff checked for secrets, unrelated cleanup and unsupported claims. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

2026-10-31 01:06:10 +00:00