@ktpartners/dgs-platform 2.9.0 → 3.3.0

package/deliver-great-systems/bin/lib/package-scan-skill.cjs

@@ -0,0 +1,96 @@
+/**
+ * package-scan-skill.cjs — Plugin skill module for /dgs:package-scan.
+ *
+ * Companion to deliver-great-systems/skills/dgs-tests/package-scan.md. Where
+ * the .md file declares the plugin contract (test-gate spec §5a), this module
+ * exposes the prerequisites check as a Node callable the future test-gate
+ * orchestrator (skills.cjs) can consume without reimplementing manifest
+ * detection.
+ *
+ * Covers roadmap requirements: PKG-24 (plugin contract) + PKG-25 (prerequisites).
+ *
+ * Public API:
+ *   checkPrerequisites(cwd) -> { available: boolean, reason: string }
+ *
+ * Never throws: absent REPOS.md, unreadable paths, missing files all resolve
+ * to { available: false, reason: <explanation> }. Invalid cwd (empty string,
+ * null, non-string) returns available=false with an explanatory reason.
+ *
+ * Design note: uses the raw REPOS.md path (not worktree-aware) intentionally —
+ * prerequisites are a static gate, not a scan; they reflect what the user has
+ * registered, not where the active worktree is. The scan orchestrator
+ * (package-scan.cjs collectScanTargets) does use resolveCodeContext for
+ * worktree-aware path resolution; that's the right choice for scans but not
+ * for gating.
+ */
+'use strict';
+const fs = require('fs');
+const path = require('path');
+const { detectEcosystems } = require('./package-ecosystems.cjs');
+const { parseReposMd } = require('./repos.cjs');
+
+function _safeDetect(dir) {
+  try {
+    if (!dir || !fs.existsSync(dir)) return [];
+    return detectEcosystems(dir) || [];
+  } catch {
+    return [];
+  }
+}
+
+function checkPrerequisites(cwd) {
+  if (typeof cwd !== 'string' || cwd.length === 0) {
+    return {
+      available: false,
+      reason: 'checkPrerequisites requires a non-empty cwd string',
+    };
+  }
+
+  const targets = [];
+  // Product root always considered a target.
+  targets.push({ name: '_product_root', dir: cwd });
+
+  // Registered repos from REPOS.md (if present). parseReposMd returns
+  // { repos: [...] } or null.
+  let parsed = null;
+  try {
+    parsed = parseReposMd(cwd);
+  } catch {
+    parsed = null;
+  }
+  const repos = (parsed && Array.isArray(parsed.repos)) ? parsed.repos : [];
+  for (const r of repos) {
+    if (!r || !r.path) continue;
+    const abs = path.isAbsolute(r.path) ? r.path : path.resolve(cwd, r.path);
+    targets.push({ name: r.name || r.path, dir: abs });
+  }
+
+  const hits = [];
+  for (const t of targets) {
+    const entries = _safeDetect(t.dir);
+    if (entries.length > 0) {
+      const ecos = Array.from(new Set(entries.map(e => e.ecosystem).filter(Boolean)));
+      hits.push({ name: t.name, ecosystems: ecos });
+    }
+  }
+
+  if (hits.length === 0) {
+    return {
+      available: false,
+      reason: 'No recognised manifests found in any registered repo or at the product root',
+    };
+  }
+  const summary = hits
+    .map(h => `${h.name} (${h.ecosystems.join(', ') || 'unknown'})`)
+    .join('; ');
+  return {
+    available: true,
+    reason: `Recognised manifests found in: ${summary}`,
+  };
+}
+
+module.exports = {
+  checkPrerequisites,
+  // Exported for test seam (helps future consumers mock manifest detection).
+  _safeDetect,
+};

package/deliver-great-systems/bin/lib/package-scan-skill.test.cjs

