@ktpartners/dgs-platform 2.6.2

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

@@ -0,0 +1,211 @@
+/**
+ * Tests for docs.cjs — BUG-008 fixes
+ *
+ * Covers resolveDocsDir product path resolution and isDirectory guards
+ * in scanDocsDir, updateIndexWithNames, and updateIndex.
+ *
+ * Uses Node.js built-in test runner (node:test) and assert (node:assert).
+ */
+
+const { describe, it, beforeEach, afterEach } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const {
+  resolveDocsDir,
+  scanDocsDir,
+  updateIndexWithNames,
+  updateIndex,
+} = require('./docs.cjs');
+
+// ─── resolveDocsDir Tests ────────────────────────────────────────────────────
+
+describe('docs', () => {
+
+  describe('resolveDocsDir', () => {
+    let tmpDir;
+
+    beforeEach(() => {
+      tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'dgs-resolve-docs-'));
+    });
+
+    afterEach(() => {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    });
+
+    it('product scope returns .planning/docs/product', () => {
+      const result = resolveDocsDir(tmpDir, 'product');
+      assert.equal(result, path.join(tmpDir, '.planning', 'docs', 'product'));
+    });
+
+    it('product scope path ends with /docs/product', () => {
+      const result = resolveDocsDir(tmpDir, 'product');
+      assert.ok(result.endsWith(path.join('docs', 'product')),
+        `Expected path ending with docs/product, got: ${result}`);
+    });
+
+    it('idea scope returns docs path for idea found in pending', () => {
+      // Create the fixture directory that resolveDocsDir searches for
+      fs.mkdirSync(path.join(tmpDir, '.planning', 'ideas', 'pending', 'my-idea'), { recursive: true });
+      const result = resolveDocsDir(tmpDir, 'idea', 'my-idea');
+      assert.ok(result.includes(path.join('ideas', 'pending', 'my-idea', 'docs')),
+        `Expected ideas/pending/my-idea/docs in path, got: ${result}`);
+    });
+
+    it('spec scope returns correct path', () => {
+      const result = resolveDocsDir(tmpDir, 'spec', 'my-spec');
+      assert.ok(result.includes(path.join('specs', 'my-spec', 'docs')),
+        `Expected specs/my-spec/docs in path, got: ${result}`);
+    });
+  });
+
+  // ─── scanDocsDir directory resilience ──────────────────────────────────────
+
+  describe('scanDocsDir', () => {
+    let tmpDir;
+
+    beforeEach(() => {
+      tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'dgs-docs-test-'));
+    });
+
+    afterEach(() => {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    });
+
+    it('returns metadata for regular files only, skipping subdirectories', () => {
+      // Create a regular file
+      fs.writeFileSync(path.join(tmpDir, 'test-doc.txt'), 'hello world');
+      // Create a subdirectory (would cause EISDIR without the guard)
+      fs.mkdirSync(path.join(tmpDir, 'subdir'));
+
+      const results = scanDocsDir(tmpDir);
+
+      // Should return exactly 1 entry (the file)
+      assert.equal(results.length, 1);
+      assert.equal(results[0].slug, 'test-doc.txt');
+    });
+
+    it('does not crash when only subdirectories exist', () => {
+      fs.mkdirSync(path.join(tmpDir, 'subdir-a'));
+      fs.mkdirSync(path.join(tmpDir, 'subdir-b'));
+
+      const results = scanDocsDir(tmpDir);
+      assert.equal(results.length, 0);
+    });
+
+    it('returns empty array for non-existent directory', () => {
+      const results = scanDocsDir(path.join(tmpDir, 'nonexistent'));
+      assert.equal(results.length, 0);
+    });
+  });
+
+  // ─── updateIndexWithNames directory resilience ─────────────────────────────
+
+  describe('updateIndexWithNames', () => {
+    let tmpDir;
+
+    beforeEach(() => {
+      tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'dgs-docs-idx-'));
+    });
+
+    afterEach(() => {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    });
+
+    it('completes without EISDIR error when subdirectory exists', () => {
+      // Create a regular file
+      fs.writeFileSync(path.join(tmpDir, 'report.pdf'), 'fake pdf content');
+      // Create a subdirectory
+      fs.mkdirSync(path.join(tmpDir, 'nested-dir'));
+
+      // Should not throw
+      assert.doesNotThrow(() => {
+        updateIndexWithNames(tmpDir);
+      });
+
+      // INDEX.md should be created
+      const indexPath = path.join(tmpDir, 'INDEX.md');
+      assert.ok(fs.existsSync(indexPath), 'INDEX.md should exist');
+
+      // INDEX.md should contain only the file, not the subdirectory
+      const content = fs.readFileSync(indexPath, 'utf-8');
+      assert.ok(content.includes('report.pdf'), 'INDEX.md should list report.pdf');
+      assert.ok(!content.includes('nested-dir'), 'INDEX.md should not list nested-dir');
+    });
+
+    it('does not include subdirectories in INDEX.md when only subdirs remain', () => {
+      // Create a file + subdir, generate INDEX, then remove the file
+      fs.writeFileSync(path.join(tmpDir, 'temp.txt'), 'temp');
+      fs.mkdirSync(path.join(tmpDir, 'subdir'));
+      updateIndexWithNames(tmpDir);
+      // Remove the file — only subdir remains
+      fs.unlinkSync(path.join(tmpDir, 'temp.txt'));
+      updateIndexWithNames(tmpDir);
+
+      // INDEX.md may still exist (subdir passes filename filter) but must not
+      // contain the subdir name in any data row
+      const indexPath = path.join(tmpDir, 'INDEX.md');
+      if (fs.existsSync(indexPath)) {
+        const content = fs.readFileSync(indexPath, 'utf-8');
+        assert.ok(!content.includes('subdir'), 'INDEX.md should not list subdirectory');
+      }
+      // If INDEX.md was removed, that is also acceptable
+    });
+  });
+
+  // ─── updateIndex directory resilience ──────────────────────────────────────
+
+  describe('updateIndex', () => {
+    let tmpDir;
+
+    beforeEach(() => {
+      tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'dgs-docs-upd-'));
+    });
+
+    afterEach(() => {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    });
+
+    it('completes without EISDIR error when subdirectory exists', () => {
+      // Create a regular file
+      fs.writeFileSync(path.join(tmpDir, 'design.png'), 'fake image');
+      // Create a subdirectory
+      fs.mkdirSync(path.join(tmpDir, 'another-dir'));
+
+      // Should not throw
+      assert.doesNotThrow(() => {
+        updateIndex(tmpDir);
+      });
+
+      // INDEX.md should be created
+      const indexPath = path.join(tmpDir, 'INDEX.md');
+      assert.ok(fs.existsSync(indexPath), 'INDEX.md should exist');
+
+      // INDEX.md should contain only the file
+      const content = fs.readFileSync(indexPath, 'utf-8');
+      assert.ok(content.includes('design.png'), 'INDEX.md should list design.png');
+      assert.ok(!content.includes('another-dir'), 'INDEX.md should not list another-dir');
+    });
+
+    it('handles mixed files and directories correctly', () => {
+      fs.writeFileSync(path.join(tmpDir, 'alpha.txt'), 'a');
+      fs.writeFileSync(path.join(tmpDir, 'beta.csv'), 'b');
+      fs.mkdirSync(path.join(tmpDir, 'gamma-dir'));
+      fs.mkdirSync(path.join(tmpDir, 'delta-dir'));
+
+      updateIndex(tmpDir);
+
+      const indexPath = path.join(tmpDir, 'INDEX.md');
+      const content = fs.readFileSync(indexPath, 'utf-8');
+
+      // Should list both files
+      assert.ok(content.includes('alpha.txt'), 'Should list alpha.txt');
+      assert.ok(content.includes('beta.csv'), 'Should list beta.csv');
+      // Should not list directories
+      assert.ok(!content.includes('gamma-dir'), 'Should not list gamma-dir');
+      assert.ok(!content.includes('delta-dir'), 'Should not list delta-dir');
+    });
+  });
+});