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

package/scripts/lib/roadmap_graph.rb

@@ -0,0 +1,210 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require_relative "graph_file"
+require_relative "graph_edges"
+require_relative "ready_set"
+require_relative "roadmap_savepoint"
+
+# RoadmapGraph (intent 337, n1): reads one roadmap file into the same shape
+# the node scope already uses - entries with their INDEX-reconciled status,
+# the edge map from "## Graph", the cycle path when one exists, the
+# topological batches, the critical paths, and the ready set. Edges are
+# parsed by GraphEdges; batches, critical paths, and downstream hops come
+# from ReadySet (327 D1, C1: the one parser, the one topological sort - a
+# local copy of either here is exactly the drift 327 forbids). This module
+# writes no file and reads no clock or environment variable (row 1.14);
+# every fact is either a value passed in or read once from the two paths
+# `analyze` is given.
+module RoadmapGraph
+  module_function
+
+  ENTRY = /\A-\s*\[([ xX])\]\s+(\S+)\s+(.*?)[—-]\s*(queued|delivering|delivered|abandoned|blocked)\b/.freeze
+  WAVE_HEADING = /\A###\s+(.+?)\s*\z/.freeze
+
+  INDEX_TAGS = { "Completed" => "delivered", "Abandoned" => "abandoned", "Active" => :active, "Future" => "queued" }.freeze
+
+  # analyze(roadmap_path, index_path:) -> a Result hash. Never raises across
+  # the boundary: a missing ## Graph section, a missing grouping heading, a
+  # cyclic graph, or an invalid byte in either file all become a named
+  # `reason` or an empty result, never an exception (rows 1.8, 1.9, 1.13).
+  def analyze(roadmap_path, index_path: nil)
+    text = read_utf8(roadmap_path)
+
+    graph_section = GraphFile.section_body(text, "## Graph")
+    unless graph_section
+      return result(has_graph: false, reason: "no ## Graph section in #{roadmap_path}")
+    end
+
+    parsed_edges = GraphEdges.parse(GraphFile.strip_fenced_blocks(graph_section))
+
+    entries_by_id, order = begin
+      parse_entries(text, roadmap_path)
+    rescue RoadmapSavepoint::MissingGroupingHeading => e
+      return result(has_graph: true, reason: e.message)
+    end
+
+    index_map = load_index(index_path)
+    entries_by_id.each_value { |e| e[:status] = reconcile_status(index_map[e[:id]], e[:raw_status]) }
+
+    declared_and_targeted = parsed_edges[:nodes]
+    entry_ids = order.dup
+
+    # 1.6: an entry the graph never named (not declared, not targeted) is
+    # folded in as a root, so a partly migrated roadmap never silently
+    # drops real work from the batches.
+    edges = parsed_edges[:edges].dup
+    entry_ids.each do |id|
+      next if declared_and_targeted.include?(id)
+
+      edges[id] = []
+      entries_by_id[id][:in_graph] = false
+    end
+    entry_ids.each do |id|
+      entries_by_id[id][:in_graph] = true if declared_and_targeted.include?(id) && entries_by_id[id][:in_graph].nil?
+    end
+
+    # 1.7: a graph id with no batch entry is named in `dangling`, never
+    # invented as a fake entry with no title.
+    dangling = declared_and_targeted.reject { |id| entries_by_id.key?(id) }
+
+    cyc = GraphEdges.cycle(edges)
+    if cyc
+      return result(has_graph: true, entries: entries_by_id, edges: edges, dangling: dangling,
+                     cycle: cyc, errors: parsed_edges[:errors])
+    end
+
+    batch_result = ReadySet.batches(edges)
+    batches = batch_result[:ok] ? order_batches(batch_result[:batches], order) : []
+    path_result = ReadySet.critical_paths(edges)
+
+    status_map = entries_by_id.each_with_object({}) { |(id, e), h| h[id] = e[:status] }
+    dead_ends = entry_ids.select do |id|
+      entries_by_id[id][:status] != "delivered" && ReadySet.dead_end?(id, edges, status_map)
+    end
+
+    ready = entry_ids.select do |id|
+      entries_by_id[id][:status] == "queued" &&
+        (edges[id] || []).all? { |t| status_map[t] == "delivered" }
+    end
+
+    result(
+      has_graph: true,
+      entries: entries_by_id,
+      edges: edges,
+      dangling: dangling,
+      cycle: nil,
+      batches: batches,
+      batches_error: batch_result[:ok] ? nil : batch_result[:error],
+      critical_paths: path_result[:ok] ? path_result : nil,
+      dead_ends: dead_ends,
+      ready: ready,
+      errors: parsed_edges[:errors]
+    )
+  end
+
+  # --- shared building blocks other callers (RoadmapQueue, n9) reuse --------
+
+  # The one place that knows how a roadmap's own "## Graph" section is read:
+  # an exact heading (GraphFile), fenced examples stripped, and an edgeless
+  # section treated the same as no section at all. Returns GraphEdges.parse's
+  # own Result hash, or nil.
+  def parse_graph_section(text)
+    section = GraphFile.section_body(text, "## Graph")
+    return nil if section.nil?
+
+    parsed = GraphEdges.parse(GraphFile.strip_fenced_blocks(section))
+    return nil if parsed[:nodes].empty?
+
+    parsed
+  end
+
+  # ReadySet.batches's own topological layers (the one sort, D1), reordered
+  # WITHIN each layer to match `order` - typically the roadmap file's own
+  # entry-encounter order (row 1.16/9.8). A computed batch names which layer
+  # an id is in; it must never silently become a ranking decision by
+  # defaulting to a lexical sort of ids that happen to share a layer.
+  def order_batches(batches, order)
+    rank = {}
+    order.each_with_index { |id, i| rank[id] = i }
+    batches.map { |layer| layer.sort_by { |id| [rank[id] || order.length, id] } }
+  end
+
+  # --- entries -----------------------------------------------------------------
+
+  def parse_entries(text, roadmap_path)
+    body = RoadmapSavepoint.grouping_section_body(text, path: roadmap_path)
+    entries = {}
+    order = []
+    body.each_line do |line|
+      stripped = line.chomp.strip
+      m = stripped.match(ENTRY)
+      next unless m
+
+      id = m[2]
+      next if entries.key?(id)
+
+      entries[id] = { id: id, title: m[3].strip, raw_status: m[4].downcase, in_graph: nil }
+      order << id
+    end
+    [entries, order]
+  end
+
+  def reconcile_status(tag, raw_status)
+    case tag
+    when "delivered" then "delivered"
+    when "abandoned" then "abandoned"
+    when "queued" then "queued"
+    when :active then raw_status == "delivered" ? "delivering" : raw_status
+    else raw_status
+    end
+  end
+
+  def load_index(index_path)
+    map = {}
+    return map unless index_path && File.exist?(index_path)
+
+    text = read_utf8(index_path)
+    INDEX_TAGS.each do |heading, tag|
+      section_body(text, heading).each_line do |line|
+        stripped = line.strip
+        next unless stripped.start_with?("- [")
+
+        m = stripped.match(/\A-\s*\[(\S+)\s/)
+        map[m[1]] = tag if m
+      end
+    end
+    map
+  end
+
+  def section_body(text, heading)
+    m = text.match(/^##\s+#{Regexp.escape(heading)}\s*$(.*?)(?=^##\s|\z)/m)
+    m ? m[1] : ""
+  end
+
+  # 1.13: an invalid byte in either file is scrubbed, never raised across
+  # the boundary.
+  def read_utf8(path)
+    text = File.read(path)
+    text.force_encoding(Encoding::UTF_8)
+    text.valid_encoding? ? text : text.scrub("")
+  end
+
+  def result(has_graph:, reason: nil, entries: {}, edges: {}, dangling: [], cycle: nil,
+             batches: [], batches_error: nil, critical_paths: nil, dead_ends: [], ready: [], errors: [])
+    {
+      has_graph: has_graph,
+      reason: reason,
+      entries: entries,
+      edges: edges,
+      dangling: dangling,
+      cycle: cycle,
+      batches: batches,
+      batches_error: batches_error,
+      critical_paths: critical_paths,
+      dead_ends: dead_ends,
+      ready: ready,
+      errors: errors,
+    }
+  end
+end

package/scripts/lib/roadmap_migration.rb

@@ -0,0 +1,95 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require_relative "roadmap_graph"
+require_relative "roadmap_render"
+require_relative "roadmap_savepoint"
+require_relative "graph_edges"
+require_relative "graph_file"
+require_relative "atomic_write"
+
+# RoadmapMigration (intent 337, n4): reads a graphless roadmap's existing
+# batch order and returns the conservative edge set that preserves it -
+# every entry of batch N needs every entry of batch N-1, batch 1 needs
+# nothing. Never overwrites a roadmap that already carries a "## Graph" (or
+# graph-like, row 4.15) heading: the owner's hand-edited edges are the only
+# place a cross-intent edge lives, and a derived guess must never replace
+# them. Block splitting and entry-id extraction are the same surgical
+# parser RoadmapRender uses (n3) - never a second one.
+module RoadmapMigration
+  module_function
+
+  GRAPH_HEADING_RE = /\A##\s+Graph\b/.freeze
+
+  # {ok:, skipped:, edges:, reason:}. Computes only; writes nothing.
+  def derive(path, index_path: nil)
+    text = File.read(path)
+
+    if text.each_line.any? { |l| l.strip.match?(GRAPH_HEADING_RE) }
+      return { ok: false, skipped: true, edges: {}, reason: "already carries a ## Graph (or graph-like) heading, left untouched" }
+    end
+
+    begin
+      body = RoadmapSavepoint.grouping_section_body(text, path: path)
+    rescue RoadmapSavepoint::MissingGroupingHeading => e
+      return { ok: false, skipped: false, edges: {}, reason: e.message }
+    end
+
+    _preamble, blocks = RoadmapRender.split_into_blocks(body)
+    batch_ids = blocks.map { |b| b[:lines].filter_map { |l| RoadmapRender.entry_id(l) } }
+
+    entries_by_id = entry_statuses(text, path, index_path)
+
+    edges = {}
+    batch_ids.each_with_index do |ids, i|
+      prev_ids = i.zero? ? [] : batch_ids[i - 1].reject { |id| abandoned?(entries_by_id, id) }
+      # An id repeated across two batches (row 4.16) must never need itself:
+      # exclude it from its own prev_ids before assigning.
+      ids.each { |id| edges[id] = prev_ids.reject { |p| p == id } }
+    end
+
+    cyc = GraphEdges.cycle(edges)
+    return { ok: false, skipped: false, edges: {}, reason: "derived graph is cyclic: #{cyc.join(' > ')}" } if cyc
+
+    { ok: true, skipped: false, edges: edges, reason: nil }
+  end
+
+  # derive + render "## Graph" through AtomicWrite. A skip (row 4.3) or a
+  # refusal (cyclic, row 4.5) writes nothing and reports why.
+  def write(path, renamer: File.method(:rename), dry_run: false, index_path: nil)
+    result = derive(path, index_path: index_path)
+    return { ok: result[:ok], written: false, content: nil, skipped: result[:skipped], reason: result[:reason] } unless result[:ok]
+
+    graph_text = render_edges(result[:edges])
+    original = File.read(path)
+    content = GraphFile.replace_or_append_section(original, "## Graph", graph_text)
+
+    if dry_run
+      { ok: true, written: false, content: content, skipped: false, reason: nil }
+    else
+      AtomicWrite.write(path, content, renamer: renamer)
+      { ok: true, written: true, content: content, skipped: false, reason: nil }
+    end
+  end
+
+  def render_edges(edges)
+    lines = edges.map do |id, needs|
+      "- #{id} needs #{needs.empty? ? 'nothing' : needs.join(' ')}\n"
+    end
+    lines.join
+  end
+
+  def entry_statuses(text, path, index_path)
+    entries_by_id, = RoadmapGraph.parse_entries(text, path)
+    resolved_index = index_path || RoadmapRender.default_index_path(path)
+    index_map = RoadmapGraph.load_index(resolved_index)
+    entries_by_id.each_value { |e| e[:status] = RoadmapGraph.reconcile_status(index_map[e[:id]], e[:raw_status]) }
+    entries_by_id
+  rescue RoadmapSavepoint::MissingGroupingHeading
+    {}
+  end
+
+  def abandoned?(entries_by_id, id)
+    entries_by_id[id] && entries_by_id[id][:status] == "abandoned"
+  end
+end

package/scripts/lib/roadmap_queue.rb

@@ -6,6 +6,8 @@ require "json"
 require_relative "roadmap_savepoint"
 require_relative "graph_file"
 require_relative "graph_edges"
+require_relative "ready_set"
+require_relative "roadmap_graph"
 
 # FileOrderRanker - the default value-ordering strategy: today's roadmap file order,
 # unchanged. This is the intent-173 ranking-swap seam (sibling to the 147 DB-swap seam): a
@@ -143,27 +145,17 @@ class RoadmapQueue
     {
       slug: File.basename(path, ".md"), path: path,
       waves: parse_waves(RoadmapSavepoint.grouping_section_body(text, path: path)),
-      graph_edges: parse_roadmap_graph(text),
+      # D15: an exact "## Graph" heading line only, never a prefix - a live
+      # roadmap can carry "## Graph (2026-09-01, superseded by ...)". A
+      # section that yields no real edge lines is treated the same as no
+      # section at all: the fallback to wave order, both silent (D15).
+      # Fence-aware (D18). Intent 337 n9: reads through the shared model
+      # (RoadmapGraph.parse_graph_section) rather than a second local
+      # parser, so this heading/fence/emptiness rule is made in one place.
+      graph_edges: RoadmapGraph.parse_graph_section(text),
     }
   end
 
-  # D15: an exact "## Graph" heading line only, never a prefix - a live
-  # roadmap can carry "## Graph (2026-09-01, superseded by ...)", which
-  # GraphFile.section_body already treats as a non-match because it locates
-  # a section by an exact stripped-line comparison. A section that yields no
-  # real edge lines (GraphEdges.parse finds zero nodes) is treated the same
-  # as no section at all: the fallback to wave order, both silent (D15).
-  # Fence-aware (D18): a fenced example edge line is never read as real.
-  def parse_roadmap_graph(text)
-    section = GraphFile.section_body(text, "## Graph")
-    return nil if section.nil?
-
-    parsed = GraphEdges.parse(GraphFile.strip_fenced_blocks(section))
-    return nil if parsed[:nodes].empty?
-
-    parsed
-  end
-
   def parse_waves(waves_body)
     waves = []
     current = nil
@@ -329,7 +321,13 @@ class RoadmapQueue
 
     (id_to_entry.keys - all_graph_nodes(edges)).each { |id| edges[id] = [] }
 
-    topological_layers(edges).each do |layer|
+    # Intent 337 n9: the one topological sort (327 D1) is ReadySet.batches;
+    # RoadmapGraph.order_batches only reorders WITHIN a layer to match the
+    # roadmap file's own entry order (row 9.8), never a second sort.
+    batch_result = ReadySet.batches(edges)
+    layers = batch_result[:ok] ? RoadmapGraph.order_batches(batch_result[:batches], id_to_entry.keys) : []
+
+    layers.each do |layer|
       layer_ids = layer.select { |id| id_to_entry.key?(id) }
       next if layer_ids.empty?
 
@@ -356,29 +354,6 @@ class RoadmapQueue
     nil
   end
 
-  # Topological layers of `edges` ({id => [needs...]}): layer one is every
-  # id needing nothing, layer k is every id all of whose needs sit in layers
-  # below k. Never called on a cyclic graph (the caller checks first), so no
-  # cycle guard is needed here.
-  def topological_layers(edges)
-    nodes = edges.keys.dup
-    edges.each_value { |targets| (targets || []).each { |t| nodes << t unless nodes.include?(t) } }
-
-    layer = {}
-    assign = nil
-    assign = lambda do |node|
-      next layer[node] if layer.key?(node)
-
-      needs = edges[node] || []
-      layer[node] = needs.empty? ? 1 : 1 + needs.map { |t| assign.call(t) }.max
-    end
-    nodes.each { |n| assign.call(n) }
-
-    grouped = Hash.new { |h, k| h[k] = [] }
-    layer.each { |n, l| grouped[l] << n }
-    grouped.keys.sort.map { |l| grouped[l].sort }
-  end
-
   def blocked_for(candidate)
     explicit = candidate[:waves].flat_map do |wave|
       wave[:entries].select { |e| e[:status] == "blocked" }.map do |e|

package/scripts/lib/roadmap_render.rb

@@ -0,0 +1,150 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require_relative "roadmap_graph"
+require_relative "roadmap_savepoint"
+require_relative "graph_file"
+require_relative "graph_tree"
+require_relative "atomic_write"
+
+# RoadmapRender (intent 337, n3): renders "## Tree" and the roadmap's own
+# grouping section (## Batches, or legacy ## Waves, owner ruling 145 -
+# never renamed) from the RoadmapGraph model and writes both back through
+# AtomicWrite, replacing exactly those two sections and leaving every other
+# byte of the file alone.
+#
+# The regroup is surgical, never a rebuild from parsed fields (327's own
+# lesson, folded at the 2026-09-10 plan review, rows 3.2/3.13/3.14): only
+# entry lines RoadmapGraph itself recognized (the canonical checkbox +
+# status grammar) ever move. A line the grammar cannot parse, and any prose
+# a human wrote between batch headings, is untouched OUTPUT text - it is
+# never even looked at, so it can never be lost. An id that already sits in
+# its computed batch's heading block is never rewritten; only an id that
+# needs to move is removed from its old block and appended, verbatim, to
+# its new one. This is what makes a no-op render byte-identical (row 3.9)
+# and a genuinely moved entry keep its own exact text (row 3.2).
+module RoadmapRender
+  module_function
+
+  TREE_WIDTH = 100
+
+  def write(path, renamer: File.method(:rename), dry_run: false, index_path: nil)
+    original = File.read(path)
+    resolved_index = index_path || default_index_path(path)
+
+    analysis = RoadmapGraph.analyze(path, index_path: resolved_index)
+    return refusal(analysis[:reason]) if analysis[:reason]
+    return refusal("cyclic graph, refusing to render: #{analysis[:cycle].join(' > ')}") if analysis[:cycle]
+
+    tree_result = render_tree(analysis)
+    return refusal(tree_result[:error]) unless tree_result[:ok]
+
+    content = GraphFile.replace_or_append_section(original, "## Tree", tree_result[:text])
+
+    heading = RoadmapSavepoint.grouping_heading(original)
+    return refusal("neither ## Batches nor ## Waves grouping heading found") unless heading
+
+    heading_text = "## #{heading}"
+    original_body = RoadmapSavepoint.grouping_section_body(original, path: path)
+    regrouped = regroup(original_body, analysis)
+    content = GraphFile.replace_or_append_section(content, heading_text, regrouped)
+
+    if dry_run
+      { ok: true, content: content, written: false, error: nil }
+    else
+      AtomicWrite.write(path, content, renamer: renamer)
+      { ok: true, content: content, written: true, error: nil }
+    end
+  end
+
+  def refusal(reason)
+    { ok: false, content: nil, written: false, error: reason }
+  end
+
+  def default_index_path(roadmap_path)
+    File.join(File.dirname(File.dirname(roadmap_path)), "INDEX.md")
+  end
+
+  def render_tree(analysis)
+    labels = analysis[:entries].each_with_object({}) { |(id, e), h| h[id] = e[:title] }
+    marks = {
+      critical_path: analysis[:critical_paths] ? (analysis[:critical_paths][:critical_path] || []) : [],
+      ready: analysis[:ready] || [],
+    }
+    GraphTree.render(edges: analysis[:edges], labels: labels, marks: marks, width: TREE_WIDTH)
+  end
+
+  # --- the surgical regroup ------------------------------------------------------
+
+  ENTRY_ID_RE = /\A-\s*\[([ xX])\]\s+(\S+)\b/.freeze
+  HEADING_RE = /\A###\s+/.freeze
+
+  def regroup(body, analysis)
+    preamble, blocks = split_into_blocks(body)
+
+    real_batches = (analysis[:batches] || []).map { |layer| layer & analysis[:entries].keys }
+    original_line_for = build_original_line_index(blocks)
+
+    total = [blocks.length, real_batches.length].max
+    rendered_blocks = (0...total).map do |i|
+      block = blocks[i]
+      computed_ids = real_batches[i] || []
+
+      existing_ids = block ? block[:lines].filter_map { |l| entry_id(l) } : []
+      removed = existing_ids - computed_ids
+      added = computed_ids - existing_ids
+
+      heading_line = block ? block[:heading] : "### Batch #{i + 1}\n"
+      lines = block ? block[:lines].reject { |l| removed.include?(entry_id(l)) } : []
+      lines += added.filter_map { |id| original_line_for[id] }
+
+      heading_line + lines.join
+    end
+
+    # GraphFile.replace_or_append_section always adds its own single blank
+    # line before a non-empty tail; a body that already ends in blank lines
+    # (round-tripped from a previous render) would otherwise grow by one
+    # blank line on every render (row 3.9's byte-identical requirement).
+    (preamble.join + rendered_blocks.join).rstrip + "\n"
+  end
+
+  def entry_id(line)
+    m = line.match(ENTRY_ID_RE)
+    m && m[2]
+  end
+
+  def build_original_line_index(blocks)
+    index = {}
+    blocks.each do |block|
+      block[:lines].each do |line|
+        id = entry_id(line)
+        index[id] ||= line if id
+      end
+    end
+    index
+  end
+
+  # [preamble_lines, blocks] - blocks is [{heading:, lines: []}, ...] in file
+  # order. Every original byte is accounted for: it lives either in the
+  # preamble (before the first "### " heading) or in exactly one block's
+  # heading/lines.
+  def split_into_blocks(body)
+    preamble = []
+    blocks = []
+    current = nil
+
+    body.each_line do |line|
+      if line.match?(HEADING_RE)
+        blocks << current if current
+        current = { heading: line, lines: [] }
+      elsif current
+        current[:lines] << line
+      else
+        preamble << line
+      end
+    end
+    blocks << current if current
+
+    [preamble, blocks]
+  end
+end