Introduce shared PHPStan base configuration

[dieselxxx]

🧱 System Design / Architecture Pull Request

Related Issue

• Link the issue(s) this PR addresses:
  Closes Shared base configuration for all FireHub repositories #1

Description

• This PR introduces a centralized PHPStan base configuration (base.neon) that defines the default static analysis ruleset for the entire FireHub ecosystem.
• It establishes a system-wide architectural boundary for static analysis, enforcing that all repositories (Core, Runtime, Adapters, Capabilities) must adhere to a shared baseline of type-safety and code quality rules.
• This architecture is required to eliminate configuration drift between repositories, ensure consistent enforcement of type safety, and define a single source of truth for static analysis behavior across FireHub.
• Affected components:
  • Core: must align with shared strict type rules and baseline analysis constraints
  • Runtime: must conform to unified static analysis expectations without weakening rules
  • Adapters: must comply with baseline rules while potentially extending configuration for integration-specific needs
  • Capabilities: must follow shared enforcement rules ensuring consistency across extension modules

Architecture Overview

System Design

• Describe the architecture being introduced or enforced:

• Core structure:
  A centralized PHPStan base configuration (base.neon) acting as the global static analysis baseline for all FireHub repositories.

  • Contracts:
    No new runtime contracts introduced. This layer defines analysis contracts (rules, constraints, and type-safety expectations) enforced via PHPStan configuration and future custom rules.

  • Boundaries:
    Strict separation between:

    • shared static analysis baseline (this repo)
    • repository-specific overrides (Core, Runtime, Adapters, Capabilities)
    • runtime/business logic (explicitly excluded)

  • Dependencies:

    • PHPStan (static analysis engine)
    • phpstan-strict-rules (strict enforcement ruleset)
    • optional FireHub PHPStan extension layer (future custom rules repo)

Design Decisions

• Key architectural decisions made:
  • Introduced a single source of truth for PHPStan configuration
  • Standardized maximum-level static analysis across FireHub ecosystem
  • Separated baseline rules from repository-specific configuration
  • Adopted strict type-safety enforcement as default behavior
• Why these decisions were chosen:
  • Prevent configuration drift across multiple repositories
  • Enforce consistent type-safety and code quality standards
  • Enable scalable governance over architecture rules
  • Reduce duplication of PHPStan configuration logic
• Rejected alternatives (if applicable):
  • Per-repository independent PHPStan configuration (inconsistency + maintenance overhead)
  • Fully centralized execution service (tight coupling)
  • Weak baseline configuration (insufficient enforcement)

System Boundaries

Included

• Shared PHPStan base.neon configuration
• Global static analysis rules (strictness, type safety, reporting rules)
• Baseline enforcement policy for all FireHub repositories
• Foundation for future custom rule extensions

Excluded

• Runtime logic
• Business/domain implementations
• Adapter implementations
• Infrastructure execution layers (DI, Autoload, DataStructures, etc.)
• CI/CD pipeline configuration

Implementation

Core Changes

• base.neon introduced as shared PHPStan configuration
• Strict analysis rules defined as ecosystem baseline

Contracts

• Analysis Contracts (not runtime contracts):
  • ValueObjects: not applicable
  • Exceptions: not applicable
  • Interfaces: not applicable

Dependencies

• New dependencies introduced:
  • phpstan/phpstan
  • phpstan/phpstan-strict-rules
• Impact on packages:
  • core-standard → must extend base config
  • core-professional → inherits stricter baseline rules
  • core-enterprise → fully aligned with governance layer

Validation

Architecture Compliance

• Matches defined Architecture issue
• No violation of Core / Runtime separation
• No unintended business logic introduced
• No infrastructure logic inside Core

Build & Stability

• Project builds successfully
• No breaking changes (or properly documented)
• Backward compatibility considered

Impact Analysis

Core Impact

• No runtime impact
• Introduces stricter static analysis expectations

Runtime Impact

• No runtime changes required
• Future refactoring may be required due to stricter rules

Future Extensions

• Custom PHPStan rules (DDD enforcement, architecture boundaries)
• CI enforcement layer
• Layer violation detection (Core vs Runtime vs Adapter)

Risks / Constraints

Risk Level

• None
• Low
• Medium
• High

Potential Risks

• Architecture lock-in if baseline becomes too strict
• Exposure of hidden type-safety issues across repos
• Risk of over-abstraction in future rule expansion

Documentation

• Architecture documented in repository / docs
• Design decisions explained
• Examples provided (if applicable)
• Migration notes are added (if needed)

Checklist

• Architecture issue linked
• System boundaries are clearly defined
• Core/Runtime separation respected
• No experimental or temporary code included
• Implementation matches architectural design
• Reviewed for long-term maintainability

Notes

Technical Notes

• This repo defines FireHub’s static analysis governance layer
• PHPStan is treated as an architectural enforcement system, not a tool

Future Work

• FireHub PHPStan custom rules repository
• Integration into Core / Runtime / Adapter repos
• CI enforcement of base configuration

Reviewer Guidance

• Focus on:
• architectural correctness
• system boundary enforcement
• long-term scalability of quality rules
• consistency across ecosystem