@zalom/plastic 2.0.0-alpha.2 → 2.0.0-alpha.20

package/scripts/lib/roadmap_savepoint.rb

@@ -3,6 +3,7 @@
 
 require "time"
 require "fileutils"
+require_relative "guarded_append"
 
 # RoadmapSavepoint - the roadmap's machine counterpart to its human `## Log` (intent 134).
 #
@@ -66,6 +67,25 @@ module RoadmapSavepoint
     File.read(ledger_path).each_line.filter_map { |line| parse_pair(line) }
   end
 
+  # Public (intent 331c): a roadmap's own ledger, parsed into `[Time, event, detail]` triples in
+  # file order - so a screen reader never re-derives the "<iso>  <event>  <detail>" line shape.
+  # `roadmap_path` is the roadmap `.md` file, never the `.savepoint.md` sibling directly (mirrors
+  # `ledger_path_for`'s own convention). No paired ledger file -> `[]`, never an invented event.
+  def ledger_entries(roadmap_path)
+    ledger_path = ledger_path_for(roadmap_path)
+    return [] unless File.exist?(ledger_path)
+
+    File.readlines(ledger_path).filter_map do |line|
+      parts = line.strip.split(/\s{2,}/, 3)
+      next nil unless parts.length == 3
+      begin
+        [Time.iso8601(parts[0]), parts[1], parts[2]]
+      rescue ArgumentError
+        nil
+      end
+    end
+  end
+
   def parse_pair(line)
     parts = line.strip.split(/\s{2,}/)
     parts.length >= 3 ? [parts[1], parts[2]] : nil
@@ -76,17 +96,37 @@ module RoadmapSavepoint
   # recorded (no-op). Creates the paired ledger file (and its directory) lazily. Raises
   # ArgumentError when `event` is outside the controlled vocabulary. Returns true when a line
   # was written, false on a dedup no-op.
-  def append(roadmap_path, event, detail, now: Time.now)
+  #
+  # Intent 335 (spec D14): the dedup check moves INSIDE one GuardedAppend hold, which makes
+  # "is this pair already recorded" and "append it" atomic against a second writer without
+  # changing what this method returns. `strict: false` keeps this ledger's existing
+  # flock-less-filesystem fallback exactly as it was before the guard existed (spec D12a): a
+  # single O_APPEND write still lands whole there, so this ledger never refuses on such a
+  # filesystem, unlike a strict transition append elsewhere in 335. `guard:` is the sole thing
+  # this module takes from 335 (spec D14: "RoadmapSavepoint takes GuardedAppend and nothing else");
+  # `flock:`/`sleeper:` pass straight through as GuardedAppend test seams, never read from an
+  # environment variable. The directory is created BEFORE the guard is called (spec D12b): the
+  # guard's own File.open would raise Errno::ENOENT on a missing parent, which must propagate as
+  # itself rather than be mistaken for lock contention.
+  def append(roadmap_path, event, detail, now: Time.now, guard: GuardedAppend, **guard_opts)
     unless EVENTS.include?(event)
       raise ArgumentError, "event must be one of #{EVENTS.join(', ')}, got #{event.inspect}"
     end
 
     ledger_path = ledger_path_for(roadmap_path)
-    return false if recorded_pairs(ledger_path).include?([event, detail])
-
     FileUtils.mkdir_p(File.dirname(ledger_path))
-    File.open(ledger_path, "a") { |io| io.write(format_line(now, event, detail)) }
-    true
+
+    pair = [event, detail]
+    written = false
+    guard.call(ledger_path, strict: false, **guard_opts) do |content|
+      if content.each_line.filter_map { |line| parse_pair(line) }.include?(pair)
+        nil
+      else
+        written = true
+        format_line(now, event, detail)
+      end
+    end
+    written
   end
 
   def format_line(time, event, detail)
@@ -141,11 +181,13 @@ module RoadmapSavepoint
   end
   private_class_method :parse_log_time
 
+  # Public (intent 331c): the Log table on a roadmap's `delivered` screen classifies every
+  # `## Log` line through this same keyword vocabulary, so a screen reader never grows a second
+  # copy of KEYWORD_TABLE.
   def classify_event(text)
     hit = KEYWORD_TABLE.find { |regex, _event| text =~ regex }
     hit && hit[1]
   end
-  private_class_method :classify_event
 
   WAVE_ENTRY = /\A-\s*\[([ xX])\]\s+(\S+)\s+.+—\s*(\S+)\s*\z/.freeze
 
@@ -217,13 +259,21 @@ module RoadmapSavepoint
   # already calling `ledger_path_for`), so this is the smaller diff than a new shared module.
   # Raises MissingGroupingHeading, naming the offending path, when neither heading is present.
   def grouping_section_body(text, path: nil)
-    GROUPING_HEADINGS.each do |heading|
-      m = text.match(/^##\s+#{Regexp.escape(heading)}\s*$(.*?)(?=^##\s|\z)/m)
-      return m[1] if m
+    heading = grouping_heading(text)
+    unless heading
+      raise MissingGroupingHeading,
+            "#{path || '(unknown roadmap file)'}: found neither '## Batches' (canonical) nor " \
+            "'## Waves' (legacy) grouping heading"
     end
-    raise MissingGroupingHeading,
-          "#{path || '(unknown roadmap file)'}: found neither '## Batches' (canonical) nor " \
-          "'## Waves' (legacy) grouping heading"
+    text.match(/^##\s+#{Regexp.escape(heading)}\s*$(.*?)(?=^##\s|\z)/m)[1]
+  end
+
+  # Public (intent 331c): "Batches" or "Waves", whichever grouping heading `text` carries - the
+  # one owner of that label so a screen's own field row (and its entries table's column header)
+  # never hand-picks between them a second way. nil when neither heading is present (mirrors
+  # grouping_section_body's own detection, one call site cheaper than two).
+  def grouping_heading(text)
+    GROUPING_HEADINGS.find { |heading| text.match?(/^##\s+#{Regexp.escape(heading)}\s*$/) }
   end
 
   # Stable dedup on the `(event, detail)` pair, keeping the first occurrence in the given