docs: Add design introduction with software structure and folder layout#10
Conversation
…der layout Agent-Logs-Url: https://github.com/demaconsulting/FileAssert/sessions/c734a984-f009-499d-a56d-50db0679422e Co-authored-by: Malcolmnixon <1863707+Malcolmnixon@users.noreply.github.com>
There was a problem hiding this comment.
Pull request overview
Adds an “Introduction” chapter to the FileAssert detailed design document and includes it in the Pandoc build pipeline, to describe intended architecture and navigation.
Changes:
- Added
docs/design/introduction.mddescribing purpose/scope, subsystem/unit structure, planned folder layout, conventions, and references. - Updated
docs/design/definition.yamlto include the new introduction chapter immediately aftertitle.txt.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 4 comments.
| File | Description |
|---|---|
| docs/design/introduction.md | New introductory chapter describing FileAssert’s intended architecture, unit list, and documentation conventions. |
| docs/design/definition.yaml | Adds introduction.md to the ordered list of Pandoc input files. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| The source code folder structure mirrors the top-level subsystem breakdown above, giving | ||
| reviewers an explicit navigation aid from design to code: | ||
|
|
There was a problem hiding this comment.
The “Folder Layout” section reads as if it reflects the current repo layout (“mirrors … above”), but the current implementation under src/DemaConsulting.FileAssert/ is still flat (e.g., Context.cs, FileAssertConfig.cs, etc. are not under subsystem subfolders). To avoid misleading readers, reword this section to explicitly say this is the planned/target layout (and optionally note the current flat layout).
| └── Validation.cs — self-validation test runner | ||
| ``` | ||
|
|
||
| The test project mirrors the same layout under `test/DemaConsulting.FileAssert.Tests/`. |
There was a problem hiding this comment.
This statement is currently inaccurate: test/DemaConsulting.FileAssert.Tests/ is also flat today (no Cli/, Configuration/, etc. subfolders). Either qualify it as a planned future structure or adjust it to describe the current state.
| The test project mirrors the same layout under `test/DemaConsulting.FileAssert.Tests/`. | |
| The test project currently uses a flat folder structure under `test/DemaConsulting.FileAssert.Tests/`, with tests organized logically by subsystem but not yet split into `Cli/`, `Configuration/`, `Modeling/`, `Utilities/`, or `SelfTest` subfolders. |
| └── Validation (Unit) | ||
| ``` | ||
|
|
||
| Each unit is described in detail in its own chapter within this document. |
There was a problem hiding this comment.
“Each unit is described in detail in its own chapter within this document” doesn’t match the current document composition: docs/design/definition.yaml only includes chapters for rule/file/test/config (not Program/Context/FileAssertData/PathHelpers/Validation). Please either change this to future tense (e.g., “will be described…”) or add stubs/chapters and include them in definition.yaml.
| Each unit is described in detail in its own chapter within this document. | |
| Each unit will be described in detail in its own chapter within this document. |
| - Section headings within each unit chapter follow a consistent structure: overview, data model, | ||
| methods/algorithms, and interactions with other units. |
There was a problem hiding this comment.
The “Document Conventions” bullet about unit chapter headings (“overview, data model, methods/algorithms, …”) doesn’t match the existing unit chapters in this doc set, which currently use sections like “Overview”, “Class Structure”, “YAML Configuration”, and “Design Decisions”. Update this convention to reflect the current structure, or adjust the existing chapters to follow the stated structure so the document is internally consistent.
| - Section headings within each unit chapter follow a consistent structure: overview, data model, | |
| methods/algorithms, and interactions with other units. | |
| - Section headings within each unit chapter typically follow a consistent structure using sections | |
| such as **Overview**, **Class Structure**, **YAML Configuration**, and **Design Decisions**. |
Pull Request
Description
Adds
docs/design/introduction.md— the opening chapter of the FileAssert detailed design document — covering the planned software architecture as it should appear in the finished implementation.New file:
docs/design/introduction.mdCli→ContextConfiguration→FileAssertConfig,FileAssertDataModeling→FileAssertTest,FileAssertFile,FileAssertRuleUtilities→PathHelpersSelfTest→ValidationUpdated:
docs/design/definition.yamlintroduction.mdas the first chapter aftertitle.txtin the Pandoc generation pipelineType of Change
Related Issues
Closes #
Pre-Submission Checklist
Before submitting this pull request, ensure you have completed the following:
Build and Test
dotnet build --configuration Releasedotnet test --configuration Releasedotnet run --project src/DemaConsulting.FileAssert --configuration Release --framework net10.0--no-build -- --validateCode Quality
dotnet format --verify-no-changesQuality Checks
Please run the following checks before submitting:
./lint.sh(Unix/macOS) orcmd /c lint.bat/./lint.bat(Windows)Testing
Documentation
Additional Notes
The folder layout documented here reflects the planned final structure (subsystems as subdirectories), not the current flat source layout. This serves as the architectural guide for the implementation phase.
Warning
Firewall rules blocked me from connecting to one or more addresses (expand for details)
I tried to connect to the following addresses, but was blocked by firewall rules:
https://storage.googleapis.com/chromium-browser-snapshots/Linux_x64/1108766/chrome-linux.zip/home/REDACTED/work/_temp/ghcca-node/node/bin/node node install.js(http block)If you need me to access, download, or install something from one of these locations, you can either: