Implement SysmlMetadataNode and Filtering subsystem for Phase 1

.reviewmark.yaml

@@ -440,6 +440,25 @@ reviews:
       - "src/DemaConsulting.SysML2Tools.Language/Semantic/AstDeserializer.cs"
       - "test/DemaConsulting.SysML2Tools.Tests/Semantic/AstSerializerTests.cs"
 
+  - id: SysML2Tools-Language-Semantic-Model-SysmlMetadataNode
+    title: Review that DemaConsulting.SysML2Tools Language Semantic Model SysmlMetadataNode Implementation is Correct
+    context:
+      - docs/design/sysml2-tools-language.md
+      - docs/reqstream/sysml2-tools-language.yaml
+      - docs/design/sysml2-tools-language/semantic.md
+      - docs/reqstream/sysml2-tools-language/semantic.yaml
+      - docs/design/sysml2-tools-language/semantic/model.md
+      - docs/reqstream/sysml2-tools-language/semantic/model.yaml
+    paths:
+      - "docs/reqstream/sysml2-tools-language/semantic/model/sysml-metadata-node.yaml"
+      - "docs/design/sysml2-tools-language/semantic/model.md"
+      - "docs/verification/sysml2-tools-language/semantic/model.md"
+      - "src/DemaConsulting.SysML2Tools.Language/Semantic/Model/SysmlNode.cs"
+      - "src/DemaConsulting.SysML2Tools.Language/Semantic/Model/AstBuilder.cs"
+      - "src/DemaConsulting.SysML2Tools.Language/Semantic/Model/ReferenceResolver.cs"
+      - "src/DemaConsulting.SysML2Tools.Language/Semantic/Model/SysmlEdge.cs"
+      - "test/DemaConsulting.SysML2Tools.Tests/Semantic/AstBuilderMetadataTests.cs"
+
   - id: SysML2Tools-Core-Layout-Design
     title: Review that DemaConsulting.SysML2Tools Layout Design is Consistent and Complete
     context:
@@ -514,6 +533,54 @@ reviews:
       - "src/DemaConsulting.SysML2Tools.Core/Io/NamespaceDoc.cs"
       - "test/DemaConsulting.SysML2Tools.Tests/Io/GlobFileCollectorTests.cs"
 
+  - id: SysML2Tools-Core-Filtering-Design
+    title: Review that DemaConsulting.SysML2Tools Filtering Design is Consistent and Complete
+    context:
+      - docs/reqstream/sysml2-tools-core.yaml
+      - docs/reqstream/sysml2-tools-core/filtering.yaml
+    paths:
+      - "docs/design/introduction.md"
+      - "docs/design/sysml2-tools-core.md"
+      - "docs/design/sysml2-tools-core/filtering.md"
+      - "docs/design/sysml2-tools-core/filtering/**/*.md"
+
+  - id: SysML2Tools-Core-Filtering-Verification
+    title: Review that DemaConsulting.SysML2Tools Filtering Verification is Consistent and Complete
+    context:
+      - docs/reqstream/sysml2-tools-core.yaml
+      - docs/reqstream/sysml2-tools-core/filtering.yaml
+    paths:
+      - "docs/verification/introduction.md"
+      - "docs/verification/sysml2-tools-core.md"
+      - "docs/verification/sysml2-tools-core/filtering.md"
+      - "docs/verification/sysml2-tools-core/filtering/**/*.md"
+
+  - id: SysML2Tools-Core-Filtering-AllRequirements
+    title: Review that All DemaConsulting.SysML2Tools Filtering Requirements are Complete
+    context:
+      - docs/design/sysml2-tools-core.md
+      - docs/reqstream/sysml2-tools-core.yaml
+    paths:
+      - "docs/reqstream/sysml2-tools-core/filtering.yaml"
+      - "docs/reqstream/sysml2-tools-core/filtering/**/*.yaml"
+
+  - id: SysML2Tools-Core-Filtering-FilterExpressionEvaluator
+    title: Review that DemaConsulting.SysML2Tools Filtering FilterExpressionEvaluator Implementation is Correct
+    context:
+      - docs/design/sysml2-tools-core.md
+      - docs/reqstream/sysml2-tools-core.yaml
+      - docs/design/sysml2-tools-core/filtering.md
+      - docs/reqstream/sysml2-tools-core/filtering.yaml
+    paths:
+      - "docs/reqstream/sysml2-tools-core/filtering/filter-expression-evaluator.yaml"
+      - "docs/design/sysml2-tools-core/filtering/filter-expression-evaluator.md"
+      - "docs/verification/sysml2-tools-core/filtering/filter-expression-evaluator.md"
+      - "src/DemaConsulting.SysML2Tools.Core/Filtering/FilterExpression.cs"
+      - "src/DemaConsulting.SysML2Tools.Core/Filtering/FilterExpressionParser.cs"
+      - "src/DemaConsulting.SysML2Tools.Core/Filtering/FilterExpressionEvaluator.cs"
+      - "test/DemaConsulting.SysML2Tools.Tests/Filtering/FilterExpressionParserTests.cs"
+      - "test/DemaConsulting.SysML2Tools.Tests/Filtering/FilterExpressionEvaluatorTests.cs"
+
   # === Layout Internal subsystem and view-strategy units ===
   - id: SysML2Tools-Core-Layout-Internal
     title: Review that DemaConsulting.SysML2Tools Layout Internal Subsystem is Consistent and Complete

