pashage

Yet Another Opinionated Re-engineering of the Unix Password Store
git clone https://git.instinctive.eu/pashage.git
Log | Files | Refs | README | LICENSE

ARCHITECTURE.md (2090B)

      1 # pashage Architecture and Design Choices
      2 
      3 ## Source Overview
      4 
      5 The following files are present in `src/` directory:
      6 
      7  - `pashage.sh` defines shell functions, providing most of the functionality,
      8  - `platform-*.sh` defines platform-specific helper shell functions,
      9  - `run.sh` prepares the environment and calls the relevant function.
     10 
     11 Note that `run.sh` detects dynamically the platform, like `pass` and
     12 `passage`, but the author intended `pashage` to be the platform-specific
     13 amalgamation of the relevant sources.
     14 
     15 The shell functions are organized in prefix-designated layers, from the
     16 highest to the lowest:
     17 
     18  - `cmd_`-prefixed functions implement the commands, by parsing arguments
     19 and calling the relevant actions;
     20  - `do_`-prefixed functions implemenmt the actions, which are the core logic
     21 of the program;
     22  - `scm_`-prefixed functions are an abstraction over git and some file-system
     23 operations on the checkout;
     24  - `platform_`-prefixed function are an abstraction of platform-specific
     25 operations;
     26  - prefixless internal helper functions are used throughout the program.
     27 
     28 ## Test Overview
     29 
     30 Best practices are enforced using [shellcheck](https://www.shellcheck.net/),
     31 and tests are performed using [shellspec](https://shellspec.info/)
     32 in sandbox mode.
     33 
     34 The following test sets can be found in `spec/` directory:
     35 
     36 - `internal_spec.sh` tests internal helper functions in isolation;
     37 - `action_spec.sh` tests action functions in isolation, mocking everything;
     38 - `usage_spec.sh` tests command functions in isolation, mocking everything;
     39 - `scm_spec.sh` tests SCM functions in isolation, using the real git
     40   and filesystem;
     41 - `pass_spec.sh` tests `pass`-like and `passage`-like behavior of
     42   the whole script;
     43 - `pashage_extra_spec.sh` tests integration, calling command functions
     44   with minimal mocks, in complement with `pass_spec.sh`.
     45 
     46 Platform functions are not tested, because the platform adherence make it
     47 too difficult to test it automatically.
     48 
     49 `age` and `gpg` are always mocked, to make the tests reproducible and easier
     50 to design, and to make the failures easier to investigate.