Rustelo/docs/architecture/foundation-dependency-analysis.md

Foundation Dependency Analysis - COMPLETE MAPPING

CIRCULAR DEPENDENCIES IDENTIFIED

1. CORE CIRCULAR DEPENDENCY CHAIN

tools → core-lib → components → tools

Details:

• tools/Cargo.toml depends on core-lib for shared functionality
• core-lib/build.rs uses tools::build::PathResolver and comprehensive analysis
• components/build.rs uses tools::comprehensive_analysis::generate_components_documentation
• tools provides build-time analysis that core-lib and components consume

2. BUILD-TIME CIRCULAR DEPENDENCY CHAIN

server → tools → shared → server
pages → tools → shared → pages  

Details:

• server/build.rs uses tools::build::PathResolver and tools::comprehensive_analysis::generate_server_documentation
• pages/build.rs uses tools::build::run_pages_scaffolding and comprehensive analysis
• tools depends on shared for types and utilities
• shared may reference server/pages components through generated code

3. CLIENT BUILD DEPENDENCY ISSUES

client/build.rs → external tools (pnpm, node) → CSS generation → client

Details:

• Client build runs pnpm run build for CSS processing
• CSS processing depends on UnoCSS config and package.json
• Generated CSS affects client compilation
• Creates external dependency cycle through Node.js toolchain

ALL BUILDERS IDENTIFIED AND ANALYSIS

1. client/build.rs - CSS BUILD COORDINATOR

fn coordinate_css_build(output_path: &Path, source_paths: &[PathBuf]) -> Result<bool, String>
fn run_direct_css_build()

Purpose:

• Manages CSS compilation via UnoCSS/Tailwind
• Coordinates pnpm install and build processes
• Handles freshness checking for CSS files
• Problem: External dependency on Node.js toolchain breaks isolation

2. pages/build.rs - PAGE SCAFFOLDING GENERATOR

build_page_generator::generate_page_components()
tools::build::run_pages_scaffolding()
tools::comprehensive_analysis::generate_pages_documentation()

Purpose:

• Generates page component implementations
• Creates scaffolding for new pages
• Generates page documentation
• Problem: Depends on tools crate, creates circular dependency

3. components/build.rs - COMPONENT DOCUMENTATION GENERATOR

fn generate_documentation_with_cache() -> Result<bool, Box<dyn std::error::Error>>
fn try_use_smart_cache() -> Result<bool, Box<dyn std::error::Error>>

Purpose:

• Generates comprehensive component documentation
• Implements smart caching system (L1/L2/L3 cache)
• Tracks component dependencies for cache invalidation
• Problem: Heavy dependency on tools crate for caching and analysis

4. server/build.rs - SERVER ROUTE DOCUMENTATION

fn generate_server_documentation() -> Result<(), Box<dyn std::error::Error>>

Purpose:

• Analyzes server-side API routes
• Generates route documentation and TOML configuration
• Documents route definitions and handlers
• Problem: Uses tools::build::PathResolver and comprehensive analysis

5. core-lib/build.rs - DISABLED CODE GENERATION

// PHASE 3.4: Code generation has been completely disabled in favor of
// pure trait-based runtime resolution. This build script now only
// provides configuration checks.

Purpose:

• Previously generated shared resources
• Now disabled in favor of trait-based resolution
• Only provides configuration checks
• Status: Correctly PAP compliant, no builders used

ENVIRONMENT VARIABLE DEPENDENCIES

Client Build Environment Variables:

• SKIP_CSS_BUILD - Skip CSS compilation
• CARGO_MANIFEST_DIR - Build context
• External: pnpm, node executables required

Pages Build Environment Variables:

• SKIP_SCAFFOLDING_BUILD - Skip page scaffolding
• SKIP_DOCS_BUILD - Skip documentation generation
• SITE_INFO_PATH - Documentation output path
• TARGET - Compilation target

Components Build Environment Variables:

• SKIP_DOCS_BUILD - Skip documentation generation
• SITE_INFO_PATH - Documentation output path
• CARGO_MANIFEST_DIR - Build context
• FORCE_REBUILD_CACHE - Force cache invalidation
• SITE_DEVTOOLS_PATH - Cache directory path

Server Build Environment Variables:

• SITE_INFO_PATH - Documentation output path
• CARGO_MANIFEST_DIR - Build context

Shared/Core Environment Variables:

• SKIP_SHARED_RESOURCES_BUILD - Skip resource generation

CODE GENERATION POINTS

1. Active Code Generation:

• client/build.rs → CSS files (public/website.css)
• pages/build.rs → Page components and documentation
• components/build.rs → Component documentation with caching
• server/build.rs → Route documentation and TOML configs

2. Disabled Code Generation:

• core-lib/build.rs → Completely disabled (PAP compliant)

3. Generated Output Locations:

• public/website.css - Generated by client build
• target/site_build/info/ - Generated documentation
• Page component files - Generated by pages build
• Route configuration files - Generated by server build

ROOT CAUSE ANALYSIS

1. Tools Crate as Central Dependency Hub

The tools crate has become a central dependency that creates circular references:

• Provides build-time utilities that all other crates need
• Contains comprehensive analysis functionality
• Implements smart caching system
• Solution: Break tools into smaller, focused trait-based crates

2. Build-time vs Runtime Confusion

Current architecture mixes build-time and runtime concerns:

• Build scripts generate code that affects runtime behavior
• Runtime traits depend on build-time generated content
• Solution: Pure runtime resolution without build-time generation

3. External Toolchain Dependencies

Client build depends on external Node.js toolchain:

• Breaks Rust-only compilation model
• Creates unpredictable build environment requirements
• Solution: Rust-only CSS processing or optional external dependency

4. Environment Variable Proliferation

Multiple environment variables control build behavior:

• Creates configuration complexity
• Breaks declarative configuration model
• Solution: Single configuration source (TOML files)

PROPOSED RESOLUTION STRATEGY

Phase 1: Break Circular Dependencies

1. Extract tools functionality into zero-dependency trait crates
2. Implement trait-based dependency injection for build concerns
3. Remove cross-crate build script dependencies

Phase 2: Eliminate Build-time Generation

1. Replace generated code with runtime configuration loading
2. Move from build.rs to runtime initialization
3. Use TOML configuration files instead of generated Rust code

Phase 3: Unify Client/SSR Architecture

1. Create unified components that work in both environments
2. Implement safe reactive patterns without reactive_graph panics
3. Handle hydration mismatches at the framework level

Phase 4: Pure Configuration-Driven Design

1. Replace all environment variables with TOML configuration
2. Implement configuration discovery and validation
3. Remove hardcoded paths and values

This analysis reveals the core architectural problems that prevent true PAP compliance and unified Client/SSR components.