ROADMAP.md

@@ -71,29 +71,49 @@ the inner `cpu` box, not the `board` container's boundary.
 
 ### View `filter [<expr>];` expression evaluation
 
-`GeneralViewLayoutStrategy` now scopes a rendered diagram to a view's `expose <...>;` subject
-subtree, but a view's `filter [<expr>];` body statement is only parsed into
-`SysmlViewNode.FilterExpressionText` (raw source text) — it is never evaluated, and a
-layout warning ("parsed but not yet evaluated") is emitted in its place. SysML v2 view filtering
-is part of the standard's view/viewpoint mechanism for selectively including/excluding elements
-from a rendered diagram by predicate, beyond simple subject-subtree containment scoping (for
-example, "only elements satisfying a given requirement" or "only elements with a given
-stereotype"); without evaluation, a modeler's `filter` statement is silently ineffective beyond
-the warning.
-
-- Design and implement an expression evaluator for the bracketed filter expression grammar
-  (boolean/membership predicates over the resolved scope's elements), reusing/aligning with
-  existing expression-parsing infrastructure where practical.
-- Apply the evaluated predicate as an additional filter over the resolved (expose) scope in
-  `GeneralViewLayoutStrategy`, removing the "not yet evaluated" warning once a filter
-  expression is present and successfully evaluated.
-- Surface a diagnostic for filter expressions that fail to parse or evaluate, mirroring the
-  unresolved-reference diagnostic pattern already used for `expose`.
-
-**Scope:** `AstBuilder`/`SysmlViewNode` (expression AST capture, if warranted, beyond raw text);
-new expression-evaluation component; `GeneralViewLayoutStrategy` filter application.
-**Visual gate:** a view with a `filter [<predicate>];` statement renders only the elements
-satisfying the predicate, with no "not yet evaluated" warning.
+**Phase 1 — done.** `GeneralViewLayoutStrategy` scopes a rendered diagram to a view's
+`expose <...>;` subject subtree, and now also evaluates a standalone view `filter <expr>;` body
+statement (via the new `DemaConsulting.SysML2Tools.Core.Filtering` subsystem —
+`FilterExpression`/`FilterExpressionParser`/`FilterExpressionEvaluator`) for a defined Phase 1
+construct subset, narrowing the rendered scope by the resulting predicate:
+
+- Metadata classification-test atoms (`@Type`, `@Pkg::Type`), matched against a new
+  `SysmlMetadataNode` semantic-model type capturing each definition's applied metadata
+  annotations (`{@Type{attr = value;}}`/`@Type;`/`@Type{}`), resolved via `ReferenceResolver`.
+- Boolean connectives: `and`, `or`, `not`, `xor`, `&`, `|`, and parenthesization.
+- `(as Type).attribute` reads, bare or compared with `==`/`!=` against a scalar (boolean, number,
+  or string) literal.
+
+Any construct outside this subset — `istype`/`hastype`/`all`, arithmetic, conditional
+expressions, general feature-chain navigation, or a syntax error — produces an explicit
+"unsupported filter construct" (or syntax-error) diagnostic and falls back to rendering the
+resolved (`expose`) scope unfiltered, exactly as Phase 0 did for every filter expression.
+
+**Phase 2 — deferred:**
+
+- The bracketed `expose <path>::**[<expr>]` filter form: Phase 1 only captures its raw
+  expression text (mirroring the pre-Phase-1 standalone-`filter` behavior) and emits an
+  "unevaluated" warning; it is never evaluated. Phase 2 should extend the Phase 1 evaluator (or a
+  successor) to cover this form too.
+- The Phase 1-excluded construct list above: `istype`/`hastype`/`all`, arithmetic operators,
+  conditional (`if`/`else`) expressions, and general feature-chain navigation (attribute/feature
+  reads not anchored by an `(as Type)` cast). Each currently produces a clear, non-crashing
+  "unsupported filter construct" diagnostic rather than silently doing nothing — full evaluation
+  of these constructs is future work.
+- Metadata annotations on **usages** (as opposed to definitions) are captured in the semantic
+  model (`SysmlMetadataNode` is attached wherever `metadataFeature` appears), but
+  `GeneralViewLayoutStrategy`'s Phase 1 filter narrowing only evaluates classification
+  tests/attribute reads against rendered `SysmlDefinitionNode` candidates (matching
+  `CollectDefinitions`'s existing scope) — extending filter evaluation to usage-level candidates
+  is future work if a future view kind renders usages directly.
+
+**Scope:** `SysmlNode.cs`/`AstBuilder.cs`/`ReferenceResolver.cs`/`SysmlEdge.cs` (metadata
+capture); `DemaConsulting.SysML2Tools.Core.Filtering` (new subsystem); `GeneralViewLayoutStrategy`/
+`LayoutWarnings` (filter application, dual unevaluated-bracket-filter warning).
+**Visual gate:** a view with a standalone `filter @Type;`-style Phase 1 statement renders only
+the elements satisfying the predicate, with no "not yet evaluated" warning for that statement;
+an unsupported construct or a bracket-form filter still falls back to the resolved scope with an
+explicit diagnostic.
 
 ---
 

docs/design/introduction.md

@@ -48,15 +48,19 @@ system, subsystem, and unit levels:
     - **AstSerializer** (Unit) — serializes SymbolTable + diagnostics to UTF-8 JSON bytes
     - **AstDeserializer** (Unit) — deserializes bytes back to SymbolTable + diagnostics
     - **Model** (Subsystem) — semantic model: public model types plus internal build/resolve implementation
-      - **SysmlNode** (Unit) — public AST node hierarchy: nine types with JSON polymorphism
-      - **AstBuilder** (Unit) — builds AST from ANTLR4 CST with qualified names and supertype lists
+      - **SysmlNode** (Unit) — public AST node hierarchy: named-element and view/import node types
+      - **SysmlMetadataNode** (Unit) — applied metadata annotation node with raw type reference and
+        captured scalar attribute values
+      - **AstBuilder** (Unit) — builds AST from ANTLR4 CST with qualified names, metadata
+        annotations, and raw view filter text
       - **SymbolTable** (Unit) — registry mapping qualified names to declaration nodes
-      - **ReferenceResolver** (Unit) — resolves supertype, typing, redefinition, import, satisfy,
-        verify, allocate, and (in a second pass) dotted feature-chain connect/transition references;
-        detects circular imports; returns a `SemanticIndex` of resolved edges
+      - **ReferenceResolver** (Unit) — resolves supertype, typing, metadata-type,
+        redefinition, import, satisfy, verify, allocate, expose, and (in a second pass) dotted
+        feature-chain connect/transition references; detects circular imports; returns a
+        `SemanticIndex` of resolved edges
       - **SupertypeWalker** (Unit) — walks specialization chains; detects cyclic specialization
-      - **SysmlEdge** (Unit) — public resolved-reference record (Supertype/Typing/Import/
-        Satisfy/Verify/Allocate/Connect/Transition)
+      - **SysmlEdge** (Unit) — public resolved-reference record (Supertype/Typing/MetadataType/
+        Import/Expose/Redefinition/Satisfy/Verify/Allocate/Connect/Transition)
       - **SemanticIndex** (Unit) — public reverse-lookup index over resolved `SysmlEdge` instances
       - **SysmlAnnotation** (Unit) — public captured-comment/documentation record
         (Comment/Documentation)
@@ -70,8 +74,12 @@ system, subsystem, and unit levels:
   stdlib.json.gz (invoked by build.ps1, not part of the MSBuild graph; excluded from the
   software-items requirements/design/verification tree — see _Scope_)
   - **Program** (Unit) — entry point: parses stdlib, runs resolution, serializes and compresses to stdlib.json.gz
-- **DemaConsulting.SysML2Tools.Core** (System) — core library: layout strategies, rendering
-  orchestration, and the SysML-coupled rendering pipeline
+- **DemaConsulting.SysML2Tools.Core** (System) — core library: layout strategies,
+  filter-expression evaluation, rendering orchestration, and the SysML-coupled rendering pipeline
+  - **Filtering** (Subsystem) — parses and evaluates the Phase 1 subset of standalone view
+    `filter [<expr>];` expressions over metadata annotations
+    - **FilterExpressionEvaluator** (Unit) — filter-expression AST, parser adaptation, and
+      evaluator for metadata classification tests, boolean connectives, and metadata-attribute reads
   - **Layout** (Subsystem) — maps the SysML semantic model onto the off-the-shelf `LayoutTree`
     intermediate representation and delegates geometric placement and routing to the off-the-shelf
     `DemaConsulting.Rendering.Layout` layered algorithm
@@ -157,12 +165,13 @@ reviewers an explicit navigation aid from design to code:
       - **Antlr/** — ANTLR4-generated C# (committed; not hand-written)
       - **Internal/** — internal implementation (SysmlDiagnosticListener)
     - **Semantic/** — semantic model subsystem
-      - **Model/** — public semantic model types (SysmlNode, AstBuilder, SymbolTable,
-        ReferenceResolver, SupertypeWalker, SysmlEdge, SemanticIndex, SysmlAnnotation,
-        SerializedStdlib, AstSerializerContext)
+      - **Model/** — public semantic model types (SysmlNode, SysmlMetadataNode, AstBuilder,
+        SymbolTable, ReferenceResolver, SupertypeWalker, SysmlEdge, SemanticIndex,
+        SysmlAnnotation, SerializedStdlib, AstSerializerContext)
   - **DemaConsulting.SysML2Tools.Stdlib/** — stdlib library
     - **Stdlib/** — SysML v2 standard library source files (EPL-2.0; see Stdlib/README.md)
   - **DemaConsulting.SysML2Tools.Core/** — core library
+    - **Filtering/** — standalone view-filter expression AST, parser, and evaluator
     - **Layout/** — layout strategies mapping the model to the off-the-shelf `LayoutTree`
       - **Internal/** — per-view layout strategies and the `LayeredPlacement` helper
     - **Rendering/** — SysML-coupled rendering pipeline (`ILayoutStrategy`, `DiagramRenderer`)

docs/design/sysml2-tools-core.md

@@ -2,12 +2,14 @@
 
 ## Architecture
 
-The `DemaConsulting.SysML2Tools` core library provides the Layout, Rendering, and Io subsystems
-for SysML v2 diagram generation and shared file-discovery. It depends on
+The `DemaConsulting.SysML2Tools` core library provides the Filtering, Layout, Rendering, and Io
+subsystems for SysML v2 diagram generation and shared file-discovery. It depends on
 `DemaConsulting.SysML2Tools.Language` for parsing and semantic analysis, and on
 `DemaConsulting.SysML2Tools.Stdlib` for the pre-compiled standard library.
 
-The core library provides three subsystems: **Layout**, **Rendering**, and **Io**. The Layout
+The core library provides four subsystems: **Filtering**, **Layout**, **Rendering**, and **Io**.
+The Filtering subsystem parses and evaluates the Phase 1 subset of standalone
+`filter [<expr>];` statements against metadata annotations captured by the semantic model. The Layout
 subsystem maps the SysML semantic model onto the `LayoutTree` intermediate representation — nine
 immutable node record types covering all SysML diagram elements — which is provided off-the-shelf
 by the `DemaConsulting.Rendering` package, and delegates geometric placement and routing to the
@@ -24,6 +26,10 @@ flowchart TD
         Language["DemaConsulting.SysML2Tools.Language"]
         Stdlib["DemaConsulting.SysML2Tools.Stdlib"]
     end
+    subgraph Filtering
+        FilterExpressionParser
+        FilterExpressionEvaluator
+    end
     subgraph Layout
         LayoutTree
         LayoutNode
@@ -38,8 +44,12 @@ flowchart TD
     subgraph Io
         GlobFileCollector
     end
+    Language --> FilterExpressionParser
+    Language --> FilterExpressionEvaluator
     Language --> DiagramRenderer
     Stdlib --> DiagramRenderer
+    DiagramRenderer --> FilterExpressionParser
+    DiagramRenderer --> FilterExpressionEvaluator
     DiagramRenderer --> ILayoutStrategy
     DiagramRenderer --> IRenderer
     ILayoutStrategy --> LayoutTree
@@ -125,8 +135,20 @@ N/A — not a safety-classified software item.
 6. Each rendered stream is wrapped in a `RenderOutput` with `SuggestedFileName` derived from
    the view name and `IRenderer.DefaultExtension`.
 
+### Filtering Data Flow
+
+1. `AstBuilder` captures a view's standalone `filter [<expr>];` statement as raw source text on
+   `SysmlViewNode.FilterExpressionText`.
+2. `GeneralViewLayoutStrategy` passes that raw text to `FilterExpressionParser.Parse`, which
+   adapts the generated SysML `ownedExpression()` parse tree into the supported Phase 1
+   `FilterExpression` AST.
+3. When parsing succeeds, `FilterExpressionEvaluator.Evaluate` applies the AST to the already
+   expose-scoped candidate definitions by reading their directly-owned `SysmlMetadataNode`
+   children; when parsing fails, layout falls back to the unfiltered scope with a warning.
+
 ## Design Constraints
 
 - Platform: multi-targets net8.0, net9.0, and net10.0 on Windows, Linux, and macOS.
 - SysML v2 parsing, semantic analysis, and standard library are provided by the Language and
-  Stdlib assemblies; the Core assembly contains only Layout, Rendering, and Io concerns.
+  Stdlib assemblies; the Core assembly contains only Filtering, Layout, Rendering, and Io
+  concerns.