x-readiness-mcp 0.3.0

package/tools/planning.js

@@ -0,0 +1,343 @@
+// tools/planning.js
+// X-API Readiness Planning Tool (Deterministic / Offline)
+//
+// Contract:
+// - Input: { scope, format }
+// - Output: canonical JSON with `features[]` (stable IDs), optionally `markdown`.
+//
+// IMPORTANT: No network calls or HTML scraping. Everything is generated from
+// `templates/master_template.json` (sources/scopes/categories.expected_rules).
+
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const MASTER_TEMPLATE_PATH = path.join(__dirname, "..", "templates", "master_template.json");
+const MASTER_TEMPLATE_MD_PATH = path.join(__dirname, "..", "templates", "master_template.md");
+
+export async function generateChecklist(scope, format = "json") {
+  // Try to load JSON first, fallback to parsing MD if JSON doesn't exist
+  let template;
+  try {
+    template = loadMasterTemplate();
+  } catch (err) {
+    // If JSON doesn't exist, we'll use the MD version (for now just throw)
+    throw new Error(`Master template not found. Please ensure master_template.json exists: ${err.message}`);
+  }
+  const scopeKey = resolveScopeKey(scope, template);
+  const selectedSources = selectSourcesByScope(scopeKey, template);
+  const selectedCategories = selectCategoriesForSources(selectedSources, template);
+
+  const checklist = buildChecklistFromTemplate(scopeKey, selectedCategories, selectedSources, template);
+
+  if (format === "markdown") {
+    return {
+      ...checklist,
+      markdown: formatAsMarkdown(checklist)
+    };
+  }
+
+  if (format === "both") {
+    return {
+      ...checklist,
+      markdown: formatAsMarkdown(checklist)
+    };
+  }
+
+  return checklist;
+}
+
+export const planningTool = generateChecklist;
+
+function loadMasterTemplate() {
+  const raw = fs.readFileSync(MASTER_TEMPLATE_PATH, "utf8");
+  const template = JSON.parse(raw);
+
+  if (!template || typeof template !== "object") {
+    throw new Error("Invalid master template: not an object");
+  }
+  if (!Array.isArray(template.sources)) {
+    throw new Error("Invalid master template: missing 'sources[]'");
+  }
+  if (!template.scopes || typeof template.scopes !== "object") {
+    throw new Error("Invalid master template: missing 'scopes'");
+  }
+  if (!template.categories || typeof template.categories !== "object") {
+    throw new Error("Invalid master template: missing 'categories'");
+  }
+  return template;
+}
+
+function resolveScopeKey(scope, template) {
+  const scopeInput = (scope || "").toString().trim();
+  if (!scopeInput) return "x_api_readiness";
+
+  const directKey = scopeInput.toLowerCase();
+  if (template.scopes[directKey]) return directKey;
+
+  const normalized = directKey.replace(/[_-]/g, "");
+  for (const key of Object.keys(template.scopes)) {
+    if (key.replace(/[_-]/g, "") === normalized) return key;
+  }
+
+  return "x_api_readiness";
+}
+
+function selectSourcesByScope(scopeKey, template) {
+  const scopeConfig = template.scopes[scopeKey] || template.scopes.x_api_readiness;
+  const includePatterns = Array.isArray(scopeConfig?.include_ids) ? scopeConfig.include_ids : ["common-*", "rest-*"];
+  const excludePatterns = Array.isArray(scopeConfig?.exclude_ids) ? scopeConfig.exclude_ids : [];
+
+  return template.sources.filter((source) => {
+    if (!source || !source.id) return false;
+
+    const isIncluded = includePatterns.some((pattern) => matchIdPattern(source.id, pattern));
+    if (!isIncluded) return false;
+
+    const isExcluded = excludePatterns.some((pattern) => matchIdPattern(source.id, pattern));
+    if (isExcluded) return false;
+
+    return true;
+  });
+}
+
+function matchIdPattern(id, pattern) {
+  if (!pattern) return false;
+  if (pattern === "*") return true;
+  if (pattern.endsWith("*")) return id.startsWith(pattern.slice(0, -1));
+  if (pattern.startsWith("*")) return id.endsWith(pattern.slice(1));
+  return id === pattern;
+}
+
+function selectCategoriesForSources(selectedSources, template) {
+  const categories = template.categories;
+
+  // Build a reverse lookup: normalized guideline URL -> [{ categoryKey, category }]
+  const byUrl = new Map();
+  for (const [categoryKey, category] of Object.entries(categories)) {
+    const url = normalizeUrl(category?.guideline_url);
+    if (!url) continue;
+    const existing = byUrl.get(url) || [];
+    existing.push({ categoryKey, category });
+    byUrl.set(url, existing);
+  }
+
+  const selected = new Map();
+  for (const source of selectedSources) {
+    const url = normalizeUrl(source?.url);
+    if (!url) continue;
+    const matches = byUrl.get(url);
+    if (!matches || matches.length === 0) continue;
+
+    for (const match of matches) {
+      selected.set(match.categoryKey, match.category);
+    }
+  }
+
+  return selected;
+}
+
+function normalizeUrl(url) {
+  if (!url || typeof url !== "string") return null;
+  try {
+    const parsed = new URL(url);
+    parsed.hash = "";
+    // Some URLs might differ only by trailing slash
+    const normalized = parsed.toString().replace(/\/$/, "");
+    return normalized;
+  } catch {
+    return url.replace(/#.*$/, "").replace(/\/$/, "");
+  }
+}
+
+function buildChecklistFromTemplate(scopeKey, selectedCategoriesMap, selectedSources, template) {
+  const generatedAt = new Date().toISOString();
+  const checklistId = `xreadiness:${template.version || "0"}:${scopeKey}`;
+
+  const selectedCategories = Array.from(selectedCategoriesMap.entries())
+    .map(([categoryKey, category]) => ({ categoryKey, category }))
+    .sort((a, b) => a.categoryKey.localeCompare(b.categoryKey));
+
+  const features = selectedCategories
+    .map(({ categoryKey, category }) => buildFeature(categoryKey, category))
+    .filter((f) => f.rules.length > 0);
+
+  // Derived flattened rules for execution tool compatibility
+  const rules = [];
+  for (const feature of features) {
+    for (const rule of feature.rules) {
+      rules.push({
+        ruleId: rule.rule_id,
+        ruleName: rule.rule_name,
+        category: feature.category_key,
+        categoryKey: feature.category_key,
+        normative: rule.normative,
+        severity: rule.severity,
+        referenceUrl: rule.reference_url
+      });
+    }
+  }
+
+  const summary = computeSummary(features);
+
+  return {
+    checklist_id: checklistId,
+    scope: scopeKey,
+    generated_at: generatedAt,
+    template_version: template.version || null,
+    template_last_updated: template.last_updated || null,
+
+    // Canonical contract
+    features,
+
+    // Derived compatibility field for current execution tool
+    rules,
+
+    // Supporting metadata
+    sources_included: selectedSources.map((s) => ({
+      id: s.id,
+      area: s.area,
+      name: s.name,
+      url: s.url,
+      priority: s.priority || null
+    })),
+    summary
+  };
+}
+
+function buildFeature(categoryKey, category) {
+  const featureId = category?.id || categoryKey.toLowerCase();
+  const featureName = category?.name || categoryKey;
+  const guidelineUrl = category?.guideline_url || null;
+  const priority = category?.priority || "medium";
+
+  const expectedRules = category?.expected_rules && typeof category.expected_rules === "object"
+    ? category.expected_rules
+    : {};
+
+  const rules = Object.entries(expectedRules)
+    .map(([ruleNumber, ruleName]) => {
+      const normative = deriveNormative(ruleName);
+      return {
+        rule_id: `${categoryKey}-${ruleNumber}`,
+        rule_number: ruleNumber,
+        rule_name: ruleName,
+        reference_url: guidelineUrl,
+        severity: priorityToSeverity(priority),
+        normative,
+        adoption_condition: null,
+        evidence_hints: buildEvidenceHints(category)
+      };
+    })
+    .sort((a, b) => compareRuleNumbers(a.rule_number, b.rule_number));
+
+  return {
+    feature_id: featureId,
+    feature_name: featureName,
+    feature_description: category?.description || null,
+    guideline_url: guidelineUrl,
+    priority,
+
+    // Helps execution tool routing (PAGINATION, SECURITY, ...)
+    category_key: categoryKey,
+
+    rules
+  };
+}
+
+function buildEvidenceHints(category) {
+  const hints = [];
+  if (Array.isArray(category?.applies_to)) hints.push(...category.applies_to);
+  if (Array.isArray(category?.keywords)) hints.push(...category.keywords);
+  return Array.from(new Set(hints.filter(Boolean).map((h) => h.toString())));
+}
+
+function priorityToSeverity(priority) {
+  const p = (priority || "medium").toString().toLowerCase();
+  if (p === "critical") return "critical";
+  if (p === "high") return "high";
+  if (p === "low") return "low";
+  return "medium";
+}
+
+function deriveNormative(text) {
+  const value = (text || "").toString();
+  if (/\bMUST NOT\b/i.test(value)) return "MUST NOT";
+  if (/\bSHOULD NOT\b/i.test(value)) return "SHOULD NOT";
+  if (/\bMUST\b/i.test(value)) return "MUST";
+  if (/\bSHOULD\b/i.test(value)) return "SHOULD";
+  if (/\bMAY\b/i.test(value)) return "MAY";
+  return null;
+}
+
+function compareRuleNumbers(a, b) {
+  const aParts = (a || "").toString().split(".").map((x) => Number(x));
+  const bParts = (b || "").toString().split(".").map((x) => Number(x));
+
+  const max = Math.max(aParts.length, bParts.length);
+  for (let i = 0; i < max; i++) {
+    const av = Number.isFinite(aParts[i]) ? aParts[i] : 0;
+    const bv = Number.isFinite(bParts[i]) ? bParts[i] : 0;
+    if (av !== bv) return av - bv;
+  }
+  return 0;
+}
+
+function computeSummary(features) {
+  const summary = {
+    total_features: features.length,
+    total_rules: 0,
+    by_severity: { critical: 0, high: 0, medium: 0, low: 0 },
+    by_normative: { MUST: 0, SHOULD: 0, MAY: 0, "MUST NOT": 0, "SHOULD NOT": 0, UNKNOWN: 0 }
+  };
+
+  for (const feature of features) {
+    for (const rule of feature.rules) {
+      summary.total_rules++;
+      const sev = rule.severity || "medium";
+      if (summary.by_severity[sev] === undefined) summary.by_severity[sev] = 0;
+      summary.by_severity[sev]++;
+
+      const norm = rule.normative || "UNKNOWN";
+      if (summary.by_normative[norm] === undefined) summary.by_normative[norm] = 0;
+      summary.by_normative[norm]++;
+    }
+  }
+
+  return summary;
+}
+
+function formatAsMarkdown(checklist) {
+  const lines = [];
+  lines.push(`# X-API Readiness Checklist (${checklist.scope})`);
+  lines.push("");
+  lines.push(`Generated: ${checklist.generated_at}`);
+  if (checklist.template_version) lines.push(`Template: ${checklist.template_version}`);
+  lines.push("");
+
+  for (const feature of checklist.features) {
+    lines.push(`## ${feature.feature_name}`);
+    if (feature.guideline_url) lines.push(`Source: ${feature.guideline_url}`);
+    lines.push("");
+
+    for (const rule of feature.rules) {
+      const norm = rule.normative ? ` (${rule.normative})` : "";
+      lines.push(`- [ ] ${rule.rule_id}${norm}: ${rule.rule_name}`);
+    }
+
+    lines.push("");
+  }
+
+  return lines.join("\n");
+}
+
+// Backward compatibility for local test runner
+export function formatChecklistAsTable(checklist) {
+  return formatAsMarkdown(checklist);
+}
+
+// Default export (used by `mcp/test-planner-v2.js`)
+export default generateChecklist;