x-readiness-mcp 0.3.0 → 0.5.1

package/tools/rule-checkers.js

@@ -0,0 +1,394 @@
+// mcp/tools/rule-checkers.js
+import fs from "node:fs/promises";
+import path from "node:path";
+import { glob } from "glob";
+
+/**
+ * Recursively find all source files in a repository
+ */
+async function findSourceFiles(repoPath, extensions = ["js", "ts", "json", "yaml", "yml"]) {
+  const patterns = extensions.map(ext => `**/*.${ext}`);
+  const allFiles = [];
+  
+  for (const pattern of patterns) {
+    const files = await glob(pattern, {
+      cwd: repoPath,
+      ignore: ["**/node_modules/**", "**/dist/**", "**/build/**", "**/.git/**", "**/mcp/**"],
+      absolute: true
+    });
+    allFiles.push(...files);
+  }
+  
+  return allFiles;
+}
+
+/**
+ * Read file content with line tracking
+ */
+async function readFileLines(filePath) {
+  const content = await fs.readFile(filePath, "utf8");
+  const lines = content.split("\n");
+  return { content, lines, filePath };
+}
+
+/**
+ * Base checker function - to be extended for specific rules
+ */
+async function checkRule(repoPath, rule) {
+  const ruleId = rule.rule_id.toLowerCase();
+  
+  // Route to specific checker based on rule category
+  const category = rule.category.toLowerCase();
+  
+  if (category.includes("pagination")) {
+    return await checkPaginationRule(repoPath, rule);
+  } else if (category.includes("error")) {
+    return await checkErrorHandlingRule(repoPath, rule);
+  } else if (category.includes("naming")) {
+    return await checkNamingRule(repoPath, rule);
+  } else if (category.includes("security")) {
+    return await checkSecurityRule(repoPath, rule);
+  } else if (category.includes("versioning")) {
+    return await checkVersioningRule(repoPath, rule);
+  } else if (category.includes("media")) {
+    return await checkMediaTypesRule(repoPath, rule);
+  } else if (category.includes("operations")) {
+    return await checkOperationsRule(repoPath, rule);
+  } else if (category.includes("filtering")) {
+    return await checkFilteringRule(repoPath, rule);
+  } else if (category.includes("sorting")) {
+    return await checkSortingRule(repoPath, rule);
+  } else if (category.includes("sparse")) {
+    return await checkSparseFieldsetsRule(repoPath, rule);
+  }
+  
+  // Default: not yet implemented
+  return {
+    status: "SKIPPED",
+    reason: "Checker not implemented for this rule category",
+    violations: []
+  };
+}
+
+/**
+ * Check pagination rules
+ */
+async function checkPaginationRule(repoPath, rule) {
+  const violations = [];
+  const files = await findSourceFiles(repoPath, ["js", "ts"]);
+  
+  for (const file of files) {
+    const { lines } = await readFileLines(file);
+    
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      const lineNum = i + 1;
+      
+      // Check for pagination-related patterns
+      if (rule.rule_id === "600") {
+        // Check if pagination links are provided
+        if (line.includes("pagination") || line.includes("/page")) {
+          // Look for links object
+          const contextLines = lines.slice(Math.max(0, i - 5), Math.min(lines.length, i + 10)).join("\n");
+          if (!contextLines.includes("links") && !contextLines.includes("next") && !contextLines.includes("prev")) {
+            violations.push({
+              file_path: path.relative(repoPath, file),
+              line_number: lineNum,
+              line_content: line.trim(),
+              message: "Pagination endpoint should include links for navigation (next, prev, etc.)"
+            });
+          }
+        }
+      }
+      
+      // Check for cursor/offset/index pagination patterns
+      if (rule.rule_id.startsWith("601")) {
+        if (line.includes("page") && (line.includes("?") || line.includes("query"))) {
+          const contextLines = lines.slice(Math.max(0, i - 3), Math.min(lines.length, i + 5)).join("\n");
+          
+          if (rule.rule_id.includes("601.1") && !contextLines.match(/cursor|token/i)) {
+            violations.push({
+              file_path: path.relative(repoPath, file),
+              line_number: lineNum,
+              line_content: line.trim(),
+              message: "Consider using cursor-based pagination strategy"
+            });
+          }
+          
+          if (rule.rule_id.includes("601.2") && !contextLines.match(/offset|limit/i)) {
+            violations.push({
+              file_path: path.relative(repoPath, file),
+              line_number: lineNum,
+              line_content: line.trim(),
+              message: "Offset-based pagination should include offset and limit parameters"
+            });
+          }
+        }
+      }
+    }
+  }
+  
+  return violations.length > 0 
+    ? { status: "FAIL", violations }
+    : { status: "PASS", violations: [] };
+}
+
+/**
+ * Check error handling rules
+ */
+async function checkErrorHandlingRule(repoPath, rule) {
+  const violations = [];
+  const files = await findSourceFiles(repoPath, ["js", "ts"]);
+  
+  for (const file of files) {
+    const { lines } = await readFileLines(file);
+    
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      const lineNum = i + 1;
+      
+      // Rule 300: Check for proper HTTP status codes
+      if (rule.rule_id === "300") {
+        if (line.match(/\.status\((\d+)\)|\.sendStatus\((\d+)\)|statusCode\s*=\s*(\d+)/)) {
+          const statusMatch = line.match(/(\d{3})/);
+          if (statusMatch) {
+            const status = parseInt(statusMatch[1]);
+            // Check if status code is valid HTTP status
+            if (status < 100 || status > 599) {
+              violations.push({
+                file_path: path.relative(repoPath, file),
+                line_number: lineNum,
+                line_content: line.trim(),
+                message: `Invalid HTTP status code ${status}. Use official HTTP status codes (100-599)`
+              });
+            }
+          }
+        }
+      }
+      
+      // Rule 303: Check for stack traces in error responses
+      if (rule.rule_id === "303") {
+        if (line.match(/stack|stackTrace/i) && (line.includes("response") || line.includes("send") || line.includes("json"))) {
+          violations.push({
+            file_path: path.relative(repoPath, file),
+            line_number: lineNum,
+            line_content: line.trim(),
+            message: "API should not expose stack traces in error responses (security risk)"
+          });
+        }
+      }
+      
+      // Rule 304: Check for errors object in error responses
+      if (rule.rule_id === "304") {
+        if (line.match(/catch|error/i) && line.match(/\.json\(|\.send\(/)) {
+          const contextLines = lines.slice(Math.max(0, i - 2), Math.min(lines.length, i + 3)).join("\n");
+          if (!contextLines.includes("errors")) {
+            violations.push({
+              file_path: path.relative(repoPath, file),
+              line_number: lineNum,
+              line_content: line.trim(),
+              message: "Error response should include an 'errors' object array"
+            });
+          }
+        }
+      }
+    }
+  }
+  
+  return violations.length > 0 
+    ? { status: "FAIL", violations }
+    : { status: "PASS", violations: [] };
+}
+
+/**
+ * Check naming convention rules
+ */
+async function checkNamingRule(repoPath, rule) {
+  const violations = [];
+  const files = await findSourceFiles(repoPath, ["js", "ts", "json"]);
+  
+  for (const file of files) {
+    const { content, lines } = await readFileLines(file);
+    
+    // For JSON files, check property names
+    if (file.endsWith(".json")) {
+      try {
+        const json = JSON.parse(content);
+        checkObjectNaming(json, file, violations, repoPath, rule);
+      } catch (e) {
+        // Skip invalid JSON
+      }
+    } else {
+      // For JS/TS files, check object property definitions
+      for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const lineNum = i + 1;
+        
+        // Check for object property definitions
+        const propMatch = line.match(/['"]([a-zA-Z_][a-zA-Z0-9_]*)['"]:/);
+        if (propMatch) {
+          const propName = propMatch[1];
+          
+          // Rule naming_01: Must start with lowercase
+          if (rule.rule_id === "naming_01" && /^[A-Z]/.test(propName) && propName !== propName.toUpperCase()) {
+            violations.push({
+              file_path: path.relative(repoPath, file),
+              line_number: lineNum,
+              line_content: line.trim(),
+              message: `Property "${propName}" should start with a lowercase letter (camelCase)`
+            });
+          }
+          
+          // Rule naming_02: Must use camelCase
+          if (rule.rule_id === "naming_02" && propName.includes("_") && !propName.startsWith("_")) {
+            violations.push({
+              file_path: path.relative(repoPath, file),
+              line_number: lineNum,
+              line_content: line.trim(),
+              message: `Property "${propName}" should use camelCase instead of snake_case`
+            });
+          }
+          
+          // Rule naming_04: Must use ASCII characters only
+          if (rule.rule_id === "naming_04" && /[^\x00-\x7F]/.test(propName)) {
+            violations.push({
+              file_path: path.relative(repoPath, file),
+              line_number: lineNum,
+              line_content: line.trim(),
+              message: `Property "${propName}" contains non-ASCII characters`
+            });
+          }
+        }
+      }
+    }
+  }
+  
+  return violations.length > 0 
+    ? { status: "FAIL", violations }
+    : { status: "PASS", violations: [] };
+}
+
+/**
+ * Helper to check object naming recursively
+ */
+function checkObjectNaming(obj, filePath, violations, repoPath, rule, path = "") {
+  if (typeof obj !== "object" || obj === null) return;
+  
+  for (const key in obj) {
+    const fullPath = path ? `${path}.${key}` : key;
+    
+    if (rule.rule_id === "naming_01" && /^[A-Z]/.test(key) && key !== key.toUpperCase()) {
+      violations.push({
+        file_path: path.relative(repoPath, filePath),
+        line_number: 0,
+        line_content: `"${key}": ...`,
+        message: `JSON property "${fullPath}" should start with lowercase (camelCase)`
+      });
+    }
+    
+    if (rule.rule_id === "naming_02" && key.includes("_") && !key.startsWith("_")) {
+      violations.push({
+        file_path: path.relative(repoPath, filePath),
+        line_number: 0,
+        line_content: `"${key}": ...`,
+        message: `JSON property "${fullPath}" should use camelCase instead of snake_case`
+      });
+    }
+    
+    if (Array.isArray(obj[key])) {
+      obj[key].forEach((item, idx) => checkObjectNaming(item, filePath, violations, repoPath, rule, `${fullPath}[${idx}]`));
+    } else if (typeof obj[key] === "object") {
+      checkObjectNaming(obj[key], filePath, violations, repoPath, rule, fullPath);
+    }
+  }
+}
+
+/**
+ * Check security rules
+ */
+async function checkSecurityRule(repoPath, rule) {
+  const violations = [];
+  const files = await findSourceFiles(repoPath, ["js", "ts"]);
+  
+  for (const file of files) {
+    const { lines } = await readFileLines(file);
+    
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      const lineNum = i + 1;
+      
+      // Rule sec_01: OAuth 2.0 Bearer Token
+      if (rule.rule_id === "sec_01" || rule.rule_id === "sec_09") {
+        if (line.match(/app\.(get|post|put|delete|patch)/i) || line.match(/router\.(get|post|put|delete|patch)/i)) {
+          const contextLines = lines.slice(Math.max(0, i - 5), Math.min(lines.length, i + 10)).join("\n");
+          if (!contextLines.match(/authorization|bearer|token|auth/i)) {
+            violations.push({
+              file_path: path.relative(repoPath, file),
+              line_number: lineNum,
+              line_content: line.trim(),
+              message: "API endpoint should be secured with OAuth 2.0 Bearer Token authentication"
+            });
+          }
+        }
+      }
+      
+      // Rule sec_02: TLS/HTTPS
+      if (rule.rule_id === "sec_02") {
+        if (line.match(/http:\/\//) && !line.includes("localhost") && !line.includes("127.0.0.1")) {
+          violations.push({
+            file_path: path.relative(repoPath, file),
+            line_number: lineNum,
+            line_content: line.trim(),
+            message: "Use HTTPS instead of HTTP for API protection"
+          });
+        }
+      }
+    }
+  }
+  
+  return violations.length > 0 
+    ? { status: "FAIL", violations }
+    : { status: "PASS", violations: [] };
+}
+
+/**
+ * Stub checkers for other categories
+ */
+async function checkVersioningRule(repoPath, rule) {
+  return { status: "SKIPPED", reason: "Versioning checker not yet implemented", violations: [] };
+}
+
+async function checkMediaTypesRule(repoPath, rule) {
+  return { status: "SKIPPED", reason: "Media types checker not yet implemented", violations: [] };
+}
+
+async function checkOperationsRule(repoPath, rule) {
+  return { status: "SKIPPED", reason: "Operations checker not yet implemented", violations: [] };
+}
+
+async function checkFilteringRule(repoPath, rule) {
+  return { status: "SKIPPED", reason: "Filtering checker not yet implemented", violations: [] };
+}
+
+async function checkSortingRule(repoPath, rule) {
+  return { status: "SKIPPED", reason: "Sorting checker not yet implemented", violations: [] };
+}
+
+async function checkSparseFieldsetsRule(repoPath, rule) {
+  return { status: "SKIPPED", reason: "Sparse fieldsets checker not yet implemented", violations: [] };
+}
+
+/**
+ * Main export - evaluate a single rule
+ */
+export async function evaluateRule(repoPath, rule) {
+  try {
+    return await checkRule(repoPath, rule);
+  } catch (error) {
+    return {
+      status: "ERROR",
+      reason: error.message,
+      violations: []
+    };
+  }
+}

package/tools/template-parser.js

@@ -0,0 +1,204 @@
+// mcp/tools/template-parser.js
+import fs from "node:fs/promises";
+import path from "node:path";
+
+const TEMPLATE_PATH = path.resolve(process.cwd(), "mcp", "templates", "master_template.md");
+
+/**
+ * Parse the master template to extract scopes, categories, and rules
+ * @returns {Promise<Object>} Parsed checklist with scopes and rules
+ */
+export async function parseTemplate() {
+  const content = await fs.readFile(TEMPLATE_PATH, "utf8");
+  const lines = content.split("\n");
+
+  const result = {
+    template_version: "2.5.0",
+    last_updated: "2026-01-28",
+    scopes: [],
+    categories: [],
+    reference_urls: {
+      common: "https://developer.siemens.com/guidelines/api-guidelines/common/index.html",
+      rest: "https://developer.siemens.com/guidelines/api-guidelines/rest/index.html"
+    }
+  };
+
+  let currentSection = null;
+  let currentScope = null;
+  let currentCategory = null;
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i].trim();
+
+    // Detect sections
+    if (line === "## Scopes") {
+      currentSection = "scopes";
+      continue;
+    }
+    if (line === "## Rule Categories") {
+      currentSection = "categories";
+      continue;
+    }
+
+    // Parse scopes
+    if (currentSection === "scopes" && line.startsWith("### ")) {
+      const scopeName = line.substring(4).trim();
+      currentScope = {
+        name: scopeName,
+        description: "",
+        includes: []
+      };
+      result.scopes.push(currentScope);
+      continue;
+    }
+
+    if (currentScope && line.startsWith("**Description:**")) {
+      currentScope.description = line.substring(16).trim();
+      continue;
+    }
+
+    if (currentScope && line.startsWith("- ")) {
+      const include = line.substring(2).trim();
+      if (include) currentScope.includes.push(include);
+      continue;
+    }
+
+    // Parse categories
+    if (currentSection === "categories" && line.match(/^### \d+\./)) {
+      const match = line.match(/^### \d+\.\s+(.+)/);
+      if (match) {
+        const categoryName = match[1].trim();
+        currentCategory = {
+          name: categoryName,
+          priority: "",
+          guideline_url: "",
+          rules: []
+        };
+        result.categories.push(currentCategory);
+      }
+      continue;
+    }
+
+    if (currentCategory && line.startsWith("**Priority:**")) {
+      currentCategory.priority = line.substring(13).trim();
+      continue;
+    }
+
+    if (currentCategory && line.startsWith("**Guideline:**")) {
+      // Extract URLs from markdown links
+      const urlMatches = line.match(/\[([^\]]+)\]\(([^)]+)\)/g);
+      if (urlMatches && urlMatches.length > 0) {
+        const firstUrl = urlMatches[0].match(/\(([^)]+)\)/);
+        if (firstUrl) {
+          currentCategory.guideline_url = firstUrl[1];
+        }
+      }
+      continue;
+    }
+
+    if (currentCategory && line.startsWith("- ")) {
+      const ruleMatch = line.match(/^- ([^:]+):\s*(.+)/);
+      if (ruleMatch) {
+        const ruleId = ruleMatch[1].trim();
+        const ruleDescription = ruleMatch[2].trim();
+        currentCategory.rules.push({
+          rule_id: ruleId,
+          rule_name: ruleDescription,
+          category: currentCategory.name,
+          priority: currentCategory.priority,
+          guideline_url: currentCategory.guideline_url
+        });
+      }
+      continue;
+    }
+
+    // Reset scope when we hit a separator
+    if (line === "---") {
+      currentScope = null;
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Generate a checklist based on scope and developer prompt
+ * @param {string} scope - The scope to use (e.g., 'x_api_readiness', 'pagination_ready')
+ * @param {string} developerPrompt - Developer intent to filter rules
+ * @returns {Promise<Object>} Filtered checklist
+ */
+export async function generateChecklist(scope, developerPrompt = "") {
+  const template = await parseTemplate();
+  
+  // Find the requested scope
+  const scopeConfig = template.scopes.find(s => s.name === scope);
+  if (!scopeConfig) {
+    throw new Error(`Unknown scope: ${scope}. Available scopes: ${template.scopes.map(s => s.name).join(", ")}`);
+  }
+
+  // Filter categories based on scope includes
+  let selectedCategories = [];
+  
+  if (scope === "x_api_readiness") {
+    // Include all categories for full X-API readiness
+    selectedCategories = template.categories;
+  } else {
+    // Filter by scope's includes
+    selectedCategories = template.categories.filter(cat => {
+      return scopeConfig.includes.some(inc => 
+        cat.name.toLowerCase().includes(inc.toLowerCase()) ||
+        inc.toLowerCase().includes(cat.name.toLowerCase())
+      );
+    });
+  }
+
+  // Further filter by developer prompt (keyword matching)
+  const prompt = developerPrompt.toLowerCase();
+  if (prompt && scope !== "x_api_readiness") {
+    const keywords = extractKeywords(prompt);
+    if (keywords.length > 0) {
+      selectedCategories = selectedCategories.filter(cat => {
+        const catName = cat.name.toLowerCase();
+        return keywords.some(kw => catName.includes(kw));
+      });
+    }
+  }
+
+  return {
+    template_version: template.template_version,
+    last_updated: template.last_updated,
+    scope: scope,
+    scope_description: scopeConfig.description,
+    developer_prompt: developerPrompt,
+    reference_urls: template.reference_urls,
+    categories: selectedCategories,
+    total_rules: selectedCategories.reduce((sum, cat) => sum + cat.rules.length, 0)
+  };
+}
+
+/**
+ * Extract keywords from developer prompt for filtering
+ */
+function extractKeywords(prompt) {
+  const keywordMap = {
+    "pagination": ["pagination", "paging", "page"],
+    "error": ["error", "errors", "error handling"],
+    "security": ["security", "auth", "oauth", "jwt", "token"],
+    "naming": ["naming", "camelcase", "kebab-case"],
+    "versioning": ["version", "versioning"],
+    "media": ["media", "content type", "json"],
+    "sorting": ["sort", "sorting"],
+    "filtering": ["filter", "filtering"],
+    "bulk": ["bulk", "batch"],
+    "sparse": ["sparse", "fields"],
+    "operations": ["operations", "crud"]
+  };
+
+  const found = [];
+  for (const [category, keywords] of Object.entries(keywordMap)) {
+    if (keywords.some(kw => prompt.includes(kw))) {
+      found.push(category);
+    }
+  }
+  return found;
+}