Merge branch feature/multi-module-support into master

==SUMMARY==
Branch feature/multi-module-support commits:
* docs: fixes syntax highlighters used for documentation generation.
* feat: Implement aggregated packaging for multi-module projects
* feat: Add multi-module project creation support to pasbuild init
* Adds single and multi-module samples
* Completed multi-module implementation.
* docs: Add multi-module projects section to quick-start guide
* docs: Update multi-module documentation with verbose graph display
* Bonus: Add verbose dependency graph display to reactor command
* Phase 7: Documentation for multi-module support
* Phase 6: Add CLI module selection flag and tests
* Phase 5: Implement reactor build command for multi-module orchestration
* Phase 4: Implement artifact resolution for module dependencies
* Phase 3: Implement topological sort and cycle detection for build order
* Phase 1.4: Validate packaging rules for multi-module support
* Bump version in preparation for next release
* If manual paths were specified, always add them.
* Phase 1.2-1.3: XML parsing for packaging types and modules
* Phase 1.1: Add packaging type support and multi-module infrastructure
* Add multi-module build support design specification

Branch master commits since creating feature branch:

==DETAILS==
commit + c9ed246
Author: Graeme Geldenhuys <graemeg@gmail.com>
Date:   Fri Dec 19 16:03:53 2025 +0000

    docs: fixes syntax highlighters used for documentation generation.

commit + c1e2927
Author: Graeme Geldenhuys <graemeg@gmail.com>
Date:   Mon Dec 15 16:58:40 2025 +0000

    feat: Implement aggregated packaging for multi-module projects

    Implement Option B from design: create single aggregated packages at
    aggregator level instead of per-module packages.

    Changes:
    - Add TAggregatedPackageCommand: Creates single binary package with all
      application executables from all modules in flat structure
    - Add TAggregatedSourcePackageCommand: Creates single source package with
      all module sources preserving directory structure
    - Modify TReactorCommand: For package goal, only compile modules (no
      per-module packaging); aggregation happens at aggregator level
    - Modify main entry point: Route aggregators to new aggregated commands
      based on packaging=pom detection

    Behavior:
    - pasbuild package (on aggregator): Creates single archive with:
      - All application module executables
      - Aggregator LICENSE/README
      - Excludes library modules
    - pasbuild source-package (on aggregator): Creates single archive with:
      - All module project.xml and src/ directories
      - Preserves module directory structure
      - Aggregator project.xml and documentation

    Backward Compatibility:
    - Single-project package behavior unchanged
    - Automatic routing based on packaging type
    - All existing tests pass

    Testing:
    - Verified with /tmp/test2 multi-module project
    - Verified with samples/multi-module project
    - Verified single-project backward compatibility

commit + 81153fd
Author: Graeme Geldenhuys <graemeg@gmail.com>
Date:   Mon Dec 15 13:51:30 2025 +0000

    feat: Add multi-module project creation support to pasbuild init

    - Add interactive option to create multi-module (aggregator) projects
    - Implement GeneratePomProjectXML() to create aggregator project.xml
    - Implement GenerateModuleProjectXML() for child module configuration
    - Add GenerateSampleLibraryUnit() to generate starter code for libraries
    - Create ExecuteMultiModuleInit() to handle multi-module initialization flow
    - Extract ExecuteSingleModuleInit() to preserve backward compatibility
    - Add helper methods: PromptModuleType(), ValidateModuleName(), etc
    - Maintain full backward compatibility with single-module init (default)
    - Users prompted to choose between single or multi-module projects
    - All modules created with proper directory structure and template files
    - Libraries get sample unit files with proper naming conventions
    - Complete project.xml and LICENSE files generated for aggregator

    Example usage:
      pasbuild init
      # Select "multi" for project structure
      # Provide aggregator metadata
      # Define child modules interactively

    This feature saves significant time when starting new multi-module projects.

commit + 928c76e
Author: Graeme Geldenhuys <graemeg@gmail.com>
Date:   Mon Dec 15 13:10:53 2025 +0000

    Adds single and multi-module samples

    * useful for testing
    * useful for users of pasbuild to see working examples.

commit + 7b32a00
Author: Graeme Geldenhuys <graemeg@gmail.com>
Date:   Mon Dec 15 13:09:17 2025 +0000

    Completed multi-module implementation.

    Tested with a few sample multi-module projects and single projects.

