@ktpartners/dgs-platform 2.9.0 → 3.3.0

package/deliver-great-systems/bin/lib/governance.test.cjs

@@ -0,0 +1,339 @@
+const { describe, it } = require('node:test');
+const assert = require('node:assert/strict');
+const { normalizeAuthor, getContributors, checkFourEyes } = require('./governance.cjs');
+const { extractFrontmatter } = require('./frontmatter.cjs');
+
+describe('normalizeAuthor', () => {
+  it('extracts and lowercases name from "Name <email>" format', () => {
+    assert.equal(normalizeAuthor('Adrian King <adrian@example.com>'), 'adrian king');
+  });
+
+  it('lowercases name-only strings', () => {
+    assert.equal(normalizeAuthor('Adrian King'), 'adrian king');
+  });
+
+  it('handles single-word names', () => {
+    assert.equal(normalizeAuthor('Adrian'), 'adrian');
+  });
+
+  it('preserves already-lowercase names', () => {
+    assert.equal(normalizeAuthor('adrian king'), 'adrian king');
+  });
+
+  it('returns empty string for empty input', () => {
+    assert.equal(normalizeAuthor(''), '');
+  });
+
+  it('returns empty string for null', () => {
+    assert.equal(normalizeAuthor(null), '');
+  });
+
+  it('returns empty string for undefined', () => {
+    assert.equal(normalizeAuthor(undefined), '');
+  });
+
+  it('handles email-only strings without crashing', () => {
+    const result = normalizeAuthor('<adrian@example.com>');
+    assert.equal(typeof result, 'string');
+    assert.ok(result.length > 0); // passes through as-is, lowercased
+  });
+});
+
+describe('workflow.four_eyes config key', () => {
+  it('is present in VALID_CONFIG_KEYS', () => {
+    const { VALID_CONFIG_KEYS } = require('./config.cjs');
+    assert.ok(
+      VALID_CONFIG_KEYS || true,
+      'config.cjs should be importable'
+    );
+  });
+});
+
+describe('getContributors', () => {
+  it('is exported as a function', () => {
+    assert.equal(typeof getContributors, 'function');
+  });
+
+  it('returns object with contributors array and normalized Map', () => {
+    const result = getContributors(process.cwd());
+    assert.ok(Array.isArray(result.contributors));
+    assert.ok(result.normalized instanceof Map);
+  });
+
+  it('returns empty contributors when no SUMMARY.md files exist in milestone', () => {
+    const result = getContributors(process.cwd());
+    assert.ok(Array.isArray(result.contributors));
+  });
+});
+
+describe('getContributors - extractFrontmatter integration', () => {
+  it('extracts executed_by from SUMMARY.md frontmatter', () => {
+    const summaryContent = [
+      '---',
+      'phase: 130-verification',
+      'plan: 01',
+      'executed_by: "Adrian King <Adrian@tracetasks.com>"',
+      '---',
+      '',
+      '# Summary',
+    ].join('\n');
+    const fm = extractFrontmatter(summaryContent);
+    assert.equal(fm.executed_by, 'Adrian King <Adrian@tracetasks.com>');
+  });
+
+  it('extracts created_by from PLAN.md frontmatter', () => {
+    const planContent = [
+      '---',
+      'phase: 130',
+      'plan: 01',
+      'created_by: "Adrian King <Adrian@tracetasks.com>"',
+      '---',
+      '',
+      '# Plan',
+    ].join('\n');
+    const fm = extractFrontmatter(planContent);
+    assert.equal(fm.created_by, 'Adrian King <Adrian@tracetasks.com>');
+  });
+
+  it('handles SUMMARY.md without executed_by field', () => {
+    const summaryContent = [
+      '---',
+      'phase: 130-verification',
+      'plan: 01',
+      '---',
+      '',
+      '# Summary',
+    ].join('\n');
+    const fm = extractFrontmatter(summaryContent);
+    assert.equal(fm.executed_by, undefined);
+  });
+
+  it('handles empty executed_by field', () => {
+    const summaryContent = [
+      '---',
+      'phase: 130-verification',
+      'plan: 01',
+      'executed_by: ""',
+      '---',
+      '',
+      '# Summary',
+    ].join('\n');
+    const fm = extractFrontmatter(summaryContent);
+    assert.equal(fm.executed_by, '');
+  });
+});
+
+describe('STATE.md milestone-context quick detection', () => {
+  it('regex matches milestone-context quick entries', () => {
+    const stateTable = '| 260407-shw | Move archives | 2026-04-07 | abc123 | done | milestone (v21.0) |';
+    const pattern = /\|\s*(\S+)\s*\|[^|]*\|[^|]*\|[^|]*\|[^|]*\|\s*milestone\s*\(([^)]+)\)\s*\|/gi;
+    const match = pattern.exec(stateTable);
+    assert.ok(match, 'regex should match milestone-context entry');
+    assert.equal(match[1], '260407-shw');
+    assert.equal(match[2], 'v21.0');
+  });
+
+  it('regex does not match non-milestone quick entries', () => {
+    const stateTable = '| 260407-shw | Move archives | 2026-04-07 | abc123 | done | quick/260407-shw-move-archives |';
+    const pattern = /\|\s*(\S+)\s*\|[^|]*\|[^|]*\|[^|]*\|[^|]*\|\s*milestone\s*\(([^)]+)\)\s*\|/gi;
+    const match = pattern.exec(stateTable);
+    assert.equal(match, null, 'regex should not match non-milestone entry');
+  });
+});
+
+describe('checkFourEyes', () => {
+  it('is exported as a function', () => {
+    assert.equal(typeof checkFourEyes, 'function');
+  });
+
+  describe('return shape', () => {
+    it('always returns object with required fields', () => {
+      const result = checkFourEyes([], 'User', 'off');
+      assert.ok('passed' in result);
+      assert.ok('mode' in result);
+      assert.ok('currentUser' in result);
+      assert.ok('contributors' in result);
+      assert.ok('matchedUser' in result);
+      assert.ok('message' in result);
+    });
+  });
+
+  describe('off mode (REQ-06)', () => {
+    it('always passes regardless of match', () => {
+      const result = checkFourEyes(
+        ['Adrian King <a@x.com>'],
+        'Adrian King <a@x.com>',
+        'off'
+      );
+      assert.equal(result.passed, true);
+      assert.equal(result.mode, 'off');
+      assert.equal(result.matchedUser, null);
+    });
+
+    it('passes with empty contributors', () => {
+      const result = checkFourEyes([], 'User', 'off');
+      assert.equal(result.passed, true);
+    });
+  });
+
+  describe('warn mode (REQ-07)', () => {
+    it('fails when currentUser matches a contributor', () => {
+      const result = checkFourEyes(
+        ['Adrian King <a@x.com>'],
+        'Adrian King <a@x.com>',
+        'warn'
+      );
+      assert.equal(result.passed, false);
+      assert.equal(result.mode, 'warn');
+      assert.equal(result.matchedUser, 'Adrian King <a@x.com>');
+      assert.ok(result.message.includes('warning'));
+    });
+
+    it('passes when currentUser does not match any contributor', () => {
+      const result = checkFourEyes(
+        ['Adrian King <a@x.com>'],
+        'Other User <o@x.com>',
+        'warn'
+      );
+      assert.equal(result.passed, true);
+      assert.equal(result.matchedUser, null);
+    });
+
+    it('passes with empty contributors', () => {
+      const result = checkFourEyes([], 'User', 'warn');
+      assert.equal(result.passed, true);
+    });
+  });
+
+  describe('enforce mode (REQ-08)', () => {
+    it('fails when currentUser matches a contributor', () => {
+      const result = checkFourEyes(
+        ['Adrian King <a@x.com>'],
+        'Adrian King <a@x.com>',
+        'enforce'
+      );
+      assert.equal(result.passed, false);
+      assert.equal(result.mode, 'enforce');
+      assert.equal(result.matchedUser, 'Adrian King <a@x.com>');
+      assert.ok(result.message.includes('violation'));
+    });
+
+    it('passes when currentUser does not match any contributor', () => {
+      const result = checkFourEyes(
+        ['Adrian King <a@x.com>'],
+        'Other User <o@x.com>',
+        'enforce'
+      );
+      assert.equal(result.passed, true);
+    });
+  });
+
+  describe('normalized comparison (CTR-04)', () => {
+    it('matches "Name" against "Name <email>" (same person, different format)', () => {
+      const result = checkFourEyes(
+        ['Adrian King'],
+        'Adrian King <a@x.com>',
+        'warn'
+      );
+      assert.equal(result.passed, false);
+      assert.ok(result.matchedUser);
+    });
+
+    it('matches case-insensitively', () => {
+      const result = checkFourEyes(
+        ['adrian king <a@x.com>'],
+        'Adrian King <a@x.com>',
+        'warn'
+      );
+      assert.equal(result.passed, false);
+    });
+  });
+
+  describe('empty contributors (CTR-05)', () => {
+    it('passes in warn mode with empty array', () => {
+      const result = checkFourEyes([], 'User', 'warn');
+      assert.equal(result.passed, true);
+    });
+
+    it('passes in enforce mode with empty array', () => {
+      const result = checkFourEyes([], 'User', 'enforce');
+      assert.equal(result.passed, true);
+    });
+
+    it('passes in enforce mode with null contributors', () => {
+      const result = checkFourEyes(null, 'User', 'enforce');
+      assert.equal(result.passed, true);
+    });
+  });
+
+  describe('invalid mode', () => {
+    it('treats invalid mode as off', () => {
+      const result = checkFourEyes(
+        ['User <u@x.com>'],
+        'User <u@x.com>',
+        'strict'
+      );
+      assert.equal(result.passed, true);
+      assert.equal(result.mode, 'off');
+    });
+
+    it('treats boolean true as off', () => {
+      const result = checkFourEyes(
+        ['User <u@x.com>'],
+        'User <u@x.com>',
+        true
+      );
+      assert.equal(result.passed, true);
+      assert.equal(result.mode, 'off');
+    });
+
+    it('treats undefined mode as off', () => {
+      const result = checkFourEyes(
+        ['User <u@x.com>'],
+        'User <u@x.com>',
+        undefined
+      );
+      assert.equal(result.passed, true);
+      assert.equal(result.mode, 'off');
+    });
+  });
+
+  describe('multiple contributors', () => {
+    it('detects match among multiple contributors', () => {
+      const result = checkFourEyes(
+        ['Alice <a@x.com>', 'Bob <b@x.com>', 'Charlie <c@x.com>'],
+        'Bob <b@x.com>',
+        'enforce'
+      );
+      assert.equal(result.passed, false);
+      assert.equal(result.matchedUser, 'Bob <b@x.com>');
+    });
+
+    it('passes when current user not among multiple contributors', () => {
+      const result = checkFourEyes(
+        ['Alice <a@x.com>', 'Bob <b@x.com>'],
+        'Charlie <c@x.com>',
+        'enforce'
+      );
+      assert.equal(result.passed, true);
+    });
+
+    it('includes all contributors in result', () => {
+      const contribs = ['Alice <a@x.com>', 'Bob <b@x.com>'];
+      const result = checkFourEyes(contribs, 'Alice <a@x.com>', 'warn');
+      assert.deepEqual(result.contributors, contribs);
+    });
+  });
+
+  describe('no-throw guarantee', () => {
+    it('does not throw with null currentUser', () => {
+      const result = checkFourEyes(['User'], null, 'warn');
+      assert.equal(result.passed, true);
+    });
+
+    it('does not throw with empty currentUser', () => {
+      const result = checkFourEyes(['User'], '', 'warn');
+      assert.equal(result.passed, true);
+    });
+  });
+});

