i

Author: i1li

README.md

@@ -14,7 +14,7 @@
 <!-- END: docs-autogen-note -->
 
 <!-- BEGIN: test-status -->
-1/22 12:56:40 - Latest Status
+1/22 14:04:42 - Latest Status
 - Tests 1339/1339 - 100%
 - Lint 0 errors / 0 warnings
 - Type-check 0 errors / 0 warnings

RULES.md

@@ -28,7 +28,7 @@ Every task must be tracked in `TODO.md` using the prescribed workflow to ensure
 Code should be clean, minimalist, dynamic, and coherent in a self-documenting way that only requires minimal comments, with full descriptions reserved for that files's relevant .md file in /docs.
 
 
-## RULE 3: Test - /test
+## RULE 3: Test - /test SEE ALSO: /docs/test.md
 
 Core principle: Test real implementations, not mocks. Tests align with Polychron's core goal to maximize dynamism and evolution.
 

docs/test.md

@@ -138,6 +138,23 @@ npm run test
 npm run test:watch
 ```
 
+- Debug runs (optional, heavy, and opt-in):
+
+The repository includes diagnostic scripts that are intentionally kept separate from the default test flow to avoid slowing down everyday runs and to reduce noisy output. To enable debug-only diagnostics that may perform heavy instrumentation (for example, `scripts/debug-unit-coverage.js`), set the `DEBUG_UNIT_COVERAGE` environment variable or use the cross-platform helper script:
+
+```bash
+# Linux / macOS (env directly)
+DEBUG_UNIT_COVERAGE=1 npm run test
+
+# Cross-platform helper (works on Windows too):
+npm run test:debug
+```
+
+Notes:
+- The debug script `scripts/debug-unit-coverage.js` now guards itself and will no-op unless `DEBUG_UNIT_COVERAGE` is set. This prevents accidental long runs when invoked directly.
+- Prefer `npm run test:debug` for a portable way to execute the full test pipeline with diagnostics enabled.
+- Consider running debug diagnostics on demand or in nightly CI jobs rather than on every PR to keep CI fast and deterministic.
+
 - Docs maintenance:
 
 ```bash

package.json

@@ -36,6 +36,7 @@
     "test:loop": "node scripts/tests-loop.js",
     "test:quick": "node scripts/run-with-log.js test.log npm run test:raw && npm run docs:status",
     "test:composer-contract": "vitest --run test/composer.integration.test.ts test/composer.registry.strict.test.ts --reporter=dot",
+    "test:debug": "node scripts/test-debug.js",
     "lint": "node scripts/run-with-log.js lint.log npm run lint:raw",
     "lint:raw": "eslint src/**/*.{js,ts}",
     "type-check": "node scripts/run-with-log.js type-check.log npm run type-check:raw",

scripts/debug-unit-coverage.js

@@ -2,6 +2,12 @@ import { initializePlayEngine } from '../src/play.js';
 
 console.log('debug-unit-coverage: starting');
 