commit + 9607786
Author: Graeme Geldenhuys <graemeg@gmail.com>
Date:   Sun Dec 14 01:59:28 2025 +0000

    docs: Add multi-module projects section to quick-start guide

    Add brief overview of multi-module support to Advanced Features section
    with example structure, basic usage examples, and link to detailed
    multi-module tutorial. This provides users an entry point to the feature
    without duplicating detailed documentation.

    Fixes: Links documentation sections together for better navigation

commit + 3ce89c4
Author: Graeme Geldenhuys <graemeg@gmail.com>
Date:   Sun Dec 14 01:51:34 2025 +0000

    docs: Update multi-module documentation with verbose graph display

    Added comprehensive documentation for the verbose dependency graph display
    feature (-v flag) in both tutorial and design documents.

    - multi-module-tutorial.adoc: New CLI reference section for -v flag
      * Shows example output with dependency tree
      * Explains benefits (visualization, verification, debugging)
      * Provides combined examples with other flags
    - design.adoc: Added verbose display examples to CLI Support section
      * Command examples
      * Example output
      * Link to detailed tutorial

    This completes documentation for all multi-module features including
    the bonus verbose dependency graph visualization.

commit + e8d15f6
Author: Graeme Geldenhuys <graemeg@gmail.com>
Date:   Sun Dec 14 01:41:51 2025 +0000

    Bonus: Add verbose dependency graph display to reactor command

    Adds DisplayDependencyGraph method to TReactorCommand that visualizes
    the module dependency graph when verbose (-v) flag is used. Shows each
    module and its dependencies with visual tree structure.

    Example output:
      Dependency Graph:

      core (no dependencies)
      ui (depends on: core)
        └─ core
      demo (depends on: ui)
        └─ ui

    All 63 tests still passing.

commit + 4b9fbee
Author: Graeme Geldenhuys <graemeg@gmail.com>
Date:   Sun Dec 14 01:33:28 2025 +0000

    Phase 7: Documentation for multi-module support

    Comprehensive documentation for multi-module projects including:

    - Updated README.adoc with multi-module features list
    - New multi-module-tutorial.adoc with step-by-step guide
      * Aggregator setup
      * Library and application module creation
      * Build examples and troubleshooting
      * Complete project structure examples
    - Updated design.adoc with Multi-Module Projects section
      * Packaging types explanation
      * Dependency resolution overview
      * Build order calculation details
      * Validation rules documentation
      * CLI support examples

    This completes the multi-module support implementation with full
    documentation for users.

commit + f2adbea
Author: Graeme Geldenhuys <graemeg@gmail.com>
Date:   Sun Dec 14 01:25:34 2025 +0000

    Phase 6: Add CLI module selection flag and tests

    Adds -m/--module flag to CLI for selecting specific module in multi-module
    builds. Enables users to build only a selected module and its dependencies.

    Key changes:
    - Added SelectedModule field to TCommandLineArgs record
    - Implemented -m/--module flag parsing in argument parser
    - Updated help text with new flag documentation and examples
    - Added 4 comprehensive tests for CLI module selection

    All 63 tests pass (59 previous + 4 new CLI tests).

commit + f94b759
Author: Graeme Geldenhuys <graemeg@gmail.com>
Date:   Sun Dec 14 01:20:02 2025 +0000

    Phase 5: Implement reactor build command for multi-module orchestration

    Adds TReactorCommand class to execute a goal on all modules in build order.
    Includes comprehensive test coverage for reactor build scenarios including
    build order preservation, module handling, multiple dependencies, and
    artifact resolution.

    Key features:
    - Executes goals on modules in topological build order
    - Skips aggregator modules (packaging=pom)
    - Resolves artifacts for each module before build
    - Provides progress logging for multi-module builds
    - Returns error code if any module fails

    All 59 tests pass (54 previous + 5 new reactor build tests).

commit + 0203f6d
Author: Graeme Geldenhuys <graemeg@gmail.com>
Date:   Sun Dec 14 01:08:45 2025 +0000

    Phase 4: Implement artifact resolution for module dependencies

    Adds ResolveArtifacts method to TModuleRegistry to map module dependencies
    to compiled unit paths. Extends TBuildConfig with ResolvedModulePaths field
    and integrates resolved paths into compile command's -Fu flags.

    Key changes:
    - Added ResolvedModulePaths field to TBuildConfig for storing artifact paths
    - Implemented ResolveArtifacts method to resolve dependencies to units directories
    - Integrated resolved module paths into BuildCompilerCommand for -Fu arguments
    - Added comprehensive tests for single/multiple/transitive dependencies

    All 54 tests pass (48 previous + 6 new artifact resolution tests).

