agentxchain 2.2.0 → 2.4.0

package/src/lib/governed-templates.js

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
@@ -9,6 +9,7 @@ export const VALID_GOVERNED_TEMPLATE_IDS = Object.freeze([
   'generic',
   'api-service',
   'cli-tool',
+  'library',
   'web-app',
 ]);
 
@@ -143,3 +144,237 @@ export function loadGovernedTemplate(templateId) {
 export function loadAllGovernedTemplates() {
   return VALID_GOVERNED_TEMPLATE_IDS.map((templateId) => loadGovernedTemplate(templateId));
 }
+
+export function listGovernedTemplateManifestIds(manifestDir = GOVERNED_TEMPLATES_DIR) {
+  if (!existsSync(manifestDir)) {
+    return [];
+  }
+
+  return readdirSync(manifestDir)
+    .filter((entry) => entry.endsWith('.json'))
+    .map((entry) => entry.slice(0, -'.json'.length))
+    .sort();
+}
+
+export function validateGovernedTemplateRegistry(options = {}) {
+  const manifestDir = options.manifestDir || GOVERNED_TEMPLATES_DIR;
+  const registeredIds = options.registeredIds || [...VALID_GOVERNED_TEMPLATE_IDS];
+  const errors = [];
+  const warnings = [];
+  const manifestIds = listGovernedTemplateManifestIds(manifestDir);
+
+  for (const templateId of registeredIds) {
+    const manifestPath = join(manifestDir, `${templateId}.json`);
+    if (!existsSync(manifestPath)) {
+      errors.push(`Registered template "${templateId}" is missing its manifest file.`);
+      continue;
+    }
+
+    let manifest;
+    try {
+      manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+    } catch (err) {
+      errors.push(`Template "${templateId}" manifest is invalid JSON: ${err.message}`);
+      continue;
+    }
+
+    const validation = validateGovernedTemplateManifest(manifest, templateId);
+    if (!validation.ok) {
+      errors.push(`Template "${templateId}" manifest is invalid: ${validation.errors.join('; ')}`);
+    }
+  }
+
+  for (const manifestId of manifestIds) {
+    if (!registeredIds.includes(manifestId)) {
+      errors.push(`Manifest "${manifestId}.json" exists on disk but is not registered in VALID_GOVERNED_TEMPLATE_IDS.`);
+    }
+  }
+
+  return {
+    ok: errors.length === 0,
+    registered_ids: registeredIds,
+    manifest_ids: manifestIds,
+    errors,
+    warnings,
+  };
+}
+
+export function validateProjectPlanningArtifacts(root, templateId) {
+  const effectiveTemplateId = templateId || 'generic';
+  const errors = [];
+  const warnings = [];
+
+  let manifest;
+  try {
+    manifest = loadGovernedTemplate(effectiveTemplateId);
+  } catch {
+    // Template load failure is already reported by validateGovernedProjectTemplate.
+    // Skip artifact check — we cannot know what artifacts to expect.
+    return {
+      ok: true,
+      template: effectiveTemplateId,
+      expected: [],
+      present: [],
+      missing: [],
+      errors,
+      warnings: ['Template could not be loaded; planning artifact check skipped.'],
+    };
+  }
+
+  const artifacts = manifest.planning_artifacts || [];
+  const expected = artifacts.map((a) => a.filename);
+  const present = [];
+  const missing = [];
+
+  for (const filename of expected) {
+    const artifactPath = join(root, '.planning', filename);
+    if (existsSync(artifactPath)) {
+      present.push(filename);
+    } else {
+      missing.push(filename);
+      errors.push(`Template "${effectiveTemplateId}" requires planning artifact ".planning/${filename}" but it is missing.`);
+    }
+  }
+
+  return {
+    ok: errors.length === 0,
+    template: effectiveTemplateId,
+    expected,
+    present,
+    missing,
+    errors,
+    warnings,
+  };
+}
+
+const TEMPLATE_GUIDANCE_HEADER = '## Template Guidance';
+
+export function validateAcceptanceHintCompletion(root, templateId) {
+  const effectiveTemplateId = templateId || 'generic';
+  const errors = [];
+  const warnings = [];
+
+  let manifest;
+  try {
+    manifest = loadGovernedTemplate(effectiveTemplateId);
+  } catch {
+    return {
+      ok: true,
+      template: effectiveTemplateId,
+      total: 0,
+      checked: 0,
+      unchecked: 0,
+      missing_file: false,
+      missing_section: false,
+      unchecked_hints: [],
+      errors,
+      warnings: ['Template could not be loaded; acceptance hint check skipped.'],
+    };
+  }
+
+  const hints = manifest.acceptance_hints || [];
+  if (hints.length === 0) {
+    return {
+      ok: true,
+      template: effectiveTemplateId,
+      total: 0,
+      checked: 0,
+      unchecked: 0,
+      missing_file: false,
+      missing_section: false,
+      unchecked_hints: [],
+      errors,
+      warnings,
+    };
+  }
+
+  const matrixPath = join(root, '.planning', 'acceptance-matrix.md');
+  if (!existsSync(matrixPath)) {
+    warnings.push('acceptance-matrix.md not found; cannot verify template acceptance hints.');
+    return {
+      ok: true,
+      template: effectiveTemplateId,
+      total: hints.length,
+      checked: 0,
+      unchecked: hints.length,
+      missing_file: true,
+      missing_section: false,
+      unchecked_hints: [...hints],
+      errors,
+      warnings,
+    };
+  }
+
+  const matrixContent = readFileSync(matrixPath, 'utf8');
+  const sectionIndex = matrixContent.indexOf(TEMPLATE_GUIDANCE_HEADER);
+  if (sectionIndex === -1) {
+    warnings.push('acceptance-matrix.md has no "## Template Guidance" section; cannot verify template acceptance hints.');
+    return {
+      ok: true,
+      template: effectiveTemplateId,
+      total: hints.length,
+      checked: 0,
+      unchecked: hints.length,
+      missing_file: false,
+      missing_section: true,
+      unchecked_hints: [...hints],
+      errors,
+      warnings,
+    };
+  }
+
+  // Parse the Template Guidance section for checked/unchecked items
+  const sectionContent = matrixContent.slice(sectionIndex);
+  const checkedPattern = /^- \[x\]\s+(.+)$/gim;
+  const checkedTexts = new Set();
+  let match;
+  while ((match = checkedPattern.exec(sectionContent)) !== null) {
+    checkedTexts.add(match[1].trim());
+  }
+
+  const uncheckedHints = [];
+  let checkedCount = 0;
+
+  for (const hint of hints) {
+    if (checkedTexts.has(hint)) {
+      checkedCount++;
+    } else {
+      uncheckedHints.push(hint);
+      warnings.push(`Acceptance hint unchecked: "${hint}"`);
+    }
+  }
+
+  return {
+    ok: true,
+    template: effectiveTemplateId,
+    total: hints.length,
+    checked: checkedCount,
+    unchecked: uncheckedHints.length,
+    missing_file: false,
+    missing_section: false,
+    unchecked_hints: uncheckedHints,
+    errors,
+    warnings,
+  };
+}
+
+export function validateGovernedProjectTemplate(templateId, source = 'agentxchain.json') {
+  const effectiveTemplateId = templateId || 'generic';
+  const effectiveSource = templateId ? source : 'implicit_default';
+  const errors = [];
+  const warnings = [];
+
+  try {
+    loadGovernedTemplate(effectiveTemplateId);
+  } catch (err) {
+    errors.push(err.message);
+  }
+
+  return {
+    ok: errors.length === 0,
+    template: effectiveTemplateId,
+    source: effectiveSource,
+    errors,
+    warnings,
+  };
+}