Implement phony/always flags

[leynos]

Summary

• parse phony and always flags on targets
• document behaviour in the design doc
• mark roadmap item as done
• test phony and always parsing via unit and cucumber tests

Testing

• make fmt
• make lint
• make test
• make markdownlint
• make nixie (fails: too many arguments. Expected 0 arguments but got 1.)

---

https://chatgpt.com/codex/tasks/task_e_6880cd8c0e4c8322b10f0b698345b930

Summary by Sourcery

Enable phony and always flags on manifest targets, update documentation, and add corresponding tests

New Features:

• Support phony and always boolean flags on targets that default to false

Documentation:

• Document phony and always flags in the design doc and mark the roadmap item as done

Tests:

• Add unit tests, Cucumber steps, and feature scenario for parsing phony and always flags

[sourcery-ai]

Reviewer's Guide

Extends the manifest parser to support optional phony and always boolean flags on targets by adding new fields and comprehensive test coverage, and updates project documentation and roadmap to reflect the feature.

Class diagram for Target struct with phony and always flags

classDiagram
    class Target {
        +String name
        +bool phony
        +bool always
        ...
    }
    class Manifest {
        +Vec<Target> targets
        ...
    }
    Manifest --> Target : contains

Loading

File-Level Changes

Change	Details	Files
Add phony and always flags to manifest parsing with default behavior	Extend target structure to include phony and always booleans defaulting to false Add unit tests verifying flag parsing and default values Create Cucumber step definitions for checking flags in CLI scenarios Add a sample YAML manifest exercising both flags	tests/ast_tests.rs tests/steps/manifest_steps.rs tests/features/manifest.feature tests/data/phony.yml
Update documentation and roadmap for new flags	Document phony and always semantics and default behavior in design doc Mark the roadmap item for these flags as completed	docs/netsuke-design.md docs/roadmap.md

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[coderabbitai]

Summary by CodeRabbit

• Documentation

  • Clarified documentation to specify that targets support optional phony and always boolean flags, both defaulting to false.
  • Updated roadmap to mark support for phony and always flags as complete.

• Tests

  • Added tests to verify correct handling and default values of phony and always flags in manifests.
  • Introduced a new manifest example and feature scenario to validate phony and always flag behaviour.
  • Added new test steps for asserting phony and always flags in feature tests.

Walkthrough

Update the documentation to clarify the phony and always flags in the Netsuke manifest. Mark the roadmap item for these flags as complete. Add comprehensive tests, including a new YAML file, feature scenario, and step definitions to verify correct parsing and default behaviour of these flags.

Changes

Files/Paths	Change Summary
docs/netsuke-design.md, docs/roadmap.md	Update documentation to clarify and mark the phony/always flags as complete.
tests/ast_tests.rs	Add test for deserialisation of phony and always flags, including default handling.
tests/data/phony.yml	Add YAML manifest defining a phony target with both flags set to true.
tests/features/manifest.feature	Add feature scenario to validate parsing of phony and always flags from manifest.
tests/steps/manifest_steps.rs	Add Cucumber step definitions to assert phony and always flags on the first target.

Sequence Diagram(s)

sequenceDiagram
    participant Tester
    participant ManifestParser
    participant Target

    Tester->>ManifestParser: Parse manifest (with/without phony/always)
    ManifestParser->>Target: Set phony and always flags (true/false or default)
    Tester->>Target: Assert phony and always flags are as expected

Loading

Estimated code review effort

2 (~15 minutes)

Possibly related PRs

• Implement initial AST structures #23: Builds upon the AST implementation of phony and always flags in the Target struct.
• Document phony and always targets #4: Extends the core implementation of these flags in the data structures and build logic.

Suggested reviewers

• codescene-delta-analysis

Poem

Flags of phony, flags of true,
Always running, nothing new!
Docs are crisp, the roadmap’s done,
Tests ensure it all will run.
With YAML neat and steps so bright,
This build system’s future’s light!
🛠️✨

---

📜 Recent review details

Configuration used: CodeRabbit UI
Review profile: ASSERTIVE
Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 805233f and 36a5355.

📒 Files selected for processing (6)

• docs/netsuke-design.md (1 hunks)
• docs/roadmap.md (1 hunks)
• tests/ast_tests.rs (1 hunks)
• tests/data/phony.yml (1 hunks)
• tests/features/manifest.feature (1 hunks)
• tests/steps/manifest_steps.rs (1 hunks)

📓 Path-based instructions (4)