commit + 0da8673
Author: Graeme Geldenhuys <graemeg@gmail.com>
Date:   Sun Dec 14 00:59:54 2025 +0000

    Phase 3: Implement topological sort and cycle detection for build order

    Implements GetBuildOrder method in TModuleRegistry using depth-first
    topological sort algorithm with cycle detection. Includes comprehensive
    test coverage for various dependency patterns (linear, diamond, complex
    graphs) and detects cyclic dependencies (simple, complex, self-reference).

    All 48 tests pass (7 new Phase 3 tests + 41 existing tests).

commit + a9eecd0
Author: Graeme Geldenhuys <graemeg@gmail.com>
Date:   Sat Dec 13 21:24:18 2025 +0000

    Phase 1.4: Validate packaging rules for multi-module support

    - Add ValidatePackagingRules method to TConfigLoader
    - Implement validation for POM aggregators (require modules, forbid mainSource)
    - Implement validation for libraries/applications (forbid child modules)
    - Add 7 new test methods in TTestValidatePackagingRules
    - Create 7 test fixture XML files for validation scenarios
    - Integrate validation call into LoadProjectXML after module parsing

    All 27 tests passing (20 existing + 7 new validation tests).
    Backward compatibility maintained.

    Phase 1: Core Infrastructure - COMPLETE

commit + 4590cb3
Author: Graeme Geldenhuys <graemeg@gmail.com>
Date:   Sat Dec 13 21:23:04 2025 +0000

    Bump version in preparation for next release

commit + 8a738a3
Author: Graeme Geldenhuys <graemeg@gmail.com>
Date:   Sat Dec 13 21:19:56 2025 +0000

    If manual paths were specified, always add them.

commit + d1a2d4a
Author: Graeme Geldenhuys <graemeg@gmail.com>
Date:   Thu Dec 11 08:33:36 2025 +0000

    Phase 1.2-1.3: XML parsing for packaging types and modules

    Following TDD - tests written first, implementation follows.

    Changes to PasBuild.Config.pas:
    - Parse <packaging> element (new, preferred)
    - Maintain backward compatibility with <projectType>
    - Support "pom" value for aggregator projects
    - ParseModules() method to parse <modules> lists
    - Call ParseModules() in LoadProjectXML

    Test infrastructure:
    - 6 XML test fixtures for packaging types
    - PasBuild.Test.Config.MultiModule with 9 new tests
    - Tests for pom, library, application, default, backward compat
    - Tests for invalid packaging value (error handling)
    - Tests for modules parsing

    Tests: 20 passing (11 from Phase 1.1 + 9 new), 0 failures, 0 errors
    Backward compatibility: Verified - <projectType> still works

    Phase 1 Tasks 1.2-1.3: COMPLETE
    Next: Task 1.4 - Validation rules

commit + af3f5cf
Author: Graeme Geldenhuys <graemeg@gmail.com>
Date:   Wed Dec 10 21:56:53 2025 +0000

    Phase 1.1: Add packaging type support and multi-module infrastructure

    Following TDD approach - tests written first, implementation follows.

    Changes:
    - Add ptPom to TProjectType enum for aggregator projects
    - Add Modules and ModuleDependencies string lists to TProjectConfig
    - Initialize lists in constructor, free in destructor
    - Add FPCUnit test infrastructure (TestRunner.pas)
    - Add comprehensive tests for packaging types and module lists
    - Configure test framework in project.xml with FPCUnit options

    Tests: 11 passing, 0 failures, 0 errors
    Memory: No leaks detected (verified with -gh flag)
    Backward compatibility: Maintained (ptApplication remains default)

    Phase 1 Task 1.1: COMPLETE

commit + d85bae2
Author: Graeme Geldenhuys <graemeg@gmail.com>
Date:   Wed Dec 10 17:00:30 2025 +0000

    Add multi-module build support design specification

    This design specification defines a comprehensive multi-module build system
    for PasBuild, enabling management of related projects within a single build
    tree (framework + examples, shared libraries, etc.).

    Key features:
    - Three packaging types: pom (aggregator), library, application
    - Declarative module dependencies with automatic build ordering
    - Artifact resolution for automatic -Fu path generation
    - Reactor builds (single command builds all modules)
    - Bootstrap auto-generation for library projects preserved
    - Full backward compatibility with single-project builds

    Design follows Maven multi-module patterns adapted to Pascal/FPC with
    path-based linking instead of artifact repositories.

    Implementation planned in 7 phases with comprehensive test coverage.