@@ -0,0 +1,136 @@
+/**
+ * package-scan-skill.test.cjs — Unit tests for Phase 152 Plan 02
+ *
+ * Covers PKG-24 (plugin skill file at deliver-great-systems/skills/dgs-tests/package-scan.md)
+ * and PKG-25 (checkPrerequisites callable).
+ */
+'use strict';
+const { describe, it } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+const { execSync } = require('node:child_process');
+const skill = require('./package-scan-skill.cjs');
+const { resetPaths } = require('./paths.cjs');
+
+function makeTmp() {
+  const d = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'pkg-skill-')));
+  // getPlanningRoot requires a git repository; initialise one so
+  // parseReposMd (which resolves via getPlanningRoot) works under test.
+  execSync('git init -q', { cwd: d });
+  resetPaths();
+  return d;
+}
+
+function cleanup(d) {
+  try { fs.rmSync(d, { recursive: true, force: true }); } catch {}
+}
+
+function writeReposMd(tmp, rows) {
+  let md = '# Repos\n\n';
+  md += '| Name | Path | GitHub URL | Description |\n';
+  md += '|------|------|------------|-------------|\n';
+  for (const r of rows) {
+    md += `| ${r.name} | ${r.path} |  |  |\n`;
+  }
+  fs.writeFileSync(path.join(tmp, 'REPOS.md'), md);
+}
+
+describe('checkPrerequisites (PKG-25)', () => {
+  it('Scenario A: product root has package.json → available=true, reason mentions product root', () => {
+    const tmp = makeTmp();
+    try {
+      fs.writeFileSync(path.join(tmp, 'package.json'), '{}');
+      writeReposMd(tmp, []);
+      const r = skill.checkPrerequisites(tmp);
+      assert.strictEqual(r.available, true);
+      assert.match(r.reason, /_product_root|product root/i);
+      assert.match(r.reason, /node/);
+    } finally { cleanup(tmp); }
+  });
+
+  it('Scenario B: registered repo has go.mod → available=true, reason mentions repo', () => {
+    const tmp = makeTmp();
+    try {
+      fs.mkdirSync(path.join(tmp, 'backend'), { recursive: true });
+      fs.writeFileSync(path.join(tmp, 'backend', 'go.mod'), 'module test\n');
+      writeReposMd(tmp, [{ name: 'backend', path: './backend' }]);
+      const r = skill.checkPrerequisites(tmp);
+      assert.strictEqual(r.available, true);
+      assert.match(r.reason, /backend/);
+      assert.match(r.reason, /go/);
+    } finally { cleanup(tmp); }
+  });
+
+  it('Scenario C: no manifests anywhere → available=false, non-empty reason', () => {
+    const tmp = makeTmp();
+    try {
+      writeReposMd(tmp, []);
+      const r = skill.checkPrerequisites(tmp);
+      assert.strictEqual(r.available, false);
+      assert.ok(typeof r.reason === 'string' && r.reason.length > 0);
+      assert.match(r.reason, /no recognised manifests found/i);
+    } finally { cleanup(tmp); }
+  });
+
+  it('Scenario D: REPOS.md absent, product root has pyproject.toml → available=true', () => {
+    const tmp = makeTmp();
+    try {
+      fs.writeFileSync(path.join(tmp, 'pyproject.toml'), '[project]\nname="x"\n');
+      const r = skill.checkPrerequisites(tmp);
+      assert.strictEqual(r.available, true);
+      assert.match(r.reason, /python/);
+    } finally { cleanup(tmp); }
+  });
+
+  it('Scenario E: multiple manifests across multiple repos → available=true, reason enumerates both', () => {
+    const tmp = makeTmp();
+    try {
+      fs.mkdirSync(path.join(tmp, 'backend'), { recursive: true });
+      fs.writeFileSync(path.join(tmp, 'backend', 'go.mod'), 'module test\n');
+      fs.mkdirSync(path.join(tmp, 'frontend'), { recursive: true });
+      fs.writeFileSync(path.join(tmp, 'frontend', 'package.json'), '{}');
+      writeReposMd(tmp, [
+        { name: 'backend', path: './backend' },
+        { name: 'frontend', path: './frontend' },
+      ]);
+      const r = skill.checkPrerequisites(tmp);
+      assert.strictEqual(r.available, true);
+      assert.match(r.reason, /backend/);
+      assert.match(r.reason, /frontend/);
+      assert.match(r.reason, /go/);
+      assert.match(r.reason, /node/);
+    } finally { cleanup(tmp); }
+  });
+
+  it('Scenario F: invariant — checkPrerequisites never throws (REPOS.md points at nonexistent path)', () => {
+    const tmp = makeTmp();
+    try {
+      writeReposMd(tmp, [{ name: 'missing', path: './does-not-exist' }]);
+      let r;
+      assert.doesNotThrow(() => { r = skill.checkPrerequisites(tmp); });
+      assert.strictEqual(r.available, false);
+      assert.ok(typeof r.reason === 'string' && r.reason.length > 0);
+    } finally { cleanup(tmp); }
+  });
+
+  it('invalid cwd (empty string) → available=false, no throw', () => {
+    let r;
+    assert.doesNotThrow(() => { r = skill.checkPrerequisites(''); });
+    assert.strictEqual(r.available, false);
+    assert.ok(typeof r.reason === 'string' && r.reason.length > 0);
+  });
+
+  it('invalid cwd (null) → available=false, no throw', () => {
+    let r;
+    assert.doesNotThrow(() => { r = skill.checkPrerequisites(null); });
+    assert.strictEqual(r.available, false);
+  });
+});
+
+describe('module contract (PKG-24)', () => {
+  it('exports checkPrerequisites as a function', () => {
+    assert.strictEqual(typeof skill.checkPrerequisites, 'function');
+  });
+});