archgraph-argo 0.26.2 → 0.28.0

package/argo/scripts/graph-semantics.js

@@ -1,227 +1,363 @@
-// Shared graph-semantics validation for SystemArchitecture.
-// Used by both validateSystemArchitecture.js (full validation) and
-// systemarchitecture-mcp-server.js (mutation-path validation).
-//
-// This module eliminates the duplicate validateGraphSemantics implementations.
-// All callers get identical core checks; ArchiMate endpoint matrix and view
-// element limits are parameterized so the full validator can check everything
-// while the mutation path only checks what changed.
-
-const {
-  elementTypeMetadata,
-  relationshipCategoryByType,
-  validateRelationshipEndpointTypes,
-} = require('./archimate32-rules');
-
-/**
- * Core graph-semantics checks that are always identical for all callers.
- * 
- * @param {object} document - parsed SystemArchitecture JSON
- * @param {string[]} errors - error accumulator
- */
-function validateGraphSemantics(document, errors) {
-  if (!document || typeof document !== 'object') {
-    return;
-  }
-
-  const elements = Array.isArray(document.elements) ? document.elements : [];
-  const relationships = Array.isArray(document.relationships) ? document.relationships : [];
-  const views = Array.isArray(document.views) ? document.views : [];
-  const elementById = new Map();
-  const relationshipById = new Map();
-
-  // --- elements: identity, type, parent ---
-  for (const element of elements) {
-    if (!element || typeof element !== 'object') {
-      continue;
-    }
-    if (elementById.has(element.id)) {
-      errors.push(`elements contains duplicate id '${element.id}'`);
-      continue;
-    }
-    elementById.set(element.id, element);
-    if (!elementTypeMetadata.has(element.type)) {
-      errors.push(`elements '${element.id}' uses unsupported ArchiMate element type '${element.type}'`);
-    }
-  }
-
-  for (const element of elements) {
-    if (!element || typeof element !== 'object' || !element.parent) {
-      continue;
-    }
-    if (!elementById.has(element.parent)) {
-      errors.push(`elements '${element.id}' references missing parent '${element.parent}'`);
-    }
-  }
-
-  // --- relationships: identity, type, endpoints, statement ---
-  for (const relationship of relationships) {
-    if (!relationship || typeof relationship !== 'object') {
-      continue;
-    }
-    if (relationshipById.has(relationship.id)) {
-      errors.push(`relationships contains duplicate id '${relationship.id}'`);
-      continue;
-    }
-    relationshipById.set(relationship.id, relationship);
-    if (!relationshipCategoryByType.has(relationship.type)) {
-      errors.push(`relationships '${relationship.id}' uses unsupported ArchiMate relationship type '${relationship.type}'`);
-    }
-
-    const source = elementById.get(relationship.source_id);
-    if (!source) {
-      errors.push(`relationships '${relationship.id}' references missing source_id '${relationship.source_id}'`);
-    } else if (relationship.source_name !== source.name) {
-      errors.push(`relationships '${relationship.id}' source_name '${relationship.source_name}' does not match element '${relationship.source_id}' name '${source.name}'`);
-    }
-
-    const target = elementById.get(relationship.target_id);
-    if (!target) {
-      errors.push(`relationships '${relationship.id}' references missing target_id '${relationship.target_id}'`);
-    } else if (relationship.target_name !== target.name) {
-      errors.push(`relationships '${relationship.id}' target_name '${relationship.target_name}' does not match element '${relationship.target_id}' name '${target.name}'`);
-    }
-
-    const expectedStatement = source && target
-      ? `${source.name} --(${relationship.type})--> ${target.name}`
-      : undefined;
-    if (expectedStatement && relationship.statement !== expectedStatement) {
-      errors.push(`relationships '${relationship.id}' statement must be '${expectedStatement}'`);
-    }
-  }
-
-  // --- views: topology, membership, endpoint co-occurrence ---
-  const topLevelViews = views.filter(view => view && typeof view === 'object' && !view.parent_element_id);
-  if (topLevelViews.length !== 1) {
-    errors.push(`views must contain exactly one top-level view named 'SystemArchitecture'; found ${topLevelViews.length}`);
-  } else if (topLevelViews[0].view_name !== 'SystemArchitecture') {
-    errors.push(`top-level view '${topLevelViews[0].view_id}' view_name must be 'SystemArchitecture'`);
-  }
-
-  const elementIdsIncludedInViews = new Set();
-  const relationshipIdsIncludedInViews = new Set();
-  for (const view of views) {
-    if (!view || typeof view !== 'object') {
-      continue;
-    }
-    if (!view.parent_element_id && view.view_name !== 'SystemArchitecture') {
-      errors.push(`views '${view.view_id}' must declare parent_element_id unless it is the top-level SystemArchitecture view`);
-    }
-    if (view.parent_element_id) {
-      const parent = elementById.get(view.parent_element_id);
-      if (!parent) {
-        errors.push(`views '${view.view_id}' references missing parent_element_id '${view.parent_element_id}'`);
-      } else if (view.parent_element_name && view.parent_element_name !== parent.name) {
-        errors.push(`views '${view.view_id}' parent_element_name '${view.parent_element_name}' does not match element '${view.parent_element_id}' name '${parent.name}'`);
-      }
-    }
-    const includedElementIds = new Set(view.included_elements || []);
-    if (includedElementIds.size !== (view.included_elements || []).length) {
-      errors.push(`views '${view.view_id}' must not contain duplicate included_elements`);
-    }
-    for (const elementId of view.included_elements || []) {
-      elementIdsIncludedInViews.add(elementId);
-      if (!elementById.has(elementId)) {
-        errors.push(`views '${view.view_id}' references missing included element '${elementId}'`);
-      }
-    }
-    const includedRelationshipIds = new Set(view.included_relationships || []);
-    if (includedRelationshipIds.size !== (view.included_relationships || []).length) {
-      errors.push(`views '${view.view_id}' must not contain duplicate included_relationships`);
-    }
-    for (const relationshipId of view.included_relationships || []) {
-      relationshipIdsIncludedInViews.add(relationshipId);
-      const rel = relationshipById.get(relationshipId);
-      if (!rel) {
-        errors.push(`views '${view.view_id}' references missing included relationship '${relationshipId}'`);
-        continue;
-      }
-      if (!includedElementIds.has(rel.source_id)) {
-        errors.push(`views '${view.view_id}' includes relationship '${relationshipId}' but not source element '${rel.source_id}'`);
-      }
-      if (!includedElementIds.has(rel.target_id)) {
-        errors.push(`views '${view.view_id}' includes relationship '${relationshipId}' but not target element '${rel.target_id}'`);
-      }
-    }
-  }
-
-  for (const element of elements) {
-    if (element && typeof element === 'object' && !elementIdsIncludedInViews.has(element.id)) {
-      errors.push(`elements '${element.id}' must be included in at least one view`);
-    }
-  }
-
-  for (const relationship of relationships) {
-    if (relationship && typeof relationship === 'object' && !relationshipIdsIncludedInViews.has(relationship.id)) {
-      errors.push(`relationships '${relationship.id}' must be included in at least one view`);
-    }
-  }
-}
-
-/**
- * Validate ArchiMate 3.2 endpoint type matrix for relationships.
- *
- * @param {object} document - parsed SystemArchitecture JSON
- * @param {string[]} errors - error accumulator
- * @param {object} [options]
- * @param {string[]} [options.touchedRelationshipIds] - if provided, only these
- *   relationships are checked; if omitted/empty, ALL relationships are checked
- */
-function validateArchiMateEndpointMatrix(document, errors, options = {}) {
-  const elementById = new Map(
-    (document.elements || []).map(element => [element.id, element]),
-  );
-  const relationshipIdSet =
-    Array.isArray(options.touchedRelationshipIds) && options.touchedRelationshipIds.length > 0
-      ? new Set(options.touchedRelationshipIds)
-      : undefined;
-
-  for (const relationship of document.relationships || []) {
-    if (relationshipIdSet && !relationshipIdSet.has(relationship.id)) {
-      continue;
-    }
-    const source = elementById.get(relationship.source_id);
-    const target = elementById.get(relationship.target_id);
-    errors.push(...validateRelationshipEndpointTypes(relationship, source, target));
-  }
-}
-
-/**
- * Validate that each view contains at most 15 included_elements.
- * included_relationships do not consume this quota.
- *
- * @param {object} document - parsed SystemArchitecture JSON
- * @param {string[]} errors - error accumulator
- * @param {object} [options]
- * @param {string[]} [options.touchedViewIds] - if provided, only these views
- *   are checked; if omitted/empty, ALL views are checked
- */
-function validateViewElementLimits(document, errors, options = {}) {
-  const touchedViewIdSet =
-    Array.isArray(options.touchedViewIds) && options.touchedViewIds.length > 0
-      ? new Set(options.touchedViewIds)
-      : undefined;
-  const MAX_INCLUDED_ELEMENTS = 15;
-
-  for (const view of document.views || []) {
-    if (!view) {
-      continue;
-    }
-    if (touchedViewIdSet && !touchedViewIdSet.has(view.view_id)) {
-      continue;
-    }
-    const elementCount = Array.isArray(view.included_elements) ? view.included_elements.length : 0;
-    if (elementCount > MAX_INCLUDED_ELEMENTS) {
-      errors.push(
-        `views '${view.view_id}' must contain at most ${MAX_INCLUDED_ELEMENTS} elements; found ${elementCount}. ` +
-        'Split the content into layered sub-views before adding more elements.',
-      );
-    }
-  }
-}
-
-module.exports = {
-  validateGraphSemantics,
-  validateArchiMateEndpointMatrix,
-  validateViewElementLimits,
-};
+// Shared graph-semantics validation for SystemArchitecture.
+// Used by both validateSystemArchitecture.js (full validation) and
+// systemarchitecture-mcp-server.js (mutation-path validation).
+//
+// This module eliminates the duplicate validateGraphSemantics implementations.
+// All callers get identical core checks; the modeling language (element types,
+// relationship types, endpoint matrix, statement grammar, root-view name and
+// view element limit) is supplied by an *ontology* so a repository that ships
+// its own schema under .argo/schema is validated against its own language.
+//
+// The ontology argument is optional: when omitted, the default ArchiMate 3.2
+// (ArchiMate 3.2 + ARGO) ontology is used, preserving historical behaviour.
+
+const { loadSchemaBundleAndOntology } = require('./schema-bundle.js');
+
+let defaultOntology = null;
+
+function resolveOntology(ontology) {
+  if (ontology) {
+    return ontology;
+  }
+  if (!defaultOntology) {
+    defaultOntology = loadSchemaBundleAndOntology(process.cwd()).ontology;
+  }
+  return defaultOntology;
+}
+
+/**
+ * Core graph-semantics checks that are always identical for all callers.
+ *
+ * @param {object} document - parsed SystemArchitecture JSON
+ * @param {string[]} errors - error accumulator
+ * @param {object} [ontology] - resolved modeling language (defaults to ArchiMate 3.2)
+ */
+function validateGraphSemantics(document, errors, ontology) {
+  if (!document || typeof document !== 'object') {
+    return;
+  }
+  const language = resolveOntology(ontology);
+  const invariants = language.invariants || {};
+  const elementTypeLabel = language.elementTypeErrorLabel || language.language || 'the';
+  const relationshipTypeLabel = language.relationshipTypeErrorLabel || language.language || 'the';
+  const rootViewName = invariants.rootViewName === undefined ? 'SystemArchitecture' : invariants.rootViewName;
+
+  const elements = Array.isArray(document.elements) ? document.elements : [];
+  const relationships = Array.isArray(document.relationships) ? document.relationships : [];
+  const views = Array.isArray(document.views) ? document.views : [];
+  const elementById = new Map();
+  const relationshipById = new Map();
+
+  // --- elements: identity, type, parent ---
+  for (const element of elements) {
+    if (!element || typeof element !== 'object') {
+      continue;
+    }
+    if (elementById.has(element.id)) {
+      errors.push(`elements contains duplicate id '${element.id}'`);
+      continue;
+    }
+    elementById.set(element.id, element);
+    if (!language.isSupportedElementType(element.type)) {
+      errors.push(`elements '${element.id}' uses unsupported ${elementTypeLabel} element type '${element.type}'`);
+    }
+  }
+
+  for (const element of elements) {
+    if (!element || typeof element !== 'object' || !element.parent) {
+      continue;
+    }
+    if (!elementById.has(element.parent)) {
+      errors.push(`elements '${element.id}' references missing parent '${element.parent}'`);
+    }
+  }
+
+  // --- relationships: identity, type, endpoints, statement ---
+  for (const relationship of relationships) {
+    if (!relationship || typeof relationship !== 'object') {
+      continue;
+    }
+    if (relationshipById.has(relationship.id)) {
+      errors.push(`relationships contains duplicate id '${relationship.id}'`);
+      continue;
+    }
+    relationshipById.set(relationship.id, relationship);
+    if (!language.isSupportedRelationshipType(relationship.type)) {
+      errors.push(`relationships '${relationship.id}' uses unsupported ${relationshipTypeLabel} relationship type '${relationship.type}'`);
+    }
+
+    const source = elementById.get(relationship.source_id);
+    if (!source) {
+      errors.push(`relationships '${relationship.id}' references missing source_id '${relationship.source_id}'`);
+    } else if (relationship.source_name !== source.name) {
+      errors.push(`relationships '${relationship.id}' source_name '${relationship.source_name}' does not match element '${relationship.source_id}' name '${source.name}'`);
+    }
+
+    const target = elementById.get(relationship.target_id);
+    if (!target) {
+      errors.push(`relationships '${relationship.id}' references missing target_id '${relationship.target_id}'`);
+    } else if (relationship.target_name !== target.name) {
+      errors.push(`relationships '${relationship.id}' target_name '${relationship.target_name}' does not match element '${relationship.target_id}' name '${target.name}'`);
+    }
+
+    if (invariants.statementGrammar === false) {
+      continue;
+    }
+    const expectedStatement = source && target
+      ? `${source.name} --(${relationship.type})--> ${target.name}`
+      : undefined;
+    if (expectedStatement && relationship.statement !== expectedStatement) {
+      errors.push(`relationships '${relationship.id}' statement must be '${expectedStatement}'`);
+    }
+  }
+
+  // --- views: topology, membership, endpoint co-occurrence ---
+  const topLevelViews = views.filter(view => view && typeof view === 'object' && !view.parent_element_id);
+  if (topLevelViews.length !== 1) {
+    errors.push(
+      rootViewName
+        ? `views must contain exactly one top-level view named '${rootViewName}'; found ${topLevelViews.length}`
+        : `views must contain exactly one top-level view; found ${topLevelViews.length}`,
+    );
+  } else if (rootViewName && topLevelViews[0].view_name !== rootViewName) {
+    errors.push(`top-level view '${topLevelViews[0].view_id}' view_name must be '${rootViewName}'`);
+  }
+
+  const elementIdsIncludedInViews = new Set();
+  const relationshipIdsIncludedInViews = new Set();
+  for (const view of views) {
+    if (!view || typeof view !== 'object') {
+      continue;
+    }
+    if (!view.parent_element_id && rootViewName && view.view_name !== rootViewName) {
+      errors.push(`views '${view.view_id}' must declare parent_element_id unless it is the top-level ${rootViewName} view`);
+    }
+    if (view.parent_element_id) {
+      const parent = elementById.get(view.parent_element_id);
+      if (!parent) {
+        errors.push(`views '${view.view_id}' references missing parent_element_id '${view.parent_element_id}'`);
+      } else if (view.parent_element_name && view.parent_element_name !== parent.name) {
+        errors.push(`views '${view.view_id}' parent_element_name '${view.parent_element_name}' does not match element '${view.parent_element_id}' name '${parent.name}'`);
+      }
+    }
+    const includedElementIds = new Set(view.included_elements || []);
+    if (includedElementIds.size !== (view.included_elements || []).length) {
+      errors.push(`views '${view.view_id}' must not contain duplicate included_elements`);
+    }
+    for (const elementId of view.included_elements || []) {
+      elementIdsIncludedInViews.add(elementId);
+      if (!elementById.has(elementId)) {
+        errors.push(`views '${view.view_id}' references missing included element '${elementId}'`);
+      }
+    }
+    const includedRelationshipIds = new Set(view.included_relationships || []);
+    if (includedRelationshipIds.size !== (view.included_relationships || []).length) {
+      errors.push(`views '${view.view_id}' must not contain duplicate included_relationships`);
+    }
+    for (const relationshipId of view.included_relationships || []) {
+      relationshipIdsIncludedInViews.add(relationshipId);
+      const rel = relationshipById.get(relationshipId);
+      if (!rel) {
+        errors.push(`views '${view.view_id}' references missing included relationship '${relationshipId}'`);
+        continue;
+      }
+      if (!includedElementIds.has(rel.source_id)) {
+        errors.push(`views '${view.view_id}' includes relationship '${relationshipId}' but not source element '${rel.source_id}'`);
+      }
+      if (!includedElementIds.has(rel.target_id)) {
+        errors.push(`views '${view.view_id}' includes relationship '${relationshipId}' but not target element '${rel.target_id}'`);
+      }
+    }
+  }
+
+  for (const element of elements) {
+    if (element && typeof element === 'object' && !elementIdsIncludedInViews.has(element.id)) {
+      errors.push(`elements '${element.id}' must be included in at least one view`);
+    }
+  }
+
+  for (const relationship of relationships) {
+    if (relationship && typeof relationship === 'object' && !relationshipIdsIncludedInViews.has(relationship.id)) {
+      errors.push(`relationships '${relationship.id}' must be included in at least one view`);
+    }
+  }
+}
+
+/**
+ * Validate the modeling language's endpoint-type matrix for relationships.
+ * No-op when the ontology disables the endpoint matrix invariant.
+ *
+ * @param {object} document - parsed SystemArchitecture JSON
+ * @param {string[]} errors - error accumulator
+ * @param {object} [options]
+ * @param {string[]} [options.touchedRelationshipIds] - if provided, only these
+ *   relationships are checked; if omitted/empty, ALL relationships are checked
+ * @param {object} [options.ontology] - resolved modeling language
+ */
+function validateArchiMateEndpointMatrix(document, errors, options = {}) {
+  const ontology = resolveOntology(options.ontology);
+  if (ontology.invariants && ontology.invariants.endpointMatrix === false) {
+    return;
+  }
+  const elementById = new Map(
+    (document.elements || []).map(element => [element.id, element]),
+  );
+  const relationshipIdSet =
+    Array.isArray(options.touchedRelationshipIds) && options.touchedRelationshipIds.length > 0
+      ? new Set(options.touchedRelationshipIds)
+      : undefined;
+
+  for (const relationship of document.relationships || []) {
+    if (relationshipIdSet && !relationshipIdSet.has(relationship.id)) {
+      continue;
+    }
+    const source = elementById.get(relationship.source_id);
+    const target = elementById.get(relationship.target_id);
+    errors.push(...ontology.validateRelationshipEndpointTypes(relationship, source, target));
+  }
+}
+
+/**
+ * Validate the ontology's per-view element limit (default 15).
+ * `maxElementsPerView: null` disables the limit. included_relationships do not
+ * consume the quota.
+ *
+ * @param {object} document - parsed SystemArchitecture JSON
+ * @param {string[]} errors - error accumulator
+ * @param {object} [options]
+ * @param {string[]} [options.touchedViewIds] - if provided, only these views
+ *   are checked; if omitted/empty, ALL views are checked
+ * @param {object} [options.ontology] - resolved modeling language
+ */
+function validateViewElementLimits(document, errors, options = {}) {
+  const ontology = resolveOntology(options.ontology);
+  const maxIncludedElements = ontology.invariants && ontology.invariants.maxElementsPerView !== undefined
+    ? ontology.invariants.maxElementsPerView
+    : 15;
+  if (maxIncludedElements === null) {
+    return;
+  }
+  const touchedViewIdSet =
+    Array.isArray(options.touchedViewIds) && options.touchedViewIds.length > 0
+      ? new Set(options.touchedViewIds)
+      : undefined;
+
+  for (const view of document.views || []) {
+    if (!view) {
+      continue;
+    }
+    if (touchedViewIdSet && !touchedViewIdSet.has(view.view_id)) {
+      continue;
+    }
+    const elementCount = Array.isArray(view.included_elements) ? view.included_elements.length : 0;
+    if (elementCount > maxIncludedElements) {
+      errors.push(
+        `views '${view.view_id}' must contain at most ${maxIncludedElements} elements; found ${elementCount}. ` +
+        'Split the content into layered sub-views before adding more elements.',
+      );
+    }
+  }
+}
+
+// Per-element-type attribute contract (issue #3): required attributes, a
+// controlled vocabulary per attribute (enumByAttr) and uniqueness per attribute.
+// Supplied by the active schema bundle's `attributesByElementType`; absent => no-op
+// (fully backward compatible).
+function attributeEntriesByName(element) {
+  const map = new Map();
+  const entries = Array.isArray(element && element.attributes) ? element.attributes : [];
+  for (const entry of entries) {
+    if (!entry || typeof entry !== 'object' || typeof entry.name !== 'string' || entry.name === '') {
+      continue;
+    }
+    if (!map.has(entry.name)) {
+      map.set(entry.name, []);
+    }
+    map.get(entry.name).push(entry);
+  }
+  return map;
+}
+
+function attributeValueOf(entry) {
+  if (entry.value !== undefined && entry.value !== null) {
+    return entry.value;
+  }
+  if (entry.content !== undefined && entry.content !== null) {
+    return entry.content;
+  }
+  return undefined;
+}
+
+function validateAttributeContracts(document, errors, ontology) {
+  const language = resolveOntology(ontology);
+  const contracts = language.attributesByElementType;
+  if (!contracts || typeof contracts !== 'object') {
+    return;
+  }
+  const uniqueTrackers = new Map();
+  for (const type of Object.keys(contracts)) {
+    uniqueTrackers.set(type, new Map());
+  }
+
+  for (const element of document.elements || []) {
+    if (!element || typeof element !== 'object') {
+      continue;
+    }
+    const contract = contracts[element.type];
+    if (!contract || typeof contract !== 'object') {
+      continue;
+    }
+    const byName = attributeEntriesByName(element);
+
+    for (const name of Array.isArray(contract.required) ? contract.required : []) {
+      const entries = byName.get(name);
+      const present = Array.isArray(entries) && entries.some((entry) => {
+        const value = attributeValueOf(entry);
+        return value !== undefined && value !== '';
+      });
+      if (!present) {
+        errors.push(`element '${element.id}' (type '${element.type}') is missing required attribute '${name}'`);
+      }
+    }
+
+    const enumByAttr = contract.enumByAttr && typeof contract.enumByAttr === 'object' ? contract.enumByAttr : {};
+    for (const [attr, allowed] of Object.entries(enumByAttr)) {
+      if (!Array.isArray(allowed)) {
+        continue;
+      }
+      for (const entry of byName.get(attr) || []) {
+        const value = attributeValueOf(entry);
+        if (value === undefined) {
+          continue;
+        }
+        const matches = allowed.some((option) => option === value || JSON.stringify(option) === JSON.stringify(value));
+        if (!matches) {
+          errors.push(`element '${element.id}' (type '${element.type}') attribute '${attr}' value ${JSON.stringify(value)} is not one of: ${allowed.map((option) => JSON.stringify(option)).join(', ')}`);
+        }
+      }
+    }
+
+    for (const attr of Array.isArray(contract.unique) ? contract.unique : []) {
+      const tracker = uniqueTrackers.get(element.type);
+      for (const entry of byName.get(attr) || []) {
+        const value = attributeValueOf(entry);
+        if (value === undefined) {
+          continue;
+        }
+        const key = JSON.stringify(value);
+        if (tracker.has(key) && tracker.get(key) !== element.id) {
+          errors.push(`element '${element.id}' (type '${element.type}') attribute '${attr}' value ${key} duplicates element '${tracker.get(key)}'`);
+        } else if (!tracker.has(key)) {
+          tracker.set(key, element.id);
+        }
+      }
+    }
+  }
+}
+
+module.exports = {
+  validateGraphSemantics,
+  validateArchiMateEndpointMatrix,
+  validateViewElementLimits,
+  validateAttributeContracts,
+};