docs/**/*.md

📄 CodeRabbit Inference Engine (AGENTS.md)

docs/**/*.md: Use the markdown files within the docs/ directory as a knowledge base and source of truth for project requirements, dependency choices, and architectural decisions.
Proactively update the relevant file(s) in the docs/ directory to reflect the latest state when new decisions are made, requirements change, libraries are added/removed, or architectural patterns evolve.
Documentation must use en-GB-oxendict spelling and grammar (with the exception of 'license' which is to be left unchanged for community consistency).

Files:

• docs/roadmap.md
• docs/netsuke-design.md

**/*.md

📄 CodeRabbit Inference Engine (AGENTS.md)

**/*.md: Validate Markdown files using make markdownlint.
Run make fmt after any documentation changes to format all Markdown files and fix table markup.
Validate Mermaid diagrams in Markdown files by running make nixie.
Markdown paragraphs and bullet points must be wrapped at 80 columns.
Code blocks in Markdown must be wrapped at 120 columns.
Tables and headings in Markdown must not be wrapped.
Use dashes (-) for list bullets in Markdown.
Use GitHub-flavoured Markdown footnotes ([^1]) for references.

Files:

• docs/roadmap.md
• docs/netsuke-design.md

---

⚙️ CodeRabbit Configuration File

**/*.md: * Avoid 2nd person or 1st person pronouns ("I", "you", "we")

• Use en-GB-oxendict (-ize / -our) spelling and grammar
• Paragraphs and bullets must be wrapped to 80 columns, except where a long URL would prevent this (in which case, silence MD013 for that line)
• Code blocks should be wrapped to 120 columns.
• Headings must not be wrapped.
• Documents must start with a level 1 heading
• Headings must correctly increase or decrease by no more than one level at a time
• Use GitHub-flavoured Markdown style for footnotes and endnotes.
• Numbered footnotes must be numbered by order of appearance in the document.

Files:

• docs/roadmap.md
• docs/netsuke-design.md

**/*.rs

📄 CodeRabbit Inference Engine (AGENTS.md)

**/*.rs: Clippy warnings MUST be disallowed.
Fix any warnings emitted during tests in the code itself rather than silencing them.
Where a function is too long, extract meaningfully named helper functions adhering to separation of concerns and CQRS.
Where a function has too many parameters, group related parameters in meaningfully named structs.
Where a function is returning a large error consider using Arc to reduce the amount of data returned.
Document public APIs using Rustdoc comments (///) so documentation can be generated with cargo doc.
Every module must begin with a module level (//!) comment explaining the module's purpose and utility.
Prefer immutable data and avoid unnecessary mut bindings.
Handle errors with the Result type instead of panicking where feasible.
Avoid unsafe code unless absolutely necessary and document any usage clearly.
Place function attributes after doc comments.
Do not use return in single-line functions.
Use predicate functions for conditional criteria with more than two branches.
Lints must not be silenced except as a last resort.
Lint rule suppressions must be tightly scoped and include a clear reason.
Prefer expect over allow.
Prefer .expect() over .unwrap().

Files:

• tests/ast_tests.rs
• tests/steps/manifest_steps.rs

---

⚙️ CodeRabbit Configuration File

**/*.rs: * Seek to keep the cyclomatic complexity of functions no more than 12.

• Adhere to single responsibility and CQRS

• Place function attributes after doc comments.

• Do not use return in single-line functions.

• Move conditionals with >2 branches into a predicate function.

• Avoid unsafe unless absolutely necessary.

• Every module must begin with a //! doc comment that explains the module's purpose and utility.

• Comments and docs must follow en-GB-oxendict (-ize / -our) spelling and grammar

• Lints must not be silenced except as a last resort.

  • #[allow] is forbidden.
  • Only narrowly scoped #[expect(lint, reason = "...")] is allowed.
  • No lint groups, no blanket or file-wide suppression.
  • Include FIXME: with link if a fix is expected.

• Use rstest fixtures for shared setup and to avoid repetition between tests.

• Replace duplicated tests with #[rstest(...)] parameterised cases.

• Prefer mockall for mocks/stubs.

• Prefer .expect() over .unwrap()

• Ensure that any API or behavioural changes are reflected in the documentation in docs/

• Ensure that any completed roadmap steps are recorded in the appropriate roadmap in docs/

• Files must not exceed 400 lines in length

  • Large modules must be decomposed
  • Long match statements or dispatch tables should be decomposed by domain and collocated with targets
  • Large blocks of inline data (e.g., test fixtures, constants or templates) must be moved to external files and inlined at compile-time or loaded at run-time.

