specpro-cli 0.1.0__py3-none-any.whl

specpro_cli/assets/scripts/powershell/verify-ledger.ps1

@@ -0,0 +1,383 @@
+#!/usr/bin/env pwsh
+<#
+.SYNOPSIS
+    Verify the implementation-issues ledger's structural invariants.
+.DESCRIPTION
+    Contract-equivalent to `scripts/bash/verify-ledger.sh`. The contract is deliberately
+    strong here: **for the same ledger, both implementations print byte-identical output
+    and return the same exit code** — this script is invoked from command documents and
+    from a pre-commit hook, and a check that disagrees with its twin across platforms is
+    worse than one that is merely missing, because each side looks authoritative.
+
+    Invariants, in the order the Bash side checks them:
+      1. the five sections exist and are in canonical order
+      2. no entry sits outside every section (appended past the sentinel)
+      3. each section's statistics row matches its actual entry counts
+      5. every ID named in a Pending-Items column exists as a pending entry
+      4. the file ends with exactly one newline
+    (The numbering matches the Bash source; 4 and 5 are ordered by their position there.)
+
+.OUTPUTS
+    Exit 0 = all invariants hold; 1 = at least one violation, details printed.
+#>
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+
+$LEDGER = if ($env:LEDGER) { $env:LEDGER } else { 'specs/implement_issues.md' }
+$script:FAIL = 0
+
+if (-not (Test-Path -LiteralPath $LEDGER -PathType Leaf)) {
+    Write-Error "✗ $LEDGER not found (run from the repository root)"
+    exit 1
+}
+
+# --- 0. the section list is DERIVED, not transcribed ---------------------------------
+# ⚠️ This block was `@('specify','plan','tasks','test-plan')` — a hand-copied duplicate
+# of the contract's table. The bash side removed that copy in ISS-88, and the two then
+# diverged exactly the way two sources of one fact do: the contract gained
+# `[constitution]`, this side never learned about it, and **nothing compared them**.
+# A copy is not a check; deriving one from the other is.
+$CONTRACT = if ($env:CONTRACT) { $env:CONTRACT }
+            else { Join-Path (Split-Path -Parent $LEDGER) 'contracts/ledger.md' }
+
+$SECTIONS = @()
+if (Test-Path -LiteralPath $CONTRACT -PathType Leaf) {
+    $inTable = $false
+    foreach ($line in Get-Content -LiteralPath $CONTRACT) {
+        if ($line -match '^## Sections and their consumers') { $inTable = $true; continue }
+        if ($inTable -and $line -match '^## ') { break }
+        if ($inTable -and $line -match '^\| `\[([a-z-]+)\]`') { $SECTIONS += $Matches[1] }
+    }
+}
+
+if ($SECTIONS.Count -eq 0) {
+    # ⚠️ An empty list is NOT "nothing to check": every section-level check below would
+    # pass vacuously, and that is indistinguishable from a clean ledger.
+    [Console]::Error.WriteLine("✗ could not derive the section list from $CONTRACT")
+    [Console]::Error.WriteLine("   A verifier with no sections to check reports success without checking anything.")
+    [Console]::Error.WriteLine("   Fix: run from the repository root, or set CONTRACT=<path to the ledger contract>.")
+    exit 1
+}
+
+# --- 0b. and the comparison runs BOTH ways -------------------------------------------
+# Deriving the list closes "the contract names a section the ledger lacks". It does NOT
+# close the reverse: a section present in the ledger but absent from the contract is
+# simply never iterated, so it is never checked — and the run still reports clean.
+$inLedger = @(Get-Content -LiteralPath $LEDGER |
+    Where-Object { $_ -match '^## \[[a-z-]+\] Phase Issues$' } |
+    ForEach-Object { [regex]::Match($_, '^## \[([a-z-]+)\]').Groups[1].Value } |
+    Sort-Object -Unique)
+$undeclared = @($inLedger | Where-Object { $SECTIONS -notcontains $_ })
+if ($undeclared.Count -gt 0) {
+    [Console]::Error.WriteLine("✗ section(s) present in the ledger but absent from the contract's table:")
+    foreach ($u in $undeclared) { [Console]::Error.WriteLine("    $u") }
+    [Console]::Error.WriteLine("    → nothing checks them: the verifier iterates the contract's list.")
+    [Console]::Error.WriteLine("      Add the row to $CONTRACT (with its consumer), or remove the section.")
+    exit 1
+}
+
+# The whole ledger as an array of lines. Every check below reads this rather than
+# re-reading the file, so a mid-run edit cannot make two checks disagree.
+$lines = Get-Content -LiteralPath $LEDGER
+
+function Get-SectionHeadingLine {
+    param([string]$Section)
+    for ($i = 0; $i -lt $lines.Count; $i++) {
+        if ($lines[$i] -ceq "## [$Section] Phase Issues") { return $i }   # 0-based
+    }
+    return -1
+}
+
+function Get-SectionBody {
+    param([int]$HeadingIndex)
+    # Body runs to the next '## [' heading, the sentinel, or EOF — whichever is first.
+    # Stopping at the sentinel matters: content appended past it is orphaned and must
+    # NOT be counted in the last section, or one misfiling is reported twice.
+    $end = $lines.Count
+    for ($i = $HeadingIndex + 1; $i -lt $lines.Count; $i++) {
+        if ($lines[$i] -match '^## \[' -or $lines[$i] -ceq '-->') { $end = $i; break }
+    }
+    if ($end -le $HeadingIndex + 1) { return @() }
+    return $lines[($HeadingIndex + 1)..($end - 1)]
+}
+
+Write-Output "Ledger integrity: $LEDGER"
+Write-Output ''
+
+# --- 1. sections exist, in canonical order --------------------------------------------
+$headings = @()
+foreach ($s in $SECTIONS) {
+    $idx = Get-SectionHeadingLine $s
+    if ($idx -lt 0) {
+        Write-Output "✗ missing section: ## [$s] Phase Issues"
+        $script:FAIL = 1
+    } else {
+        $headings += $idx
+        Write-Output ("  ✓ [{0,-9}] heading at line {1}" -f $s, ($idx + 1))
+    }
+}
+if ($headings.Count -eq $SECTIONS.Count) {
+    $sorted = $headings | Sort-Object
+    if (($headings -join ',') -ne ($sorted -join ',')) {
+        Write-Output '✗ sections are not in canonical order'
+        $script:FAIL = 1
+    }
+}
+
+# --- 2. no orphaned entries (entry outside every section) -----------------------------
+$lastHeading = -1
+for ($i = $lines.Count - 1; $i -ge 0; $i--) {
+    if ($lines[$i] -match '^## \[.*\] Phase Issues$') { $lastHeading = $i; break }
+}
+$sentinel = -1
+for ($i = $lines.Count - 1; $i -ge 0; $i--) {
+    if ($lines[$i] -ceq '-->') { $sentinel = $i; break }
+}
+if ($sentinel -ge 0 -and $lastHeading -ge 0 -and $sentinel -gt $lastHeading) {
+    # ⚠️ `$a..$b` with $a > $b yields a DESCENDING range in PowerShell, and indexing
+    # past the end throws — where Bash's `awk 'NR>s'` simply yields nothing. So the
+    # empty range has to be tested for rather than relied on to be empty.
+    $orphan = @()
+    if ($sentinel + 1 -le $lines.Count - 1) {
+        $orphan = @($lines[($sentinel + 1)..($lines.Count - 1)] | Where-Object { $_ -match '^- \[[ x]\] ISS-' })
+    }
+    if ($orphan.Count -gt 0) {
+        Write-Output "✗ orphaned entry after the end-of-file sentinel (line $($sentinel + 1)):"
+        foreach ($o in $orphan) {
+            $trimmed = if ($o.Length -gt 90) { $o.Substring(0, 90) } else { $o }
+            Write-Output "      $trimmed"
+        }
+        Write-Output '      → it belongs to no section; move it into its own section'
+        $script:FAIL = 1
+    } else {
+        Write-Output '  ✓ no entries appended past the end-of-file sentinel'
+    }
+}
+
+# --- 3. statistics table matches actual counts ----------------------------------------
+Write-Output ''
+foreach ($s in $SECTIONS) {
+    $h = Get-SectionHeadingLine $s
+    if ($h -lt 0) { continue }
+    $body = Get-SectionBody $h
+    $res = @($body | Where-Object { $_ -match '^- \[x\] ISS-' }).Count
+    $pen = @($body | Where-Object { $_ -match '^- \[ \] ISS-' }).Count
+    $tot = $res + $pen
+
+    $row = $lines | Where-Object { $_ -match "^\| \[$s\]" } | Select-Object -First 1
+    $cells = $row -split '\|'
+    $tTot = if ($cells.Count -gt 2) { $cells[2].Trim() } else { '' }
+    $tRes = if ($cells.Count -gt 3) { $cells[3].Trim() } else { '' }
+    $tPen = if ($cells.Count -gt 4) { $cells[4].Trim() } else { '' }
+
+    if ($tot -eq [int]$tTot -and $res -eq [int]$tRes -and $pen -eq [int]$tPen) {
+        Write-Output ("  ✓ [{0,-9}] actual {1}/{2}/{3} = table" -f $s, $tot, $res, $pen)
+    } else {
+        Write-Output ("  ✗ [{0,-9}] actual {1}/{2}/{3}  ≠  table {4}/{5}/{6}" -f $s, $tot, $res, $pen, $tTot, $tRes, $tPen)
+        # Direction matters: the two directions have different root causes and different
+        # correct fixes. "Fix the table" is the WRONG advice for the over-count direction
+        # — there the entry was never written, and the fix is to write it.
+        if ([int]$tTot -gt $tot) {
+            Write-Output ("      → table EXCEEDS the section by {0}: the summary claims entries that do not exist." -f ([int]$tTot - $tot))
+            Write-Output '        Signature of a SKIPPED WRITE — most often an idempotency guard that searched'
+            Write-Output '        the whole file for the ID and matched a mention (the statistics Pending-Items'
+            Write-Output '        column, the Last Updated line, a cross-reference) instead of the entry itself.'
+            Write-Output "        Fix: write the missing entry body (and confirm the guard matches '^- \[[x ]\] ISS-<N>:' )."
+        } elseif ([int]$tTot -lt $tot) {
+            Write-Output ("      → section EXCEEDS the table by {0}: the derived summary was not updated." -f ($tot - [int]$tTot))
+            Write-Output '        Fix: update the table (the section entries are authoritative).'
+        } else {
+            Write-Output '      → counts agree but the resolved/pending split differs; reconcile against the section.'
+        }
+        $script:FAIL = 1
+    }
+}
+
+# --- 5. Pending-Items column names only entries that exist ----------------------------
+Write-Output ''
+foreach ($s in $SECTIONS) {
+    $h = Get-SectionHeadingLine $s
+    if ($h -lt 0) { continue }
+    $body = Get-SectionBody $h
+    $row = $lines | Where-Object { $_ -match "^\| \[$s\]" } | Select-Object -First 1
+    $cells = $row -split '\|'
+    $column = if ($cells.Count -gt 5) { $cells[5] } else { '' }
+    $named = @([regex]::Matches($column, 'ISS-[0-9]+') | ForEach-Object { $_.Value } | Sort-Object -Unique)
+
+    if ($named.Count -eq 0) {
+        Write-Output ("  ✓ [{0,-9}] Pending-Items column names no IDs" -f $s)
+        continue
+    }
+    # ⚠️ `$miss` is built with a LEADING space per item, matching the Bash side's
+    # `miss="$miss $id"`. The result renders as `names  ISS-99` — two spaces — and that
+    # is the output this script has to reproduce byte-for-byte. Tidying it to a single
+    # space here would be an improvement that breaks the contract.
+    $miss = ''
+    foreach ($id in $named) {
+        $pattern = "^- \[ \] $id`:"
+        if (-not ($body | Where-Object { $_ -match $pattern })) { $miss += " $id" }
+    }
+    if ($miss -eq '') {
+        Write-Output ("  ✓ [{0,-9}] every named pending ID exists as an entry" -f $s)
+    } else {
+        Write-Output ("  ✗ [{0,-9}] Pending-Items names {1} but no such pending entry exists in this section" -f $s, $miss)
+        Write-Output '      → the summary names an entry the file does not contain — a skipped or lost write,'
+        Write-Output '        not a formatting slip. Write the entry body, or correct the column if it was over-bumped.'
+        $script:FAIL = 1
+    }
+}
+
+# --- 4b. a completed hand-off names an entry that EXISTS in its target section --------
+# ISS-110 / ISS-93 / ISS-90 ③: a decision whose closing line was "hand this to
+# /specpro-tasks --review-issues" created no `[tasks]` entry — so that command read an
+# EMPTY queue and exited having done nothing, while the decision read as complete. The
+# channel was never the problem (登记即路由); what was missing was the OBLIGATION to write
+# the entry, and a point where its absence stops something. This is that point.
+#
+# ⚠️ LINE-START anchor, never a full-text match (TOOL-009): the ledger is full of prose
+# ABOUT hand-offs and a check that matched a mention would fire on the discussion.
+# ⚠️ Only `[x]` entries — a `[ ]` entry has not handed anything off yet.
+Write-Output ''
+$handoffs = @()
+$cur = ''
+for ($i = 0; $i -lt $lines.Count; $i++) {
+    $ln = $lines[$i]
+    if ($ln -match '^- \[[ x]\] ISS-[0-9]+:') { $cur = $ln }
+    if ($ln -match '^  \*\*移交\*\*: \[[a-z-]+\] → ISS-[0-9]+') {
+        if ($cur -match '^- \[x\]') {
+            $handoffs += [pscustomobject]@{ LineNo = $i + 1; Entry = $cur; Handoff = $ln }
+        }
+    }
+}
+if ($handoffs.Count -eq 0) {
+    Write-Output '  ✓ no completed entry carries a hand-off line (nothing to resolve)'
+} else {
+    $bad = 0
+    foreach ($h in $handoffs) {
+        $target = [regex]::Match($h.Handoff, '\[([a-z-]+)\]').Groups[1].Value
+        $hid = [regex]::Match($h.Handoff, 'ISS-[0-9]+').Value
+        $src = [regex]::Match($h.Entry, 'ISS-[0-9]+').Value
+        if (-not ($SECTIONS -contains $target)) {
+            Write-Output ("  ✗ hand-off at line {0} targets [{1}], which the contract does not define" -f $h.LineNo, $target)
+            Write-Output '      → the named partition has no consumer; a hand-off there is a dead end.'
+            $bad = 1
+            continue
+        }
+        $hh = Get-SectionHeadingLine $target
+        $body = Get-SectionBody $hh
+        if ($body | Where-Object { $_ -match "^- \[[ x]\] $hid`:" }) {
+            Write-Output ("  ✓ hand-off {0} → [{1}] {2} resolves" -f $src, $target, $hid)
+        } else {
+            Write-Output ("  ✗ hand-off at line {0} names {1} in [{2}], but no such entry exists there" -f $h.LineNo, $hid, $target)
+            Write-Output '      → the decision says the work moved; the target section says nothing arrived.'
+            Write-Output '        Register the entry in that section (登记即路由), or drop the hand-off line.'
+            $bad = 1
+        }
+    }
+    if ($bad -ne 0) { $script:FAIL = 1 }
+}
+
+# --- 4. exactly one trailing newline --------------------------------------------------
+Write-Output ''
+$raw = [System.IO.File]::ReadAllText((Resolve-Path -LiteralPath $LEDGER).Path)
+if ($raw.EndsWith("`n") -and -not $raw.EndsWith("`n`n")) {
+    Write-Output '  ✓ single trailing newline'
+} else {
+    Write-Output '  ✗ file does not end with exactly one newline'
+    Write-Output '      → append-based writers will fuse the next entry onto the previous line'
+    $script:FAIL = 1
+}
+
+# --- 6. every entry block is bounded, and carries exactly one tail ----------------
+# The ledger is position-structured at TWO levels: an entry is decided by position
+# within a section, and a section by position within the file. The checks above see
+# neither: a misplaced tail changes no count, and check 2 looks only at entry HEADERS.
+# Observed three times — twice a `**Resolution**` landed past the end-of-file sentinel,
+# once past a SECTION boundary. Same writer bug, different boundary; each time every
+# check above reported OK.
+#
+# ⚠️ The block-boundary flush is written out twice rather than factored into a helper:
+# a PowerShell scriptblock invoked with `&` runs in a CHILD scope, so `$bounds += …`
+# inside it would be discarded on return — the check would collect nothing and report
+# a clean ledger. Duplication is the cheaper mistake here.
+Write-Output ""
+$bounds = @()
+$entry = $null; $rel = 0; $res = 0; $eid = ""
+
+for ($n = 0; $n -lt $lines.Count; $n++) {
+    $l = $lines[$n]; $lineNo = $n + 1
+
+    if ($l -match '^- \[[ x]\] ISS-') {
+        if ($null -ne $entry -and ($rel -ne 1 -or $res -gt 1)) { $bounds += "BLOCK|$eid|$rel|$res" }
+        $entry = $l; $rel = 0; $res = 0
+        $eid = if ($l -match 'ISS-[0-9]+') { $Matches[0] } else { '?' }
+        continue
+    }
+    if ($l -match '^## \[' -or $l -match '^-->') {
+        if ($null -ne $entry -and ($rel -ne 1 -or $res -gt 1)) { $bounds += "BLOCK|$eid|$rel|$res" }
+        $entry = $null
+        continue
+    }
+    if ($l -match '^  \*\*Related\*\*:') {
+        if ($null -eq $entry) { $bounds += "STRAY|$lineNo|Related" } else { $rel++ }
+    }
+    if ($l -match '^  \*\*Resolution\*\*') {
+        if ($null -eq $entry) { $bounds += "STRAY|$lineNo|Resolution" } else { $res++ }
+    }
+}
+if ($null -ne $entry -and ($rel -ne 1 -or $res -gt 1)) { $bounds += "BLOCK|$eid|$rel|$res" }
+
+if ($bounds.Count -eq 0) {
+    Write-Output "  ✓ every entry block is bounded and carries exactly one Related line"
+} else {
+    foreach ($b in $bounds) {
+        $p = $b -split '\|'
+        if ($p[0] -eq 'BLOCK') {
+            Write-Output ("  ✗ {0}: block carries Related={1} Resolution={2} (want 1 and <=1)" -f $p[1], $p[2], $p[3])
+            Write-Output "      → the block does not end where it should: a tail line was split off,"
+            Write-Output "        or a foreign line was absorbed."
+        } else {
+            Write-Output ("  ✗ line {0} carries a {1} OUTSIDE any entry block" -f $p[1], $p[2])
+            Write-Output "      → a field line was written past a boundary; it belongs to no entry,"
+            Write-Output "        so no reader will ever attribute it correctly."
+        }
+    }
+    $script:FAIL = 1
+}
+
+# --- 7. entry IDs are globally unique ---------------------------------------------------
+# Why this exists (T206 / ISS-166): every consumer ADDRESSES an entry by its ID — the
+# documented marking form is a line-start match on `ISS-<N>`. Two entries sharing one make
+# that address name NEITHER of them, and nothing else reports it: the statistics table
+# still reconciles (bump the count and it agrees), the section checks still pass, the
+# sentinel still holds. The collision is silent until someone reads the whole file — the
+# failure TOOL-011 recorded for its own numbering, in a file since retired while this one
+# inherited none of it.
+#
+# ⚠️ Numeric sort, never a plain lexicographic one: the IDs are variable width, so
+# `ISS-100` sorts BEFORE `ISS-97` character-wise. Same reason "take the next number" must
+# use a numeric sort — see the note in commands/specpro.implement.md.
+Write-Output ''
+$ids = [System.IO.File]::ReadAllLines((Resolve-Path -LiteralPath $LEDGER).Path) |
+    Where-Object { $_ -match '^- \[[x ]\] ISS-[0-9]+:' } |
+    ForEach-Object { [int]([regex]::Match($_, 'ISS-([0-9]+):').Groups[1].Value) }
+$dups = $ids | Group-Object | Where-Object { $_.Count -gt 1 } | ForEach-Object { $_.Name }
+if (-not $dups) {
+    Write-Output '  ✓ entry IDs are unique'
+} else {
+    Write-Output ("  ✗ these entry IDs are used more than once:" + (($dups | Sort-Object { [int]$_ }) -join ' ' | ForEach-Object { " $_" }))
+    Write-Output '      → an ID is how a --review-issues run ADDRESSES an entry; two entries'
+    Write-Output '        sharing one mean the address names neither of them, and the counts'
+    Write-Output '        still reconcile, so nothing else would have reported this.'
+    $script:FAIL = 1
+}
+
+# --- verdict ---------------------------------------------------------------------------
+Write-Output ''
+if ($script:FAIL -eq 0) {
+    Write-Output '✓ ledger integrity: all invariants hold'
+    exit 0
+} else {
+    Write-Output '✗ ledger integrity: VIOLATIONS FOUND (see above)'
+    exit 1
+}