# csv2journal Vision ## Purpose `csv2journal` converts financial transactions from CSV files into journals that can be read by [hledger](https://hledger.org/). It is intended to improve the rule-authoring and regression-checking experience of hledger's CSV import workflow without attempting to replace hledger itself. The project addresses three related problems: 1. Complex classifications are difficult to express when matching is limited to a flat combination of regular expressions. 2. Order-dependent, first-match-wins rules can hide overlaps and make the effect of changing a rule difficult to understand. 3. Defining rules for a new CSV requires a manual loop across several external tools, with no integrated view of unmatched, ambiguous, or historically changed rows. ## Operating Context `csv2journal` is one component of a larger, version-controlled accounting project. A project manifest selects one recursively scanned input root, one import profile, and that profile's rules file. Within the input root, `example.csv` is paired with the colocated `example.csv.journal`. The sole CSV without such a journal is the current import; the pairs are approved history. One invocation checks or converts that current CSV, or starts an interactive session for its rules. The larger project keeps the CSVs and generated journals and combines those journals into the complete journal used for reporting with hledger. A generated journal is reviewed by the user before it is accepted into version control. Once accepted, it is treated as an approved historical record. `csv2journal` does not manage the complete journal, commit files to version control, or correct approved historical journals. ## Product Vision The project shall provide a deterministic converter and an integrated, interactive rule-authoring environment. CSV parsing and profile-level transaction mappings shall be described by the import profile. The profile shall own an order-independent set of individually named classification rules. Rules shall support string, exact-decimal, and regular-expression predicates combined with nested boolean logic. The profile and exactly one matching rule shall jointly determine the journal transaction produced from a CSV row. The interactive environment shall let users inspect source rows, edit the rules through structured controls, and see matching and generated-output changes without leaving the application. It shall provide filters for unmatched and multiply matched rows and shall show whether candidate changes would alter approved historical output. Project and profile settings remain file-authored rather than interactive in milestone one. The same validation shall be available non-interactively so conversions can be checked from scripts and continuous-integration environments. ## Core Principles ### Unambiguous classification Rule order shall never resolve classification. Every transaction row must match exactly one rule before a journal can be finalized. Zero matches and multiple matches are explicit errors rather than conditions that produce a best-effort result. ### Historical safety Current profile settings and rules must continue to reproduce the approved journal represented by every historical CSV/journal pair. Comparison shall be based on the supported journal structure rather than incidental formatting. There is no in-application mechanism for accepting a historical semantic difference. Approved journals are immutable to `csv2journal`. If an approved journal is incorrect, the user must correct and review it outside this project. The corrected file then becomes the approved historical record against which later conversions are checked. ### Snapshot consistency Each operation shall evaluate immutable, read-once snapshots of the relevant project files. A result must not silently combine file contents observed at different times during one operation or interactive session. ### Safe finalization Failed validation shall not write a partial journal to the filesystem. A successful conversion shall create its output atomically and shall never overwrite an existing filesystem object. ### Inspectable configuration Project, profile, and rule configuration shall be stored in human-readable YAML files suitable for version control. Interactive rule edits remain in memory until explicitly saved. Draft rules may be saved before their behavior is complete; saving a draft is distinct from successfully checking or finalizing a conversion. ### Pragmatic hledger integration The project shall implement only the CSV conversion and journal syntax needed by its supported workflows. It shall produce valid hledger 1.52.3 journal data, but feature parity with hledger's CSV importer or complete journal parser is not a goal. Runtime operation shall not depend on invoking hledger. ## Goals The project shall: - Convert one CSV input into one deterministic hledger journal output. - Support one reusable import profile for the input root's CSV layout and locale conventions. - Support named, order-independent rules with string, exact-decimal, and regular-expression predicates composed with nested `and`, `or`, and `not` expressions. - Diagnose the matching status of every transaction row that can be evaluated. - Generate a simple balanced transaction from every valid, unambiguously classified data row. - Validate candidate output against every approved historical pair under the input root. - Provide `check`, `convert`, and `interactive` command-line operations. - Provide a local web interface for editing rules and inspecting their current and historical effects. - Fit naturally into a larger, version-controlled accounting project without privately copying its source or output files. ## Non-Goals The following are not goals of milestone one: - Replacing hledger as the accounting and reporting engine. - Managing, stitching together, or committing the larger project's complete journal. - Modifying or approving changes to historical journals. - Achieving feature parity with hledger's CSV importer or journal language. - Resolving ambiguous rules through declaration order, priorities, or fallback behavior. - Supporting multiple profiles or input roots in one project manifest. - Editing the project manifest or profile settings through the web interface. - Acting as a hosted or multi-user financial application. - Providing authentication or transport encryption for the interactive server. - Owning private snapshots of CSV inputs or journal outputs as a history store. ## Technical Constraints - The implementation shall use Zig 0.17.0 or a compatible later 0.17 release. - The project shall be packaged as a Nix flake. - CSV parsing, YAML parsing, and regular expressions shall use the project-pinned dependencies. - Interactive rule authoring shall be provided through a web server started by the CLI. - The server shall default to `127.0.0.1:8080`; network exposure beyond loopback shall be the user's responsibility. ## Requirements Milestone-specific, testable behavior is defined in [REQUIREMENTS.md](REQUIREMENTS.md). That document may refine workflows and supported data shapes without weakening the principles established here.