From 95e71a5fa26e2b4eaa5621b755b62ffb64a2f4b1 Mon Sep 17 00:00:00 2001 From: Leynos Date: Sat, 19 Jul 2025 12:07:58 +0100 Subject: [PATCH 1/4] Mark AST deserialisation complete --- docs/netsuke-design.md | 6 ++++++ docs/roadmap.md | 4 ++-- 2 files changed, 8 insertions(+), 2 deletions(-) diff --git a/docs/netsuke-design.md b/docs/netsuke-design.md index 8bf58073..a3705be1 100644 --- a/docs/netsuke-design.md +++ b/docs/netsuke-design.md @@ -549,6 +549,12 @@ follows semantic versioning rules. Global and target variable maps now share the `HashMap` type for consistency. This keeps YAML manifests concise while ensuring forward compatibility. +Unit tests in `tests/ast_tests.rs` and behavioural scenarios in +`tests/features/manifest.feature` validate the deserialisation logic. They +verify that unknown fields result in errors and that minimal manifests parse +correctly. This testing strategy guards against regression as the schema +evolves. + ## Section 4: Dynamic Builds with the Jinja Templating Engine To provide the dynamic capabilities and logical expressiveness that make a diff --git a/docs/roadmap.md b/docs/roadmap.md index 2cc9aabd..bdb1c2c8 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -20,9 +20,9 @@ compilation pipeline from parsing to execution. (NetsukeManifest, Rule, Target, StringOrList, Recipe) in `src/ast.rs`. *(done)* - - [ ] Annotate AST structs with #[derive(Deserialize)] and + - [x] Annotate AST structs with #[derive(Deserialize)] and #[serde(deny_unknown_fields)] - to enable serde_yml parsing. + to enable serde_yml parsing. *(done)* - [ ] Implement parsing for the netsuke_version field and validate it using the semver crate. From 8ee368a546b9a10d4b556279859f041e158bbdc1 Mon Sep 17 00:00:00 2001 From: Leynos Date: Sat, 19 Jul 2025 13:23:00 +0100 Subject: [PATCH 2/4] Document AST deserialisation --- docs/netsuke-design.md | 53 ++++++++++++++++++++++++++++++++++++++---- 1 file changed, 49 insertions(+), 4 deletions(-) diff --git a/docs/netsuke-design.md b/docs/netsuke-design.md index a3705be1..941d0398 100644 --- a/docs/netsuke-design.md +++ b/docs/netsuke-design.md @@ -493,6 +493,49 @@ pub enum StringOrList { flexibility for users to specify single sources, dependencies, and rule names as a simple string and multiple as a list, enhancing user-friendliness.* +#### Example Manifest and AST + +The following minimal Netsukefile shows how the derived structures behave when +unknown fields are denied. + +YAML + +```yaml +netsuke_version: "1.0.0" +targets: + - name: hello + recipe: + kind: command + command: echo hi +``` + +Rust + +```rust +use std::collections::HashMap; +use netsuke::ast::*; + +let ast = NetsukeManifest { + netsuke_version: Version::parse("1.0.0").unwrap(), + vars: HashMap::new(), + rules: vec![], + steps: vec![], + targets: vec![Target { + name: StringOrList::String("hello".into()), + recipe: Recipe::Command { + command: "echo hi".into(), + }, + sources: StringOrList::Empty, + deps: StringOrList::Empty, + order_only_deps: StringOrList::Empty, + vars: HashMap::new(), + phony: false, + always: false, + }], + defaults: vec![], +}; +``` + ### 3.3 The Two-Pass Parsing Requirement The integration of a templating engine like Jinja fundamentally shapes the @@ -549,11 +592,13 @@ follows semantic versioning rules. Global and target variable maps now share the `HashMap` type for consistency. This keeps YAML manifests concise while ensuring forward compatibility. +### 3.5 Testing + Unit tests in `tests/ast_tests.rs` and behavioural scenarios in -`tests/features/manifest.feature` validate the deserialisation logic. They -verify that unknown fields result in errors and that minimal manifests parse -correctly. This testing strategy guards against regression as the schema -evolves. +`tests/features/manifest.feature` exercise the deserialisation logic. They +assert that manifests fail to parse when unknown fields are present and that a +minimal manifest round-trips correctly. This suite guards against regressions +as the schema evolves. ## Section 4: Dynamic Builds with the Jinja Templating Engine From 547a5a0da610b905d5b4df44e1fa5bc68e7357ad Mon Sep 17 00:00:00 2001 From: Leynos Date: Sat, 19 Jul 2025 13:38:07 +0100 Subject: [PATCH 3/4] Format README and step definitions --- tests/steps/manifest_steps.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tests/steps/manifest_steps.rs b/tests/steps/manifest_steps.rs index ce78e5a1..eaf692e7 100644 --- a/tests/steps/manifest_steps.rs +++ b/tests/steps/manifest_steps.rs @@ -7,7 +7,7 @@ use std::fs; #[expect( clippy::needless_pass_by_value, - reason = "Cucumber requires owned String arguments", + reason = "Cucumber requires owned String arguments" )] #[when(expr = "the manifest file {string} is parsed")] fn parse_manifest(world: &mut CliWorld, path: String) { From ba4c5d43a9e73ddf4349cf3ace19a2b5b2b31843 Mon Sep 17 00:00:00 2001 From: Leynos Date: Sun, 20 Jul 2025 14:53:28 +0100 Subject: [PATCH 4/4] Fix spelling and citation punctuation --- docs/behavioural-testing-in-rust-with-cucumber.md | 6 +++--- docs/netsuke-design.md | 4 ++-- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/behavioural-testing-in-rust-with-cucumber.md b/docs/behavioural-testing-in-rust-with-cucumber.md index 0c08c636..27a5b888 100644 --- a/docs/behavioural-testing-in-rust-with-cucumber.md +++ b/docs/behavioural-testing-in-rust-with-cucumber.md @@ -1135,7 +1135,7 @@ aligned with what is needed. Stack Overflow, accessed on 14 July 2025, -[^23]: Data tables - Cucumber Rust Book, accessed on 14 July 2025, +[^23]: Data tables – Cucumber Rust Book — accessed on 14 July 2025 — [^24]: Cucumber Data Tables — Tutorialspoint, accessed on 14 July 2025, @@ -1164,8 +1164,8 @@ aligned with what is needed. accessed on July 14, 2025, -[^31]: Cucumber in cucumber - Rust - [Docs.rs](http://Docs.rs), accessed on - 14 July 2025, +[^31]: Cucumber in cucumber – Rust – [Docs.rs](http://Docs.rs) — accessed on 14 + July 2025 — [^32]: CLI (command-line interface) - Cucumber Rust Book, accessed on diff --git a/docs/netsuke-design.md b/docs/netsuke-design.md index 941d0398..863d1628 100644 --- a/docs/netsuke-design.md +++ b/docs/netsuke-design.md @@ -595,8 +595,8 @@ concise while ensuring forward compatibility. ### 3.5 Testing Unit tests in `tests/ast_tests.rs` and behavioural scenarios in -`tests/features/manifest.feature` exercise the deserialisation logic. They -assert that manifests fail to parse when unknown fields are present and that a +`tests/features/manifest.feature` exercise the deserialization logic. They +assert that manifests fail to parse when unknown fields are present, and that a minimal manifest round-trips correctly. This suite guards against regressions as the schema evolves.