|
|
|
|
@ -0,0 +1,218 @@
|
|
|
|
|
#!/usr/bin/env tclsh |
|
|
|
|
# goals_lint.tcl - lint the two-tier goals documentation |
|
|
|
|
# (root GOALS.md / GOALS-archive.md indexes + goals/ / goals/archive/ detail files) |
|
|
|
|
# |
|
|
|
|
# Validates the contracts declared in goals/AGENTS.md and root AGENTS.md: |
|
|
|
|
# - detail-file header grammar: '# G-<id> <title>' then a blank line, then |
|
|
|
|
# Status:/Scope:/Goal:/Acceptance: exactly once each, in order, one line each, |
|
|
|
|
# before any '## section'; no prose riding a header field |
|
|
|
|
# - Status: values are exactly one of proposed|active|abandoned|superseded or |
|
|
|
|
# 'achieved YYYY-MM-DD' |
|
|
|
|
# - active-tree detail files are not 'achieved'; archive detail files are |
|
|
|
|
# - no orphans: every goals/*.md detail file has a GOALS.md index entry and vice |
|
|
|
|
# versa; every goals/archive/*.md file has a GOALS-archive.md record and vice versa |
|
|
|
|
# - Status:/Scope: mirror lines in detail files match the owning index entry |
|
|
|
|
# |
|
|
|
|
# Plain tclsh (8.6+ or 9), no package dependencies - runnable from any checkout: |
|
|
|
|
# tclsh scriptlib/developer/goals_lint.tcl [repo-root] |
|
|
|
|
# Exit 0 when clean; exit 1 with one 'path: problem' line per finding. |
|
|
|
|
|
|
|
|
|
set root [expr {$argc >= 1 ? [lindex $argv 0] : [file dirname [file dirname [file dirname [file normalize [info script]]]]]}] |
|
|
|
|
if {![file isfile [file join $root GOALS.md]] || ![file isdir [file join $root goals]]} { |
|
|
|
|
puts stderr "goals_lint: '$root' does not look like the punkshell repo root (need GOALS.md and goals/)" |
|
|
|
|
exit 2 |
|
|
|
|
} |
|
|
|
|
|
|
|
|
|
set findings {} |
|
|
|
|
proc flag {path msg} { |
|
|
|
|
global findings |
|
|
|
|
lappend findings "$path: $msg" |
|
|
|
|
} |
|
|
|
|
|
|
|
|
|
set status_re {^(proposed|active|abandoned|superseded|achieved \d{4}-\d{2}-\d{2})$} |
|
|
|
|
|
|
|
|
|
proc read_lines {path} { |
|
|
|
|
set f [open $path r] |
|
|
|
|
fconfigure $f -encoding utf-8 |
|
|
|
|
set lines [split [read $f] \n] |
|
|
|
|
close $f |
|
|
|
|
return $lines |
|
|
|
|
} |
|
|
|
|
|
|
|
|
|
# --- parse an index file (GOALS.md or GOALS-archive.md) --------------------- |
|
|
|
|
# returns dict: id -> {status <s> title <t> scope <scope-or-empty>} |
|
|
|
|
proc parse_index {path} { |
|
|
|
|
global status_re |
|
|
|
|
set entries [dict create] |
|
|
|
|
set relpath [file tail $path] |
|
|
|
|
set curid "" |
|
|
|
|
foreach line [read_lines $path] { |
|
|
|
|
if {[regexp {^### G-(\d+) \[([^\]]*)\] (.*)$} $line -> id status title]} { |
|
|
|
|
set curid $id |
|
|
|
|
if {[dict exists $entries $id]} { |
|
|
|
|
flag $relpath "duplicate index entry G-$id" |
|
|
|
|
} |
|
|
|
|
if {![regexp $status_re $status]} { |
|
|
|
|
flag $relpath "G-$id: bad status '\[$status\]' (want proposed|active|abandoned|superseded|achieved YYYY-MM-DD)" |
|
|
|
|
} |
|
|
|
|
dict set entries $id [dict create status $status title $title scope ""] |
|
|
|
|
} elseif {[regexp {^### } $line]} { |
|
|
|
|
set curid "" |
|
|
|
|
} elseif {$curid ne "" && [regexp {^Scope: (.*)$} $line -> scope]} { |
|
|
|
|
dict set entries $curid scope $scope |
|
|
|
|
} |
|
|
|
|
} |
|
|
|
|
return $entries |
|
|
|
|
} |
|
|
|
|
|
|
|
|
|
# --- lint one detail file ---------------------------------------------------- |
|
|
|
|
# returns dict {id <id> status <s> scope <s>} (empty strings when unparseable) |
|
|
|
|
proc lint_detail {path relpath} { |
|
|
|
|
global status_re |
|
|
|
|
set lines [read_lines $path] |
|
|
|
|
set fname [file tail $path] |
|
|
|
|
set result [dict create id "" status "" scope ""] |
|
|
|
|
|
|
|
|
|
if {![regexp {^G-(\d+)-[a-z0-9-]+\.md$} $fname -> fid]} { |
|
|
|
|
flag $relpath "filename does not match G-<id>-<slug>.md" |
|
|
|
|
set fid "" |
|
|
|
|
} |
|
|
|
|
dict set result id $fid |
|
|
|
|
|
|
|
|
|
if {![regexp {^# G-(\d+) .+$} [lindex $lines 0] -> hid]} { |
|
|
|
|
flag $relpath "line 1 is not '# G-<id> <title>'" |
|
|
|
|
set hid "" |
|
|
|
|
} |
|
|
|
|
if {$fid ne "" && $hid ne "" && $hid ne $fid} { |
|
|
|
|
flag $relpath "title-line id G-$hid does not match filename id G-$fid" |
|
|
|
|
} |
|
|
|
|
if {[lindex $lines 1] ne ""} { |
|
|
|
|
flag $relpath "line 2 is not blank" |
|
|
|
|
} |
|
|
|
|
|
|
|
|
|
# header fields: Status/Scope/Goal/Acceptance exactly once each, in order, |
|
|
|
|
# before the first '## ' section |
|
|
|
|
set want {Status Scope Goal Acceptance} |
|
|
|
|
set found [dict create] |
|
|
|
|
set order {} |
|
|
|
|
set i 2 |
|
|
|
|
foreach line [lrange $lines 2 end] { |
|
|
|
|
incr i |
|
|
|
|
if {[regexp {^## } $line]} break |
|
|
|
|
if {[regexp {^(Status|Scope|Goal|Acceptance): ?(.*)$} $line -> field value]} { |
|
|
|
|
if {[dict exists $found $field]} { |
|
|
|
|
flag $relpath "duplicate header field '$field:' (line $i)" |
|
|
|
|
} else { |
|
|
|
|
dict set found $field $value |
|
|
|
|
lappend order $field |
|
|
|
|
} |
|
|
|
|
if {$value eq ""} { |
|
|
|
|
flag $relpath "empty header field '$field:' (line $i)" |
|
|
|
|
} |
|
|
|
|
} |
|
|
|
|
} |
|
|
|
|
foreach field $want { |
|
|
|
|
if {![dict exists $found $field]} { |
|
|
|
|
flag $relpath "missing header field '$field:'" |
|
|
|
|
} |
|
|
|
|
} |
|
|
|
|
if {[llength $order] == 4 && $order ne $want} { |
|
|
|
|
flag $relpath "header fields out of order ([join $order /] - want [join $want /])" |
|
|
|
|
} |
|
|
|
|
|
|
|
|
|
if {[dict exists $found Status]} { |
|
|
|
|
set status [dict get $found Status] |
|
|
|
|
dict set result status $status |
|
|
|
|
if {![regexp $status_re $status]} { |
|
|
|
|
flag $relpath "bad Status line 'Status: $status' - must be exactly proposed|active|abandoned|superseded or 'achieved YYYY-MM-DD' with no additional prose (verification evidence belongs in ## Progress / ## Notes)" |
|
|
|
|
} |
|
|
|
|
} |
|
|
|
|
if {[dict exists $found Scope]} { |
|
|
|
|
dict set result scope [dict get $found Scope] |
|
|
|
|
} |
|
|
|
|
return $result |
|
|
|
|
} |
|
|
|
|
|
|
|
|
|
# --- run ---------------------------------------------------------------------- |
|
|
|
|
set active_index [parse_index [file join $root GOALS.md]] |
|
|
|
|
set archive_index [parse_index [file join $root GOALS-archive.md]] |
|
|
|
|
|
|
|
|
|
foreach {dir index indexname achieved_expected} [list \ |
|
|
|
|
goals $active_index GOALS.md 0 \ |
|
|
|
|
[file join goals archive] $archive_index GOALS-archive.md 1] { |
|
|
|
|
set seen [dict create] |
|
|
|
|
foreach path [lsort [glob -nocomplain -directory [file join $root $dir] G-*.md]] { |
|
|
|
|
set relpath [string map {\\ /} [file join $dir [file tail $path]]] |
|
|
|
|
set info [lint_detail $path $relpath] |
|
|
|
|
set id [dict get $info id] |
|
|
|
|
if {$id eq ""} continue |
|
|
|
|
dict set seen $id 1 |
|
|
|
|
set achieved [string match "achieved *" [dict get $info status]] |
|
|
|
|
if {$achieved_expected && !$achieved && [dict get $info status] ne ""} { |
|
|
|
|
flag $relpath "archived detail file Status is '[dict get $info status]' - archive/ holds achieved goals only" |
|
|
|
|
} elseif {!$achieved_expected && $achieved} { |
|
|
|
|
flag $relpath "achieved goal still in goals/ - the achieved flip includes archiving (move to goals/archive/, record in GOALS-archive.md)" |
|
|
|
|
} |
|
|
|
|
if {![dict exists $index $id]} { |
|
|
|
|
flag $relpath "orphan detail file - no G-$id entry in $indexname" |
|
|
|
|
continue |
|
|
|
|
} |
|
|
|
|
set entry [dict get $index $id] |
|
|
|
|
if {[dict get $info status] ne "" && [dict get $info status] ne [dict get $entry status]} { |
|
|
|
|
flag $relpath "Status mirror '[dict get $info status]' disagrees with $indexname '\[[dict get $entry status]\]' (index wins)" |
|
|
|
|
} |
|
|
|
|
if {[dict get $info scope] ne "" && [dict get $entry scope] ne "" \ |
|
|
|
|
&& [dict get $info scope] ne [dict get $entry scope]} { |
|
|
|
|
flag $relpath "Scope mirror disagrees with $indexname (index wins)" |
|
|
|
|
} |
|
|
|
|
} |
|
|
|
|
foreach id [dict keys $index] { |
|
|
|
|
if {![dict exists $seen $id]} { |
|
|
|
|
flag $indexname "G-$id has no detail file in $dir/" |
|
|
|
|
} |
|
|
|
|
} |
|
|
|
|
} |
|
|
|
|
|
|
|
|
|
# --- informational: candidate stale references to archived goals --------------- |
|
|
|
|
# An active detail file mentioning an archived goal with no achieved/archive/landed |
|
|
|
|
# marker on ANY of the mentioning lines has likely missed the archive-time reference |
|
|
|
|
# sweep (goals/AGENTS.md Archive rules) - a reader cannot tell the referenced goal is |
|
|
|
|
# done. One marked mention per file suffices; pure-history mentions on other lines |
|
|
|
|
# are fine. Heuristic - reported as warnings, never fatal. |
|
|
|
|
set warnings {} |
|
|
|
|
foreach path [lsort [glob -nocomplain -directory [file join $root goals] G-*.md]] { |
|
|
|
|
set relpath goals/[file tail $path] |
|
|
|
|
set mentioned [dict create] ;# id -> 1 when any mentioning line carries a marker |
|
|
|
|
set lines [read_lines $path] |
|
|
|
|
set n [llength $lines] |
|
|
|
|
for {set i 0} {$i < $n} {incr i} { |
|
|
|
|
set line [lindex $lines $i] |
|
|
|
|
# marker may sit on the mention line or a wrapped neighbour |
|
|
|
|
set window "$line [lindex $lines [expr {$i-1}]] [lindex $lines [expr {$i+1}]]" |
|
|
|
|
set marked [regexp -nocase {achieved|archive|landed} $window] |
|
|
|
|
foreach id [regexp -all -inline {G-\d+} $line] { |
|
|
|
|
set num [string range $id 2 end] |
|
|
|
|
if {![dict exists $archive_index $num]} continue |
|
|
|
|
if {$marked || ![dict exists $mentioned $num]} { |
|
|
|
|
dict set mentioned $num $marked |
|
|
|
|
} |
|
|
|
|
} |
|
|
|
|
} |
|
|
|
|
dict for {num marked} $mentioned { |
|
|
|
|
if {!$marked} { |
|
|
|
|
lappend warnings "$relpath: references archived goal G-$num with no achieved/archive marker anywhere - reference sweep candidate (goals/AGENTS.md Archive rules)" |
|
|
|
|
} |
|
|
|
|
} |
|
|
|
|
} |
|
|
|
|
|
|
|
|
|
if {[llength $warnings]} { |
|
|
|
|
puts stderr "goals_lint: [llength $warnings] informational warning(s):" |
|
|
|
|
puts stderr [join $warnings \n] |
|
|
|
|
} |
|
|
|
|
if {[llength $findings]} { |
|
|
|
|
puts [join $findings \n] |
|
|
|
|
puts stderr "goals_lint: [llength $findings] finding(s)" |
|
|
|
|
exit 1 |
|
|
|
|
} |
|
|
|
|
puts "goals_lint: clean ([dict size $active_index] active-index goals, [dict size $archive_index] archived)" |
|
|
|
|
exit 0 |
Julian Noble