@ktpartners/dgs-platform 2.6.2

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

@@ -0,0 +1,486 @@
+/**
+ * Tests for paths.cjs — Planning root detection and PATHS singleton
+ *
+ * Uses Node.js built-in test runner (node:test) and assert (node:assert/strict).
+ * Each test creates an isolated temp directory fixture and cleans up after.
+ *
+ * Covers PATH-01 through PATH-05 requirements.
+ */
+
+const { describe, it, afterEach } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const { getPlanningRoot, getPaths, initPaths, resetPaths, PROJECTS_DIR } = require('./paths.cjs');
+
+// ─── Helpers ────────────────────────────────────────────────────────────────
+
+function makeTempDir() {
+  return fs.mkdtempSync(path.join(os.tmpdir(), 'dgs-paths-test-'));
+}
+
+function removeTempDir(dir) {
+  fs.rmSync(dir, { recursive: true, force: true });
+}
+
+// ─── 1. Detection cascade — .planning/ layout (PATH-01, PATH-02) ────────────
+
+describe('detection cascade — .planning/ layout', () => {
+  let cwd;
+
+  afterEach(() => {
+    resetPaths();
+    if (cwd) removeTempDir(cwd);
+    cwd = null;
+  });
+
+  it('detects .planning/ layout from .planning/dgs.config.json', () => {
+    cwd = makeTempDir();
+    fs.mkdirSync(path.join(cwd, '.planning'), { recursive: true });
+    fs.writeFileSync(path.join(cwd, '.planning', 'dgs.config.json'), '{}');
+
+    const root = getPlanningRoot(cwd);
+    assert.equal(root, path.join(cwd, '.planning'));
+  });
+
+  it('detects .planning/ layout from .planning/config.json', () => {
+    cwd = makeTempDir();
+    fs.mkdirSync(path.join(cwd, '.planning'), { recursive: true });
+    fs.writeFileSync(path.join(cwd, '.planning', 'config.json'), '{}');
+
+    const root = getPlanningRoot(cwd);
+    assert.equal(root, path.join(cwd, '.planning'));
+  });
+
+  it('detects .planning/ layout when both config files exist', () => {
+    cwd = makeTempDir();
+    fs.mkdirSync(path.join(cwd, '.planning'), { recursive: true });
+    fs.writeFileSync(path.join(cwd, '.planning', 'dgs.config.json'), '{}');
+    fs.writeFileSync(path.join(cwd, '.planning', 'config.json'), '{}');
+
+    const root = getPlanningRoot(cwd);
+    assert.equal(root, path.join(cwd, '.planning'));
+  });
+});
+
+// ─── 2. Detection cascade — root layout (PATH-01, PATH-02) ──────────────────
+
+describe('detection cascade — root layout', () => {
+  let cwd;
+
+  afterEach(() => {
+    resetPaths();
+    if (cwd) removeTempDir(cwd);
+    cwd = null;
+  });
+
+  it('detects root layout from dgs.config.json with planningRoot "."', () => {
+    cwd = makeTempDir();
+    fs.writeFileSync(
+      path.join(cwd, 'dgs.config.json'),
+      JSON.stringify({ planningRoot: '.' })
+    );
+
+    const root = getPlanningRoot(cwd);
+    assert.equal(root, cwd);
+  });
+
+  it('returns .planning/ when root dgs.config.json has no planningRoot field', () => {
+    cwd = makeTempDir();
+    fs.writeFileSync(
+      path.join(cwd, 'dgs.config.json'),
+      JSON.stringify({ mode: 'interactive' })
+    );
+
+    const root = getPlanningRoot(cwd);
+    assert.equal(root, path.join(cwd, '.planning'));
+  });
+
+  it('falls through when root dgs.config.json has malformed JSON', () => {
+    cwd = makeTempDir();
+    fs.writeFileSync(path.join(cwd, 'dgs.config.json'), '{not valid json!!!');
+
+    // Should NOT crash — falls through to default
+    const root = getPlanningRoot(cwd);
+    // Malformed config falls through; no PROJECT.md => default .planning/
+    assert.equal(root, path.join(cwd, '.planning'));
+  });
+
+  it('auto-detects root layout when PROJECT.md exists at root with no .planning/ dir', () => {
+    cwd = makeTempDir();
+    fs.writeFileSync(path.join(cwd, 'PROJECT.md'), '# Project: Test');
+
+    const root = getPlanningRoot(cwd);
+    assert.equal(root, cwd);
+  });
+
+  it('returns .planning/ when PROJECT.md exists at root AND .planning/ directory exists', () => {
+    cwd = makeTempDir();
+    fs.writeFileSync(path.join(cwd, 'PROJECT.md'), '# Project: Test');
+    fs.mkdirSync(path.join(cwd, '.planning'), { recursive: true });
+
+    const root = getPlanningRoot(cwd);
+    assert.equal(root, path.join(cwd, '.planning'));
+  });
+});
+
+// ─── 3. Detection cascade — default (PATH-02) ───────────────────────────────
+
+describe('detection cascade — default', () => {
+  let cwd;
+
+  afterEach(() => {
+    resetPaths();
+    if (cwd) removeTempDir(cwd);
+    cwd = null;
+  });
+
+  it('defaults to .planning/ when no signals are found', () => {
+    cwd = makeTempDir();
+
+    const root = getPlanningRoot(cwd);
+    assert.equal(root, path.join(cwd, '.planning'));
+  });
+});
+
+// ─── 4. Detection cascade — priority (PATH-02) ──────────────────────────────
+
+describe('detection cascade — priority', () => {
+  let cwd;
+
+  afterEach(() => {
+    resetPaths();
+    if (cwd) removeTempDir(cwd);
+    cwd = null;
+  });
+
+  it('.planning/config.json takes precedence over root dgs.config.json with planningRoot "."', () => {
+    cwd = makeTempDir();
+    // .planning/ layout signal
+    fs.mkdirSync(path.join(cwd, '.planning'), { recursive: true });
+    fs.writeFileSync(path.join(cwd, '.planning', 'config.json'), '{}');
+    // Root layout signal
+    fs.writeFileSync(
+      path.join(cwd, 'dgs.config.json'),
+      JSON.stringify({ planningRoot: '.' })
+    );
+
+    const root = getPlanningRoot(cwd);
+    assert.equal(root, path.join(cwd, '.planning'));
+  });
+});
+
+// ─── 5. PATHS object shape (PATH-03) ────────────────────────────────────────
+
+describe('PATHS object shape', () => {
+  let cwd;
+
+  afterEach(() => {
+    resetPaths();
+    if (cwd) removeTempDir(cwd);
+    cwd = null;
+  });
+
+  const EXPECTED_KEYS = [
+    'ROOT', 'PHASES', 'IDEAS', 'SPECS', 'JOBS', 'DOCS',
+    'CODEBASE', 'MILESTONES', 'CONFIG', 'CONFIG_LEGACY',
+    'QUICK', 'TODOS', 'RESEARCH', 'DEBUG', 'ARCHIVE', 'PROJECTS', 'LAYOUT',
+  ];
+
+  it('returns object with all 17 expected keys', () => {
+    cwd = makeTempDir();
+    fs.mkdirSync(path.join(cwd, '.planning'), { recursive: true });
+    fs.writeFileSync(path.join(cwd, '.planning', 'config.json'), '{}');
+
+    const paths = getPaths(cwd);
+    assert.deepEqual(Object.keys(paths).sort(), EXPECTED_KEYS.slice().sort());
+  });
+
+  it('for .planning/ layout: ROOT ends with .planning and LAYOUT is dotplanning', () => {
+    cwd = makeTempDir();
+    fs.mkdirSync(path.join(cwd, '.planning'), { recursive: true });
+    fs.writeFileSync(path.join(cwd, '.planning', 'config.json'), '{}');
+
+    const paths = getPaths(cwd);
+    assert.ok(paths.ROOT.endsWith('.planning'));
+    assert.equal(paths.LAYOUT, 'dotplanning');
+  });
+
+  it('for root layout: ROOT equals cwd and LAYOUT is root', () => {
+    cwd = makeTempDir();
+    fs.writeFileSync(
+      path.join(cwd, 'dgs.config.json'),
+      JSON.stringify({ planningRoot: '.' })
+    );
+
+    const paths = getPaths(cwd);
+    assert.equal(paths.ROOT, cwd);
+    assert.equal(paths.LAYOUT, 'root');
+  });
+
+  it('all path values (except LAYOUT) are absolute', () => {
+    cwd = makeTempDir();
+    fs.mkdirSync(path.join(cwd, '.planning'), { recursive: true });
+    fs.writeFileSync(path.join(cwd, '.planning', 'config.json'), '{}');
+
+    const paths = getPaths(cwd);
+    for (const [key, value] of Object.entries(paths)) {
+      if (key === 'LAYOUT') continue;
+      assert.ok(
+        path.isAbsolute(value),
+        `Expected ${key} to be absolute, got: ${value}`
+      );
+    }
+  });
+
+  it('CONFIG ends with dgs.config.json', () => {
+    cwd = makeTempDir();
+    fs.mkdirSync(path.join(cwd, '.planning'), { recursive: true });
+    fs.writeFileSync(path.join(cwd, '.planning', 'config.json'), '{}');
+
+    const paths = getPaths(cwd);
+    assert.ok(paths.CONFIG.endsWith('dgs.config.json'));
+  });
+
+  it('CONFIG_LEGACY ends with config.json', () => {
+    cwd = makeTempDir();
+    fs.mkdirSync(path.join(cwd, '.planning'), { recursive: true });
+    fs.writeFileSync(path.join(cwd, '.planning', 'config.json'), '{}');
+
+    const paths = getPaths(cwd);
+    assert.ok(paths.CONFIG_LEGACY.endsWith('config.json'));
+  });
+
+  it('subdirectory paths are derived from ROOT', () => {
+    cwd = makeTempDir();
+    fs.mkdirSync(path.join(cwd, '.planning'), { recursive: true });
+    fs.writeFileSync(path.join(cwd, '.planning', 'config.json'), '{}');
+
+    const paths = getPaths(cwd);
+    assert.equal(paths.PHASES, path.join(paths.ROOT, 'phases'));
+    assert.equal(paths.IDEAS, path.join(paths.ROOT, 'ideas'));
+    assert.equal(paths.SPECS, path.join(paths.ROOT, 'specs'));
+    assert.equal(paths.JOBS, path.join(paths.ROOT, 'jobs'));
+    assert.equal(paths.DOCS, path.join(paths.ROOT, 'docs'));
+    assert.equal(paths.CODEBASE, path.join(paths.ROOT, 'codebase'));
+    assert.equal(paths.MILESTONES, path.join(paths.ROOT, 'milestones'));
+    assert.equal(paths.QUICK, path.join(paths.ROOT, 'quick'));
+    assert.equal(paths.TODOS, path.join(paths.ROOT, 'todos'));
+    assert.equal(paths.RESEARCH, path.join(paths.ROOT, 'research'));
+    assert.equal(paths.DEBUG, path.join(paths.ROOT, 'debug'));
+    assert.equal(paths.ARCHIVE, path.join(paths.ROOT, 'archive'));
+    assert.equal(paths.PROJECTS, path.join(paths.ROOT, 'projects'));
+  });
+});
+
+// ─── 6. Object.freeze (PATH-03) ─────────────────────────────────────────────
+
+describe('Object.freeze', () => {
+  let cwd;
+
+  afterEach(() => {
+    resetPaths();
+    if (cwd) removeTempDir(cwd);
+    cwd = null;
+  });
+
+  it('getPaths returns a frozen object', () => {
+    cwd = makeTempDir();
+    fs.mkdirSync(path.join(cwd, '.planning'), { recursive: true });
+    fs.writeFileSync(path.join(cwd, '.planning', 'config.json'), '{}');
+
+    const paths = getPaths(cwd);
+    assert.equal(Object.isFrozen(paths), true);
+  });
+
+  it('attempting to add a property does not modify the object', () => {
+    cwd = makeTempDir();
+    fs.mkdirSync(path.join(cwd, '.planning'), { recursive: true });
+    fs.writeFileSync(path.join(cwd, '.planning', 'config.json'), '{}');
+
+    const paths = getPaths(cwd);
+    try {
+      paths.NEW_PROP = 'value';
+    } catch {
+      // strict mode would throw
+    }
+    assert.equal(paths.NEW_PROP, undefined);
+  });
+});
+
+// ─── 7. Caching (PATH-03, PATH-04) ──────────────────────────────────────────
+
+describe('caching', () => {
+  let cwdA, cwdB;
+
+  afterEach(() => {
+    resetPaths();
+    if (cwdA) removeTempDir(cwdA);
+    if (cwdB) removeTempDir(cwdB);
+    cwdA = null;
+    cwdB = null;
+  });
+
+  it('same cwd returns same object (referential equality)', () => {
+    cwdA = makeTempDir();
+    fs.mkdirSync(path.join(cwdA, '.planning'), { recursive: true });
+    fs.writeFileSync(path.join(cwdA, '.planning', 'config.json'), '{}');
+
+    const first = getPaths(cwdA);
+    const second = getPaths(cwdA);
+    assert.equal(first === second, true, 'Expected referential equality');
+  });
+
+  it('different cwd returns different object', () => {
+    cwdA = makeTempDir();
+    fs.mkdirSync(path.join(cwdA, '.planning'), { recursive: true });
+    fs.writeFileSync(path.join(cwdA, '.planning', 'config.json'), '{}');
+
+    cwdB = makeTempDir();
+    fs.mkdirSync(path.join(cwdB, '.planning'), { recursive: true });
+    fs.writeFileSync(path.join(cwdB, '.planning', 'config.json'), '{}');
+
+    const pathsA = getPaths(cwdA);
+    const pathsB = getPaths(cwdB);
+    assert.notEqual(pathsA === pathsB, true, 'Expected different objects');
+  });
+
+  it('resetPaths clears the cache (new reference after reset)', () => {
+    cwdA = makeTempDir();
+    fs.mkdirSync(path.join(cwdA, '.planning'), { recursive: true });
+    fs.writeFileSync(path.join(cwdA, '.planning', 'config.json'), '{}');
+
+    const before = getPaths(cwdA);
+    resetPaths();
+    const after = getPaths(cwdA);
+    assert.notEqual(before === after, true, 'Expected different reference after reset');
+  });
+});
+
+// ─── 8. initPaths / resetPaths (PATH-04) ─────────────────────────────────────
+
+describe('initPaths / resetPaths', () => {
+  let cwd;
+
+  afterEach(() => {
+    resetPaths();
+    if (cwd) removeTempDir(cwd);
+    cwd = null;
+  });
+
+  it('initPaths returns the same PATHS object as getPaths', () => {
+    cwd = makeTempDir();
+    fs.mkdirSync(path.join(cwd, '.planning'), { recursive: true });
+    fs.writeFileSync(path.join(cwd, '.planning', 'config.json'), '{}');
+
+    const fromInit = initPaths(cwd);
+    const fromGet = getPaths(cwd);
+    assert.equal(fromInit === fromGet, true, 'initPaths and getPaths should return same reference');
+  });
+
+  it('resetPaths clears cache (verified by reference comparison)', () => {
+    cwd = makeTempDir();
+    fs.mkdirSync(path.join(cwd, '.planning'), { recursive: true });
+    fs.writeFileSync(path.join(cwd, '.planning', 'config.json'), '{}');
+
+    const before = initPaths(cwd);
+    resetPaths();
+    const after = initPaths(cwd);
+    assert.notEqual(before === after, true, 'Expected new reference after resetPaths');
+  });
+});
+
+// ─── 9. Leaf module constraint (PATH-05) ─────────────────────────────────────
+
+describe('leaf module constraint', () => {
+  it('paths.cjs has no DGS module imports (no require("./") patterns)', () => {
+    const source = fs.readFileSync(
+      path.join(__dirname, 'paths.cjs'),
+      'utf-8'
+    );
+    // Check for require('./anything') — would indicate DGS module import
+    const dgsImports = source.match(/require\s*\(\s*['"]\.\/[^'"]*['"]\s*\)/g);
+    assert.equal(dgsImports, null, 'paths.cjs should have zero DGS module imports');
+  });
+
+  it('paths.cjs uses fs and path builtins', () => {
+    const source = fs.readFileSync(
+      path.join(__dirname, 'paths.cjs'),
+      'utf-8'
+    );
+    assert.ok(
+      /require\s*\(\s*['"]fs['"]\s*\)/.test(source),
+      'Expected require("fs") in paths.cjs'
+    );
+    assert.ok(
+      /require\s*\(\s*['"]path['"]\s*\)/.test(source),
+      'Expected require("path") in paths.cjs'
+    );
+  });
+});
+
+// ─── 10. Edge cases ──────────────────────────────────────────────────────────
+
+describe('edge cases', () => {
+  let cwd;
+
+  afterEach(() => {
+    resetPaths();
+    if (cwd) removeTempDir(cwd);
+    cwd = null;
+  });
+
+  it('paths returned even when subdirectories do not exist on disk', () => {
+    cwd = makeTempDir();
+    // No .planning/ directory created, no config files — default case
+
+    const paths = getPaths(cwd);
+    // Should still return all paths even though none of these directories exist
+    assert.ok(paths.PHASES);
+    assert.ok(paths.IDEAS);
+    assert.ok(paths.SPECS);
+    assert.ok(paths.ROOT);
+  });
+
+  it('PROJECTS_DIR constant equals "projects"', () => {
+    assert.equal(PROJECTS_DIR, 'projects');
+  });
+
+  it('getPaths().PROJECTS returns absolute path ending in /projects', () => {
+    cwd = makeTempDir();
+    fs.mkdirSync(path.join(cwd, '.planning'), { recursive: true });
+    fs.writeFileSync(path.join(cwd, '.planning', 'config.json'), '{}');
+
+    const paths = getPaths(cwd);
+    assert.ok(path.isAbsolute(paths.PROJECTS), 'Expected PROJECTS to be absolute');
+    assert.ok(paths.PROJECTS.endsWith('/projects') || paths.PROJECTS.endsWith('\\projects'),
+      'Expected PROJECTS path to end with /projects');
+  });
+
+  it('relative cwd is normalized to absolute path', () => {
+    // This test verifies that passing a relative cwd gives the same result
+    // as passing the equivalent absolute path
+    cwd = makeTempDir();
+    fs.mkdirSync(path.join(cwd, '.planning'), { recursive: true });
+    fs.writeFileSync(path.join(cwd, '.planning', 'config.json'), '{}');
+
+    // Get paths with absolute cwd
+    const absResult = getPaths(cwd);
+    resetPaths();
+
+    // Calling with '.' should resolve to process.cwd(), which is different from
+    // our temp dir, but the key behavior is that relative paths get resolved
+    // to absolute via path.resolve()
+    const dotResult = getPaths('.');
+    // The important assertion: all returned paths are absolute regardless of input
+    for (const [key, value] of Object.entries(dotResult)) {
+      if (key === 'LAYOUT') continue;
+      assert.ok(
+        path.isAbsolute(value),
+        `Expected ${key} to be absolute even with relative cwd input`
+      );
+    }
+  });
+});