@documentation-robotics/cli 0.1.0 → 0.1.7

package/dist/audit/relationships/ai/parser.js

@@ -0,0 +1,197 @@
+import { recommendationImpactScore } from "../../types.js";
+import { getErrorMessage } from "../../../utils/errors.js";
+class ResponseParser {
+  /**
+   * Parse element evaluation recommendations from Claude response
+   */
+  parseElementRecommendations(response) {
+    const jsonMatch = response.match(/```json\n([\s\S]*?)\n```/) || response.match(/\[[\s\S]*\]/);
+    if (!jsonMatch) {
+      const truncated = response.substring(0, 200);
+      throw new Error(`Failed to extract JSON from AI response. Expected JSON array in code block or raw JSON array.
+Received: ${truncated}${response.length > 200 ? "..." : ""}`);
+    }
+    const jsonString = jsonMatch[1] || jsonMatch[0];
+    let recommendations;
+    try {
+      recommendations = JSON.parse(jsonString);
+    } catch (error) {
+      const truncated = jsonString.substring(0, 200);
+      throw new Error(`Failed to parse JSON from AI response: ${getErrorMessage(error)}
+Received: ${truncated}${jsonString.length > 200 ? "..." : ""}`);
+    }
+    if (!Array.isArray(recommendations))
+      throw new Error("Expected JSON array of recommendations from AI response");
+    return recommendations.map((r, index) => {
+      if (typeof r != "object" || r === null)
+        throw new Error(`Recommendation at index ${index} is not a valid object`);
+      const rec = r;
+      if (!rec.predicate || typeof rec.predicate != "string")
+        throw new Error(`Recommendation at index ${index} missing or invalid required field: predicate (must be string)`);
+      const sourceNodeType = rec.sourceNodeType || rec.source;
+      if (!sourceNodeType || typeof sourceNodeType != "string")
+        throw new Error(`Recommendation at index ${index} missing or invalid required field: sourceNodeType or source (must be string)`);
+      const destinationNodeType = rec.destinationNodeType || rec.destination;
+      if (!destinationNodeType || typeof destinationNodeType != "string")
+        throw new Error(`Recommendation at index ${index} missing or invalid required field: destinationNodeType or destination (must be string)`);
+      const justification = rec.justification || rec.reason;
+      if (!justification || typeof justification != "string")
+        throw new Error(`Recommendation at index ${index} missing or invalid required field: justification or reason (must be string)`);
+      const priority = rec.priority;
+      if (priority && typeof priority != "string")
+        throw new Error(`Recommendation at index ${index} has invalid priority field (must be string)`);
+      const standardReference = rec.standardReference;
+      if (standardReference !== void 0 && typeof standardReference != "string")
+        throw new Error(`Recommendation at index ${index} has invalid standardReference field (must be string)`);
+      const resolvedPriority = priority || "medium", impactScore = recommendationImpactScore(resolvedPriority);
+      return {
+        sourceNodeType,
+        predicate: rec.predicate,
+        destinationNodeType,
+        justification,
+        priority: resolvedPriority,
+        standardReference: typeof standardReference == "string" ? standardReference : void 0,
+        impactScore,
+        alignmentScore: 100 - impactScore
+      };
+    });
+  }
+  /**
+   * Parse layer review from Claude response
+   */
+  parseLayerReview(response) {
+    const jsonMatch = response.match(/```json\n([\s\S]*?)\n```/) || response.match(/\{[\s\S]*\}/);
+    if (!jsonMatch) {
+      const truncated = response.substring(0, 200);
+      throw new Error(`Failed to extract JSON from layer review. Expected JSON object in code block or raw JSON object.
+Received: ${truncated}${response.length > 200 ? "..." : ""}`);
+    }
+    const jsonString = jsonMatch[1] || jsonMatch[0];
+    let review;
+    try {
+      review = JSON.parse(jsonString);
+    } catch (error) {
+      const truncated = jsonString.substring(0, 200);
+      throw new Error(`Failed to parse JSON from layer review: ${getErrorMessage(error)}
+Received: ${truncated}${jsonString.length > 200 ? "..." : ""}`);
+    }
+    if (typeof review != "object" || review === null)
+      throw new Error("Layer review response is not a valid object");
+    const reviewObj = review, coherenceIssues = reviewObj.coherenceIssues || reviewObj.coherence_issues;
+    if (!coherenceIssues || !Array.isArray(coherenceIssues))
+      throw new Error("Layer review missing or invalid required field: coherenceIssues (must be array)");
+    if (!coherenceIssues.every((item) => typeof item == "string"))
+      throw new Error("Layer review coherenceIssues must contain only strings");
+    const missingPatterns = reviewObj.missingPatterns || reviewObj.missing_patterns;
+    if (!missingPatterns || !Array.isArray(missingPatterns))
+      throw new Error("Layer review missing or invalid required field: missingPatterns (must be array)");
+    if (!missingPatterns.every((item) => typeof item == "string"))
+      throw new Error("Layer review missingPatterns must contain only strings");
+    const recommendations = reviewObj.recommendations;
+    if (!recommendations || !Array.isArray(recommendations))
+      throw new Error("Layer review missing or invalid required field: recommendations (must be array)");
+    const validatedRecommendations = recommendations.map((r, index) => {
+      if (typeof r != "object" || r === null)
+        throw new Error(`Recommendation at index ${index} in layer review is not a valid object`);
+      const rec = r;
+      if (!rec.predicate || typeof rec.predicate != "string")
+        throw new Error(`Recommendation at index ${index} in layer review missing or invalid required field: predicate (must be string)`);
+      const sourceNodeType = rec.sourceNodeType || rec.source;
+      if (!sourceNodeType || typeof sourceNodeType != "string")
+        throw new Error(`Recommendation at index ${index} in layer review missing or invalid required field: sourceNodeType or source (must be string)`);
+      const destinationNodeType = rec.destinationNodeType || rec.destination;
+      if (!destinationNodeType || typeof destinationNodeType != "string")
+        throw new Error(`Recommendation at index ${index} in layer review missing or invalid required field: destinationNodeType or destination (must be string)`);
+      const justification = rec.justification || rec.reason;
+      if (!justification || typeof justification != "string")
+        throw new Error(`Recommendation at index ${index} in layer review missing or invalid required field: justification or reason (must be string)`);
+      const priority = rec.priority;
+      if (priority && typeof priority != "string")
+        throw new Error(`Recommendation at index ${index} in layer review has invalid priority field (must be string)`);
+      const standardReference = rec.standardReference;
+      if (standardReference !== void 0 && typeof standardReference != "string")
+        throw new Error(`Recommendation at index ${index} in layer review has invalid standardReference field (must be string)`);
+      const resolvedPriority = priority || "medium", impactScore = recommendationImpactScore(resolvedPriority);
+      return {
+        sourceNodeType,
+        predicate: rec.predicate,
+        destinationNodeType,
+        justification,
+        priority: resolvedPriority,
+        standardReference: typeof standardReference == "string" ? standardReference : void 0,
+        impactScore,
+        alignmentScore: 100 - impactScore
+      };
+    }), balanceAssessment = reviewObj.balanceAssessment || reviewObj.balance_assessment;
+    if (!balanceAssessment || typeof balanceAssessment != "string")
+      throw new Error("Layer review missing or invalid required field: balanceAssessment (must be string)");
+    return {
+      coherenceIssues,
+      missingPatterns,
+      recommendations: validatedRecommendations,
+      balanceAssessment
+    };
+  }
+  /**
+   * Parse inter-layer validation from Claude response
+   */
+  parseInterLayerValidation(response) {
+    const jsonMatch = response.match(/```json\n([\s\S]*?)\n```/) || response.match(/\{[\s\S]*\}/);
+    if (!jsonMatch) {
+      const truncated = response.substring(0, 200);
+      throw new Error(`Failed to extract JSON from inter-layer validation. Expected JSON object in code block or raw JSON object.
+Received: ${truncated}${response.length > 200 ? "..." : ""}`);
+    }
+    const jsonString = jsonMatch[1] || jsonMatch[0];
+    let validation;
+    try {
+      validation = JSON.parse(jsonString);
+    } catch (error) {
+      const truncated = jsonString.substring(0, 200);
+      throw new Error(`Failed to parse JSON from inter-layer validation: ${getErrorMessage(error)}
+Received: ${truncated}${jsonString.length > 200 ? "..." : ""}`);
+    }
+    if (typeof validation != "object" || validation === null)
+      throw new Error("Inter-layer validation response is not a valid object");
+    const validationObj = validation, violations = validationObj.violations || validationObj.hierarchy_violations || validationObj.cross_layer_violations || validationObj.layer_violations;
+    if (!violations || !Array.isArray(violations))
+      throw new Error("Inter-layer validation missing or invalid required field: violations (must be array)");
+    const validatedViolations = violations.map((v, index) => {
+      if (typeof v != "object" || v === null)
+        throw new Error(`Violation at index ${index} is not a valid object`);
+      const violation = v, rawSource = violation.source, sourceLayer = violation.sourceLayer || (typeof rawSource == "object" && rawSource !== null ? rawSource.layer : void 0) || violation.source_layer || violation.from;
+      if (!sourceLayer || typeof sourceLayer != "string")
+        throw new Error(`Violation at index ${index} missing or invalid field: sourceLayer (must be string)`);
+      const rawDest = violation.destination, targetLayer = violation.targetLayer || (typeof rawDest == "object" && rawDest !== null ? rawDest.layer : void 0) || violation.target_layer || violation.to;
+      if (!targetLayer || typeof targetLayer != "string")
+        throw new Error(`Violation at index ${index} missing or invalid field: targetLayer (must be string)`);
+      const issue = violation.issue || violation.violation || violation.description || violation.message || violation.problem;
+      if (!issue || typeof issue != "string")
+        throw new Error(`Violation at index ${index} missing or invalid field: issue (must be string)`);
+      return {
+        sourceLayer,
+        targetLayer,
+        issue
+      };
+    }), rawRecs = validationObj.recommendations;
+    if (!rawRecs || !Array.isArray(rawRecs))
+      throw new Error("Inter-layer validation missing or invalid required field: recommendations (must be array)");
+    const recommendations = rawRecs.map((r) => {
+      if (typeof r == "string")
+        return r;
+      if (typeof r == "object" && r !== null) {
+        const obj = r;
+        return String(obj.action || obj.description || JSON.stringify(r));
+      }
+      return String(r);
+    });
+    return {
+      violations: validatedViolations,
+      recommendations
+    };
+  }
+}
+export {
+  ResponseParser
+};
+//# sourceMappingURL=parser.js.map