Files:

• tests/ast_tests.rs
• tests/steps/manifest_steps.rs

**/*{_test,tests}.rs

📄 CodeRabbit Inference Engine (AGENTS.md)

**/*{_test,tests}.rs: Write unit and behavioural tests for new functionality. Run both before and after making any change.
Use rstest fixtures for shared setup.
Replace duplicated tests with #[rstest(...)] parameterised cases.
Prefer mockall for mocks/stubs.

Files:

• tests/ast_tests.rs

🧠 Learnings (1)

tests/ast_tests.rs (1)

Learnt from: CR
PR: leynos/netsuke#0
File: docs/roadmap.md:0-0
Timestamp: 2025-07-20T02:49:27.706Z
Learning: Applies to docs/src/ast.rs : Support phony and always boolean flags on targets.

🧰 Additional context used

📓 Path-based instructions (4)

docs/**/*.md

📄 CodeRabbit Inference Engine (AGENTS.md)

docs/**/*.md: Use the markdown files within the docs/ directory as a knowledge base and source of truth for project requirements, dependency choices, and architectural decisions.
Proactively update the relevant file(s) in the docs/ directory to reflect the latest state when new decisions are made, requirements change, libraries are added/removed, or architectural patterns evolve.
Documentation must use en-GB-oxendict spelling and grammar (with the exception of 'license' which is to be left unchanged for community consistency).

Files:

• docs/roadmap.md
• docs/netsuke-design.md

**/*.md

📄 CodeRabbit Inference Engine (AGENTS.md)

**/*.md: Validate Markdown files using make markdownlint.
Run make fmt after any documentation changes to format all Markdown files and fix table markup.
Validate Mermaid diagrams in Markdown files by running make nixie.
Markdown paragraphs and bullet points must be wrapped at 80 columns.
Code blocks in Markdown must be wrapped at 120 columns.
Tables and headings in Markdown must not be wrapped.
Use dashes (-) for list bullets in Markdown.
Use GitHub-flavoured Markdown footnotes ([^1]) for references.

Files:

• docs/roadmap.md
• docs/netsuke-design.md

---

⚙️ CodeRabbit Configuration File

**/*.md: * Avoid 2nd person or 1st person pronouns ("I", "you", "we")

• Use en-GB-oxendict (-ize / -our) spelling and grammar
• Paragraphs and bullets must be wrapped to 80 columns, except where a long URL would prevent this (in which case, silence MD013 for that line)
• Code blocks should be wrapped to 120 columns.
• Headings must not be wrapped.
• Documents must start with a level 1 heading
• Headings must correctly increase or decrease by no more than one level at a time
• Use GitHub-flavoured Markdown style for footnotes and endnotes.
• Numbered footnotes must be numbered by order of appearance in the document.

Files:

• docs/roadmap.md
• docs/netsuke-design.md

**/*.rs

📄 CodeRabbit Inference Engine (AGENTS.md)

**/*.rs: Clippy warnings MUST be disallowed.
Fix any warnings emitted during tests in the code itself rather than silencing them.
Where a function is too long, extract meaningfully named helper functions adhering to separation of concerns and CQRS.
Where a function has too many parameters, group related parameters in meaningfully named structs.
Where a function is returning a large error consider using Arc to reduce the amount of data returned.
Document public APIs using Rustdoc comments (///) so documentation can be generated with cargo doc.
Every module must begin with a module level (//!) comment explaining the module's purpose and utility.
Prefer immutable data and avoid unnecessary mut bindings.
Handle errors with the Result type instead of panicking where feasible.
Avoid unsafe code unless absolutely necessary and document any usage clearly.
Place function attributes after doc comments.
Do not use return in single-line functions.
Use predicate functions for conditional criteria with more than two branches.
Lints must not be silenced except as a last resort.
Lint rule suppressions must be tightly scoped and include a clear reason.
Prefer expect over allow.
Prefer .expect() over .unwrap().

Files:

• tests/ast_tests.rs
• tests/steps/manifest_steps.rs

---

⚙️ CodeRabbit Configuration File

**/*.rs: * Seek to keep the cyclomatic complexity of functions no more than 12.

• Adhere to single responsibility and CQRS

• Place function attributes after doc comments.

• Do not use return in single-line functions.

• Move conditionals with >2 branches into a predicate function.

• Avoid unsafe unless absolutely necessary.