Author: graemeg

README.adoc

@@ -41,6 +41,9 @@ allowing you to override only what you need to change.
 * ✅ Cross-platform path handling (Maven convention)
 * ✅ Self-hosting (PasBuild can build itself)
 * ✅ Zero memory leaks (verified with -gh)
+* ✅ Multi-module projects with dependency resolution
+* ✅ Topological build ordering with cycle detection
+* ✅ Module selection flag (-m) for selective builds
 
 **Platform Support:**
 

docs/design.adoc

@@ -954,6 +954,154 @@ Currently all major features are implemented. Future enhancements will be driven
 See `implementation-progress.adoc` for detailed task breakdown and current status.
 
 
+== Multi-Module Projects
+
+PasBuild supports Maven-style multi-module projects with aggregators, libraries, and applications.
+
+=== Packaging Types
+
+Three packaging types organize multi-module projects:
+
+[cols="1,2,3"]
+|===
+|Type |Purpose |Example
+
+|`pom` (aggregator)
+|Coordinates multiple modules
+|Root project with `<modules>` list
+
+|`library`
+|Provides reusable components
+|Framework, utilities, UI toolkit
+
+|`application`
+|Final executable
+|Demo, tool, end-user application
+|===
+
+=== Project Structure
+
+[source]
+----
+my-framework/                      # Aggregator (packaging=pom)
+├── project.xml
+├── core/                          # Library (packaging=library)
+│   ├── project.xml
+│   └── src/main/pascal/
+├── ui/                            # Library (depends on core)
+│   ├── project.xml
+│   └── src/main/pascal/
+└── demo/                          # Application (depends on ui)
+    ├── project.xml
+    └── src/main/pascal/
+----
+
+=== Module Declaration
+
+Aggregators list child modules:
+
+[source,xml]
+----
+<project>
+  <build>
+    <packaging>pom</packaging>
+  </build>
+  <modules>
+    <module>core</module>
+    <module>ui</module>
+    <module>demo</module>
+  </modules>
+</project>
+----
+
+Modules declare dependencies:
+
+[source,xml]
+----
+<project>
+  <!-- UI depends on core -->
+  <modules>
+    <module>../core</module>
+  </modules>
+</project>
+----
+
+=== Dependency Resolution
+
+PasBuild automatically:
+
+1. Discovers all modules from aggregator
+2. Resolves dependencies between modules
+3. Detects circular dependencies
+4. Computes topological build order
+5. Adds resolved module paths to `-Fu` flags
+
+=== Build Order Calculation
+
+Uses depth-first topological sort to determine order:
+
+[source]
+----
+demo (application)
+  └── ui (library)
+      └── core (library)
+
+Build order: core → ui → demo
+----
+
+Cycle detection prevents:
+
+[source]
+----
+A → B → A (cycle detected, build fails)
+----
+
+=== Validation Rules
+
+All configurations are validated:
+
+* Aggregators (pom) MUST have `<modules>`, forbid `<mainSource>`
+* Libraries can optionally have `<mainSource>`
+* Applications MUST have `<mainSource>`
+* Only libraries and applications produce artifacts
+* Module dependencies cannot reference aggregators
+* Paths must remain within project tree (security)
+
+=== CLI Support
+
+Build specific modules:
+
+[source,bash]
+----
+pasbuild compile -m demo              # Build demo and dependencies
+pasbuild test -m core                 # Test core only
+pasbuild package -m ui -p release     # Package with profile
+----
+
+Display dependency graph in verbose mode:
+
+[source,bash]
+----
+pasbuild compile -v                   # Show dependency graph
+pasbuild compile -v -m demo           # Show graph and build demo
+----
+
+Example output:
+
+[source]
+----
+[INFO] Dependency Graph:
+[INFO]
+[INFO] core (no dependencies)
+[INFO] ui (depends on: core)
+[INFO]   └─ core
+[INFO] demo (depends on: ui)
+[INFO]   └─ ui
+----
+
+For details and examples, see `multi-module-tutorial.adoc`.
+
+
 == Appendix: Technology Choices
 
 === Programming Language

docs/implementation-progress.adoc

@@ -2,6 +2,8 @@
 :toc: left
 :toclevels: 3
 :sectnums:
+:source-highlighter: rouge
+:icons: font
 
 == Overview