Principles shared by both projects

1. Spec-First — implementation follows the spec; deviations require the spec to be updated first, not the other way around.
2. Single Responsibility — each component does exactly one thing and exposes only what its callers need.
3. Dependency Direction — EntryPoint depends on all libraries; libraries never depend on each other.
4. Non-Failing Parse — parsers and navigators never abort; they forward problems to the caller (DirNav skips unreadable files; Tokenizer and Lexer emit error tokens rather than panicking).
5. Complete Reporting — errors are collected, never short-circuited. PageValidator's Validator visits the entire file before returning a report.
6. Caller-Defined Interfaces — components expose traits or callbacks (e.g., the DirEvent trait) so callers control behavior without modifying library code.

Toolchain

  Language: Rust (edition 2018)
  Build:    Cargo - each crate builds independently (no workspace manifest)

Directory layout

  rs_textfinder/
  ├── Constitution.md
  ├── Structure.md
  ├── RustCmdLine/
  │   ├── Cargo.toml          ← library crate: rust_cmd_line
  │   └── src/cmd_line_lib.rs
  ├── RustDirNav/
  │   ├── Cargo.toml          ← library crate: rust_dir_nav
  │   └── src/dir_nav_lib.rs
  ├── RustTextFinder/
  │   ├── Cargo.toml          ← binary crate: rust_text_finder
  │   └── src/text_finder.rs
  └── RustTfVerify/
      ├── Cargo.toml          ← binary crate: tf_verify
      └── src/main.rs         ← integration verification harness

Dependency graph (physical)

  RustCmdLine   RustDirNav
       \            /
        \          /
      RustTextFinder

  RustTfVerify ──(subprocess)──► text_finder binary

Toolchain

  Language: C++23 with named modules (.ixx files)
  Build:    CMake 3.28+ (FILE_SET CXX_MODULES support required)

Directory layout

  CppTextFinder/
  ├── CMakeLists.txt       ← top-level; sets standard, adds subdirectories
  ├── Constitution.md
  ├── Structure.md
  ├── CommandLine/
  │   ├── CMakeLists.txt
  │   └── src/
  │       ├── CmdLine.ixx  ← export module cmd_line;
  │       └── test.cpp
  ├── DirNav/
  │   └── src/DirNav.ixx   ← export module dir_nav;
  ├── Output/
  │   └── src/Output.ixx   ← export module output;
  └── EntryPoint/
      └── src/main.cpp     ← imports all three modules

Rule from Structure.md

Each part folder owns its own CMakeLists.txt. No part's build file references another part's source directory directly. Only the top-level CMakeLists.txt names the parts.

Toolchain

  Language: Rust (edition 2021)
  Build:    Cargo workspace - each component is a separate crate

Directory layout

  rs_page_validator/
  ├── Cargo.toml       ← workspace root
  ├── Constitution.md
  ├── Structure.md
  ├── tokenizer/
  │   ├── Cargo.toml   ← library crate: tokenizer
  │   ├── Spec.md
  │   ├── Notes.md
  │   └── src/lib.rs
  ├── lexer/
  │   ├── Cargo.toml   ← library crate: lexer
  │   ├── Spec.md
  │   ├── Notes.md
  │   └── src/lib.rs
  ├── validator/
  │   ├── Cargo.toml   ← library crate: validator
  │   ├── Spec.md
  │   ├── Notes.md
  │   └── src/lib.rs
  └── entry_point/
      ├── Cargo.toml   ← binary crate: rs_page_validator
      ├── Spec.md
      ├── Notes.md
      └── src/main.rs

Workspace Cargo.toml

  [workspace]
  members = ["tokenizer", "lexer", "validator", "entry_point"]
  resolver = "2"

DirEvent trait

  pub trait DirEvent {
    fn do_dir(&mut self, d: &str);
    fn do_file(&mut self, f: &str);
  }

DirNav<App: DirEvent> struct — methods

  DirNav::new() -> DirNav<App>
  recurse(p: bool) -> &mut Self   // default: true
  hide(p: bool) -> &mut Self      // hide empty dirs, default: true
  add_skip(s: &str) -> &mut Self  // add dir name to skip list
  add_pat(p: &str) -> &mut Self   // add file extension filter
  clear() -> &mut Self            // reset skip list and patterns
  visit(path: &str)               // execute depth-first walk
  get_dirs() -> usize             // count of visited directories
  get_files() -> usize            // count of visited files

Default skip list

  bin  obj  target  build  out  __pycache__
  .venv  venv  dist  .git  .vs  .idea  archive

Invariants

• Never aborts on read errors — skips and continues
• Fires do_dir before any do_file in that directory
• Counts are cumulative across the full walk

ValidationError and Report types

  struct ValidationError {
    rule:    &'static str,
    message: String,
    line:    usize,
    col:     usize,
  }

  struct Report {
    file:   PathBuf,
    errors: Vec<ValidationError>,
    // is_valid() -> bool
  }

Eight structural rules

  doctype       document begins with <!DOCTYPE html>
  root-element  exactly one <html> wraps the document
  head-required <head> present, contains at least one <title>
  body-required <body> present as direct child of <html>
  tag-nesting   every open tag has a matching close in stack order
  void-elements void elements carry no close tag
  attr-quotes   all attribute values are quoted
  duplicate-id  id attribute values are unique within the document

Invariant

• Never short-circuits — all errors collected before Report is returned