Document the template standard library (#443)

[leynos]

Summary

This branch adds brief Netsuke-focused YAML and Jinja syntax primers followed by a complete template standard-library reference, so readers can understand manifest structure before using every registered helper. Each helper has a concrete signature, defaults, purity classification, platform caveats, and copy-pasteable usage, while the documented examples remain executable contracts against the real Netsuke binary.

The guide distinguishes manifest-time control from build-time behaviour: foreach and when select entries before typed AST deserialization, IR generation, and Ninja execution, while direct build-time branching belongs in recipe commands or scripts unless runtime conditions are explicitly modelled. It also makes host-dependent return contracts explicit: realpath may return an absolute path for relative input, while shell and grep return a persisted temporary-file path in tempfile, stream, and streaming modes.

Closes #443

Review walkthrough

• Start with the dedicated standard-library guide for the YAML and Jinja primers, manifest-control timing, and the complete path, collection, file-test, time, host-context, and network reference.
• Then review the documentation-example loader and registry contracts for drift detection across the guide, including both syntax-primer manifests.
• Finish with the end-to-end documentation tests, which run the standard-library examples through the real binary in isolated workspaces with controlled fixtures and stub executables.
• The shorter entrypoints in the users' guide, README, and documentation index route readers to the complete reference.

Validation

• make check-fmt: passed
• make test: passed
• make typecheck: passed
• make lint: passed
• make markdownlint: passed
• make nixie: passed
• coderabbit review --agent: passed with 0 findings on the final branch

Notes

The registered fetch expression is checked for documentation and registry drift but deliberately not executed, so the documentation suite never makes a network request. All newly marked manifests compile through the real binary with deterministic local fixtures where required.

References

• Issue: #443
• Lody session: 53aea663-c306-435b-ae5d-2ae10811cc90

[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

Walkthrough

A dedicated standard-library guide now documents YAML/Jinja syntax and helper signatures. Documentation links and executable-example discovery were expanded, while registry and end-to-end tests cover filesystem, time, host, collection, and fetch-expression examples.

Changes

Standard-library guide

Layer / File(s)	Summary
Document YAML, Jinja, and helpers docs/stdlib-yaml-and-jinja-guide.md	Document manifest structure, template rendering, helper signatures, path and collection operations, filesystem and file-type tests, time handling, host inspection, command execution, globbing, fetching, and tested examples.

Documentation integration

Layer / File(s)	Summary
Link and register the guide README.md, docs/contents.md, docs/users-guide.md, docs/developers-guide.md, tests/documentation_examples/*	Link the dedicated guide from project documentation, include it in fenced-example discovery, register its example identifiers, and document the expanded test workflow.

Executable-example validation

Layer / File(s)	Summary
Validate documented helper behaviour tests/documentation_examples_e2e_tests.rs	Exercise documented path, collection, file-type, time, and controlled host-context examples with temporary fixtures, stub executables, environment variables, symlinks, and a FIFO.

Sequence Diagram(s)

sequenceDiagram
  participant Guide as stdlib guide
  participant Harness as documentation harness
  participant Netsuke
  participant Fixtures as test fixtures
  Guide->>Harness: provide tested-example fences
  Harness->>Netsuke: load registered manifests
  Fixtures->>Netsuke: provide controlled files and host context
  Netsuke->>Harness: generate documented outputs
  Harness->>Harness: assert outputs and fetch registration

Loading

Suggested labels: Issue

Suggested reviewers: codescene-access

Poem

Paths bloom in YAML light,
Jinja spins the helpers right,
Files and clocks join the tune,
Stubbed hosts hum beneath the moon,
Fetch waits safely, out of sight.

🚥 Pre-merge checks | ✅ 20

✅ Passed checks (20 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The changes satisfy #443 by adding the guide, registered tested examples, and documentation links, including non-executing network coverage.
Out of Scope Changes check	✅ Passed	The edits stay within documentation and test coverage needed for the stdlib guide.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Testing (Overall)	✅ Passed	New doc-example tests exercise real builds, filesystem fixtures, time, host context, and registry drift; the oracles would fail on plausible regressions.
User-Facing Documentation	✅ Passed	PASS: The users’ guide signposts the new stdlib guide, and that guide documents the YAML/Jinja syntax and helper surface for end users.
Developer Documentation	✅ Passed	PASS: Record the new stdlib guide in docs/developers-guide.md; no new internal API, architecture, ADR, roadmap, or execplan changes need follow-up.
Module-Level Documentation	✅ Passed	PASS: Each touched Rust module has a top-level //! doc comment, and the shared loader module explains how the tests relate to the published docs.
Testing (Unit And Behavioural)	✅ Passed	PASS: loader unit tests cover malformed markers, duplicates, and non-YAML manifests, while new E2E suites run real Netsuke with fixtures/stubs across stdlib workflows.
Testing (Property / Proof)	✅ Passed	The PR adds docs and fixed executable examples; it does not introduce a range-based invariant that would warrant property or proof recommendations.
Testing (Compile-Time / Ui)	✅ Passed	No Rust/TS compile-time surface changed; the new docs outputs are covered by focused semantic assertions and exact-output checks, so trybuild/snapshots aren’t required.
Unit Architecture	✅ Passed	The PR only changes docs and boundary tests; side-effects stay isolated via temp workspaces, stub executables, and explicit env injection, with no hidden mutable state added.
Domain Architecture	✅ Passed	PASS: The PR only changes documentation and documentation tests; no domain-layer code or boundary logic was added, so no new leakage appears.
Observability	✅ Passed	Only docs and test files changed; no production runtime behaviour, logging, metrics, tracing, or alerts were altered.
Security And Privacy	✅ Passed	Approve: no real secrets, credentials, or sensitive data were added; the token and URL examples are placeholders, and host-observing helpers are marked trusted-only.
Performance And Resource Use	✅ Passed	Only docs and bounded test-harness changes; added loops are fixed-size and the loader remains linear over small doc files.
Concurrency And State	✅ Passed	New tests use isolated tempdirs and env_clear; the only global env mutation goes through EnvLock via override_ninja_env, so state is owned and serialised.
Architectural Complexity And Maintainability	✅ Passed	Only docs and documented-example IDs changed; no new abstractions, layers, registries, or dependencies were introduced.
Rust Compiler Lint Integrity	✅ Passed	PASS: The Rust edits only add test cases; I found no #[allow]/#[expect] suppressions, fake-use anchors, or new clone() calls in the touched Rust files.
Title check	✅ Passed	The title matches the main change and includes the required issue reference (#443).
Description check	✅ Passed	The description clearly describes the new standard-library guide, examples, and related tests.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch issue-443-document-the-template-standard-library-in-a-dedicated-stdlib-guide-with-executable-examples

---

_{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

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: f3a548d60e

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/stdlib-yaml-and-jinja-guide.md`:
- Around line 54-57: Update the manifest control-key section around `foreach`
and `when` to state that they evaluate before typed AST deserialization, IR
generation, and Ninja execution. Clarify that direct build-time branching
applies to recipes unless runtime conditions are explicitly designed, while
preserving the existing syntax guidance.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 5f7749bf-5f24-4f18-b713-aaf5309f9996

📥 Commits

Reviewing files that changed from the base of the PR and between 57c4cc1 and f3a548d.

📒 Files selected for processing (8)

• README.md
• docs/contents.md
• docs/developers-guide.md
• docs/stdlib-yaml-and-jinja-guide.md
• docs/users-guide.md
• tests/documentation_examples/mod.rs
• tests/documentation_examples_e2e_tests.rs
• tests/documentation_examples_tests.rs

🔗 Linked repositories identified

CodeRabbit considers these linked repositories for cross-repo context during reviews:

• leynos/rstest-bdd (auto-detected)
• leynos/ortho-config (auto-detected)
• leynos/shared-actions (auto-detected)

[codescene-access]

No quality gates enabled for this code.

[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