+// Only run this heavy diagnostic when explicitly enabled via env var to avoid accidental slow test runs
+if (!process.env.DEBUG_UNIT_COVERAGE) {
+  console.log('debug-unit-coverage: disabled. Set DEBUG_UNIT_COVERAGE=1 to enable (or use "npm run test:debug").');
+  process.exit(0);
+}
+
 function walkTree(node, path = [], results = []) {
   if (!node) return results;
   const keys = Object.keys(node.children || {});

scripts/docs.js

@@ -9,6 +9,7 @@ import readLogSafe from './utils/readLogSafe.js';
 import formatDate from './utils/formatDate.js';
 import splitByCodeFences from './utils/splitByCodeFences.js';
 import normalizeCodeForComparison from './utils/normalizeCodeForComparison.js';
+import { getFailuresFromLog } from './utils/getFailuresFromLog.js';
 
 const projectRoot = process.cwd();
 const srcDir = path.join(projectRoot, 'src');
@@ -214,6 +215,83 @@ function updateRootReadmeStatus() {
 }
 
 
+export { getFailuresFromLog };
+
+/*
+ * Scan root-level TODO*.md files and synchronize the "Test Failures" section with current log
+ * - Marks entries as fixed (checked) when the failure no longer appears in the log
+ * - Ensures ongoing failures remain unchecked
+ * - Appends any new failures that are not already present
+ */
+function updateTodosStatus() {
+  const failures = getFailuresFromLog();
+  const todoFiles = fs.readdirSync(projectRoot).filter(f => /^TODO(?:[-_].+)?\.md$/i.test(f));
+  if (todoFiles.length === 0) return;
+
+  for (const todo of todoFiles) {
+    const p = path.join(projectRoot, todo);
+    let content = fs.readFileSync(p, 'utf8');
+    const reSection = /(##\s*Test Failures[\s\S]*?)(?=\n##\s|$)/i;
+    const m = content.match(reSection);
+    if (!m) continue;
+
+    const section = m[1];
+    const lines = section.split(/\r?\n/);
+    const updated = [...lines];
+    let changed = false;
+
+    // Update existing items
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      if (!/^- \[[ x]?\]/.test(line)) continue;
+      const body = line.replace(/^\s*- \[[ x]?\]\s*/, '');
+      const parts = body.split('—').map(s => s.trim());
+      const locPart = parts[0] || '';
+      const descPart = parts[1] || '';
+
+      const matched = failures.find(f => (f.file && locPart.includes(f.file)) || (descPart && f.desc && descPart.includes(f.desc)));
+      if (matched) {
+        if (/^- \[x\]/i.test(line)) {
+          updated[i] = line.replace(/^- \[x\]/i, '- [ ]'); changed = true;
+        }
+        if (matched.msg && !line.includes(matched.msg)) { updated[i] = updated[i] + ` — ${matched.msg}`; changed = true; }
+      } else {
+        if (!/^- \[x\]/i.test(line)) {
+          const date = formatDate();
+          updated[i] = line.replace(/^- \[\s\]/i, '- [x]') + ` (fixed ${date})`; changed = true;
+        }
+      }
+    }
+
+    // Append any new failures
+    const existingKeys = new Set(lines.filter(l => /^- \[/.test(l)).map(l => l.replace(/\s*\(fixed.*?\)\s*$/, '').trim()));
+    const toAppend = [];
+    for (const f of failures) {
+      const candidate = `- [ ] ${f.loc || f.file} — ${f.desc}${f.msg ? ` — ${f.msg}` : ''}`;
+      if (!Array.from(existingKeys).some(k => k.includes(f.desc) || k.includes(f.file))) {
+        toAppend.push(candidate);
+      }
+    }
+
+    if (toAppend.length) {
+      const insertPos = m.index + section.length;
+      const before = content.slice(0, insertPos);
+      const after = content.slice(insertPos);
+      content = before + '\n' + toAppend.join('\n') + '\n' + after;
+      changed = true;
+    }
+
+    if (changed) {
+      // replace the old section text with the new updated block
+      const newSection = updated.join('\n');
+      content = content.replace(m[1], newSection);
+      fs.writeFileSync(p, content, 'utf8');
+      console.log(`Updated: ${todo} (synchronized with test.log)`);
+    }
+  }
+}
+
+
 function enforceLinksInText(text, isReadme=false) {
   let out = text;
   const codePrefix = isReadme ? 'src' : '../src';
@@ -478,7 +556,14 @@ if (cmd === 'fix') fixAll(verbose);
 else if (cmd === 'watch') watchAll();
 else if (cmd === 'check') checkAll();
 else if (cmd === 'index') generateIndex();
-else if (cmd === 'status') updateRootReadmeStatus();
+else if (cmd === 'status') {
+  updateRootReadmeStatus();
+  try {
+    updateTodosStatus();
+  } catch (e) {
+    console.error('Error updating TODO status:', e && e.message ? e.message : e);
+  }
+}
 else {
   console.error('Usage: node scripts/docs.js [fix|watch|check|index|status] [--verbose]');
   process.exit(1);

scripts/new-todo.js

@@ -19,6 +19,7 @@ function sanitizeName(raw) {
 }
 
 import makeTemplate from './utils/TODO-template.js';
+import { getFailuresFromLog } from './utils/getFailuresFromLog.js';
 
 const HEADER = makeTemplate(dateStr);
 
@@ -65,7 +66,7 @@ function usage() {
 /**
  * CLI entrypoint: create TODO.md with header and initial status block.
  */
-function main() {
+async function main() {
   const args = process.argv.slice(2);
 
   // Determine filename: default TODO.md, or TODO-<name>.md when a simple name is provided.
@@ -101,101 +102,31 @@ function main() {
   try {
     const logPath = path.join(projectRoot, 'log', 'test.log');
     if (fs.existsSync(logPath)) {
-      const logText = fs.readFileSync(logPath, 'utf8');
-      const lines = logText.split(/\r?\n/);
-      // Strip ANSI sequences (colors/formatting) for reliable regex matching
-      const stripAnsi = s => s.replace(/\x1b\[[0-9;]*m/g, '');
-      const cleanLines = lines.map(l => stripAnsi(l));
-
-      const failures = [];
-      // First, try to detect explicit FAIL lines (some reporters)
-      for (let i = 0; i < cleanLines.length; i++) {
-        const line = cleanLines[i];
-        const failMatch = line.match(/\bFAIL\b\s+(\S+)\s*>\s*(.+)$/i);
-        if (failMatch) {
-          const file = failMatch[1];
-          const desc = failMatch[2].trim().replace(/\s+/g, ' ');
-          // look ahead for error message and location markers
-          let msg = '';
-          let loc = '';
-          for (let j = i + 1; j < Math.min(cleanLines.length, i + 30); j++) {
-            const lraw = cleanLines[j];
-            const l = lraw.trim();
-            if (!loc) {
-              const locMatch = lraw.match(/❯\s*(\S+:\d+:\d+)/);
-              if (locMatch) loc = locMatch[1];
-            }
-            if (!msg) {
-              const errMatch = l.match(/^([A-Za-z0-9_]+Error|AssertionError|Error):\s*(.+)$/);
-              if (errMatch) { msg = errMatch[0]; break; }
-            }
-          }
-          if (!msg) {
-            for (let j = i + 1; j < Math.min(cleanLines.length, i + 10); j++) {
-              const l = cleanLines[j].trim();
-              if (l && !/^stdout|^\[|^·/.test(l)) { msg = l.replace(/\s+/g, ' '); break; }
-            }
-          }
-          failures.push({ file, loc, desc, msg });
-        }
-      }
-
-      // Second, detect vitest-style stdout/stderr lines that include the test file and description,
-      // followed shortly by an Error/Assertion message or stack trace.
-      const testLineRe = /(?:stdout|stderr)\s*\|\s*(\S+)\s*>\s*(.+)$/i;
-      for (let i = 0; i < cleanLines.length; i++) {
-        const m = cleanLines[i].match(testLineRe);
-        if (m) {
-          const file = m[1];
-          // description may include multiple '>' segments; use the last segment after '>' as the test name
-          const segments = m[2].split('>');
-          const desc = segments.map(s => s.trim()).filter(Boolean).slice(-1)[0] || segments[0].trim();
-
-          // look ahead for an Error/TypeError/Assertion message within the next 20 lines
-          let msg = '';
-          let loc = '';
-          for (let j = i + 1; j < Math.min(cleanLines.length, i + 40); j++) {
-            const lraw = cleanLines[j];
-            const l = lraw.trim();
-            if (!l) continue;
-            if (!loc) {
-              const locMatch = lraw.match(/(\S+\.ts:\d+:\d+)/);
-              if (locMatch) loc = locMatch[1];
-            }
-            const errMatch = l.match(/^([A-Za-z0-9_]+Error|AssertionError|Error|TypeError):\s*(.+)$/);
-            if (errMatch) { msg = errMatch[0]; break; }
-            const inlineErr = l.match(/Error:\s*(.+)/);
-            if (inlineErr) { msg = `Error: ${inlineErr[1]}`; break; }
-            if (cleanLines[j].match(testLineRe)) break;
-          }
-
-          if (msg) {
-            failures.push({ file, loc, desc: desc.replace(/\s+/g, ' '), msg });
+      try {
+        const failures = getFailuresFromLog(projectRoot);
+
+        if (failures.length > 0) {
+          const seen = new Set();
+          const linesToAppend = ['\n\n## Test Failures (from log/test.log)\n'];
+          for (const f of failures) {
+            const key = `${f.file}|${f.loc}|${f.desc}|${f.msg}`;
+            if (seen.has(key)) continue;
+            seen.add(key);
+            const locPart = f.loc ? `${f.loc}` : f.file;
+            const msgPart = f.msg ? ` — ${f.msg}` : '';
+            linesToAppend.push(`- [ ] ${locPart} — ${f.desc}${msgPart}`);
           }
+          fs.appendFileSync(todoPath, linesToAppend.join('\n') + '\n', 'utf8');
+          console.log(`Appended ${seen.size} test failure(s) from log/test.log to ${path.relative(projectRoot, todoPath)}`);
+        } else {
+          console.log('No test failures found in log/test.log to append.');
         }
-      }
-
-      if (failures.length > 0) {
-        // Deduplicate
-        const seen = new Set();
-        const linesToAppend = ['\n\n## Test Failures (from log/test.log)\n'];
-        for (const f of failures) {
-          const key = `${f.file}|${f.loc}|${f.desc}|${f.msg}`;
-          if (seen.has(key)) continue;
-          seen.add(key);
-          const locPart = f.loc ? `${f.loc}` : f.file;
-          const msgPart = f.msg ? ` — ${f.msg}` : '';
-          linesToAppend.push(`- [ ] ${locPart} — ${f.desc}${msgPart}`);
-        }
-        fs.appendFileSync(todoPath, linesToAppend.join('\n') + '\n', 'utf8');
-        console.log(`Appended ${seen.size} test failure(s) from log/test.log to ${path.relative(projectRoot, todoPath)}`);
-      } else {
-        console.log('No test failures found in log/test.log to append.');
+      } catch (e) {
+        console.error('Failed to detect test failures from log/test.log:', e && e.message ? e.message : e);
       }
     }
   } catch (e) {
     console.error('Warning: failed to parse or append test log:', e && e.message ? e.message : e);
-  }
-}
+  }}
 
 main();

scripts/run-with-log.js

@@ -6,7 +6,10 @@
 import { spawn } from 'child_process';
 import { createWriteStream } from 'fs';
 import { mkdir } from 'fs/promises';
+import stripAnsi from './utils/stripAnsi.js';
+import path from 'path';
 
+const cwd = process.cwd();
 const [, , logFile, ...command] = process.argv;
 
 if (!logFile || command.length === 0) {
@@ -21,17 +24,58 @@ await mkdir('log', { recursive: true });
 const logStream = createWriteStream(`log/${logFile}`);
 const proc = spawn(command[0], command.slice(1), { shell: true, stdio: 'pipe' });
 
+/**
+ * Normalize a single line for the persistent log:
+ * - Strip ANSI escapes
+ * - Replace absolute repo paths with relative ones
+ * - Shorten node_modules references
+ * - Prefix with a timestamp and stream label (STDOUT/STDERR)
+ */
+function normalizeForLog(line, label = 'STDOUT') {
+  let s = String(line || '');
+  s = stripAnsi(s);
+  // Collapse file:// prefixes that appear in stack traces
+  s = s.replace(/file:\/\/[\/\\]*/g, '');
+  // Replace absolute repository-root paths with a short <repo>/ prefix
+  if (cwd && typeof s === 'string') {
+    const safeCwd = cwd.replace(/\\/g, '/');
+    s = s.split(safeCwd).join('<repo>');
+  }
+  // Collapse repetitive node_modules paths to a concise token
+  s = s.replace(/node_modules[\\\/](@?[^\\\/\s]+)[\\\/]?/g, 'node_modules/$1/...');
+  // Omit timestamps for a cleaner persistent log
+  return `${label}: ${s}`;
+}
+
+function writeNormalized(streamLabel, chunk) {
+  // Split into lines and write each normalized line
+  const raw = String(chunk);
+  const lines = raw.split(/\r?\n/);
+  for (let i = 0; i < lines.length; i++) {
+    const l = lines[i];
+    if (l === '' && i === lines.length - 1) continue; // trailing newline
+    const normalized = normalizeForLog(l, streamLabel) + '\n';
+    logStream.write(normalized);
+  }
+}
+
 proc.stdout.on('data', (data) => {
+  // Mirror colored output to console for developer convenience
   process.stdout.write(data);
-  logStream.write(data);
+  // Write a cleaned, timestamped copy to the persistent log
+  writeNormalized('STDOUT', data);
 });
 
 proc.stderr.on('data', (data) => {
+  // Mirror colored output to console
   process.stderr.write(data);
-  logStream.write(data);
+  // Clean and write to the persistent log, labeled STDERR
+  writeNormalized('STDERR', data);
 });
 
 proc.on('close', (code) => {
+  const summary = `[${new Date().toISOString()}] PROCESS EXIT: code=${code}\n`;
+  logStream.write(summary);
   logStream.end();
   process.exit(code);
 });

scripts/test-debug.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+// Historically this was a .cjs shim to handle Windows `npm.cmd` spawn behavior; now ESM with explicit platform handling.
+import { spawnSync } from 'child_process';
+
+console.log('test:debug - running tests with DEBUG_UNIT_COVERAGE=1');
+
+const env = { ...process.env, DEBUG_UNIT_COVERAGE: '1' };
+const npmCmd = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+
+const res = spawnSync(npmCmd, ['run', 'test'], { stdio: 'inherit', env });
+if (res.error) {
+  console.error('test:debug failed to start tests', res.error);
+  process.exit(1);
+}
+process.exit(res.status || 0);