archgraph-argo 0.10.10 → 0.10.12

package/argo/scripts/ensureArgoHarnessEnvironment.js

@@ -23,6 +23,9 @@ const {
   getWorkspaceRoot,
   resolveArgoPath,
 } = require('./argo-paths.js');
+const {
+  repairSubdiagramViews,
+} = require('./repair-subdiagram-views.js');
 
 const REQUIRED_TOOL_NAMES = [
   'getSystemArchitecture',
@@ -51,6 +54,16 @@ async function main() {
     });
     report.mcp = verifyArgoMcpServer({ workspaceRoot });
     report.systemArchitecture = await verifyCanonicalSystemArchitecture();
+    report.subdiagramViews = report.systemArchitecture.status === 'ok'
+      ? await ensureSubdiagramViewsConsistency({
+          checkOnly: options.checkOnly,
+          workspaceRoot,
+        })
+      : {
+          status: 'skipped',
+          mode: options.checkOnly ? 'check' : 'fix-direct',
+          reason: 'system architecture invalid; subdiagram_views repair skipped',
+        };
     report.neo4j = await ensureNeo4jProjection({ checkOnly: options.checkOnly });
     report.semanticLifecycle = await ensureCanonicalSemanticLifecycle({
       checkOnly: options.checkOnly,
@@ -77,6 +90,9 @@ async function main() {
   if (report.semanticLifecycle && report.semanticLifecycle.status === 'failed') {
     report.status = 'failed';
   }
+  if (report.subdiagramViews && report.subdiagramViews.status === 'failed') {
+    report.status = 'failed';
+  }
 
   writeJson(reportPath, report);
   console.log(JSON.stringify(report, null, 2));
@@ -264,6 +280,34 @@ async function verifyCanonicalSystemArchitecture() {
   };
 }
 
+async function ensureSubdiagramViewsConsistency({ checkOnly, workspaceRoot }) {
+  const mode = checkOnly ? 'check' : 'fix-direct';
+  try {
+    const result = await repairSubdiagramViews({
+      workspaceRoot,
+      architecturePath: DEFAULT_GRAPH_PATH,
+      mode,
+    });
+    return {
+      status: result.status,
+      mode,
+      graphPath: result.graphPath,
+      driftCount: result.driftCount,
+      fixedCount: result.fixedCount,
+      written: Boolean(result.written),
+      backupPath: result.backupPath || null,
+      reports: result.reports || [],
+      ...(result.error === undefined ? {} : { error: result.error }),
+    };
+  } catch (error) {
+    return {
+      status: 'failed',
+      mode,
+      error: String(error && error.message ? error.message : error),
+    };
+  }
+}
+
 async function ensureNeo4jProjection({ checkOnly }) {
   const config = getNeo4jConfig();
   const dirtyBefore = getNeo4jGraphSyncState(DEFAULT_GRAPH_PATH);

package/argo/scripts/repair-subdiagram-views.js

@@ -0,0 +1,288 @@
+'use strict';
+
+// Repair the parent->child side of the sub-diagram link.
+//
+// The ARGO MCP view-write path maintains `view.parent_element_id` (child -> parent)
+// but historically never updated the mirror field `element.subdiagram_views`
+// (parent -> child). This script rebuilds every element's `subdiagram_views`
+// from the canonical source of truth — the views' `parent_element_id` — so the
+// two sides agree again.
+//
+// Modes:
+//   --check   (default) dry-run: print the per-element diff, exit 1 if any drift.
+//   --fix     apply the corrections. For the intent graph
+//             (design/KG/SystemArchitecture.json) this writes THROUGH the ARGO MCP
+//             (applySystemArchitectureMutation), never touching the file directly.
+//   --direct  (with --fix) write the JSON file directly with a .bak backup. Use for
+//             non-intent-graph copies (KGlibrary samples, defaults template, EA exports)
+//             that may not satisfy the intent-graph validation rules.
+//
+// Options:
+//   --path <p>             Graph JSON path (default: design/KG/SystemArchitecture.json).
+//                          Relative paths resolve against --workspaceRoot.
+//   --workspaceRoot <dir>  Workspace root (default: the repository root).
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { applyMutations, callTool } = require('./systemarchitecture-mcp-server.js');
+
+const DEFAULT_GRAPH_PATH = 'design/KG/SystemArchitecture.json';
+
+function parseArgs(argv) {
+  const args = { check: true, fix: false, direct: false, graphPath: DEFAULT_GRAPH_PATH };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--check') {
+      args.check = true;
+      args.fix = false;
+    } else if (arg === '--fix') {
+      args.fix = true;
+      args.check = false;
+    } else if (arg === '--direct') {
+      args.direct = true;
+    } else if (arg === '--path' && i + 1 < argv.length) {
+      args.graphPath = argv[i + 1];
+      i += 1;
+    } else if (arg === '--workspaceRoot' && i + 1 < argv.length) {
+      args.workspaceRoot = argv[i + 1];
+      i += 1;
+    } else {
+      throw new Error(`Unknown argument: ${arg}`);
+    }
+  }
+  return args;
+}
+
+function resolveGraphPath(args) {
+  const workspaceRoot = path.resolve(args.workspaceRoot || path.resolve(__dirname, '..', '..'));
+  const resolved = path.isAbsolute(args.graphPath)
+    ? args.graphPath
+    : path.resolve(workspaceRoot, args.graphPath);
+  return { workspaceRoot, absolutePath: resolved, relativePath: path.relative(workspaceRoot, resolved) };
+}
+
+function readDocument(absolutePath, label) {
+  return JSON.parse(fs.readFileSync(absolutePath, 'utf8'));
+}
+
+function sortedEntries(entries) {
+  if (!Array.isArray(entries)) {
+    return [];
+  }
+  return entries
+    .filter(entry => entry && typeof entry.view_id === 'string' && entry.view_id.length > 0)
+    .map(entry => ({ view_id: entry.view_id, view_name: String(entry.view_name || '') }))
+    .sort((a, b) => a.view_id.localeCompare(b.view_id));
+}
+
+function entriesEqual(left, right) {
+  if (left.length !== right.length) {
+    return false;
+  }
+  for (let i = 0; i < left.length; i += 1) {
+    if (left[i].view_id !== right[i].view_id || left[i].view_name !== right[i].view_name) {
+      return false;
+    }
+  }
+  return true;
+}
+
+// Map element id -> canonical [{ view_id, view_name }] derived from view.parent_element_id.
+function computeDesired(document) {
+  const desired = new Map();
+  for (const view of document.views || []) {
+    if (!view || !view.parent_element_id || !view.view_id) {
+      continue;
+    }
+    const list = desired.get(view.parent_element_id) || [];
+    if (!list.some(entry => entry.view_id === view.view_id)) {
+      list.push({ view_id: view.view_id, view_name: String(view.view_name || '') });
+    }
+    desired.set(view.parent_element_id, list);
+  }
+  return desired;
+}
+
+function computeMutations(document, desired) {
+  const mutations = [];
+  const reports = [];
+  for (const element of document.elements || []) {
+    if (!element || !element.id) {
+      continue;
+    }
+    const canonical = sortedEntries(desired.get(element.id) || []);
+    const current = sortedEntries(element.subdiagram_views || []);
+    if (entriesEqual(current, canonical)) {
+      continue;
+    }
+    reports.push({
+      elementId: element.id,
+      elementName: element.name,
+      current,
+      canonical,
+    });
+    mutations.push({
+      type: 'updateElement',
+      id: element.id,
+      patch: { subdiagram_views: canonical },
+    });
+  }
+  return { mutations, reports };
+}
+
+function describeEntry(entry) {
+  return `${entry.view_id}:${entry.view_name}`;
+}
+
+function printReports(reports) {
+  if (reports.length === 0) {
+    console.log('OK: all elements have subdiagram_views consistent with view.parent_element_id.');
+    return;
+  }
+  console.log(`Found ${reports.length} element(s) with drifted subdiagram_views:`);
+  for (const report of reports) {
+    console.log(`- ${report.elementId} (${report.elementName})`);
+    console.log(`    current  : [${report.current.map(describeEntry).join(', ')}]`);
+    console.log(`    canonical: [${report.canonical.map(describeEntry).join(', ')}]`);
+  }
+}
+
+// Rebuild each element's subdiagram_views from view.parent_element_id, returning a
+// structured report. Modes:
+//   'check'      dry-run: report drift, never write.
+//   'fix-direct' apply corrections by writing the JSON directly with a .bak backup.
+//   'fix-mcp'    apply corrections through ARGO MCP applySystemArchitectureMutation
+//                (only for the intent graph, whose validation rules hold).
+async function repairSubdiagramViews({
+  workspaceRoot,
+  architecturePath = DEFAULT_GRAPH_PATH,
+  mode = 'check',
+} = {}) {
+  const { workspaceRoot: resolvedRoot, absolutePath, relativePath } = resolveGraphPath({
+    workspaceRoot,
+    graphPath: architecturePath,
+  });
+  const document = readDocument(absolutePath, relativePath);
+  const desired = computeDesired(document);
+  const { mutations, reports } = computeMutations(document, desired);
+
+  if (mode === 'check') {
+    return {
+      status: reports.length === 0 ? 'ok' : 'failed',
+      graphPath: relativePath,
+      driftCount: reports.length,
+      fixedCount: 0,
+      written: false,
+      reports,
+    };
+  }
+
+  if (reports.length === 0) {
+    return {
+      status: 'ok',
+      graphPath: relativePath,
+      driftCount: 0,
+      fixedCount: 0,
+      written: false,
+      reports: [],
+    };
+  }
+
+  if (mode === 'fix-direct') {
+    const { document: fixedDocument } = applyMutations(document, mutations);
+    const backupPath = `${absolutePath}.bak`;
+    fs.copyFileSync(absolutePath, backupPath);
+    fs.writeFileSync(absolutePath, `${JSON.stringify(fixedDocument, null, 2)}\n`, 'utf8');
+    return {
+      status: 'ok',
+      graphPath: relativePath,
+      driftCount: reports.length,
+      fixedCount: reports.length,
+      written: true,
+      backupPath,
+      reports,
+    };
+  }
+
+  if (mode === 'fix-mcp') {
+    const result = await callTool(
+      'applySystemArchitectureMutation',
+      {
+        mutations,
+        workspaceRoot: resolvedRoot,
+        architecturePath: relativePath,
+      },
+      undefined,
+    );
+    if (result && result.status === 'passed' && result.written === true) {
+      return {
+        status: 'ok',
+        graphPath: relativePath,
+        driftCount: reports.length,
+        fixedCount: reports.length,
+        written: true,
+        reports,
+      };
+    }
+    return {
+      status: 'failed',
+      graphPath: relativePath,
+      driftCount: reports.length,
+      fixedCount: 0,
+      written: false,
+      reports,
+      error: result && Array.isArray(result.errors) ? result.errors : result,
+    };
+  }
+
+  throw new Error(`Unsupported repair mode: ${mode}`);
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const mode = args.check ? 'check' : (args.direct ? 'fix-direct' : 'fix-mcp');
+  const result = await repairSubdiagramViews({
+    workspaceRoot: args.workspaceRoot,
+    architecturePath: args.graphPath,
+    mode,
+  });
+
+  if (mode === 'check') {
+    printReports(result.reports);
+    process.exitCode = result.driftCount === 0 ? 0 : 1;
+    return;
+  }
+
+  if (result.status !== 'ok') {
+    console.error(`Repair failed: ${JSON.stringify(result.error === undefined ? result : result.error, null, 2)}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  if (result.driftCount === 0) {
+    console.log('Nothing to fix: subdiagram_views already consistent.');
+    return;
+  }
+
+  if (mode === 'fix-direct') {
+    console.log(`Fixed ${result.fixedCount} element(s) directly in ${result.graphPath} (backup: ${result.backupPath}).`);
+  } else {
+    console.log(`Fixed ${result.fixedCount} element(s) through ARGO MCP applySystemArchitectureMutation.`);
+  }
+}
+
+if (require.main === module) {
+  main().catch((error) => {
+    console.error(`Repair failed: ${String(error && error.stack ? error.stack : error)}`);
+    process.exitCode = 1;
+  });
+}
+
+module.exports = {
+  computeDesired,
+  computeMutations,
+  parseArgs,
+  repairSubdiagramViews,
+  sortedEntries,
+};

package/argo/scripts/systemarchitecture-mcp-server.js

@@ -1204,6 +1204,7 @@ function applyMutations(document, mutations) {
         throw new Error(`View '${mutation.view.view_id}' already exists`);
       }
       nextDocument.views.push(clone(mutation.view));
+      upsertSubdiagramViewIntoElement(nextDocument, mutation.view.parent_element_id, mutation.view);
       touchedViewIds.add(mutation.view.view_id);
       viewLimitCheckIds.add(mutation.view.view_id);
       mutationSummaries.push({ type: mutation.type, id: mutation.view.view_id });
@@ -1218,7 +1219,13 @@ function applyMutations(document, mutations) {
       if (!view) {
         throw new Error(`View '${viewId}' does not exist`);
       }
+      const oldParentId = view.parent_element_id;
+      const oldViewId = view.view_id;
       Object.assign(view, clone(mutation.patch));
+      if (oldParentId !== view.parent_element_id) {
+        removeSubdiagramViewFromElement(nextDocument, oldParentId, oldViewId);
+      }
+      upsertSubdiagramViewIntoElement(nextDocument, view.parent_element_id, view);
       touchedViewIds.add(view.view_id);
       if (Object.prototype.hasOwnProperty.call(mutation.patch, 'included_elements')) {
         viewLimitCheckIds.add(view.view_id);
@@ -1229,11 +1236,12 @@ function applyMutations(document, mutations) {
 
     if (mutation.type === 'removeView') {
       requireId(mutation.view_id, 'mutation.view_id');
-      const beforeCount = nextDocument.views.length;
-      nextDocument.views = nextDocument.views.filter(view => view.view_id !== mutation.view_id);
-      if (nextDocument.views.length === beforeCount) {
+      const view = findView(nextDocument.views, mutation.view_id);
+      if (!view) {
         throw new Error(`View '${mutation.view_id}' does not exist`);
       }
+      removeSubdiagramViewFromElement(nextDocument, view.parent_element_id, mutation.view_id);
+      nextDocument.views = nextDocument.views.filter(entry => entry.view_id !== mutation.view_id);
       touchedViewIds.add(mutation.view_id);
       mutationSummaries.push({ type: mutation.type, id: mutation.view_id });
       continue;
@@ -1311,6 +1319,36 @@ function findView(entries, viewId) {
   return Array.isArray(entries) ? entries.find(entry => entry && entry.view_id === viewId) : undefined;
 }
 
+function removeSubdiagramViewFromElement(document, elementId, viewId) {
+  if (!elementId || !viewId) {
+    return;
+  }
+  const element = findById(document.elements, elementId);
+  if (!element || !Array.isArray(element.subdiagram_views)) {
+    return;
+  }
+  element.subdiagram_views = element.subdiagram_views.filter(entry => !(entry && entry.view_id === viewId));
+}
+
+function upsertSubdiagramViewIntoElement(document, elementId, view) {
+  if (!elementId || !view || !view.view_id) {
+    return;
+  }
+  const element = findById(document.elements, elementId);
+  if (!element) {
+    return;
+  }
+  if (!Array.isArray(element.subdiagram_views)) {
+    element.subdiagram_views = [];
+  }
+  const existing = element.subdiagram_views.find(entry => entry && entry.view_id === view.view_id);
+  if (existing) {
+    existing.view_name = view.view_name;
+  } else {
+    element.subdiagram_views.push({ view_id: view.view_id, view_name: view.view_name });
+  }
+}
+
 function addUnique(existing, additions) {
   const result = Array.isArray(existing) ? [...existing] : [];
   for (const addition of additions) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "archgraph-argo",
-  "version": "0.10.10",
+  "version": "0.10.12",
   "description": "Deploy the ArchGraph ARGO toolchain, skills, and rules (schema, scripts, argo-init skill, global rule) with one command.",
   "license": "MIT",
   "bin": {