github.com/Racer159/jackal@v0.32.7-0.20240401174413-0bd2339e4f2e/adr/0021-composable-components.md (about)

     1  # 21. Composable Components
     2  
     3  Date: 2023-10-26
     4  
     5  ## Status
     6  
     7  Accepted
     8  
     9  ## Context
    10  
    11  Jackal has supports composing components together between packages on `jackal package create` since v0.16.0.  This has allowed package creators to make more complex packages from smaller reusable bits.  As this functionality grew however there were a few problems that developed:
    12  
    13  1. Import chains did not handle scaling to larger numbers of layers with test coverage usually only covering the first import.
    14  2. When OCI skeletons were added they were largely bolted on after the fact without rethinking how they would impact composability.
    15  3. Component filtering via the `only` filter was not implemented in a central location leading to bugs with create-time filters.
    16  
    17  ## Decision
    18  
    19  We decided to separate composability into its own package that represents a composability import chain as a doubly linked list.  This allows us to represent the whole chain as it exists relative to the "head" Jackal package (the definition that Jackal was asked to build) to more easily handle packages that are in different locations (such as OCI skeletons in one's cache).  We also run the compose functions on all components so that the additional filter logic that is needed for these components can be handled more concisely and built upon (as it might for `flavor` https://github.com/Racer159/jackal/issues/2101).
    20  
    21  ## Consequences
    22  
    23  Maintaining the full context within a linked list does use more memory and some operations on it are less efficient than they could be if we one-shotted the compose.  This is a decent tradeoff however as most import chains won't be longer than 4 or 5 elements in practice and these structs and operations are relatively small.