• Every module must begin with a //! doc comment that explains the module's purpose and utility.

• Comments and docs must follow en-GB-oxendict (-ize / -our) spelling and grammar

• Lints must not be silenced except as a last resort.

  • #[allow] is forbidden.
  • Only narrowly scoped #[expect(lint, reason = "...")] is allowed.
  • No lint groups, no blanket or file-wide suppression.
  • Include FIXME: with link if a fix is expected.

• Use rstest fixtures for shared setup and to avoid repetition between tests.

• Replace duplicated tests with #[rstest(...)] parameterised cases.

• Prefer mockall for mocks/stubs.

• Prefer .expect() over .unwrap()

• Ensure that any API or behavioural changes are reflected in the documentation in docs/

• Ensure that any completed roadmap steps are recorded in the appropriate roadmap in docs/

• Files must not exceed 400 lines in length

  • Large modules must be decomposed
  • Long match statements or dispatch tables should be decomposed by domain and collocated with targets
  • Large blocks of inline data (e.g., test fixtures, constants or templates) must be moved to external files and inlined at compile-time or loaded at run-time.

Files:

• tests/ast_tests.rs
• tests/steps/manifest_steps.rs

**/*{_test,tests}.rs

📄 CodeRabbit Inference Engine (AGENTS.md)

**/*{_test,tests}.rs: Write unit and behavioural tests for new functionality. Run both before and after making any change.
Use rstest fixtures for shared setup.
Replace duplicated tests with #[rstest(...)] parameterised cases.
Prefer mockall for mocks/stubs.

Files:

• tests/ast_tests.rs

🧠 Learnings (1)

tests/ast_tests.rs (1)

Learnt from: CR
PR: leynos/netsuke#0
File: docs/roadmap.md:0-0
Timestamp: 2025-07-20T02:49:27.706Z
Learning: Applies to docs/src/ast.rs : Support phony and always boolean flags on targets.

🔇 Additional comments (8)

docs/roadmap.md (1)

30-30: LGTM! Roadmap correctly updated.

The checklist item has been properly marked as completed, reflecting the implementation of phony and always flags.

docs/netsuke-design.md (1)

594-596: Clear documentation of the new boolean flags.

The explanation properly describes the purpose and default behaviour of the phony and always flags, maintaining consistency with the established documentation style.

tests/data/phony.yml (1)

1-9: Well-structured test data for the new flags.

The manifest correctly demonstrates usage of phony and always flags with a realistic clean target example.

tests/features/manifest.feature (1)

8-11: Appropriate feature test coverage for the new flags.

The scenario correctly tests parsing of phony and always flags using the dedicated test data file and follows established Cucumber patterns.

tests/ast_tests.rs (1)

217-246: Comprehensive unit test coverage for the boolean flags.

The test properly verifies both explicit flag setting and default behaviour, following established testing patterns in the file.

tests/steps/manifest_steps.rs (3)

58-63: Implementation correctly follows established patterns.

The function properly uses .expect() over .unwrap() and follows the same error handling approach as existing functions in the file.

---

65-70: Implementation correctly follows established patterns.

The function properly uses .expect() over .unwrap() and follows the same error handling approach as existing functions in the file.

---

58-70: Add function documentation and consider consolidating duplicate logic.

