Document Hierarchy: API Rules Index → Flattening Patterns → Conditions Reference → Rule Mapping
Purpose: Traceability matrix connecting each rule to its flattening pattern(s), source condition(s), and implementation file(s). Use this to trace a behavior from high-level rule down to exact source code.
| Rule | Description | F## | C## | Implementation File |
|---|---|---|---|---|
| Rule 1 | Category Name Matching | F01 | C05, C09, C09b, C13 | src/lib/helpers/api_builder/decisions.mjs |
| Rule 2 | Single Function File Promotion | - | C10, C13 | src/lib/helpers/api_builder/decisions.mjs |
| Rule 3 | Nested Category Mirroring | - | C10 | src/lib/helpers/api_builder/decisions.mjs |
| Rule 4 | Default Export Promotion | - | C11, C17 | src/lib/helpers/api_builder/decisions.mjs |
| Rule 5 | Multi-Default Export Coordination | - | C02, C03 | src/lib/helpers/api_builder/decisions.mjs |
| Rule 6 | Self-Referential / Circular Reference Prevention | - | C01, C09a | src/lib/helpers/api_builder/decisions.mjs |
| Rule 7 | Auto-Flattening - Single Named Export | F03 | C04, C08, C12, C18 | src/lib/helpers/api_builder/decisions.mjs |
| Rule 8 | Object / Namespace Default Flattening | F02, F04, F05 | C11, C17 | src/lib/helpers/api_builder/decisions.mjs |
| Rule 9 | Function Name Preference | - | C15, C16 | src/lib/helpers/api_builder/decisions.mjs |
| Rule 10 | Parent-Level Promotion - Generic Filenames | F02 | C14 | src/lib/helpers/api_builder/decisions.mjs |
| Rule 11 | AddApi Special File Pattern | F06 | C33 | src/lib/helpers/api_builder/add_api.mjs |
| Rule 12 | Module Ownership and Selective API Overwriting | F07 | - | src/lib/handlers/ownership.mjs |
| Rule 13 | AddApi Path Deduplication Flattening (New in v3) | F08 | C34 | src/lib/handlers/api-manager.mjs |
| Pattern | Rules | Conditions |
|---|---|---|
| F01: Basic Flattening | Rule 1, Rule 6 | C01, C05, C07 |
| F02: Function Folder Matching | Rule 8, Rule 10 | C10, C14, C15 |
| F03: Auto-Flatten Single Named Export | Rule 7 | C04, C08 |
| F04: Default Export Object Flattening | Rule 4, Rule 8 | C11, C12 |
| F05: Module Processing Pipeline | Rule 1, Rule 5 | C08, C09, C09b |
| F06: AddApi Special File Pattern | Rule 11 | C33 |
| F07: Ownership and Module Identity | Rule 12 | - |
| F08: AddApi Path Deduplication | Rule 13 | C34 |
| Condition | Rules |
|---|---|
| C01 | Rule 6 |
| C02 | Rule 5 |
| C03 | Rule 5 |
| C04 | Rule 7 |
| C05 | Rule 1 |
| C07 | All (fallback) |
| C08 | Rule 7 |
| C09 | Rule 1, Rule 5 |
| C09a | Rule 6 |
| C09b | Rule 1 (fallback) |
| C10 | Rule 2, Rule 3 |
| C11 | Rule 4, Rule 8 |
| C12 | Rule 7, Rule 8 |
| C13 | Rule 1, Rule 2 |
| C14 | Rule 10 |
| C15 | Rule 9 |
| C16 | Rule 9 |
| C17 | Rule 4, Rule 8 |
| C18 | Rule 7 |
| C33 | Rule 11 |
| C34 | Rule 13 |
| File | Responsibilities | Rules |
|---|---|---|
src/lib/helpers/api_builder/decisions.mjs |
Core flattening decision logic - getFlatteningDecision(), processModuleForAPI(), buildCategoryDecisions() |
Rules 1-10 |
src/lib/helpers/api_builder/add_api.mjs |
AddApi special file detection and module merging | Rule 11 |
src/lib/handlers/ownership.mjs |
Module ownership stack - tracks which module "owns" each API path; event-driven via impl:created / impl:changed lifecycle events |
Rule 12 |
src/lib/handlers/api-manager.mjs |
AddApi path deduplication via isDirectChild guard in addApiComponent() |
Rule 13 |
Rule 12 (Module Ownership) operates at the handler level, not the condition level. The ownership system is event-driven (impl:created, impl:changed) and does not participate in the getFlatteningDecision() / buildCategoryDecisions() decision pipeline. For this reason, Rule 12 has no associated C## entry - its implementation is entirely within src/lib/handlers/ownership.mjs.
Rule 13 (AddApi Path Deduplication) does not exist in v2. The isDirectChild guard and the post-buildAPI hoisting logic in addApiComponent() were added as part of the v3 rewrite. See F08 and C34 for full details.
Conditions C11 and C17 contribute to both Rule 4 (Default Export Promotion) and Rule 8 (Object/Namespace Default Flattening). The same source condition fires in both single-file and multi-file directory contexts; the rule that applies depends on the surrounding directory structure and depth.
C07 (the else branch of getFlatteningDecision()) is a fallback for all rules. It is not assigned to a specific rule because it only fires when no affirmative condition matches. It is included in the cross-reference index but excluded from the main traceability matrix.