package/dist/audit/relationships/ai/parser.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/audit/relationships/ai/parser.ts"],
+  "sourcesContent": ["import { recommendationImpactScore } from \"../../types.js\";\nimport { getErrorMessage } from \"../../../utils/errors.js\";\n\nexport interface RelationshipRecommendation {\n  sourceNodeType: string;\n  predicate: string;\n  destinationNodeType: string;\n  justification: string;\n  priority: \"high\" | \"medium\" | \"low\";\n  standardReference?: string;\n  /** How necessary this recommendation is (0\u2013100). Derived from priority. */\n  impactScore: number;\n  /** 100 - impactScore; aligns with NodeAIEvaluation.alignmentScore semantics */\n  alignmentScore: number;\n}\n\nexport interface LayerReview {\n  coherenceIssues: string[];\n  missingPatterns: string[];\n  recommendations: RelationshipRecommendation[];\n  balanceAssessment: string;\n}\n\nexport interface InterLayerValidation {\n  violations: Array<{\n    sourceLayer: string;\n    targetLayer: string;\n    issue: string;\n  }>;\n  recommendations: string[];\n}\n\nexport class ResponseParser {\n  /**\n   * Parse element evaluation recommendations from Claude response\n   */\n  parseElementRecommendations(response: string): RelationshipRecommendation[] {\n    // Extract JSON from Claude response\n    const jsonMatch =\n      response.match(/```json\\n([\\s\\S]*?)\\n```/) || response.match(/\\[[\\s\\S]*\\]/);\n\n    if (!jsonMatch) {\n      const truncated = response.substring(0, 200);\n      throw new Error(\n        `Failed to extract JSON from AI response. Expected JSON array in code block or raw JSON array.\\nReceived: ${truncated}${response.length > 200 ? \"...\" : \"\"}`\n      );\n    }\n\n    const jsonString = jsonMatch[1] || jsonMatch[0];\n    let recommendations: unknown;\n\n    try {\n      recommendations = JSON.parse(jsonString);\n    } catch (error: unknown) {\n      const truncated = jsonString.substring(0, 200);\n      throw new Error(\n        `Failed to parse JSON from AI response: ${getErrorMessage(error)}\\nReceived: ${truncated}${jsonString.length > 200 ? \"...\" : \"\"}`\n      );\n    }\n\n    if (!Array.isArray(recommendations)) {\n      throw new Error(\"Expected JSON array of recommendations from AI response\");\n    }\n\n    // Validate structure and normalize field names\n    return recommendations.map((r: unknown, index: number) => {\n      // Type narrowing: ensure r is an object\n      if (typeof r !== \"object\" || r === null) {\n        throw new Error(`Recommendation at index ${index} is not a valid object`);\n      }\n\n      const rec = r as Record<string, unknown>;\n\n      // Validate and extract required fields with type guards\n      if (!rec.predicate || typeof rec.predicate !== \"string\") {\n        throw new Error(\n          `Recommendation at index ${index} missing or invalid required field: predicate (must be string)`\n        );\n      }\n\n      const sourceNodeType = rec.sourceNodeType || rec.source;\n      if (!sourceNodeType || typeof sourceNodeType !== \"string\") {\n        throw new Error(\n          `Recommendation at index ${index} missing or invalid required field: sourceNodeType or source (must be string)`\n        );\n      }\n\n      const destinationNodeType = rec.destinationNodeType || rec.destination;\n      if (!destinationNodeType || typeof destinationNodeType !== \"string\") {\n        throw new Error(\n          `Recommendation at index ${index} missing or invalid required field: destinationNodeType or destination (must be string)`\n        );\n      }\n\n      const justification = rec.justification || rec.reason;\n      if (!justification || typeof justification !== \"string\") {\n        throw new Error(\n          `Recommendation at index ${index} missing or invalid required field: justification or reason (must be string)`\n        );\n      }\n\n      const priority = rec.priority;\n      if (priority && typeof priority !== \"string\") {\n        throw new Error(\n          `Recommendation at index ${index} has invalid priority field (must be string)`\n        );\n      }\n\n      const standardReference = rec.standardReference;\n      if (standardReference !== undefined && typeof standardReference !== \"string\") {\n        throw new Error(\n          `Recommendation at index ${index} has invalid standardReference field (must be string)`\n        );\n      }\n\n      const resolvedPriority = (priority as \"high\" | \"medium\" | \"low\") || \"medium\";\n      const impactScore = recommendationImpactScore(resolvedPriority);\n      return {\n        sourceNodeType,\n        predicate: rec.predicate,\n        destinationNodeType,\n        justification,\n        priority: resolvedPriority,\n        standardReference: typeof standardReference === \"string\" ? standardReference : undefined,\n        impactScore,\n        alignmentScore: 100 - impactScore,\n      };\n    });\n  }\n\n  /**\n   * Parse layer review from Claude response\n   */\n  parseLayerReview(response: string): LayerReview {\n    const jsonMatch =\n      response.match(/```json\\n([\\s\\S]*?)\\n```/) || response.match(/\\{[\\s\\S]*\\}/);\n\n    if (!jsonMatch) {\n      const truncated = response.substring(0, 200);\n      throw new Error(\n        `Failed to extract JSON from layer review. Expected JSON object in code block or raw JSON object.\\nReceived: ${truncated}${response.length > 200 ? \"...\" : \"\"}`\n      );\n    }\n\n    const jsonString = jsonMatch[1] || jsonMatch[0];\n    let review: unknown;\n\n    try {\n      review = JSON.parse(jsonString);\n    } catch (error: unknown) {\n      const truncated = jsonString.substring(0, 200);\n      throw new Error(\n        `Failed to parse JSON from layer review: ${getErrorMessage(error)}\\nReceived: ${truncated}${jsonString.length > 200 ? \"...\" : \"\"}`\n      );\n    }\n\n    // Type narrowing: ensure review is an object\n    if (typeof review !== \"object\" || review === null) {\n      throw new Error(\"Layer review response is not a valid object\");\n    }\n\n    const reviewObj = review as Record<string, unknown>;\n\n    // Validate and extract required fields with type guards\n    const coherenceIssues = reviewObj.coherenceIssues || reviewObj.coherence_issues;\n    if (!coherenceIssues || !Array.isArray(coherenceIssues)) {\n      throw new Error(\"Layer review missing or invalid required field: coherenceIssues (must be array)\");\n    }\n    if (!coherenceIssues.every((item) => typeof item === \"string\")) {\n      throw new Error(\"Layer review coherenceIssues must contain only strings\");\n    }\n\n    const missingPatterns = reviewObj.missingPatterns || reviewObj.missing_patterns;\n    if (!missingPatterns || !Array.isArray(missingPatterns)) {\n      throw new Error(\"Layer review missing or invalid required field: missingPatterns (must be array)\");\n    }\n    if (!missingPatterns.every((item) => typeof item === \"string\")) {\n      throw new Error(\"Layer review missingPatterns must contain only strings\");\n    }\n\n    const recommendations = reviewObj.recommendations;\n    if (!recommendations || !Array.isArray(recommendations)) {\n      throw new Error(\"Layer review missing or invalid required field: recommendations (must be array)\");\n    }\n\n    // Validate each recommendation in the array with per-element structural validation\n    const validatedRecommendations = recommendations.map((r: unknown, index: number) => {\n      // Type narrowing: ensure r is an object\n      if (typeof r !== \"object\" || r === null) {\n        throw new Error(`Recommendation at index ${index} in layer review is not a valid object`);\n      }\n\n      const rec = r as Record<string, unknown>;\n\n      // Validate and extract required fields with type guards (matching parseElementRecommendations)\n      if (!rec.predicate || typeof rec.predicate !== \"string\") {\n        throw new Error(\n          `Recommendation at index ${index} in layer review missing or invalid required field: predicate (must be string)`\n        );\n      }\n\n      const sourceNodeType = rec.sourceNodeType || rec.source;\n      if (!sourceNodeType || typeof sourceNodeType !== \"string\") {\n        throw new Error(\n          `Recommendation at index ${index} in layer review missing or invalid required field: sourceNodeType or source (must be string)`\n        );\n      }\n\n      const destinationNodeType = rec.destinationNodeType || rec.destination;\n      if (!destinationNodeType || typeof destinationNodeType !== \"string\") {\n        throw new Error(\n          `Recommendation at index ${index} in layer review missing or invalid required field: destinationNodeType or destination (must be string)`\n        );\n      }\n\n      const justification = rec.justification || rec.reason;\n      if (!justification || typeof justification !== \"string\") {\n        throw new Error(\n          `Recommendation at index ${index} in layer review missing or invalid required field: justification or reason (must be string)`\n        );\n      }\n\n      const priority = rec.priority;\n      if (priority && typeof priority !== \"string\") {\n        throw new Error(\n          `Recommendation at index ${index} in layer review has invalid priority field (must be string)`\n        );\n      }\n\n      const standardReference = rec.standardReference;\n      if (standardReference !== undefined && typeof standardReference !== \"string\") {\n        throw new Error(\n          `Recommendation at index ${index} in layer review has invalid standardReference field (must be string)`\n        );\n      }\n\n      const resolvedPriority = (priority as \"high\" | \"medium\" | \"low\") || \"medium\";\n      const impactScore = recommendationImpactScore(resolvedPriority);\n      return {\n        sourceNodeType,\n        predicate: rec.predicate,\n        destinationNodeType,\n        justification,\n        priority: resolvedPriority,\n        standardReference: typeof standardReference === \"string\" ? standardReference : undefined,\n        impactScore,\n        alignmentScore: 100 - impactScore,\n      };\n    });\n\n    const balanceAssessment = reviewObj.balanceAssessment || reviewObj.balance_assessment;\n    if (!balanceAssessment || typeof balanceAssessment !== \"string\") {\n      throw new Error(\"Layer review missing or invalid required field: balanceAssessment (must be string)\");\n    }\n\n    return {\n      coherenceIssues,\n      missingPatterns,\n      recommendations: validatedRecommendations,\n      balanceAssessment,\n    };\n  }\n\n  /**\n   * Parse inter-layer validation from Claude response\n   */\n  parseInterLayerValidation(response: string): InterLayerValidation {\n    const jsonMatch =\n      response.match(/```json\\n([\\s\\S]*?)\\n```/) || response.match(/\\{[\\s\\S]*\\}/);\n\n    if (!jsonMatch) {\n      const truncated = response.substring(0, 200);\n      throw new Error(\n        `Failed to extract JSON from inter-layer validation. Expected JSON object in code block or raw JSON object.\\nReceived: ${truncated}${response.length > 200 ? \"...\" : \"\"}`\n      );\n    }\n\n    const jsonString = jsonMatch[1] || jsonMatch[0];\n    let validation: unknown;\n\n    try {\n      validation = JSON.parse(jsonString);\n    } catch (error: unknown) {\n      const truncated = jsonString.substring(0, 200);\n      throw new Error(\n        `Failed to parse JSON from inter-layer validation: ${getErrorMessage(error)}\\nReceived: ${truncated}${jsonString.length > 200 ? \"...\" : \"\"}`\n      );\n    }\n\n    // Type narrowing: ensure validation is an object\n    if (typeof validation !== \"object\" || validation === null) {\n      throw new Error(\"Inter-layer validation response is not a valid object\");\n    }\n\n    const validationObj = validation as Record<string, unknown>;\n\n    // Normalize top-level violations key (Claude may use alternate key names)\n    const violations =\n      validationObj.violations ||\n      validationObj.hierarchy_violations ||\n      validationObj.cross_layer_violations ||\n      validationObj.layer_violations;\n    if (!violations || !Array.isArray(violations)) {\n      throw new Error(\"Inter-layer validation missing or invalid required field: violations (must be array)\");\n    }\n\n    // Validate each violation object with field normalization\n    const validatedViolations = violations.map((v: unknown, index: number) => {\n      if (typeof v !== \"object\" || v === null) {\n        throw new Error(`Violation at index ${index} is not a valid object`);\n      }\n      const violation = v as Record<string, unknown>;\n\n      // Normalize sourceLayer: accepts sourceLayer, source.layer, source_layer, from\n      const rawSource = violation.source;\n      const sourceLayer =\n        violation.sourceLayer ||\n        (typeof rawSource === \"object\" && rawSource !== null\n          ? (rawSource as Record<string, unknown>).layer\n          : undefined) ||\n        violation.source_layer ||\n        violation.from;\n      if (!sourceLayer || typeof sourceLayer !== \"string\") {\n        throw new Error(`Violation at index ${index} missing or invalid field: sourceLayer (must be string)`);\n      }\n\n      // Normalize targetLayer: accepts targetLayer, destination.layer, target.layer, target_layer, to\n      const rawDest = violation.destination;\n      const targetLayer =\n        violation.targetLayer ||\n        (typeof rawDest === \"object\" && rawDest !== null\n          ? (rawDest as Record<string, unknown>).layer\n          : undefined) ||\n        violation.target_layer ||\n        violation.to;\n      if (!targetLayer || typeof targetLayer !== \"string\") {\n        throw new Error(`Violation at index ${index} missing or invalid field: targetLayer (must be string)`);\n      }\n\n      // Normalize issue: accepts issue, violation, description, message, problem\n      const issue =\n        violation.issue ||\n        violation.violation ||\n        violation.description ||\n        violation.message ||\n        violation.problem;\n      if (!issue || typeof issue !== \"string\") {\n        throw new Error(`Violation at index ${index} missing or invalid field: issue (must be string)`);\n      }\n\n      return {\n        sourceLayer: sourceLayer as string,\n        targetLayer: targetLayer as string,\n        issue: issue as string,\n      };\n    });\n\n    // Normalize recommendations: accept string[] or object[]{action, description}\n    const rawRecs = validationObj.recommendations;\n    if (!rawRecs || !Array.isArray(rawRecs)) {\n      throw new Error(\"Inter-layer validation missing or invalid required field: recommendations (must be array)\");\n    }\n    const recommendations = rawRecs.map((r: unknown) => {\n      if (typeof r === \"string\") return r;\n      if (typeof r === \"object\" && r !== null) {\n        const obj = r as Record<string, unknown>;\n        return String(obj.action || obj.description || JSON.stringify(r));\n      }\n      return String(r);\n    });\n\n    return {\n      violations: validatedViolations,\n      recommendations,\n    };\n  }\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/audit/relationships/ai/prompts.js

@@ -0,0 +1,274 @@
+class PromptTemplates {
+  /**
+   * Generate element evaluation prompt for low-coverage node types
+   */
+  elementEvaluation(nodeType, coverage, predicates) {
+    const [layer, type] = nodeType.split("."), standard = this.getLayerStandard(layer), targetRange = this.getTargetRange();
+    return `Evaluate the node type '${nodeType}' for missing intra-layer relationships.
+
+Layer: ${layer}
+Node Type: ${type}
+Current Relationships: ${coverage.relationshipsPerNodeType} (target: ${targetRange})
+Layer Standard: ${standard}
+
+Available Predicates:
+${predicates.map((p) => `- ${p}: ${this.getPredicateDefinition(p)}`).join(`
+`)}
+
+Suggest meaningful intra-layer relationships based on ${standard} patterns.
+For each suggestion, provide:
+1. Source node type (this type: ${nodeType})
+2. Predicate (from available list)
+3. Destination node type (must exist in ${layer} layer)
+4. Architectural justification (reference ${standard} specification)
+5. Priority (high/medium/low)
+
+Format as JSON array of relationship recommendations.`;
+  }
+  /**
+   * Generate layer review prompt for overall coherence evaluation
+   */
+  layerReview(layer, coverage) {
+    const layerMetrics = coverage.find((c) => c.layer === layer);
+    if (!layerMetrics)
+      throw new Error(`No coverage metrics found for layer: ${layer}`);
+    const standard = this.getLayerStandard(layer);
+    return `Review the ${layer} layer relationship coverage.
+
+Node Types: ${layerMetrics.nodeTypeCount}
+Current Relationships: ${layerMetrics.relationshipCount}
+Isolation: ${layerMetrics.isolationPercentage}%
+Density: ${layerMetrics.relationshipsPerNodeType} per node type
+Standard: ${standard}
+
+Evaluate:
+1. Semantic coherence of existing relationships
+2. Missing critical relationship patterns from ${standard}
+3. Prioritized recommendations for relationship additions
+4. Balance assessment (are we over/under-specifying?)
+
+Respond with ONLY the following JSON, wrapped in a json code block (no other text before or after):
+
+\`\`\`json
+{
+  "coherenceIssues": ["description of coherence issue"],
+  "missingPatterns": ["description of missing pattern from ${standard}"],
+  "recommendations": [
+    {
+      "sourceNodeType": "${layer}.nodeType",
+      "predicate": "predicate-name",
+      "destinationNodeType": "${layer}.otherNodeType",
+      "justification": "architectural justification",
+      "priority": "high"
+    }
+  ],
+  "balanceAssessment": "brief assessment of relationship density and coverage"
+}
+\`\`\``;
+  }
+  /**
+   * Generate inter-layer gap identification prompt.
+   *
+   * Identifies cross-layer relationship schemas that are architecturally missing
+   * from the spec — schemas that SHOULD exist but DON'T — rather than validating
+   * existing ones. Output `violations` entries represent missing schemas;
+   * `recommendations` list the concrete spec files to create.
+   *
+   * @param sourceLayer - The more-abstract (lower-numbered) layer in the pair
+   * @param targetLayer - The more-concrete (higher-numbered) layer in the pair
+   * @param context - Optional spec context to ground suggestions in real node types
+   */
+  interLayerValidation(sourceLayer, targetLayer, context) {
+    const sourceNum = context?.sourceLayerNumber ?? this.getLayerNumber(sourceLayer), targetNum = context?.targetLayerNumber ?? this.getLayerNumber(targetLayer), [concreteLayer, concreteNum, abstractLayer, abstractNum] = sourceNum < targetNum ? [targetLayer, targetNum, sourceLayer, sourceNum] : [sourceLayer, sourceNum, targetLayer, targetNum], concreteTypes = context?.concreteNodeTypes?.join(", ") ?? this.getLayerNodeTypeHint(concreteLayer), abstractTypes = context?.abstractNodeTypes?.join(", ") ?? this.getLayerNodeTypeHint(abstractLayer), existingSection = context?.existingSchemas && context.existingSchemas.length > 0 ? `
+## Schemas Already Defined for This Pair
+Do NOT re-suggest these \u2014 they exist:
+${context.existingSchemas.map((s) => `- ${s}`).join(`
+`)}
+` : "", predicateSection = context?.availablePredicates && context.availablePredicates.length > 0 ? `
+## Valid Cross-Layer Predicates
+Only use predicates from this list:
+${context.availablePredicates.map((p) => `- ${p}`).join(`
+`)}
+` : `
+## Commonly Valid Cross-Layer Predicates
+Use one of: realizes, serves, accesses, uses, references, triggers, monitors, tests, covers, satisfies, implements, depends-on, maps-to, requires
+`;
+    return `You are an architecture spec analyst for the Documentation Robotics 12-layer model.
+
+## Task
+Identify cross-layer relationship schemas that are MISSING from the spec for the layer pair:
+  **${concreteLayer}** (layer ${concreteNum}, more concrete) \u2192 **${abstractLayer}** (layer ${abstractNum}, more abstract)
+
+A "missing schema" is a relationship type that:
+- Would be meaningfully instantiated in real codebases regularly \u2014 not just theoretically possible
+- Does NOT yet exist in the spec for this layer pair
+- Enables traceability, governance, or cross-cutting concern validation across this boundary
+- Follows the correct reference direction: ${concreteLayer} \u2192 ${abstractLayer}
+
+## The 12-Layer Model (concrete \u2192 abstract)
+
+| # | Layer | Standard | Representative Node Types |
+|---|-------|----------|--------------------------|
+| 12 | testing | IEEE 829 | testsuite, testcase, testdata, teststrategy, testcoverage |
+| 11 | apm | OpenTelemetry | metric, trace, span, alert, dashboard, traceconfiguration |
+| 10 | navigation | Router patterns | route, menu, menuitem, breadcrumb, flow, tab |
+|  9 | ux | Component patterns | view, subview, librarycomponent, actioncomponent, formcomponent |
+|  8 | data-store | DB patterns | database, table, collection, index, view |
+|  7 | data-model | JSON Schema | entity, attribute, relationship, enum, type |
+|  6 | api | OpenAPI 3.0 | operation, pathitem, requestbody, response, schema, securityscheme |
+|  5 | technology | ArchiMate | node, device, systemsoftware, technologyservice, infrastructureservice |
+|  4 | application | ArchiMate | applicationcomponent, applicationservice, applicationfunction, applicationinterface |
+|  3 | security | NIST SP 800-53 | secureresource, securitypolicy, threat, control, accesscontrol |
+|  2 | business | ArchiMate | businessprocess, businessservice, businessfunction, businessrole, businessobject |
+|  1 | motivation | ArchiMate | goal, driver, requirement, principle, constraint, outcome, stakeholder |
+
+## Reference Direction Rule
+CONCRETE layers (higher numbers, closer to implementation) reference ABSTRACT layers (lower numbers, closer to goals). References flow downward through the stack:
+  testing(12) \u2192 apm(11) \u2192 navigation(10) \u2192 ux(9) \u2192 data-store(8) \u2192 data-model(7) \u2192 api(6) \u2192 technology(5) \u2192 application(4) \u2192 security(3) \u2192 business(2) \u2192 motivation(1)
+
+For this pair, valid schemas define relationships **from ${concreteLayer} node types to ${abstractLayer} node types**.
+${existingSection}${predicateSection}
+## Node Types in This Pair
+
+**${concreteLayer}** (source of relationships): ${concreteTypes}
+**${abstractLayer}** (target of relationships): ${abstractTypes}
+
+## Anti-Noise Criteria
+ONLY suggest a schema if ALL of the following hold:
+1. A real development team would routinely create instances of this relationship
+2. The schema enables meaningful traceability or cross-cutting validation at this layer boundary
+3. The source and target node types are semantically compatible (the relationship "makes sense" to a developer)
+4. The gap would affect \u226510% of real models containing both layers
+5. The relationship is NOT already covered by an existing schema for this pair
+
+Do NOT suggest schemas that are:
+- Speculative, aspirational, or "might be useful someday"
+- Already covered by existing schemas (listed above)
+- In the wrong direction (abstract \u2192 concrete references are violations of the model)
+- Between node types with no natural semantic connection
+
+## Output Format
+Respond with ONLY the following JSON, wrapped in a json code block (no other text before or after):
+
+\`\`\`json
+{
+  "violations": [
+    {
+      "sourceLayer": "${concreteLayer}",
+      "targetLayer": "${abstractLayer}",
+      "issue": "Missing schema: {sourceNodeType}.{predicate}.{targetNodeType} \u2014 {one-sentence architectural justification}"
+    }
+  ],
+  "recommendations": [
+    "Add spec/schemas/relationships/${concreteLayer}/{sourceNodeType}.{predicate}.{targetNodeType}.relationship.schema.json"
+  ]
+}
+\`\`\`
+
+Rules:
+- Each violation entry corresponds to exactly one missing schema
+- Each recommendation is the concrete spec file path to create for that schema
+- Limit to at most 8 gap suggestions \u2014 prefer highest-confidence, highest-impact gaps
+- If no schemas are architecturally missing, return: { "violations": [], "recommendations": [] }`;
+  }
+  /**
+   * Get the canonical layer number (1–12) for a layer name.
+   * Returns 0 if the layer name is unrecognized.
+   */
+  getLayerNumber(layer) {
+    const idx = [
+      "motivation",
+      "business",
+      "security",
+      "application",
+      "technology",
+      "api",
+      "data-model",
+      "data-store",
+      "ux",
+      "navigation",
+      "apm",
+      "testing"
+    ].indexOf(layer);
+    return idx >= 0 ? idx + 1 : 0;
+  }
+  /**
+   * Get a representative hint string for the node types in a layer.
+   * Used as a fallback when context.concreteNodeTypes / context.abstractNodeTypes
+   * are not provided by the caller.
+   */
+  getLayerNodeTypeHint(layer) {
+    return {
+      motivation: "goal, driver, requirement, principle, constraint, outcome, stakeholder",
+      business: "businessprocess, businessservice, businessfunction, businessrole, businessobject, businessactor, product",
+      security: "secureresource, securitypolicy, threat, control, accesscontrol, identitysubject",
+      application: "applicationcomponent, applicationservice, applicationfunction, applicationinterface, applicationevent",
+      technology: "node, device, systemsoftware, technologyservice, technologyfunction, infrastructureservice",
+      api: "openapidocument, pathitem, operation, requestbody, response, schema, securityscheme, server, ratelimit",
+      "data-model": "entity, attribute, relationship, enum, type",
+      "data-store": "database, table, collection, index, view",
+      ux: "view, subview, librarycomponent, actioncomponent, formcomponent, contentcomponent, loadingstate, modal",
+      navigation: "route, menu, menuitem, breadcrumb, flow, tab",
+      apm: "metric, trace, span, alert, dashboard, traceconfiguration, logsource, sdkconfig",
+      testing: "testsuite, testcase, testdata, teststrategy, testcoverage"
+    }[layer] ?? "see layer spec for node types";
+  }
+  /**
+   * Get the standard/framework for a layer
+   */
+  getLayerStandard(layer) {
+    return {
+      motivation: "ArchiMate 3.2",
+      business: "ArchiMate 3.2",
+      security: "NIST SP 800-53",
+      application: "ArchiMate 3.2",
+      technology: "ArchiMate 3.2",
+      api: "OpenAPI 3.0",
+      "data-model": "JSON Schema Draft 7",
+      "data-store": "Database patterns",
+      ux: "React/Component patterns",
+      navigation: "Router patterns",
+      apm: "OpenTelemetry",
+      testing: "Test patterns"
+    }[layer] || "Architecture best practices";
+  }
+  /**
+   * Get target relationship range for a node type
+   *
+   * Returns a static range "2-5" for all types. This is intentionally
+   * simplified for AI prompts to avoid over-constraining suggestions.
+   * Type-specific refinement could be added in the future if needed,
+   * but the current approach works well for generating diverse recommendations.
+   */
+  getTargetRange() {
+    return "2-5";
+  }
+  /**
+   * Get predicate definition/description
+   *
+   * NOTE: These predicate definitions are intentionally a curated subset
+   * rather than being loaded from the full relationship catalog. This is
+   * by design to keep AI prompts focused on the most common and important
+   * relationships. The full catalog has 252 relationship types which would
+   * overwhelm the AI context window and reduce prompt clarity.
+   */
+  getPredicateDefinition(predicate) {
+    return {
+      realizes: "Realization relationship - implements or fulfills",
+      serves: "Serving relationship - provides service to",
+      accesses: "Access relationship - reads/writes data",
+      triggers: "Triggering relationship - initiates or causes",
+      influences: "Influence relationship - affects or impacts",
+      uses: "Usage relationship - employs or utilizes",
+      composes: "Composition relationship - structural part-of",
+      aggregates: "Aggregation relationship - logical grouping",
+      specializes: "Specialization relationship - is-a subtype of",
+      assigns: "Assignment relationship - allocates responsibility",
+      flows: "Flow relationship - information or control transfer"
+    }[predicate] || "Relationship between elements";
+  }
+}
+export {
+  PromptTemplates
+};
+//# sourceMappingURL=prompts.js.map

package/dist/audit/relationships/ai/prompts.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/audit/relationships/ai/prompts.ts"],
+  "sourcesContent": ["import type { CoverageMetrics } from \"../../types.js\";\n\n/**\n * Optional spec context passed to interLayerValidation() to ground the prompt\n * in real node types and existing schemas rather than relying on static hints.\n */\nexport interface InterLayerContext {\n  /** 1-based layer number of the more-abstract (lower-numbered) layer */\n  sourceLayerNumber: number;\n  /** 1-based layer number of the more-concrete (higher-numbered) layer */\n  targetLayerNumber: number;\n  /** Node types available in the more-concrete layer (concrete \u2192 abstract references) */\n  concreteNodeTypes?: string[];\n  /** Node types available in the more-abstract layer */\n  abstractNodeTypes?: string[];\n  /** Cross-layer schemas already defined for this pair \u2014 excluded from suggestions */\n  existingSchemas?: string[];\n  /** Predicates valid for cross-layer use in this spec version */\n  availablePredicates?: string[];\n}\n\nexport class PromptTemplates {\n  /**\n   * Generate element evaluation prompt for low-coverage node types\n   */\n  elementEvaluation(\n    nodeType: string,\n    coverage: CoverageMetrics,\n    predicates: string[]\n  ): string {\n    const [layer, type] = nodeType.split(\".\");\n    const standard = this.getLayerStandard(layer);\n    const targetRange = this.getTargetRange();\n\n    return `Evaluate the node type '${nodeType}' for missing intra-layer relationships.\n\nLayer: ${layer}\nNode Type: ${type}\nCurrent Relationships: ${coverage.relationshipsPerNodeType} (target: ${targetRange})\nLayer Standard: ${standard}\n\nAvailable Predicates:\n${predicates.map((p) => `- ${p}: ${this.getPredicateDefinition(p)}`).join(\"\\n\")}\n\nSuggest meaningful intra-layer relationships based on ${standard} patterns.\nFor each suggestion, provide:\n1. Source node type (this type: ${nodeType})\n2. Predicate (from available list)\n3. Destination node type (must exist in ${layer} layer)\n4. Architectural justification (reference ${standard} specification)\n5. Priority (high/medium/low)\n\nFormat as JSON array of relationship recommendations.`;\n  }\n\n  /**\n   * Generate layer review prompt for overall coherence evaluation\n   */\n  layerReview(layer: string, coverage: CoverageMetrics[]): string {\n    const layerMetrics = coverage.find((c) => c.layer === layer);\n    if (!layerMetrics) {\n      throw new Error(`No coverage metrics found for layer: ${layer}`);\n    }\n\n    const standard = this.getLayerStandard(layer);\n\n    return `Review the ${layer} layer relationship coverage.\n\nNode Types: ${layerMetrics.nodeTypeCount}\nCurrent Relationships: ${layerMetrics.relationshipCount}\nIsolation: ${layerMetrics.isolationPercentage}%\nDensity: ${layerMetrics.relationshipsPerNodeType} per node type\nStandard: ${standard}\n\nEvaluate:\n1. Semantic coherence of existing relationships\n2. Missing critical relationship patterns from ${standard}\n3. Prioritized recommendations for relationship additions\n4. Balance assessment (are we over/under-specifying?)\n\nRespond with ONLY the following JSON, wrapped in a json code block (no other text before or after):\n\n\\`\\`\\`json\n{\n  \"coherenceIssues\": [\"description of coherence issue\"],\n  \"missingPatterns\": [\"description of missing pattern from ${standard}\"],\n  \"recommendations\": [\n    {\n      \"sourceNodeType\": \"${layer}.nodeType\",\n      \"predicate\": \"predicate-name\",\n      \"destinationNodeType\": \"${layer}.otherNodeType\",\n      \"justification\": \"architectural justification\",\n      \"priority\": \"high\"\n    }\n  ],\n  \"balanceAssessment\": \"brief assessment of relationship density and coverage\"\n}\n\\`\\`\\``;\n  }\n\n  /**\n   * Generate inter-layer gap identification prompt.\n   *\n   * Identifies cross-layer relationship schemas that are architecturally missing\n   * from the spec \u2014 schemas that SHOULD exist but DON'T \u2014 rather than validating\n   * existing ones. Output `violations` entries represent missing schemas;\n   * `recommendations` list the concrete spec files to create.\n   *\n   * @param sourceLayer - The more-abstract (lower-numbered) layer in the pair\n   * @param targetLayer - The more-concrete (higher-numbered) layer in the pair\n   * @param context - Optional spec context to ground suggestions in real node types\n   */\n  interLayerValidation(\n    sourceLayer: string,\n    targetLayer: string,\n    context?: InterLayerContext\n  ): string {\n    // Determine which layer is more concrete (higher-numbered = closer to implementation).\n    // The pipeline always passes source=lower-index, target=higher-index, so target\n    // is typically the concrete layer. Use context numbers when available.\n    const sourceNum = context?.sourceLayerNumber ?? this.getLayerNumber(sourceLayer);\n    const targetNum = context?.targetLayerNumber ?? this.getLayerNumber(targetLayer);\n\n    const [concreteLayer, concreteNum, abstractLayer, abstractNum] =\n      sourceNum < targetNum\n        ? [targetLayer, targetNum, sourceLayer, sourceNum]\n        : [sourceLayer, sourceNum, targetLayer, targetNum];\n\n    // Node type sections \u2014 use context when available, otherwise fall back to static list\n    const concreteTypes =\n      context?.concreteNodeTypes?.join(\", \") ??\n      this.getLayerNodeTypeHint(concreteLayer);\n    const abstractTypes =\n      context?.abstractNodeTypes?.join(\", \") ??\n      this.getLayerNodeTypeHint(abstractLayer);\n\n    // Existing-schema section (skip boilerplate when the pair has no prior schemas)\n    const existingSection =\n      context?.existingSchemas && context.existingSchemas.length > 0\n        ? `\\n## Schemas Already Defined for This Pair\\nDo NOT re-suggest these \u2014 they exist:\\n${context.existingSchemas.map((s) => `- ${s}`).join(\"\\n\")}\\n`\n        : \"\";\n\n    // Available predicates section\n    const predicateSection =\n      context?.availablePredicates && context.availablePredicates.length > 0\n        ? `\\n## Valid Cross-Layer Predicates\\nOnly use predicates from this list:\\n${context.availablePredicates.map((p) => `- ${p}`).join(\"\\n\")}\\n`\n        : `\\n## Commonly Valid Cross-Layer Predicates\\nUse one of: realizes, serves, accesses, uses, references, triggers, monitors, tests, covers, satisfies, implements, depends-on, maps-to, requires\\n`;\n\n    return `You are an architecture spec analyst for the Documentation Robotics 12-layer model.\n\n## Task\nIdentify cross-layer relationship schemas that are MISSING from the spec for the layer pair:\n  **${concreteLayer}** (layer ${concreteNum}, more concrete) \u2192 **${abstractLayer}** (layer ${abstractNum}, more abstract)\n\nA \"missing schema\" is a relationship type that:\n- Would be meaningfully instantiated in real codebases regularly \u2014 not just theoretically possible\n- Does NOT yet exist in the spec for this layer pair\n- Enables traceability, governance, or cross-cutting concern validation across this boundary\n- Follows the correct reference direction: ${concreteLayer} \u2192 ${abstractLayer}\n\n## The 12-Layer Model (concrete \u2192 abstract)\n\n| # | Layer | Standard | Representative Node Types |\n|---|-------|----------|--------------------------|\n| 12 | testing | IEEE 829 | testsuite, testcase, testdata, teststrategy, testcoverage |\n| 11 | apm | OpenTelemetry | metric, trace, span, alert, dashboard, traceconfiguration |\n| 10 | navigation | Router patterns | route, menu, menuitem, breadcrumb, flow, tab |\n|  9 | ux | Component patterns | view, subview, librarycomponent, actioncomponent, formcomponent |\n|  8 | data-store | DB patterns | database, table, collection, index, view |\n|  7 | data-model | JSON Schema | entity, attribute, relationship, enum, type |\n|  6 | api | OpenAPI 3.0 | operation, pathitem, requestbody, response, schema, securityscheme |\n|  5 | technology | ArchiMate | node, device, systemsoftware, technologyservice, infrastructureservice |\n|  4 | application | ArchiMate | applicationcomponent, applicationservice, applicationfunction, applicationinterface |\n|  3 | security | NIST SP 800-53 | secureresource, securitypolicy, threat, control, accesscontrol |\n|  2 | business | ArchiMate | businessprocess, businessservice, businessfunction, businessrole, businessobject |\n|  1 | motivation | ArchiMate | goal, driver, requirement, principle, constraint, outcome, stakeholder |\n\n## Reference Direction Rule\nCONCRETE layers (higher numbers, closer to implementation) reference ABSTRACT layers (lower numbers, closer to goals). References flow downward through the stack:\n  testing(12) \u2192 apm(11) \u2192 navigation(10) \u2192 ux(9) \u2192 data-store(8) \u2192 data-model(7) \u2192 api(6) \u2192 technology(5) \u2192 application(4) \u2192 security(3) \u2192 business(2) \u2192 motivation(1)\n\nFor this pair, valid schemas define relationships **from ${concreteLayer} node types to ${abstractLayer} node types**.\n${existingSection}${predicateSection}\n## Node Types in This Pair\n\n**${concreteLayer}** (source of relationships): ${concreteTypes}\n**${abstractLayer}** (target of relationships): ${abstractTypes}\n\n## Anti-Noise Criteria\nONLY suggest a schema if ALL of the following hold:\n1. A real development team would routinely create instances of this relationship\n2. The schema enables meaningful traceability or cross-cutting validation at this layer boundary\n3. The source and target node types are semantically compatible (the relationship \"makes sense\" to a developer)\n4. The gap would affect \u226510% of real models containing both layers\n5. The relationship is NOT already covered by an existing schema for this pair\n\nDo NOT suggest schemas that are:\n- Speculative, aspirational, or \"might be useful someday\"\n- Already covered by existing schemas (listed above)\n- In the wrong direction (abstract \u2192 concrete references are violations of the model)\n- Between node types with no natural semantic connection\n\n## Output Format\nRespond with ONLY the following JSON, wrapped in a json code block (no other text before or after):\n\n\\`\\`\\`json\n{\n  \"violations\": [\n    {\n      \"sourceLayer\": \"${concreteLayer}\",\n      \"targetLayer\": \"${abstractLayer}\",\n      \"issue\": \"Missing schema: {sourceNodeType}.{predicate}.{targetNodeType} \u2014 {one-sentence architectural justification}\"\n    }\n  ],\n  \"recommendations\": [\n    \"Add spec/schemas/relationships/${concreteLayer}/{sourceNodeType}.{predicate}.{targetNodeType}.relationship.schema.json\"\n  ]\n}\n\\`\\`\\`\n\nRules:\n- Each violation entry corresponds to exactly one missing schema\n- Each recommendation is the concrete spec file path to create for that schema\n- Limit to at most 8 gap suggestions \u2014 prefer highest-confidence, highest-impact gaps\n- If no schemas are architecturally missing, return: { \"violations\": [], \"recommendations\": [] }`;\n  }\n\n  /**\n   * Get the canonical layer number (1\u201312) for a layer name.\n   * Returns 0 if the layer name is unrecognized.\n   */\n  private getLayerNumber(layer: string): number {\n    const order = [\n      \"motivation\",\n      \"business\",\n      \"security\",\n      \"application\",\n      \"technology\",\n      \"api\",\n      \"data-model\",\n      \"data-store\",\n      \"ux\",\n      \"navigation\",\n      \"apm\",\n      \"testing\",\n    ];\n    const idx = order.indexOf(layer);\n    return idx >= 0 ? idx + 1 : 0;\n  }\n\n  /**\n   * Get a representative hint string for the node types in a layer.\n   * Used as a fallback when context.concreteNodeTypes / context.abstractNodeTypes\n   * are not provided by the caller.\n   */\n  private getLayerNodeTypeHint(layer: string): string {\n    const hints: Record<string, string> = {\n      motivation: \"goal, driver, requirement, principle, constraint, outcome, stakeholder\",\n      business:\n        \"businessprocess, businessservice, businessfunction, businessrole, businessobject, businessactor, product\",\n      security: \"secureresource, securitypolicy, threat, control, accesscontrol, identitysubject\",\n      application:\n        \"applicationcomponent, applicationservice, applicationfunction, applicationinterface, applicationevent\",\n      technology:\n        \"node, device, systemsoftware, technologyservice, technologyfunction, infrastructureservice\",\n      api: \"openapidocument, pathitem, operation, requestbody, response, schema, securityscheme, server, ratelimit\",\n      \"data-model\": \"entity, attribute, relationship, enum, type\",\n      \"data-store\": \"database, table, collection, index, view\",\n      ux: \"view, subview, librarycomponent, actioncomponent, formcomponent, contentcomponent, loadingstate, modal\",\n      navigation: \"route, menu, menuitem, breadcrumb, flow, tab\",\n      apm: \"metric, trace, span, alert, dashboard, traceconfiguration, logsource, sdkconfig\",\n      testing: \"testsuite, testcase, testdata, teststrategy, testcoverage\",\n    };\n    return hints[layer] ?? \"see layer spec for node types\";\n  }\n\n  /**\n   * Get the standard/framework for a layer\n   */\n  getLayerStandard(layer: string): string {\n    const standards: Record<string, string> = {\n      motivation: \"ArchiMate 3.2\",\n      business: \"ArchiMate 3.2\",\n      security: \"NIST SP 800-53\",\n      application: \"ArchiMate 3.2\",\n      technology: \"ArchiMate 3.2\",\n      api: \"OpenAPI 3.0\",\n      \"data-model\": \"JSON Schema Draft 7\",\n      \"data-store\": \"Database patterns\",\n      ux: \"React/Component patterns\",\n      navigation: \"Router patterns\",\n      apm: \"OpenTelemetry\",\n      testing: \"Test patterns\",\n    };\n    return standards[layer] || \"Architecture best practices\";\n  }\n\n  /**\n   * Get target relationship range for a node type\n   *\n   * Returns a static range \"2-5\" for all types. This is intentionally\n   * simplified for AI prompts to avoid over-constraining suggestions.\n   * Type-specific refinement could be added in the future if needed,\n   * but the current approach works well for generating diverse recommendations.\n   */\n  private getTargetRange(): string {\n    // Default target based on common patterns across all types\n    return \"2-5\";\n  }\n\n  /**\n   * Get predicate definition/description\n   *\n   * NOTE: These predicate definitions are intentionally a curated subset\n   * rather than being loaded from the full relationship catalog. This is\n   * by design to keep AI prompts focused on the most common and important\n   * relationships. The full catalog has 252 relationship types which would\n   * overwhelm the AI context window and reduce prompt clarity.\n   */\n  private getPredicateDefinition(predicate: string): string {\n    // Curated predicate definitions (subset of relationship catalog)\n    const definitions: Record<string, string> = {\n      realizes: \"Realization relationship - implements or fulfills\",\n      serves: \"Serving relationship - provides service to\",\n      accesses: \"Access relationship - reads/writes data\",\n      triggers: \"Triggering relationship - initiates or causes\",\n      influences: \"Influence relationship - affects or impacts\",\n      uses: \"Usage relationship - employs or utilizes\",\n      composes: \"Composition relationship - structural part-of\",\n      aggregates: \"Aggregation relationship - logical grouping\",\n      specializes: \"Specialization relationship - is-a subtype of\",\n      assigns: \"Assignment relationship - allocates responsibility\",\n      flows: \"Flow relationship - information or control transfer\",\n    };\n\n    return definitions[predicate] || \"Relationship between elements\";\n  }\n}\n"],
+  "mappings": "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",
+  "names": []
+}