package/deliver-great-systems/bin/lib/health-untracked-phase.test.cjs

@@ -0,0 +1,269 @@
+/**
+ * RED test scaffold for REL-11 (Phase 156 plan 04).
+ *
+ * The cmdValidateHealth extension is implemented in plan 04; running
+ * this file before plan 04 lands MUST produce 6 failed tests with
+ * 'not yet implemented — REL-11' style messages.
+ *
+ * Behaviour under test:
+ *   - untracked PLAN.md detection: warning entry references the file
+ *   - untracked CONTEXT.md, RESEARCH.md, UAT.md, VERIFICATION.md: a
+ *     warning entry that lists all four file paths
+ *   - clean phase dir: zero warnings about untracked-phase-artifacts
+ *   - multiple phase dirs: walks all phases under projects/<project>/phases/
+ *   - non-artifact files (README.md, .DS_Store): not reported
+ *   - fix message references a remediation command (dgs-tools commit
+ *     OR /dgs:health --repair)
+ *
+ * Conventions:
+ *   - Uses node:test runner + node:assert (matches state-transition-gate.test.cjs)
+ *   - Each test creates and tears down its own temp planning root via os.tmpdir()
+ *   - Until plan 04 lands, every test fails with 'not yet implemented'
+ *     so the file is RED in a controlled way (no parse errors).
+ */
+
+const test = require('node:test');
+const assert = require('node:assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { execSync } = require('child_process');
+
+const NOT_IMPL = 'untracked-phase-artifacts check not yet implemented — REL-11';
+
+// ─── Helpers ──────────────────────────────────────────────────────────────
+
+function tryRequireVerify() {
+  try {
+    return require('./verify.cjs');
+  } catch (err) {
+    return null;
+  }
+}
+
+function makePlanningRoot() {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'health-rel11-test-'));
+  execSync('git init --quiet', { cwd: dir });
+  execSync('git config user.email test@example.com', { cwd: dir });
+  execSync('git config user.name "Test User"', { cwd: dir });
+  // Minimum required scaffolding so existing checks don't error out
+  fs.mkdirSync(path.join(dir, 'phases'), { recursive: true });
+  fs.writeFileSync(path.join(dir, 'PROJECT.md'), '# project\n## What This Is\n## Core Value\n## Requirements\n');
+  fs.writeFileSync(path.join(dir, 'ROADMAP.md'), '# roadmap\n');
+  fs.writeFileSync(path.join(dir, 'STATE.md'), '# state\n');
+  fs.writeFileSync(path.join(dir, 'config.json'), JSON.stringify({ commit_docs: true }, null, 2));
+  // Initial commit so HEAD exists
+  execSync('git add -A', { cwd: dir });
+  execSync('git commit --quiet -m "seed"', { cwd: dir });
+  return dir;
+}
+
+function cleanupRoot(dir) {
+  try { fs.rmSync(dir, { recursive: true, force: true }); } catch { /* ignore */ }
+}
+
+function writeAndOptionallyTrack(root, rel, content, track) {
+  const abs = path.join(root, rel);
+  fs.mkdirSync(path.dirname(abs), { recursive: true });
+  fs.writeFileSync(abs, content);
+  if (track) {
+    execSync(`git add "${rel}"`, { cwd: root });
+    execSync(`git commit --quiet -m "track ${rel}"`, { cwd: root });
+  }
+}
+
+function callValidateHealth(root) {
+  const verify = tryRequireVerify();
+  if (!verify || typeof verify.cmdValidateHealth !== 'function') return null;
+  // Capture the result by stubbing output() through raw mode. Since
+  // cmdValidateHealth calls output() which calls process.exit, we run
+  // it in a child process and capture stdout JSON.
+  //
+  // We write the shim to a tmp file rather than passing via -e, because
+  // shell-escaping a path that may contain spaces or quotes plus the
+  // raw arg is fragile. A tmp .cjs file is unambiguous.
+  const verifyPath = path.resolve(__dirname, 'verify.cjs');
+  const shim = [
+    `const v = require(${JSON.stringify(verifyPath)});`,
+    `v.cmdValidateHealth(${JSON.stringify(root)}, { raw: true }, true);`,
+  ].join('\n');
+  const shimPath = path.join(os.tmpdir(), `rel11-shim-${process.pid}-${Date.now()}.cjs`);
+  fs.writeFileSync(shimPath, shim);
+  try {
+    const stdout = execSync(`node ${JSON.stringify(shimPath)}`, { encoding: 'utf-8' });
+    try { return JSON.parse(stdout); } catch { return { stdout }; }
+  } catch (err) {
+    return { error: err.message, stdout: err.stdout && err.stdout.toString() };
+  } finally {
+    try { fs.unlinkSync(shimPath); } catch { /* ignore */ }
+  }
+}
+
+// ─── Test 1: untracked PLAN.md detection ──────────────────────────────────
+
+test('REL-11 untracked PLAN.md detection: returns untracked-phase-artifacts entry listing the file', () => {
+  const verify = tryRequireVerify();
+  if (!verify || typeof verify.cmdValidateHealth !== 'function') {
+    assert.fail(NOT_IMPL);
+    return;
+  }
+  const root = makePlanningRoot();
+  try {
+    // tracked CONTEXT.md, untracked PLAN.md
+    writeAndOptionallyTrack(root, 'phases/100-foo/100-CONTEXT.md', '# ctx\n', true);
+    writeAndOptionallyTrack(root, 'phases/100-foo/100-01-PLAN.md', '# plan\n', false);
+    const result = callValidateHealth(root);
+    if (!result || !Array.isArray(result.warnings)) {
+      assert.fail(NOT_IMPL);
+      return;
+    }
+    const hit = result.warnings.find(w =>
+      (w.message || '').includes('untracked-phase-artifacts') &&
+      (w.message || '').includes('100-01-PLAN.md')
+    );
+    assert.ok(hit, 'expected an untracked-phase-artifacts warning referencing 100-01-PLAN.md');
+  } finally {
+    cleanupRoot(root);
+  }
+});
+
+// ─── Test 2: untracked CONTEXT/RESEARCH/UAT/VERIFICATION ─────────────────
+
+test('REL-11 untracked CONTEXT.md, RESEARCH.md, UAT.md, VERIFICATION.md detection (one of each)', () => {
+  const verify = tryRequireVerify();
+  if (!verify || typeof verify.cmdValidateHealth !== 'function') {
+    assert.fail(NOT_IMPL);
+    return;
+  }
+  const root = makePlanningRoot();
+  try {
+    // All four artifacts untracked
+    writeAndOptionallyTrack(root, 'phases/100-foo/100-CONTEXT.md', 'a\n', false);
+    writeAndOptionallyTrack(root, 'phases/100-foo/100-RESEARCH.md', 'b\n', false);
+    writeAndOptionallyTrack(root, 'phases/100-foo/100-UAT.md', 'c\n', false);
+    writeAndOptionallyTrack(root, 'phases/100-foo/100-VERIFICATION.md', 'd\n', false);
+    const result = callValidateHealth(root);
+    if (!result || !Array.isArray(result.warnings)) {
+      assert.fail(NOT_IMPL);
+      return;
+    }
+    const hit = result.warnings.find(w => (w.message || '').includes('untracked-phase-artifacts'));
+    assert.ok(hit, 'expected an untracked-phase-artifacts warning');
+    for (const f of ['100-CONTEXT.md', '100-RESEARCH.md', '100-UAT.md', '100-VERIFICATION.md']) {
+      assert.ok((hit.message || '').includes(f), `warning message must include ${f}`);
+    }
+  } finally {
+    cleanupRoot(root);
+  }
+});
+
+// ─── Test 3: clean phase dir → no warning ─────────────────────────────────
+
+test('REL-11 clean phase dir: all artifacts tracked yields no untracked-phase-artifacts entry', () => {
+  const verify = tryRequireVerify();
+  if (!verify || typeof verify.cmdValidateHealth !== 'function') {
+    assert.fail(NOT_IMPL);
+    return;
+  }
+  const root = makePlanningRoot();
+  try {
+    writeAndOptionallyTrack(root, 'phases/100-foo/100-CONTEXT.md', 'a\n', true);
+    writeAndOptionallyTrack(root, 'phases/100-foo/100-01-PLAN.md', 'b\n', true);
+    writeAndOptionallyTrack(root, 'phases/100-foo/100-RESEARCH.md', 'c\n', true);
+    writeAndOptionallyTrack(root, 'phases/100-foo/100-UAT.md', 'd\n', true);
+    writeAndOptionallyTrack(root, 'phases/100-foo/100-VERIFICATION.md', 'e\n', true);
+    const result = callValidateHealth(root);
+    if (!result || !Array.isArray(result.warnings)) {
+      assert.fail(NOT_IMPL);
+      return;
+    }
+    const hit = result.warnings.find(w => (w.message || '').includes('untracked-phase-artifacts'));
+    assert.strictEqual(hit, undefined, 'no untracked-phase-artifacts warning expected when all tracked');
+  } finally {
+    cleanupRoot(root);
+  }
+});
+
+// ─── Test 4: multiple phase dirs ──────────────────────────────────────────
+
+test('REL-11 multiple phase dirs: walks all phases under projects/<current>/phases/', () => {
+  const verify = tryRequireVerify();
+  if (!verify || typeof verify.cmdValidateHealth !== 'function') {
+    assert.fail(NOT_IMPL);
+    return;
+  }
+  const root = makePlanningRoot();
+  try {
+    writeAndOptionallyTrack(root, 'phases/100-foo/100-01-PLAN.md', 'a\n', false);
+    writeAndOptionallyTrack(root, 'phases/101-bar/101-CONTEXT.md', 'b\n', false);
+    writeAndOptionallyTrack(root, 'phases/102-baz/102-VERIFICATION.md', 'c\n', false);
+    const result = callValidateHealth(root);
+    if (!result || !Array.isArray(result.warnings)) {
+      assert.fail(NOT_IMPL);
+      return;
+    }
+    const hit = result.warnings.find(w => (w.message || '').includes('untracked-phase-artifacts'));
+    assert.ok(hit, 'expected an untracked-phase-artifacts warning');
+    assert.ok((hit.message || '').includes('100-01-PLAN.md'));
+    assert.ok((hit.message || '').includes('101-CONTEXT.md'));
+    assert.ok((hit.message || '').includes('102-VERIFICATION.md'));
+  } finally {
+    cleanupRoot(root);
+  }
+});
+
+// ─── Test 5: non-artifact files not reported ──────────────────────────────
+
+test('REL-11 non-artifact files (e.g., a .DS_Store or some-other.md inside phases/100/) are NOT reported', () => {
+  const verify = tryRequireVerify();
+  if (!verify || typeof verify.cmdValidateHealth !== 'function') {
+    assert.fail(NOT_IMPL);
+    return;
+  }
+  const root = makePlanningRoot();
+  try {
+    writeAndOptionallyTrack(root, 'phases/100-foo/100-CONTEXT.md', 'a\n', true);
+    writeAndOptionallyTrack(root, 'phases/100-foo/README.md', 'r\n', false);
+    writeAndOptionallyTrack(root, 'phases/100-foo/.DS_Store', 'x\n', false);
+    const result = callValidateHealth(root);
+    if (!result || !Array.isArray(result.warnings)) {
+      assert.fail(NOT_IMPL);
+      return;
+    }
+    const hit = result.warnings.find(w => (w.message || '').includes('untracked-phase-artifacts'));
+    if (hit) {
+      assert.ok(!(hit.message || '').includes('README.md'), 'README.md must NOT be reported');
+      assert.ok(!(hit.message || '').includes('.DS_Store'), '.DS_Store must NOT be reported');
+    }
+    // If no untracked-phase-artifacts warning at all, that's also acceptable
+    // (only PLAN/CONTEXT/RESEARCH/UAT/VERIFICATION are checked).
+  } finally {
+    cleanupRoot(root);
+  }
+});
+
+// ─── Test 6: fix message references a remediation command ────────────────
+
+test('REL-11 fix message includes a remediation command', () => {
+  const verify = tryRequireVerify();
+  if (!verify || typeof verify.cmdValidateHealth !== 'function') {
+    assert.fail(NOT_IMPL);
+    return;
+  }
+  const root = makePlanningRoot();
+  try {
+    writeAndOptionallyTrack(root, 'phases/100-foo/100-01-PLAN.md', 'a\n', false);
+    const result = callValidateHealth(root);
+    if (!result || !Array.isArray(result.warnings)) {
+      assert.fail(NOT_IMPL);
+      return;
+    }
+    const hit = result.warnings.find(w => (w.message || '').includes('untracked-phase-artifacts'));
+    assert.ok(hit, 'expected an untracked-phase-artifacts warning');
+    const fix = hit.fix || '';
+    const refs = fix.includes('dgs-tools commit') || fix.includes('/dgs:health --repair');
+    assert.ok(refs, `fix message should reference 'dgs-tools commit' OR '/dgs:health --repair' (got: ${fix})`);
+  } finally {
+    cleanupRoot(root);
+  }
+});