Align v0.1.0 documentation and test every example

[leynos]

Summary

This branch gives early adopters an accurate account of Netsuke v0.1.0 and
prevents its user-facing examples from drifting away from executable
behaviour.

It replaces outdated product claims with an honest completion assessment and
road ahead, reorganizes the user's guide around real tasks, corrects linked
example manifests, and adds Rust integration, rstest-bdd, end-to-end, and
property coverage for the README and user's guide examples.

Review follow-ups align the configured default with hello.txt, correct the
photo-edit and writing outputs, and reject unsupported reusable-rule deps
instead of accepting and silently dropping them. Target and action
dependencies remain the supported implicit-dependency contract until the
planned rule-level deps_from feature is implemented.

Review walkthrough

• Start with the revised README
  for the v0.1.0 positioning, completion assessment, limitations, and
  post-release priorities.
• Review the user's guide
  for the task-oriented first-run flow, current manifest and CLI contracts,
  corrected defaults, target-only dependency guidance, diagnostics,
  accessibility, and safety boundaries.
• Check the corrected photo editing
  and writing
  manifests for their declared output contracts.
• Review the documentation-example loader,
  integration contracts,
  loader properties and failures,
  and real-Ninja E2E tests.
• Review the rule schema
  and AST validation test
  for the localized rejection of rule-level deps.

Validation

• Rebasing: clean replay onto origin/main at 2afbcb6; range-diff found
  one whitespace-only replay artefact, removed in 764e869
• Documentation-loader properties: valid, duplicate-identifier, and
  unterminated-fence contracts passed; a deliberate duplicate-rejection
  mutation failed and shrank to the minimal input
• make check-fmt: passed
• make test: passed, 1,150 tests with no failures or skips
• make typecheck: passed
• make lint: passed, including Rustdoc, Clippy, and Whitaker
• make markdownlint: passed, 69 files with zero errors
• make nixie: passed
• git diff --check: passed

Notes

Each manifest example runs in an isolated temporary workspace. The documented
first-run flows execute with real Ninja and assert the exact cat hello.txt
output; the rstest-bdd scenarios retain the novice-flow fake-Ninja process
boundary. Deterministic child-only stubs exercise the photo-edit and writing
manifests without requiring Darktable, Pandoc, or LaTeX.

The CLI rewrite requested in later review feedback was not applied: the live
parser still exposes manifest, build --emit, --diag-json, and the current
presentation flags, and does not expose generate, root --no-input, or
canonical --json. Changing the guide alone would make it inaccurate.

[sourcery-ai]

Sorry @leynos, you have reached your weekly rate limit of 500000 diff characters.

Please try again later or upgrade to continue using Sourcery

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

Summary

• Aligned README, user guide, developer guidance, examples, ADRs and design documents with Netsuke v0.1.0 behaviour.
• Reworked the CLI around generate, removing the retired manifest command and build --emit; added policy-based output controls, canonical --json, non-interactive validation, and NETSUKE_CONFIG precedence.
• Added versioned JSON result envelopes for successful build, clean, generate and graph commands, with diagnostics remaining on stderr and help/version passthrough preserved.
• Rejected unsupported rule-level deps during manifest deserialisation.
• Added executable documentation coverage, loader/property tests, BDD scenarios, isolated workspaces and Unix Ninja end-to-end tests for README, user-guide and example workflows.
• Refactored shared test helpers, capability-scoped filesystem access and JSON assertions; fixed stderr-thread cleanup on process-wait failures.
• Updated the CLI design documentation, ADR-004, Netsuke CLI design, Netsuke design and roadmap to record the implemented contracts.

Validation passed for 1,150 tests, formatting, type checking, linting, Markdown and Nixie validation, and whitespace checks.

Walkthrough

Netsuke’s v0.1.0 workflow now uses generate, typed output policies, unified JSON results and diagnostics, narrowed configuration selection, updated manifest rules, refreshed examples, and executable documentation contract tests.

Changes

v0.1.0 CLI and build workflow

