Merge pull request #92 from stacknil/stacknil/parser-handler-registry

refactor(parser): add handler registry

Author: stacknil

CHANGELOG.md

@@ -17,6 +17,9 @@ All notable user-visible changes should be recorded here.
 
 ### Changed
 
+- Refactored parser internals into timestamp, source-envelope, program-dispatch,
+  program-handler, and failure-classifier modules behind the unchanged
+  `AuthLogParser` interface.
 - Detector rules now emit separate findings for time-separated detection
   episodes within the same rule subject instead of collapsing each subject to a
   single best window.

CMakeLists.txt

@@ -9,6 +9,15 @@ set(CMAKE_CXX_EXTENSIONS OFF)
 add_library(loglens_lib
     src/config.cpp
     src/parser.cpp
+    src/parser/failure_classifier.cpp
+    src/parser/pam_handlers.cpp
+    src/parser/program_dispatch.cpp
+    src/parser/source_envelope_parser.cpp
+    src/parser/sshd_handlers.cpp
+    src/parser/su_handlers.cpp
+    src/parser/sudo_handlers.cpp
+    src/parser/text_utils.cpp
+    src/parser/timestamp_parser.cpp
     src/signal.cpp
     src/detector.cpp
     src/report.cpp

docs/parser-conformance-matrix.md

@@ -1,7 +1,8 @@
 # Parser Conformance Matrix
 
 This matrix documents the parser behavior that LogLens currently treats as
-reviewable contract surface. It is derived from `src/parser.cpp`,
+reviewable contract surface. It is derived from `src/parser.cpp`, the internal
+`src/parser/` handler registry,
 `src/event.hpp`, `tests/test_parser.cpp`, and the checked-in parser fixture
 corpus.
 

docs/parser-contract.md

@@ -47,6 +47,24 @@ Recognized success or audit families include accepted password, accepted publick
 
 This is the main trust boundary: unsupported input should remain inspectable, even when it does not produce a finding.
 
+## Internal parsing pipeline
+
+`AuthLogParser` remains the single public parser interface. Its implementation
+is split into internal modules with one-way flow:
+
+1. `timestamp_parser` parses the selected input mode's timestamp and hostname.
+2. `source_envelope_parser` extracts the program tag, optional pid, and raw message.
+3. `program_dispatch` selects a registered `sshd`, PAM, `sudo`, or `su` handler.
+4. The selected handler either emits a normalized event or returns a structured
+   failure result.
+5. `failure_classifier` assigns malformed-source and unsupported-pattern
+   telemetry without turning unsupported evidence into an event.
+
+All registered program handlers return the same internal result shape:
+`matched`, optional `event`, `failure_category`, and `reason`. The registry and
+handler modules are implementation details; callers continue to depend only on
+`AuthLogParser`, `Event`, and the parser telemetry contract.
+
 Parser failure categories are intentionally coarser than unknown-pattern
 buckets: