# Architecture Rules

## Purpose
To enforce structural patterns, type usage, and dependency management rules that maintain architectural integrity.

## Requirements

### Requirement: Import Hub Enforcement [VBL201]
The system SHALL enforce the import hub pattern, where non-hub modules must not expose public imports.

Priority: High

#### Scenario: Public import in non-hub module
- **WHEN** a module not designated as a "hub" (e.g., `__init__.py`) imports a name without aliasing it to private (e.g., `import os`)
- **THEN** a violation is reported

#### Scenario: Valid private alias
- **WHEN** a module imports a name as private (e.g., `import os as _os`)
- **THEN** no violation is reported

### Requirement: Import Spaghetti Detection [VBL202]
The system SHALL prevent excessive relative import depth to reduce coupling.

Priority: High

#### Scenario: Excessive relative depth
- **WHEN** a relative import exceeds the maximum allowed depth (e.g., `from ...module import name`)
- **THEN** a violation is reported

#### Scenario: Invalid sibling import in hub
- **WHEN** a re-export hub (`__.py`) uses single-level relative import (`from . import`)
- **THEN** a violation is reported (to prevent circular backward imports)

### Requirement: Collection Type Variance (REQ-004) [Not Implemented]
The system SHALL require abstract collection types for parameters and concrete types for returns.

Priority: High

#### Scenario: Concrete parameter type
- **WHEN** a function parameter is typed as a concrete collection (e.g., `list`, `dict`)
- **THEN** a suggestion to use an abstract type (e.g., `Sequence`, `Mapping`) is reported

#### Scenario: Abstract return type
- **WHEN** a return type is annotated as abstract (e.g., `Sequence`)
- **THEN** a suggestion to use a concrete or immutable type is reported