Layer / File(s)	Summary
Canonical CLI and configuration contracts src/cli/*, src/main.rs, src/locale_resolution.rs, src/ast.rs	Replace legacy flags and selectors with typed policies, --json, --no-input, generate, NETSUKE_CONFIG, and explicit rejection of rule-level deps.
Command dispatch and JSON output src/runner/*, src/json_envelope.rs, src/result_json.rs	Route commands through dispatchers with versioned JSON success documents and JSON-aware stream handling.
Documentation and examples README.md, docs/*, examples/*, locales/*	Update release documentation, localized help, configuration guidance, and example manifests for the revised CLI and build flows.
Validation coverage tests/*, .github/workflows/netsukefile-test.yml, build.rs	Align unit, BDD, integration, property, end-to-end, workflow, and documentation tests with the new contracts.

Possibly related issues

• leynos/actix-v2a#53 — Documentation-example tests cover manifest-time branching and command-selection behaviour related to the issue.

Possibly related PRs

• leynos/netsuke#274 — Shares the JSON diagnostics plumbing extended here.
• leynos/netsuke#277 — Shares output-preference and status-formatting changes.
• leynos/netsuke#327 — Shares the configuration-selector precedence coverage narrowed here.

Suggested labels: Roadmap

Suggested reviewers: codescene-access, codescene-delta-analysis

Poem

YAML winds through Jinja bright,
Ninja graphs emerge in flight.
JSON speaks when streams grow still,
Policies shape each build and drill.
Docs and tests now guard the way.

---

Caution

Pre-merge checks failed

Please resolve all errors before merging. Addressing warnings is optional.

• Ignore

❌ Failed checks (3 errors, 1 inconclusive)

Check name	Status	Explanation	Resolution
Testing (Overall)	❌ Error	src/runner/dispatch.rs adds a new cli.json && output.is_some() generate branch, but tests cover --json generate and generate --output separately, not the combined path.	Add an integration/BDD test for netsuke --json generate --output <file> that asserts the file is written and stdout carries the JSON result envelope.
Module-Level Documentation	❌ Error	tests/cli_tests/parsing.rs only says 'CLI parsing coverage.', which does not clearly explain the module’s purpose or its link to the parser layer.	Expand the module doc in tests/cli_tests/parsing.rs to state that it exercises the Clap-facing CLI parser and merged CLI wiring, not just 'coverage'.
Rust Compiler Lint Integrity	❌ Error	build.rs adds module-wide #[expect(dead_code, unused_imports)] on shared source modules, hiding real unused-code diagnostics instead of narrowing the build-script surface.	Replace the broad expectations with a smaller build-script module boundary or a dedicated helper that imports only the symbols it actually uses.
Architectural Complexity And Maintainability	❓ Inconclusive	placeholder	Need to inspect architecture-relevant files before verdict.

✅ Passed checks (16 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title matches the PR’s main scope: aligning v0.1.0 docs and adding example coverage tests.
Description check	✅ Passed	The description is clearly related and summarises the documentation, example, and test changes.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
User-Facing Documentation	✅ Passed	docs/users-guide.md documents the new CLI, config, JSON, and safety behaviour; README signposts the core flow; en-US and es-ES locale keys stay aligned.
Developer Documentation	✅ Passed	Developer guide, design docs, ADR, roadmap, execplan, and both locales are in sync with the changed CLI/config/runtime boundaries; roadmap items are checked off.
Testing (Unit And Behavioural)	✅ Passed	PASS: The PR adds real CLI/E2E tests (assert_cmd, docs, logging) and unit tests cover parser/merge/AST edge cases, failures, and invariants.
Testing (Property / Proof)	✅ Passed	PASS: The PR adds proptest/Kani coverage for the new invariants—documented-example parsing, config precedence, Ninja resolution, and cycle/JSON contracts—matching the check.
Testing (Compile-Time / Ui)	✅ Passed	PASS: compile-time coverage already uses trybuild in tests/kani_cfg_ui_tests.rs, and the UI/text output changes are guarded by insta snapshots plus focused JSON/string assertions.
Unit Architecture	✅ Passed	PASS: command-side effects stay at explicit edges; path/config resolvers remain read-only, and dispatch/result JSON helpers make publication boundaries visible.
Domain Architecture	✅ Passed	Rule now models only domain fields, deps is rejected at the parse boundary, and env/fs/CLI concerns stay in manifest/runner adapters.
Observability	✅ Passed	PASS: runtime paths add structured tracing at subprocess boundaries, context-rich file I/O errors, and JSON error/result envelopes for startup/runtime failures.
Security And Privacy	✅ Passed	Keep it green: the diff adds no secrets or auth changes; JSON/generate paths only emit user-selected artefacts, and new tests use temp workspaces and fake Ninja stubs.
Performance And Resource Use	✅ Passed	PASS: The patch only factors duplicate JSON test setup; it adds no unbounded loops, heavy allocations, or hot-path I/O regressions.
Concurrency And State	✅ Passed	PASS: stderr forwarding now joins on all exit paths, and a regression test covers the wait() failure path; no unsynchronised shared state was introduced.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/users-guide-example-coverage

---

_{Comment @coderabbitai help to get the list of available commands.}

[sourcery-ai]

Sorry @leynos, you have reached your weekly rate limit of 500000 diff characters.

Please try again later or upgrade to continue using Sourcery

[buzzybee-df12]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[leynos]

@coderabbitai resume

[coderabbitai]

✅ Action performed

Reviews resumed.

[leynos]

@coderabbitai Please suggest a fix for this issue and supply a prompt for an AI coding agent to enable it to apply the fix. Include the file and symbol names indicated in the issue at the head of your response. Ensure that this is validated against the current version of the codegraph.

If further refinement to address this finding would be deleterious, please supply a clear explanatory one to two paragraph markdown message I can paste into the CodeScene web ui's diagnostic suppression function so this diagnostic can be silenced.

tests/assert_cmd_tests.rs

Comment on lines +49 to +52

fn generate_streams_to_stdout_by_default() -> Result<()> {
    let temp = setup_simple_workspace("generate stdout test")?;
    let output = create_netsuke_command(temp.path())
        .arg("generate")

❌ New issue: Code Duplication
The module contains 2 functions with similar structure: generate_streams_to_stdout_by_default,generate_streams_to_stdout_with_directory

[leynos]

@coderabbitai Please suggest a fix for this issue and supply a prompt for an AI coding agent to enable it to apply the fix. Include the file and symbol names indicated in the issue at the head of your response. Ensure that this is validated against the current version of the codegraph.

If further refinement to address this finding would be deleterious, please supply a clear explanatory one to two paragraph markdown message I can paste into the CodeScene web ui's diagnostic suppression function so this diagnostic can be silenced.

tests/bdd/steps/accessibility_preferences.rs

Comment on file

fn simulated_env(world: &TestWorld) -> impl Fn(&str) -> Option<String> + '_ {
    move |key| match key {
        "NO_COLOR" => world.simulated_no_color.get(),
        "NETSUKE_NO_EMOJI" => world.simulated_no_emoji.get(),

❌ New issue: Code Duplication
The module contains 2 functions with similar structure: prefix_has_non_ascii,prefix_is_ascii