Both functions lack Rustdoc comments (///) as required by the coding guidelines for public APIs. Additionally, the functions follow nearly identical patterns - consider parameterising them to reduce duplication.

Add documentation for both functions:

+/// Asserts that the first target in the manifest has the phony flag set to true.
 #[then("the first target is phony")]
 fn first_target_phony(world: &mut CliWorld) {
     let manifest = world.manifest.as_ref().expect("manifest");
     let first = manifest.targets.first().expect("targets");
     assert!(first.phony);
 }

+/// Asserts that the first target in the manifest has the always flag set to true.
 #[then("the first target is always rebuilt")]
 fn first_target_always(world: &mut CliWorld) {
     let manifest = world.manifest.as_ref().expect("manifest");
     let first = manifest.targets.first().expect("targets");
     assert!(first.always);
 }

Alternatively, consider consolidating these into a single parameterised function to eliminate duplication, though this may require restructuring the Cucumber step definitions.

Likely an incorrect or invalid review comment.

✨ Finishing Touches

• 📝 Generate Docstrings

🧪 Generate unit tests

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch codex/implement-support-for-phony-and-always-flags

---

🪧 Tips

Chat

There are 3 ways to chat with CodeRabbit:

• Review comments: Directly reply to a review comment made by CodeRabbit. Example:
  • I pushed a fix in commit <commit_id>, please review it.
  • Explain this complex logic.
  • Open a follow-up GitHub issue for this discussion.
• Files and specific lines of code (under the "Files changed" tab): Tag @coderabbitai in a new review comment at the desired location with your query. Examples:
  • @coderabbitai explain this code block.
  • @coderabbitai modularize this function.
• PR comments: Tag @coderabbitai in a new PR comment to ask questions about the PR branch. For the best results, please provide a very specific query, as very limited context is provided in this mode. Examples:
  • @coderabbitai gather interesting stats about this repository and render them as a table. Additionally, render a pie chart showing the language distribution in the codebase.
  • @coderabbitai read src/utils.ts and explain its main purpose.
  • @coderabbitai read the files in the src/scheduler package and generate a class diagram using mermaid and a README in the markdown format.
  • @coderabbitai help me debug CodeRabbit configuration file.

Support

Need help? Create a ticket on our support page for assistance with any issues or questions.

Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments.

CodeRabbit Commands (Invoked using PR comments)

• @coderabbitai pause to pause the reviews on a PR.
• @coderabbitai resume to resume the paused reviews.
• @coderabbitai review to trigger an incremental review. This is useful when automatic reviews are disabled for the repository.
• @coderabbitai full review to do a full review from scratch and review all the files again.
• @coderabbitai summary to regenerate the summary of the PR.
• @coderabbitai generate docstrings to generate docstrings for this PR.
• @coderabbitai generate sequence diagram to generate a sequence diagram of the changes in this PR.
• @coderabbitai generate unit tests to generate unit tests for this PR.
• @coderabbitai resolve resolve all the CodeRabbit review comments.
• @coderabbitai configuration to show the current CodeRabbit configuration for the repository.
• @coderabbitai help to get help.

Other keywords and placeholders

• Add @coderabbitai ignore anywhere in the PR description to prevent this PR from being reviewed.
• Add @coderabbitai summary to generate the high-level summary at a specific location in the PR description.
• Add @coderabbitai anywhere in the PR title to generate the title automatically.

CodeRabbit Configuration File (.coderabbit.yaml)

• You can programmatically configure CodeRabbit by adding a .coderabbit.yaml file to the root of your repository.
• Please see the configuration documentation for more information.
• If your editor has YAML language server enabled, you can add the path at the top of this file to enable auto-completion and validation: # yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json

Documentation and Community

• Visit our Documentation for detailed information on how to use CodeRabbit.
• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[sourcery-ai]

Hey @leynos - I've reviewed your changes and they look great!

Prompt for AI Agents

Please address the comments from this code review:
## Individual Comments

### Comment 1
<location> `docs/netsuke-design.md:594` </location>
<code_context>
 follows semantic versioning rules. Global and target variable maps now share
 the `HashMap<String, String>` type for consistency. This keeps YAML manifests
 concise while ensuring forward compatibility.
+Targets also accept optional `phony` and `always` booleans. They default to
+`false`, making it explicit when a step should run regardless of file
+timestamps.
</code_context>

<issue_to_address>
This paragraph exceeds the 80 column wrapping limit for paragraphs and bullets.

Please wrap this paragraph so that no line exceeds 80 columns, as per the documentation guidelines.
</issue_to_address>

### Comment 2
<location> `docs/netsuke-design.md:596` </location>
<code_context>
 concise while ensuring forward compatibility.
+Targets also accept optional `phony` and `always` booleans. They default to
+`false`, making it explicit when a step should run regardless of file
+timestamps.

 ### 3.5 Testing
</code_context>

<issue_to_address>
This line is part of a paragraph that is not wrapped to 80 columns.

Please wrap the entire paragraph to 80 columns as required by the style guide.
</issue_to_address>

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

[sourcery-ai]

issue (review_instructions): This paragraph exceeds the 80 column wrapping limit for paragraphs and bullets.

Please wrap this paragraph so that no line exceeds 80 columns, as per the documentation guidelines.

Review instructions:

Path patterns: **/*.md

Instructions:
Paragraphs and bullets must be wrapped to 80 columns

[sourcery-ai]

issue (review_instructions): This line is part of a paragraph that is not wrapped to 80 columns.

Please wrap the entire paragraph to 80 columns as required by the style guide.

Review instructions:

Path patterns: **/*.md

Instructions:
Paragraphs and bullets must be wrapped to 80 columns