a731a45cd6
* test(#3116): failing-first — parseLedger throws on CRLF WINDOWS.md On repos with core.autocrlf=true (Windows default), .planning/WINDOWS.md is checked out CRLF. The \n--- close-fence scan leaves the last frontmatter line's CR attached, and the key:value regex's . doesn't match CR, so the parser throws WINDOWS_LEDGER_MALFORMED on the last key. * fix(#3116): strip trailing CR per line in parseFrontmatterStrict The \n--- close-fence scan lands on the LF of the last frontmatter line's CRLF, so yamlBody ends with a bare \r. split(/\r?\n/) strips CR from interior lines but the last line's \r survives. The key:value regex fails because . doesn't match CR. Fix: strip \r per line (rawLine.replace(/\r$/, '')) rather than normalizing raw — the writer round-trips raw byte-exact. * chore(#3116): add changeset fragment * chore(#3116): backfill changeset PR number 3137 --------- Co-authored-by: sim <sim@local>
949 lines
32 KiB
TypeScript
949 lines
32 KiB
TypeScript
/**
|
|
* Broken-windows ledger — optionally enforced cross-phase defect register (issue #1950).
|
|
*
|
|
* Manages `.planning/WINDOWS.md`: a cross-phase ledger of small defects (stubs,
|
|
* TODOs, skipped tests, lint warnings, unrun verifies, unmet truths, deviations).
|
|
* When `workflow.windows_enforce` is true, `/gsd-ship` blocks while any entry is
|
|
* `open`; an entry can be `waived` only with a recorded reason or `fixed`.
|
|
*
|
|
* LEAF MODULE — imports ONLY: node:fs, node:path. No other src/ imports.
|
|
*
|
|
* Storage format (`.planning/WINDOWS.md`):
|
|
* ---
|
|
* schema_version: 1
|
|
* open_count: N
|
|
* waived_count: N
|
|
* fixed_count: N
|
|
* total_count: N
|
|
* last_updated: <ISO-8601>
|
|
* ---
|
|
* # Broken Windows Ledger
|
|
* <human-readable prose>
|
|
* ```json
|
|
* [ <entries array, canonical JSON> ]
|
|
* ```
|
|
*
|
|
* Frontmatter holds scalar counts (the FAST path the ship gate reads via jq
|
|
* without parsing JSON). The JSON code block is the AUTHORITATIVE entries
|
|
* source. The two must agree; read paths cross-check and fail closed on drift.
|
|
*
|
|
* Exports:
|
|
* Constants: REASON, LEDGER_FILE_NAME, SCHEMA_VERSION, KINDS
|
|
* Pure: emptyLedger, parseLedger, renderLedger, appendWindow,
|
|
* markWaived, markFixed, openCount, findByStatus
|
|
* I/O: cmdWindowsStatus, cmdWindowsAppend, cmdWindowsWaive,
|
|
* cmdWindowsMarkFixed
|
|
*
|
|
* Reasoning shape — every cmd* function returns JSON suitable for `--raw`:
|
|
* success: { ok: true, ledger: <Ledger>, ... }
|
|
* failure: { ok: false, reason: <REASON.*>, message: <string> }
|
|
* Failure throws an ExitError-shaped error carrying REASON so the gsd-tools
|
|
* dispatcher's `--json-errors` mode emits it as a structured code (CONTRIBUTING.md
|
|
* "Prohibited: Raw Text Matching"). The frozen REASON enum is the typed surface
|
|
* tests assert against.
|
|
*/
|
|
|
|
import fs from 'node:fs';
|
|
import path from 'node:path';
|
|
|
|
// ─── Constants ─────────────────────────────────────────────────────────────
|
|
|
|
export const LEDGER_FILE_NAME = 'WINDOWS.md';
|
|
export const SCHEMA_VERSION = 1;
|
|
|
|
/**
|
|
* Frozen reason enum. Tests assert against these — they are the typed surface
|
|
* per CONTRIBUTING.md. Adding a new code requires updating this enum, the I/O
|
|
* entry point that emits it, AND the test that locks Object.keys(REASON).sort()
|
|
* — three coordinated changes that keep code and tests from drifting.
|
|
*/
|
|
export const REASON = Object.freeze({
|
|
WINDOWS_OK: 'windows_ok',
|
|
WINDOWS_LEDGER_MISSING: 'windows_ledger_missing',
|
|
WINDOWS_LEDGER_MALFORMED: 'windows_ledger_malformed',
|
|
WINDOWS_ID_NOT_FOUND: 'windows_id_not_found',
|
|
WINDOWS_ALREADY_RESOLVED: 'windows_already_resolved',
|
|
WINDOWS_WAIVE_REASON_EMPTY: 'windows_waive_reason_empty',
|
|
WINDOWS_INVALID_KIND: 'windows_invalid_kind',
|
|
WINDOWS_INVALID_FILE: 'windows_invalid_file',
|
|
WINDOWS_INVALID_TEXT: 'windows_invalid_text',
|
|
WINDOWS_INVALID_ID: 'windows_invalid_id',
|
|
WINDOWS_APPEND_MISSING_FIELD: 'windows_append_missing_field',
|
|
WINDOWS_USAGE: 'windows_usage',
|
|
});
|
|
|
|
/** Allowed window kinds. Aligned with the issue's enumerated sources. */
|
|
export const KINDS = Object.freeze([
|
|
'stub',
|
|
'todo',
|
|
'fixme',
|
|
'skipped-test',
|
|
'lint-warning',
|
|
'unmet-truth',
|
|
'unrun-verify',
|
|
'deviation',
|
|
]);
|
|
|
|
const KIND_SET = new Set(KINDS);
|
|
|
|
// ─── Types ─────────────────────────────────────────────────────────────────
|
|
|
|
export type WindowKind =
|
|
| 'stub'
|
|
| 'todo'
|
|
| 'fixme'
|
|
| 'skipped-test'
|
|
| 'lint-warning'
|
|
| 'unmet-truth'
|
|
| 'unrun-verify'
|
|
| 'deviation';
|
|
|
|
export type WindowStatus = 'open' | 'waived' | 'fixed';
|
|
|
|
export interface WindowEntry {
|
|
id: number;
|
|
kind: WindowKind;
|
|
phase: string;
|
|
file: string; // '' when not applicable
|
|
line: number | null; // null when not applicable
|
|
description: string;
|
|
status: WindowStatus;
|
|
reason: string; // '' unless status === 'waived'
|
|
recorded_at: string; // ISO-8601
|
|
resolved_at: string | null;
|
|
}
|
|
|
|
/** Input shape for appendWindow — id/status/timestamps are assigned by the fn. */
|
|
export type WindowInput = Pick<WindowEntry, 'kind' | 'phase' | 'description'> &
|
|
Partial<Pick<WindowEntry, 'file' | 'line'>>;
|
|
|
|
export interface Ledger {
|
|
schema_version: number;
|
|
open_count: number;
|
|
waived_count: number;
|
|
fixed_count: number;
|
|
total_count: number;
|
|
last_updated: string;
|
|
entries: WindowEntry[];
|
|
}
|
|
|
|
// ─── Errors ────────────────────────────────────────────────────────────────
|
|
|
|
/**
|
|
* Error carrying a REASON code. gsd-tools.cjs's `--json-errors` mode catches
|
|
* this and emits `{ ok: false, reason: err.reason, message: err.message }` to
|
|
* stderr; otherwise the message goes to stderr as plain text and the exit
|
|
* code is non-zero.
|
|
*/
|
|
export class WindowsError extends Error {
|
|
reason: string;
|
|
constructor(reason: string, message: string) {
|
|
super(message);
|
|
this.name = 'WindowsError';
|
|
this.reason = reason;
|
|
}
|
|
}
|
|
|
|
// ─── Pure: constructors + counts ───────────────────────────────────────────
|
|
|
|
export function emptyLedger(now: string): Ledger {
|
|
return {
|
|
schema_version: SCHEMA_VERSION,
|
|
open_count: 0,
|
|
waived_count: 0,
|
|
fixed_count: 0,
|
|
total_count: 0,
|
|
last_updated: now,
|
|
entries: [],
|
|
};
|
|
}
|
|
|
|
export function openCount(ledger: Ledger): number {
|
|
return ledger.open_count;
|
|
}
|
|
|
|
export function findByStatus(ledger: Ledger, status: WindowStatus): WindowEntry[] {
|
|
return ledger.entries.filter((e) => e.status === status);
|
|
}
|
|
|
|
function recomputeCounts(ledger: Ledger): Ledger {
|
|
let open = 0, waived = 0, fixed = 0;
|
|
for (const e of ledger.entries) {
|
|
if (e.status === 'open') open++;
|
|
else if (e.status === 'waived') waived++;
|
|
else if (e.status === 'fixed') fixed++;
|
|
}
|
|
return {
|
|
...ledger,
|
|
open_count: open,
|
|
waived_count: waived,
|
|
fixed_count: fixed,
|
|
total_count: ledger.entries.length,
|
|
};
|
|
}
|
|
|
|
function validateKind(kind: unknown): asserts kind is WindowKind {
|
|
if (typeof kind !== 'string' || !KIND_SET.has(kind)) {
|
|
throw new WindowsError(
|
|
REASON.WINDOWS_INVALID_KIND,
|
|
`Invalid window kind: ${JSON.stringify(kind)}. Allowed: ${KINDS.join(', ')}.`,
|
|
);
|
|
}
|
|
}
|
|
|
|
function validateDescription(description: unknown): string {
|
|
if (typeof description !== 'string' || description.trim() === '') {
|
|
throw new WindowsError(
|
|
REASON.WINDOWS_APPEND_MISSING_FIELD,
|
|
'Window description must be a non-empty string.',
|
|
);
|
|
}
|
|
rejectBacktickRun(description, 'description');
|
|
return description;
|
|
}
|
|
|
|
/**
|
|
* Reject any string field that contains a 4-backtick run. The ledger's JSON
|
|
* code block uses a 4-backtick fence; a 4-backtick run inside stringified
|
|
* entry text would terminate the fence early and brick the next parse
|
|
* (issue #1950 review H1). JSON.stringify does not escape backticks, so we
|
|
* must catch them at validate time.
|
|
*/
|
|
function rejectBacktickRun(value: string, field: string): void {
|
|
if (value.includes(FORBIDDEN_BACKTICK_RUN)) {
|
|
throw new WindowsError(
|
|
REASON.WINDOWS_INVALID_TEXT,
|
|
`Window ${field} contains a 4-backtick run, which would corrupt the ledger's JSON code fence.`,
|
|
);
|
|
}
|
|
}
|
|
|
|
function validateFile(file: unknown): string {
|
|
if (file == null || file === '') return '';
|
|
if (typeof file !== 'string') {
|
|
throw new WindowsError(
|
|
REASON.WINDOWS_INVALID_FILE,
|
|
'Window file must be a string when provided.',
|
|
);
|
|
}
|
|
// Reject path traversal — the ledger is a project-local artifact; absolute or
|
|
// parent-escaping paths serve no legitimate purpose and could mislead a human
|
|
// reviewer into investigating the wrong location. Reject NUL bytes too.
|
|
if (file.includes('\0')) {
|
|
throw new WindowsError(
|
|
REASON.WINDOWS_INVALID_FILE,
|
|
'Window file contains a NUL byte.',
|
|
);
|
|
}
|
|
if (path.isAbsolute(file) || /(^|[/\\])\.\.([/\\]|$)/.test(file)) {
|
|
throw new WindowsError(
|
|
REASON.WINDOWS_INVALID_FILE,
|
|
`Window file rejects path traversal/absolute paths: ${file}`,
|
|
);
|
|
}
|
|
return file;
|
|
}
|
|
|
|
function validateLine(line: unknown): number | null {
|
|
if (line == null || line === '') return null;
|
|
// Strict: number or numeric string only; reject garbage like "abc" (which
|
|
// Number() would silently coerce to NaN → null, hiding type drift). Issue
|
|
// #1950 review M2.
|
|
const n = typeof line === 'number' ? line : Number(line);
|
|
if (!Number.isInteger(n) || n < 1) {
|
|
throw new WindowsError(
|
|
REASON.WINDOWS_APPEND_MISSING_FIELD,
|
|
`Window line must be a positive integer when provided (got: ${JSON.stringify(line)}).`,
|
|
);
|
|
}
|
|
return n;
|
|
}
|
|
|
|
function nextId(entries: WindowEntry[]): number {
|
|
let max = 0;
|
|
for (const e of entries) if (e.id > max) max = e.id;
|
|
return max + 1;
|
|
}
|
|
|
|
/**
|
|
* Append a window to the ledger. Assigns the next dense id (max+1), sets
|
|
* status=open, timestamps via opts.now.
|
|
*
|
|
* Concurrency (issue #1950 review L2): NOT safe for concurrent writers. Two
|
|
* parallel `gsd_run windows append` invocations both read the same snapshot,
|
|
* both compute the same nextId, both write — the second atomic rename wins
|
|
* and the first append (and the entry it added) is silently lost. This is
|
|
* acceptable in the current single-executor-per-phase model; document if the
|
|
* executor ever gains parallel wave-level append.
|
|
*/
|
|
export function appendWindow(
|
|
ledger: Ledger,
|
|
input: WindowInput,
|
|
opts: { now: string } = { now: new Date().toISOString() },
|
|
): { ledger: Ledger; entry: WindowEntry } {
|
|
validateKind(input.kind);
|
|
const description = validateDescription(input.description);
|
|
const file = validateFile(input.file);
|
|
const line = validateLine(input.line);
|
|
|
|
const id = nextId(ledger.entries);
|
|
const entry: WindowEntry = {
|
|
id,
|
|
kind: input.kind,
|
|
phase: String(input.phase ?? ''),
|
|
file,
|
|
line,
|
|
description,
|
|
status: 'open',
|
|
reason: '',
|
|
recorded_at: opts.now,
|
|
resolved_at: null,
|
|
};
|
|
|
|
const entries = [...ledger.entries, entry];
|
|
const result = recomputeCounts({ ...ledger, entries, last_updated: opts.now });
|
|
return { ledger: result, entry };
|
|
}
|
|
|
|
function findEntryOrFail(ledger: Ledger, id: number): WindowEntry {
|
|
const entry = ledger.entries.find((e) => e.id === id);
|
|
if (!entry) {
|
|
throw new WindowsError(
|
|
REASON.WINDOWS_ID_NOT_FOUND,
|
|
`No window with id ${id}.`,
|
|
);
|
|
}
|
|
return entry;
|
|
}
|
|
|
|
function assertOpen(entry: WindowEntry): void {
|
|
if (entry.status !== 'open') {
|
|
throw new WindowsError(
|
|
REASON.WINDOWS_ALREADY_RESOLVED,
|
|
`Window ${entry.id} is already ${entry.status} (resolved_at=${entry.resolved_at}).`,
|
|
);
|
|
}
|
|
}
|
|
|
|
export function markWaived(
|
|
ledger: Ledger,
|
|
id: number,
|
|
reason: string,
|
|
opts: { now: string } = { now: new Date().toISOString() },
|
|
): Ledger {
|
|
if (typeof reason !== 'string' || reason.trim() === '') {
|
|
throw new WindowsError(
|
|
REASON.WINDOWS_WAIVE_REASON_EMPTY,
|
|
'Waive requires a non-empty recorded reason.',
|
|
);
|
|
}
|
|
const entry = findEntryOrFail(ledger, id);
|
|
assertOpen(entry);
|
|
|
|
const newStatus: WindowStatus = 'waived';
|
|
const entries = ledger.entries.map((e) =>
|
|
e.id === id
|
|
? { ...e, status: newStatus, reason, resolved_at: opts.now }
|
|
: e,
|
|
);
|
|
return recomputeCounts({ ...ledger, entries, last_updated: opts.now });
|
|
}
|
|
|
|
export function markFixed(
|
|
ledger: Ledger,
|
|
id: number,
|
|
opts: { now: string } = { now: new Date().toISOString() },
|
|
): Ledger {
|
|
const entry = findEntryOrFail(ledger, id);
|
|
assertOpen(entry);
|
|
|
|
const newStatus: WindowStatus = 'fixed';
|
|
const entries = ledger.entries.map((e) =>
|
|
e.id === id
|
|
? { ...e, status: newStatus, resolved_at: opts.now }
|
|
: e,
|
|
);
|
|
return recomputeCounts({ ...ledger, entries, last_updated: opts.now });
|
|
}
|
|
|
|
// ─── Pure: parse / render ──────────────────────────────────────────────────
|
|
|
|
// JSON-FENCE strategy (issue #1950 review H1): a description containing the
|
|
// 3-backtick markdown fence sequence would terminate the code block early
|
|
// inside JSON.stringify output (which does not escape backticks), corrupting
|
|
// the file and bricking the next parse. We use a 4-backtick fence which
|
|
// cannot collide with anything JSON.stringify can emit on its own (JSON has
|
|
// no 4-backtick operator), AND validate that no entry's text fields contain
|
|
// a 4-backtick run, so the rendered file is provably reparseable.
|
|
const JSON_FENCE_OPEN = '````json';
|
|
const JSON_FENCE_CLOSE = '````';
|
|
const FORBIDDEN_BACKTICK_RUN = '````';
|
|
|
|
/**
|
|
* Minimal strict frontmatter parser for flat scalar keys. Only supports the
|
|
* shape this module emits: `key: <number|string>` per line. Throws on any
|
|
* structural deviation — fail-closed on drift.
|
|
*/
|
|
function parseFrontmatterStrict(raw: string): Record<string, number | string> {
|
|
if (!raw.startsWith('---\n') && !raw.startsWith('---\r\n')) {
|
|
throw new WindowsError(
|
|
REASON.WINDOWS_LEDGER_MALFORMED,
|
|
'Ledger missing frontmatter opening ---',
|
|
);
|
|
}
|
|
const headerEnd = raw.startsWith('---\r\n') ? 5 : 4;
|
|
const closeIdx = raw.indexOf('\n---', headerEnd);
|
|
if (closeIdx === -1) {
|
|
throw new WindowsError(
|
|
REASON.WINDOWS_LEDGER_MALFORMED,
|
|
'Ledger missing frontmatter closing ---',
|
|
);
|
|
}
|
|
const yamlBody = raw.slice(headerEnd, closeIdx);
|
|
const out: Record<string, number | string> = {};
|
|
for (const rawLine of yamlBody.split(/\r?\n/)) {
|
|
// #3116: the `\n---` scan leaves the final line's CR attached on a CRLF
|
|
// ledger, and `.` never matches CR, so the key: value regex below fails on
|
|
// it. Strip the trailing CR per line so the rest of `raw` (which
|
|
// parseJsonBlock also slices by byte offset) is unaffected.
|
|
const line = rawLine.replace(/\r$/, '');
|
|
if (line.trim() === '') continue;
|
|
const m = line.match(/^([a-zA-Z0-9_]+):\s*(.*)$/);
|
|
if (!m) {
|
|
throw new WindowsError(
|
|
REASON.WINDOWS_LEDGER_MALFORMED,
|
|
`Ledger frontmatter line is not key: value: ${JSON.stringify(line)}`,
|
|
);
|
|
}
|
|
const [, key, valueStr] = m;
|
|
const trimmed = valueStr.trim();
|
|
if (/^-?\d+$/.test(trimmed)) {
|
|
out[key] = Number(trimmed);
|
|
} else if (/^-?\d+\.\d+$/.test(trimmed)) {
|
|
out[key] = Number(trimmed);
|
|
} else {
|
|
// String — strip surrounding quotes if present.
|
|
out[key] =
|
|
(trimmed.startsWith('"') && trimmed.endsWith('"')) ||
|
|
(trimmed.startsWith("'") && trimmed.endsWith("'"))
|
|
? trimmed.slice(1, -1)
|
|
: trimmed;
|
|
}
|
|
}
|
|
return out;
|
|
}
|
|
|
|
function parseJsonBlock(raw: string): WindowEntry[] {
|
|
const start = raw.indexOf(JSON_FENCE_OPEN);
|
|
if (start === -1) {
|
|
throw new WindowsError(
|
|
REASON.WINDOWS_LEDGER_MALFORMED,
|
|
'Ledger missing JSON code block for entries.',
|
|
);
|
|
}
|
|
const end = raw.indexOf(JSON_FENCE_CLOSE, start + JSON_FENCE_OPEN.length);
|
|
if (end === -1) {
|
|
throw new WindowsError(
|
|
REASON.WINDOWS_LEDGER_MALFORMED,
|
|
'Ledger JSON code block not terminated.',
|
|
);
|
|
}
|
|
const jsonText = raw.slice(start + JSON_FENCE_OPEN.length, end).trim();
|
|
let parsed: unknown;
|
|
try {
|
|
parsed = JSON.parse(jsonText);
|
|
} catch (e) {
|
|
throw new WindowsError(
|
|
REASON.WINDOWS_LEDGER_MALFORMED,
|
|
`Ledger JSON block failed to parse: ${(e as Error).message}`,
|
|
);
|
|
}
|
|
if (!Array.isArray(parsed)) {
|
|
throw new WindowsError(
|
|
REASON.WINDOWS_LEDGER_MALFORMED,
|
|
'Ledger JSON block must be an array.',
|
|
);
|
|
}
|
|
return parsed.map(validateEntryShape);
|
|
}
|
|
|
|
function validateEntryShape(e: unknown, i: number): WindowEntry {
|
|
if (typeof e !== 'object' || e === null) {
|
|
throw new WindowsError(
|
|
REASON.WINDOWS_LEDGER_MALFORMED,
|
|
`Ledger entry ${i} is not an object.`,
|
|
);
|
|
}
|
|
const o = e as Record<string, unknown>;
|
|
const required = ['id', 'kind', 'phase', 'file', 'description', 'status', 'reason', 'recorded_at'];
|
|
for (const k of required) {
|
|
if (!(k in o)) {
|
|
throw new WindowsError(
|
|
REASON.WINDOWS_LEDGER_MALFORMED,
|
|
`Ledger entry ${i} missing required field: ${k}`,
|
|
);
|
|
}
|
|
}
|
|
if (typeof o.id !== 'number' || !Number.isInteger(o.id) || o.id < 1) {
|
|
throw new WindowsError(
|
|
REASON.WINDOWS_LEDGER_MALFORMED,
|
|
`Ledger entry ${i} has invalid id.`,
|
|
);
|
|
}
|
|
if (typeof o.kind !== 'string' || !KIND_SET.has(o.kind)) {
|
|
throw new WindowsError(
|
|
REASON.WINDOWS_LEDGER_MALFORMED,
|
|
`Ledger entry ${i} has invalid kind: ${JSON.stringify(o.kind)}`,
|
|
);
|
|
}
|
|
if (typeof o.status !== 'string' || !['open', 'waived', 'fixed'].includes(o.status)) {
|
|
throw new WindowsError(
|
|
REASON.WINDOWS_LEDGER_MALFORMED,
|
|
`Ledger entry ${i} has invalid status: ${JSON.stringify(o.status)}`,
|
|
);
|
|
}
|
|
if (typeof o.description !== 'string' || typeof o.reason !== 'string') {
|
|
throw new WindowsError(
|
|
REASON.WINDOWS_LEDGER_MALFORMED,
|
|
`Ledger entry ${i} has non-string description/reason.`,
|
|
);
|
|
}
|
|
const phaseStr = typeof o.phase === 'string'
|
|
? o.phase
|
|
: (o.phase == null ? '' : typeof o.phase === 'number' || typeof o.phase === 'boolean' ? String(o.phase) : '');
|
|
const recordedStr = typeof o.recorded_at === 'string'
|
|
? o.recorded_at
|
|
: (o.recorded_at == null ? '' : typeof o.recorded_at === 'number' || typeof o.recorded_at === 'boolean' ? String(o.recorded_at) : '');
|
|
const resolvedStr = typeof o.resolved_at === 'string'
|
|
? o.resolved_at
|
|
: (o.resolved_at == null ? null : typeof o.resolved_at === 'number' || typeof o.resolved_at === 'boolean' ? String(o.resolved_at) : null);
|
|
return {
|
|
id: o.id,
|
|
kind: o.kind as WindowKind,
|
|
phase: phaseStr,
|
|
file: typeof o.file === 'string' ? o.file : '',
|
|
line: o.line == null ? null : (Number(o.line) || null),
|
|
description: o.description,
|
|
status: o.status as WindowStatus,
|
|
reason: o.reason,
|
|
recorded_at: recordedStr,
|
|
resolved_at: resolvedStr,
|
|
};
|
|
}
|
|
|
|
export function parseLedger(raw: string): Ledger {
|
|
const fm = parseFrontmatterStrict(raw);
|
|
if (fm.schema_version !== SCHEMA_VERSION) {
|
|
throw new WindowsError(
|
|
REASON.WINDOWS_LEDGER_MALFORMED,
|
|
`Ledger schema_version must be ${SCHEMA_VERSION}; got ${JSON.stringify(fm.schema_version)}.`,
|
|
);
|
|
}
|
|
const requiredCounts = ['open_count', 'waived_count', 'fixed_count', 'total_count'];
|
|
for (const k of requiredCounts) {
|
|
const v = fm[k];
|
|
if (typeof v !== 'number' || !Number.isInteger(v)) {
|
|
throw new WindowsError(
|
|
REASON.WINDOWS_LEDGER_MALFORMED,
|
|
`Ledger ${k} must be an integer; got ${JSON.stringify(v)}.`,
|
|
);
|
|
}
|
|
}
|
|
if (typeof fm.last_updated !== 'string') {
|
|
throw new WindowsError(
|
|
REASON.WINDOWS_LEDGER_MALFORMED,
|
|
`Ledger last_updated must be a string; got ${JSON.stringify(fm.last_updated)}.`,
|
|
);
|
|
}
|
|
|
|
const entries = parseJsonBlock(raw);
|
|
const ledger: Ledger = {
|
|
schema_version: SCHEMA_VERSION,
|
|
open_count: typeof fm.open_count === 'number' ? fm.open_count : 0,
|
|
waived_count: typeof fm.waived_count === 'number' ? fm.waived_count : 0,
|
|
fixed_count: typeof fm.fixed_count === 'number' ? fm.fixed_count : 0,
|
|
total_count: typeof fm.total_count === 'number' ? fm.total_count : 0,
|
|
last_updated: typeof fm.last_updated === 'string' ? fm.last_updated : '',
|
|
entries,
|
|
};
|
|
|
|
// Cross-check: frontmatter counts must agree with entries-derived counts.
|
|
const recomputed = recomputeCounts(ledger);
|
|
if (
|
|
recomputed.open_count !== ledger.open_count ||
|
|
recomputed.waived_count !== ledger.waived_count ||
|
|
recomputed.fixed_count !== ledger.fixed_count ||
|
|
recomputed.total_count !== ledger.total_count
|
|
) {
|
|
throw new WindowsError(
|
|
REASON.WINDOWS_LEDGER_MALFORMED,
|
|
`Ledger counts disagree with entries: frontmatter open/waived/fixed/total=` +
|
|
`${ledger.open_count}/${ledger.waived_count}/${ledger.fixed_count}/${ledger.total_count}` +
|
|
` but entries yield ${recomputed.open_count}/${recomputed.waived_count}/${recomputed.fixed_count}/${recomputed.total_count}.`,
|
|
);
|
|
}
|
|
return ledger;
|
|
}
|
|
|
|
export function renderLedger(ledger: Ledger): string {
|
|
const fm = [
|
|
'---',
|
|
`schema_version: ${ledger.schema_version}`,
|
|
`open_count: ${ledger.open_count}`,
|
|
`waived_count: ${ledger.waived_count}`,
|
|
`fixed_count: ${ledger.fixed_count}`,
|
|
`total_count: ${ledger.total_count}`,
|
|
`last_updated: ${ledger.last_updated}`,
|
|
'---',
|
|
'',
|
|
].join('\n');
|
|
|
|
const header = [
|
|
'# Broken Windows Ledger',
|
|
'',
|
|
'> Cross-phase defect register. With `workflow.windows_enforce` enabled, `/gsd-ship` blocks while `open_count > 0`.',
|
|
'> Waive with `gsd-tools windows waive <id> "<reason>"` (reason required).',
|
|
'> Mark fixed with `gsd-tools windows fixed <id>`.',
|
|
'',
|
|
].join('\n');
|
|
|
|
const table = renderTable(ledger.entries);
|
|
const jsonBlock = [JSON_FENCE_OPEN, JSON.stringify(ledger.entries, null, 2), JSON_FENCE_CLOSE, ''].join('\n');
|
|
|
|
return [fm, header, table, '', jsonBlock].join('\n');
|
|
}
|
|
|
|
function renderTable(entries: WindowEntry[]): string {
|
|
if (entries.length === 0) {
|
|
return [
|
|
'| id | phase | kind | file | line | description | status | reason | recorded_at | resolved_at |',
|
|
'|----|-------|------|------|------|-------------|--------|--------|-------------|-------------|',
|
|
'| _(none)_ | | | | | _No windows recorded._ | | | | |',
|
|
].join('\n');
|
|
}
|
|
const rows = [
|
|
'| id | phase | kind | file | line | description | status | reason | recorded_at | resolved_at |',
|
|
'|----|-------|------|------|------|-------------|--------|--------|-------------|-------------|',
|
|
];
|
|
for (const e of entries) {
|
|
// Escape backslash FIRST, then pipe — markdown table cells treat `\` as
|
|
// the escape introducer, so a description containing `\|` would render
|
|
// as an escaped pipe (i.e. a literal `|` inside the cell) and split the
|
|
// column. Escaping `\` → `\\` first makes the subsequent `\|` replacement
|
|
// unambiguous. (CodeQL: js/incomplete-sanitization — issue #1950 PR #2441.)
|
|
const cell = (s: string | number | null) =>
|
|
String(s ?? '')
|
|
.replace(/\\/g, '\\\\')
|
|
.replace(/\|/g, '\\|');
|
|
rows.push(
|
|
[
|
|
'|', cell(e.id), '|', cell(e.phase), '|', cell(e.kind), '|',
|
|
cell(e.file), '|', cell(e.line ?? ''), '|',
|
|
cell(e.description), '|', cell(e.status), '|',
|
|
cell(e.reason), '|', cell(e.recorded_at), '|', cell(e.resolved_at), '|',
|
|
].join(' '),
|
|
);
|
|
}
|
|
return rows.join('\n');
|
|
}
|
|
|
|
// ─── I/O entry points ──────────────────────────────────────────────────────
|
|
|
|
function ledgerPath(cwd: string): string {
|
|
return path.join(cwd, '.planning', LEDGER_FILE_NAME);
|
|
}
|
|
|
|
function readLedgerOrNull(cwd: string): Ledger | null {
|
|
const p = ledgerPath(cwd);
|
|
let raw: string;
|
|
try {
|
|
raw = fs.readFileSync(p, 'utf8');
|
|
} catch (e: unknown) {
|
|
// ENOENT is the only "no ledger yet" case. Every other fs error (EACCES,
|
|
// EPERM, EIO, ENOTDIR, EBADF, ...) must NOT be silently coerced to "empty
|
|
// ledger" — that would fail the ship gate OPEN on an unreadable ledger,
|
|
// contradicting the workflow's documented "fail closed on unreadable"
|
|
// invariant (issue #1950 review H2). Propagate as malformed so the gate
|
|
// blocks and the operator sees a real diagnostic.
|
|
const code = (e && typeof e === 'object' && 'code' in e)
|
|
? String((e as { code?: unknown }).code)
|
|
: '';
|
|
if (code === 'ENOENT') return null;
|
|
throw new WindowsError(
|
|
REASON.WINDOWS_LEDGER_MALFORMED,
|
|
`Could not read ledger at ${p} (${code || 'unknown fs error'}): ${(e as Error).message}.`,
|
|
);
|
|
}
|
|
// parseLedger throws WindowsError on malformed content — caller surfaces it.
|
|
return parseLedger(raw);
|
|
}
|
|
|
|
function ensurePlanningDir(cwd: string): void {
|
|
const dir = path.join(cwd, '.planning');
|
|
if (!fs.existsSync(dir)) {
|
|
fs.mkdirSync(dir, { recursive: true });
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Errnos that Windows throws transiently on rename when a reader or antivirus
|
|
* scanner holds the target. We retry through these; anything else propagates.
|
|
*
|
|
* NOTE (issue #1950 review L3): the retry uses a short busy-wait rather than
|
|
* setTimeout — this is a synchronous CLI path with no event loop to yield on,
|
|
* and the cumulative wait is bounded at 25+50+100+200 = 375ms across 5 attempts.
|
|
* If a future caller moves this onto an async path, swap to awaitable sleeps.
|
|
*/
|
|
const RENAME_RETRY_ERRNOS = new Set(['EPERM', 'EBUSY', 'EACCES']);
|
|
const RENAME_MAX_ATTEMPTS = 5;
|
|
const RENAME_BACKOFF_MS = 25;
|
|
|
|
function renameWithRetry(tmp: string, target: string): void {
|
|
let lastErr: unknown;
|
|
for (let attempt = 0; attempt < RENAME_MAX_ATTEMPTS; attempt++) {
|
|
try {
|
|
fs.renameSync(tmp, target);
|
|
return;
|
|
} catch (err: unknown) {
|
|
lastErr = err;
|
|
const code = (err && typeof err === 'object' && 'code' in err) ? String((err as { code?: unknown }).code) : '';
|
|
if (code && RENAME_RETRY_ERRNOS.has(code) && attempt < RENAME_MAX_ATTEMPTS - 1) {
|
|
// Exponential-ish backoff: 25ms, 50ms, 100ms, 200ms.
|
|
const delay = RENAME_BACKOFF_MS * Math.pow(2, attempt);
|
|
const start = Date.now();
|
|
while (Date.now() - start < delay) {
|
|
// Busy-wait a very short time — Windows transient locks usually clear in <100ms.
|
|
}
|
|
continue;
|
|
}
|
|
throw err;
|
|
}
|
|
}
|
|
throw lastErr;
|
|
}
|
|
|
|
function writeLedgerAtomic(cwd: string, ledger: Ledger): void {
|
|
ensurePlanningDir(cwd);
|
|
const p = ledgerPath(cwd);
|
|
const tmp = `${p}.${process.pid}.tmp`;
|
|
|
|
// #2893: preserve any prose below the JSON ledger block. renderLedger
|
|
// reconstructs frontmatter + header + table + JSON — it does not include
|
|
// trailing prose that users may have written below the closing fence.
|
|
// Without this, every append/waive/fixed silently destroys that prose.
|
|
let trailingProse = '';
|
|
try {
|
|
const existing = fs.readFileSync(p, 'utf8');
|
|
// #2893: search for the CLOSING fence starting AFTER the opening fence,
|
|
// mirroring parseJsonBlock — indexOf(JSON_FENCE_CLOSE) alone would match
|
|
// the opening fence ('````json' starts with '````').
|
|
const openIdx = existing.indexOf(JSON_FENCE_OPEN);
|
|
if (openIdx !== -1) {
|
|
const fenceEnd = existing.indexOf(JSON_FENCE_CLOSE, openIdx + JSON_FENCE_OPEN.length);
|
|
if (fenceEnd !== -1) {
|
|
const afterFence = existing.slice(fenceEnd + JSON_FENCE_CLOSE.length);
|
|
// Drop leading newlines; keep the rest as prose.
|
|
trailingProse = afterFence.replace(/^\n+/, '');
|
|
}
|
|
}
|
|
} catch {
|
|
// File doesn't exist yet (first write) — no prose to preserve.
|
|
}
|
|
|
|
const rendered = renderLedger(ledger);
|
|
const content = trailingProse ? `${rendered}${trailingProse}` : rendered;
|
|
fs.writeFileSync(tmp, content, 'utf8');
|
|
try {
|
|
renameWithRetry(tmp, p);
|
|
} catch (err) {
|
|
// Clean up the orphaned tmp file so repeated failures don't accumulate
|
|
// `.planning/WINDOWS.md.<pid>.tmp` files (issue #1950 review M1). Best-effort:
|
|
// unlink failures (e.g., already gone) are swallowed.
|
|
try { fs.unlinkSync(tmp); } catch { /* best-effort cleanup */ }
|
|
throw err;
|
|
}
|
|
}
|
|
|
|
function nowIso(): string {
|
|
return new Date().toISOString();
|
|
}
|
|
|
|
/** Emit a JSON result to stdout in the canonical shape. */
|
|
function emit(obj: unknown): void {
|
|
process.stdout.write(JSON.stringify(obj, null, 2));
|
|
}
|
|
|
|
/** `gsd-tools windows status [--raw]`. */
|
|
export function cmdWindowsStatus(cwd: string, opts: { raw?: boolean } = {}): void {
|
|
let ledger: Ledger;
|
|
try {
|
|
ledger = readLedgerOrNull(cwd) ?? emptyLedger(nowIso());
|
|
} catch (e) {
|
|
if (e instanceof WindowsError) throw e;
|
|
throw new WindowsError(
|
|
REASON.WINDOWS_LEDGER_MALFORMED,
|
|
`Unexpected error reading ledger: ${(e as Error).message}`,
|
|
);
|
|
}
|
|
void opts; // status output is JSON in both human and raw modes (single shape)
|
|
emit({ ok: true, ledger });
|
|
}
|
|
|
|
/** `gsd-tools windows append --kind K --phase N [--file F] [--line L] --description D`. */
|
|
export function cmdWindowsAppend(
|
|
cwd: string,
|
|
args: string[],
|
|
opts: { raw?: boolean } = {},
|
|
): void {
|
|
void opts;
|
|
const parsed = parseArgs(args, {
|
|
flags: ['--kind', '--phase', '--file', '--line', '--description'],
|
|
required: ['--kind', '--phase', '--description'],
|
|
});
|
|
|
|
let ledger: Ledger;
|
|
try {
|
|
ledger = readLedgerOrNull(cwd) ?? emptyLedger(nowIso());
|
|
} catch (e) {
|
|
if (e instanceof WindowsError) throw e;
|
|
throw new WindowsError(REASON.WINDOWS_LEDGER_MALFORMED, (e as Error).message);
|
|
}
|
|
|
|
const result = appendWindow(
|
|
ledger,
|
|
{
|
|
kind: parsed.values['--kind'] as WindowKind,
|
|
phase: parsed.values['--phase'] ?? '',
|
|
file: parsed.values['--file'] ?? '',
|
|
line: parsed.values['--line'] == null ? null : Number(parsed.values['--line']),
|
|
description: parsed.values['--description'] ?? '',
|
|
},
|
|
{ now: nowIso() },
|
|
);
|
|
writeLedgerAtomic(cwd, result.ledger);
|
|
emit({ ok: true, ledger: result.ledger, entry: result.entry });
|
|
}
|
|
|
|
/** `gsd-tools windows waive <id> "<reason>"`. */
|
|
export function cmdWindowsWaive(
|
|
cwd: string,
|
|
args: string[],
|
|
opts: { raw?: boolean } = {},
|
|
): void {
|
|
void opts;
|
|
const { positionals } = parseArgs(args, { flags: [], required: [], positionals: 2 });
|
|
const idStr = positionals[0];
|
|
const reason = positionals[1];
|
|
|
|
const id = parseIdOrThrow(idStr);
|
|
|
|
let ledger: Ledger;
|
|
try {
|
|
ledger = readLedgerOrNull(cwd) ?? emptyLedger(nowIso());
|
|
} catch (e) {
|
|
if (e instanceof WindowsError) throw e;
|
|
throw new WindowsError(REASON.WINDOWS_LEDGER_MALFORMED, (e as Error).message);
|
|
}
|
|
|
|
const updated = markWaived(ledger, id, reason ?? '', { now: nowIso() });
|
|
writeLedgerAtomic(cwd, updated);
|
|
emit({ ok: true, ledger: updated });
|
|
}
|
|
|
|
/** `gsd-tools windows fixed <id>`. */
|
|
export function cmdWindowsMarkFixed(
|
|
cwd: string,
|
|
args: string[],
|
|
opts: { raw?: boolean } = {},
|
|
): void {
|
|
void opts;
|
|
const { positionals } = parseArgs(args, { flags: [], required: [], positionals: 1 });
|
|
const id = parseIdOrThrow(positionals[0]);
|
|
|
|
let ledger: Ledger;
|
|
try {
|
|
ledger = readLedgerOrNull(cwd) ?? emptyLedger(nowIso());
|
|
} catch (e) {
|
|
if (e instanceof WindowsError) throw e;
|
|
throw new WindowsError(REASON.WINDOWS_LEDGER_MALFORMED, (e as Error).message);
|
|
}
|
|
|
|
const updated = markFixed(ledger, id, { now: nowIso() });
|
|
writeLedgerAtomic(cwd, updated);
|
|
emit({ ok: true, ledger: updated });
|
|
}
|
|
|
|
function parseIdOrThrow(raw: string | undefined): number {
|
|
if (raw == null || raw === '') {
|
|
throw new WindowsError(
|
|
REASON.WINDOWS_INVALID_ID,
|
|
'Window id is required.',
|
|
);
|
|
}
|
|
const n = Number(raw);
|
|
if (!Number.isInteger(n) || n < 1) {
|
|
throw new WindowsError(
|
|
REASON.WINDOWS_INVALID_ID,
|
|
`Window id must be a positive integer (got: ${JSON.stringify(raw)}).`,
|
|
);
|
|
}
|
|
return n;
|
|
}
|
|
|
|
/** Minimal argv parser — flag values via `--flag value` or `--flag=value`. */
|
|
function parseArgs(
|
|
args: string[],
|
|
spec: { flags: string[]; required: string[]; positionals?: number },
|
|
): { values: Record<string, string | undefined>; positionals: string[] } {
|
|
const values: Record<string, string | undefined> = {};
|
|
const positionals: string[] = [];
|
|
const flagSet = new Set(spec.flags);
|
|
|
|
for (let i = 0; i < args.length; i++) {
|
|
const a = args[i];
|
|
if (a == null) continue;
|
|
if (a.startsWith('--')) {
|
|
const eq = a.indexOf('=');
|
|
const flagName = eq === -1 ? a : a.slice(0, eq);
|
|
if (!flagSet.has(flagName)) {
|
|
throw new WindowsError(
|
|
REASON.WINDOWS_USAGE,
|
|
`Unknown flag: ${flagName}`,
|
|
);
|
|
}
|
|
if (eq !== -1) {
|
|
values[flagName] = a.slice(eq + 1);
|
|
} else {
|
|
const next = args[i + 1];
|
|
if (next == null || next.startsWith('--')) {
|
|
if (!(flagName in values)) values[flagName] = undefined;
|
|
} else {
|
|
values[flagName] = next;
|
|
i++;
|
|
}
|
|
}
|
|
} else {
|
|
positionals.push(a);
|
|
}
|
|
}
|
|
|
|
for (const r of spec.required) {
|
|
if (values[r] == null || values[r] === '') {
|
|
throw new WindowsError(
|
|
REASON.WINDOWS_USAGE,
|
|
`Missing required flag: ${r}`,
|
|
);
|
|
}
|
|
}
|
|
|
|
const want = spec.positionals ?? 0;
|
|
if (positionals.length < want) {
|
|
throw new WindowsError(
|
|
REASON.WINDOWS_USAGE,
|
|
`Expected ${want} positional argument(s); got ${positionals.length}.`,
|
|
);
|
|
}
|
|
|
|
return { values, positionals };
|
|
}
|