Add ANTLR4 parser, embed OMG stdlib, and implement lint command

.cspell.yaml

@@ -54,6 +54,12 @@ words:
   - Sysml
   - sysml
   - sysml2tools
+  - kerml
+  - KerML
+  - daltskin
+  - interp
+  - Dlanguage
+  - uppercased
   - venv
   - versionmark
   - Weasyprint
@@ -68,6 +74,8 @@ ignorePaths:
   - "**/third-party/**"
   - "**/3rd-party/**"
   - "**/generated/**"
+  - "**/Parser/Antlr/**"
+  - "**/Stdlib/**"
   - "**/AGENT_REPORT_*.md"
   - "**/.agent-logs/**"
   - "**/bin/**"

.editorconfig

@@ -93,3 +93,12 @@ dotnet_code_quality_unused_parameters = all:suggestion
 
 # Nullable reference types
 csharp_nullable_reference_types = enable
+
+# ANTLR4-generated C# — suppress diagnostics that do not apply to generated code
+[src/DemaConsulting.SysML2Tools/Parser/Antlr/*.cs]
+generated_code = true
+# CS1584/CS1658 — XML doc cref uses SysML keywords ('namespace', 'class') as identifiers
+dotnet_diagnostic.CS1584.severity = none
+dotnet_diagnostic.CS1658.severity = none
+# CS3021 — CLSCompliant attribute; assembly does not declare [CLSCompliant]
+dotnet_diagnostic.CS3021.severity = none

.gitattributes

@@ -5,3 +5,6 @@
 # Windows batch files require CRLF line endings to function correctly.
 *.bat text eol=crlf
 *.cmd text eol=crlf
+
+# ANTLR4-generated parser files — excluded from CodeQL and language stats.
+src/DemaConsulting.SysML2Tools/Parser/Antlr/*.cs linguist-generated=true

.github/codeql-config.yml

@@ -4,6 +4,10 @@
 
 name: "SysML2 Tools CodeQL Config"
 
+# Exclude ANTLR4-generated parser files from all analysis
+paths-ignore:
+  - src/DemaConsulting.SysML2Tools/Parser/Antlr
+
 # Query filters to disable specific queries for certain paths
 query-filters:
   - exclude:
@@ -16,3 +20,26 @@ query-filters:
       id: cs/path-combine
     paths:
       - src/DemaConsulting.SysML2Tools/PathHelpers.cs
+
+  # Suppress false positives in ANTLR4-generated parser files.
+  # These are mechanical code generation artefacts, not hand-written logic.
+  - exclude:
+      id: cs/complex-condition
+    paths:
+      - src/DemaConsulting.SysML2Tools/Parser/Antlr
+  - exclude:
+      id: cs/useless-assignment-to-local
+    paths:
+      - src/DemaConsulting.SysML2Tools/Parser/Antlr
+  - exclude:
+      id: cs/virtual-call-in-constructor
+    paths:
+      - src/DemaConsulting.SysML2Tools/Parser/Antlr
+  - exclude:
+      id: cs/missed-ternary-operator
+    paths:
+      - src/DemaConsulting.SysML2Tools/Parser/Antlr
+  - exclude:
+      id: cs/coupled-types
+    paths:
+      - src/DemaConsulting.SysML2Tools/Parser/Antlr

.reviewmark.yaml

@@ -15,6 +15,7 @@ needs-review:
   - "docs/user_guide/**/*.md"     # User guide documentation
   - "!**/obj/**"                  # Exclude build output
   - "!**/bin/**"                  # Exclude build output
+  - "!src/**/Parser/Antlr/**"    # ANTLR4-generated C# — not hand-written
   - "!node_modules/**"            # Exclude npm dependencies
   - "!**/.venv/**"                # Exclude Python virtual environment
 
@@ -137,6 +138,38 @@ reviews:
     paths:
       - "docs/reqstream/sysml2-tools-core/**/*.yaml"
 
+  - id: SysML2Tools-Core-Parser-Design
+    title: Review that DemaConsulting.SysML2Tools Parser Design is Consistent and Complete
+    context:
+      - docs/reqstream/sysml2-tools-core.yaml
+    paths:
+      - "docs/design/introduction.md"
+      - "docs/design/sysml2-tools-core.md"
+      - "docs/design/sysml2-tools-core/parser.md"
+      - "docs/design/ots/antlr4.md"
+
+  - id: SysML2Tools-Core-Parser-Verification
+    title: Review that DemaConsulting.SysML2Tools Parser Verification is Consistent and Complete
+    context:
+      - docs/reqstream/sysml2-tools-core.yaml
+    paths:
+      - "docs/verification/introduction.md"
+      - "docs/verification/sysml2-tools-core.md"
+      - "docs/verification/sysml2-tools-core/parser.md"
+      - "docs/verification/ots/antlr4.md"
+
+  - id: SysML2Tools-Core-Parser-Implementation
+    title: Review of DemaConsulting.SysML2Tools Parser Implementation
+    context:
+      - docs/reqstream/sysml2-tools-core/parser.yaml
+      - docs/design/sysml2-tools-core/parser.md
+    paths:
+      - "src/DemaConsulting.SysML2Tools/Parser/WorkspaceParser.cs"
+      - "src/DemaConsulting.SysML2Tools/Parser/Internal/SysmlDiagnosticListener.cs"
+      - "src/DemaConsulting.SysML2Tools/Parser/Internal/StdlibLoader.cs"
+      - "test/DemaConsulting.SysML2Tools.Tests/Parser/WorkspaceParserTests.cs"
+      - "test/DemaConsulting.SysML2Tools.Tests/Parser/OmgModelsTests.cs"
+
   # SysML2Tools SVG Renderer
   - id: SysML2Tools-Svg-Architecture
     title: Review that DemaConsulting.SysML2Tools.Svg Architecture Satisfies Requirements
@@ -321,6 +354,17 @@ reviews:
       - "src/**/Utilities/PathHelpers.cs"
       - "test/**/Utilities/PathHelpersTests.cs"
 
+  - id: SysML2Tools-Tool-Lint
+    title: Review of SysML2 Tools Lint subsystem architecture and interfaces
+    context:
+      - docs/design/sysml2-tools-tool.md
+      - docs/reqstream/sysml2-tools-tool.yaml
+    paths:
+      - "docs/reqstream/sysml2-tools-tool/lint.yaml"
+      - "docs/design/sysml2-tools-tool/lint.md"
+      - "docs/verification/sysml2-tools-tool/lint.md"
+      - "src/**/Lint/LintCommand.cs"
+
   # OTS Items
   - id: OTS-BuildMark
     title: Review of BuildMark OTS verification evidence
@@ -391,3 +435,10 @@ reviews:
       - "docs/reqstream/ots/xunit.yaml"
       - "docs/design/ots/xunit.md"
       - "docs/verification/ots/xunit.md"
+
+  - id: OTS-ANTLR4
+    title: Review of ANTLR4 OTS verification evidence
+    paths:
+      - "docs/reqstream/ots/antlr4.yaml"
+      - "docs/design/ots/antlr4.md"
+      - "docs/verification/ots/antlr4.md"

docs/design/definition.yaml

@@ -1,8 +1,10 @@
 ---
 resource-path:
   - docs/design
+  - docs/design/sysml2-tools-core
   - docs/design/sysml2-tools-tool
   - docs/design/sysml2-tools-tool/cli
+  - docs/design/sysml2-tools-tool/lint
   - docs/design/sysml2-tools-tool/self-test
   - docs/design/sysml2-tools-tool/utilities
   - docs/design/ots
@@ -15,14 +17,17 @@ input-files:
   - docs/design/sysml2-tools-tool/program.md
   - docs/design/sysml2-tools-tool/cli.md
   - docs/design/sysml2-tools-tool/cli/context.md
+  - docs/design/sysml2-tools-tool/lint.md
   - docs/design/sysml2-tools-tool/self-test.md
   - docs/design/sysml2-tools-tool/self-test/validation.md
   - docs/design/sysml2-tools-tool/utilities.md
   - docs/design/sysml2-tools-tool/utilities/path-helpers.md
   - docs/design/sysml2-tools-core.md
+  - docs/design/sysml2-tools-core/parser.md
   - docs/design/sysml2-tools-svg.md
   - docs/design/sysml2-tools-png.md
   - docs/design/ots.md
+  - docs/design/ots/antlr4.md
   - docs/design/ots/buildmark.md
   - docs/design/ots/fileassert.md
   - docs/design/ots/pandoc.md

docs/design/introduction.md

@@ -15,48 +15,29 @@ how they are realized.
 
 ## Scope
 
-This document covers the detailed design of the following software items:
-
-**Local items:**
-
-- **DemaConsulting.SysML2Tools** (System — core library, Phase 0 stub)
-- **DemaConsulting.SysML2Tools.Svg** (System — SVG renderer, Phase 0 stub)
-- **DemaConsulting.SysML2Tools.Png** (System — PNG renderer, Phase 0 stub)
-- **DemaConsulting.SysML2Tools.Tool** (System — dotnet tool)
-  - **Program** — entry point and execution orchestrator
-  - **Cli** subsystem
-    - **Context** — command-line argument parser and I/O owner
-  - **SelfTest** subsystem
-    - **Validation** — self-validation test runner
-  - **Utilities** subsystem
-    - **PathHelpers** — safe path combination utilities
-
-**OTS items:**
-
-- **BuildMark** — integration and usage design
-- **FileAssert** — integration and usage design
-- **Pandoc** — integration and usage design
-- **ReqStream** — integration and usage design
-- **ReviewMark** — integration and usage design
-- **SarifMark** — integration and usage design
-- **SonarMark** — integration and usage design
-- **VersionMark** — integration and usage design
-- **WeasyPrint** — integration and usage design
-- **xUnit** — integration and usage design
+This document defines the design for each software item in SysML2 Tools —
+full architectural and detailed design for local items (systems, subsystems,
+and units), and integration/usage design for OTS software items. A reviewer
+should be able to understand how each item satisfies its requirements without
+reading source code.
 
 The following topics are out of scope:
 
-- Design documents are not produced for the test projects or build pipeline CI configuration
-- The internal design of OTS software items is excluded; only integration and usage design is documented
+- Design documents are not produced for the test projects or build pipeline CI configuration.
+- The internal design of OTS software items is excluded; only integration and usage design is documented.
 
 ## Software Structure
 
 The following list shows how the SysML2 Tools software items are organized across the
 system, subsystem, and unit levels:
 
-- **DemaConsulting.SysML2Tools** (System) — core library: SysML v2 parsing, semantic
-  model, layout algorithms, and `IRenderer` interface
-  - TODO: subsystems and units to be defined in Phase 1+
+- **DemaConsulting.SysML2Tools** (System) — core library: SysML v2 parsing engine, embedded stdlib,
+  and future semantic model/layout
+  - **Parser** (Subsystem) — SysML v2 parsing engine
+    - **WorkspaceParser** (Unit) — public API: parses file glob patterns and source strings against the embedded stdlib
+    - **Internal** (Subsystem) — internal implementation details
+      - **SysmlDiagnosticListener** (Unit) — collects ANTLR4 syntax errors as SysmlDiagnostic records
+      - **StdlibLoader** (Unit) — enumerates and loads embedded .sysml stdlib resources; defers .kerml to Phase 2
 - **DemaConsulting.SysML2Tools.Svg** (System) — SVG renderer: renders `LayoutTree` to
   SVG output with zero external dependencies
   - TODO: subsystems and units to be defined in Phase 4+
@@ -68,13 +49,16 @@ system, subsystem, and unit levels:
   - **Program** (Unit) — entry point and execution orchestrator
   - **Cli** (Subsystem) — command-line argument parsing and I/O
     - **Context** (Unit) — argument parser and I/O owner
+  - **Lint** (Subsystem) — lint command implementation
+    - **LintCommand** (Unit) — resolves glob patterns, invokes WorkspaceParser, reports diagnostics
   - **SelfTest** (Subsystem) — self-validation test runner
     - **Validation** (Unit) — self-validation test runner
   - **Utilities** (Subsystem) — shared utilities
     - **PathHelpers** (Unit) — safe path combination utilities
 
 **OTS Dependencies:**
 
+- ANTLR4 (OTS) — ANTLR4 runtime (Antlr4.Runtime.Standard)
 - BuildMark (OTS) — build-notes documentation tool
 - FileAssert (OTS) — document assertion tool
 - Pandoc (OTS) — Markdown-to-HTML conversion tool
@@ -94,19 +78,27 @@ The source code folder structure mirrors the top-level system breakdown above, g
 reviewers an explicit navigation aid from design to code:
 
 - **src/** — source projects
-  - **DemaConsulting.SysML2Tools/** — core library (Phase 0: stub)
+  - **DemaConsulting.SysML2Tools/** — core library
+    - **Grammar/** — ANTLR4 grammar files (hand-maintained; see Grammar/README.md)
+    - **Parser/** — SysML v2 parsing subsystem
+      - **Antlr/** — ANTLR4-generated C# (committed; not hand-written)
+      - **Internal/** — internal implementation (SysmlDiagnosticListener, StdlibLoader)
+    - **Stdlib/** — embedded SysML v2 standard library files (EPL-2.0; see Stdlib/README.md)
   - **DemaConsulting.SysML2Tools.Svg/** — SVG renderer (Phase 0: stub)
   - **DemaConsulting.SysML2Tools.Png/** — PNG renderer (Phase 0: stub)
   - **DemaConsulting.SysML2Tools.Tool/** — dotnet tool CLI wrapper
     - **Cli/** — command-line interface subsystem
+    - **Lint/** — lint command subsystem
     - **SelfTest/** — self-validation subsystem
     - **Utilities/** — shared utilities subsystem
 - **docs/design/** — design documentation
-  - **sysml2-tools-core/** — TODO: core library unit/subsystem design (Phase 1+)
+  - **sysml2-tools-core/** — core library unit/subsystem design
+    - **parser/** — Parser subsystem design (Internal subsystem)
   - **sysml2-tools-svg/** — TODO: SVG renderer unit/subsystem design (Phase 4+)
   - **sysml2-tools-png/** — TODO: PNG renderer unit/subsystem design (Phase 4+)
   - **sysml2-tools-tool/** — DemaConsulting.SysML2Tools.Tool unit/subsystem design
     - **cli/** — Cli subsystem design
+    - **lint/** — Lint subsystem design
     - **self-test/** — SelfTest subsystem design
     - **utilities/** — Utilities subsystem design
 

docs/design/ots.md

@@ -13,6 +13,7 @@ scope; only how this project integrates and uses each item is documented.
 
 The following OTS items have integration design documentation:
 
+- ANTLR4 (_antlr4.md_) — ANTLR4 runtime (Antlr4.Runtime.Standard)
 - BuildMark (_buildmark.md_) — build-notes documentation tool
 - FileAssert (_fileassert.md_) — document assertion tool
 - Pandoc (_pandoc.md_) — Markdown-to-HTML conversion tool

docs/design/ots/antlr4.md

@@ -0,0 +1,50 @@
+## ANTLR4
+
+This document describes the integration and usage design for the `ANTLR4` OTS software item
+(`Antlr4.Runtime.Standard` 4.13.1).
+
+### Purpose
+
+`Antlr4.Runtime.Standard` is the official ANTLR4 C# runtime library. It is used to execute the
+pre-generated SysML v2 lexer and parser (`SysMLv2Lexer` and `SysMLv2Parser`) that were produced
+from the hand-maintained ANTLR4 grammar files in `Grammar/`. The runtime provides the core
+infrastructure for tokenizing SysML v2 source text, building concrete syntax trees, and
+dispatching syntax errors to registered error listeners.
+
+### Features Used
+
+- `AntlrInputStream` — wraps a `string` source for character-by-character input consumption by
+  the lexer.
+- `CommonTokenStream` — bridges the lexer to the parser by buffering the token sequence produced
+  by `SysMLv2Lexer`.
+- Generated lexer class `SysMLv2Lexer` and generated parser class `SysMLv2Parser` — produced from
+  the grammar files using `antlr-4.13.1-complete.jar` and committed under `Parser/Antlr/`.
+- `IAntlrErrorListener<IToken>` — interface implemented by `SysmlDiagnosticListener` to receive
+  parser syntax errors.
+- `IAntlrErrorListener<int>` — interface implemented by `SysmlDiagnosticListener` to receive
+  lexer syntax errors.
+
+### Integration Pattern
+
+The grammar files (`Grammar/SysMLv2Lexer.g4` and `Grammar/SysMLv2Parser.g4`) are the
+authoritative source. The generated C# files are produced by running
+`antlr-4.13.1-complete.jar` as documented in `Grammar/README.md` and committed to the
+`Parser/Antlr/` folder. The generated files must not be manually edited.
+
+At runtime the integration sequence is as follows:
+
+1. A `SysmlDiagnosticListener` is constructed, bound to the current file path and a shared
+   diagnostic list.
+2. An `AntlrInputStream` is created from the source text string.
+3. A `SysMLv2Lexer` is instantiated over the input stream. The default error listeners are
+   removed and the `SysmlDiagnosticListener` is registered on the lexer.
+4. A `CommonTokenStream` is created from the lexer.
+5. A `SysMLv2Parser` is instantiated over the token stream. The default error listeners are
+   removed and the same `SysmlDiagnosticListener` is registered on the parser.
+6. The entry rule `rootNamespace()` is invoked. In Phase 1 the returned CST root is discarded.
+7. Any lexer or parser errors encountered during steps 3–6 are delivered to
+   `SysmlDiagnosticListener` via the `IAntlrErrorListener` interface, which appends a
+   `SysmlDiagnostic` record to the shared list.
+
+No initialization or disposal beyond the steps above is required; ANTLR4 objects are
+short-lived and garbage-collected after each parse call.