yarramate 0.3.0 → 0.3.1

package/dist/adapters/likec4-cli.js

@@ -4,7 +4,7 @@ import { resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { createHash, randomUUID } from 'node:crypto';
 import Ajv2020Module from 'ajv/dist/2020.js';
-import { isSeq, parseDocument } from 'yaml';
+import { isMap, isSeq, parseDocument } from 'yaml';
 import { isMainModule, resolveCliWorkspaceSources, } from '../cli-support.js';
 import { compileWorkspace } from '../compiler.js';
 import { adapterMappingLocation, loadAdapterMapping, validateAdapterMapping, } from '../adapter-mapping.js';
@@ -73,7 +73,7 @@ const publishFiles = (files) => {
     }
 };
 const usage = 'Usage:\n' +
-    '  yarramate-likec4 map --sync <mapping.yaml> <workspace-or-source...>\n' +
+    '  yarramate-likec4 map --sync [--prune] <mapping.yaml> <workspace-or-source...>\n' +
     '  yarramate-likec4 check <projection.yaml> <mapping.yaml> [--json] [--kinds <kind-mapping.yaml>] [--compare <from-state> <to-state>] <workspace-or-source...>\n' +
     '  yarramate-likec4 check <likec4-project.yaml> [--json] <workspace-or-source...>\n' +
     '  yarramate-likec4 export <projection.yaml> <mapping.yaml> [--kinds <kind-mapping.yaml>] [--compare <from-state> <to-state>] <workspace-or-source...>\n' +
@@ -91,7 +91,10 @@ const checkJson = (ok, diagnostics) => `${JSON.stringify({
 const sameJson = (left, right) => JSON.stringify(left) === JSON.stringify(right);
 const lowerCamel = (value) => value.replaceAll(/-([a-z0-9])/g, (_, character) => character.toUpperCase());
 const runLikeC4MapSync = (args, cwd) => {
-    const [sync, mappingPath, ...sourcePaths] = args;
+    const sync = args[0];
+    const prune = args[1] === '--prune';
+    const mappingPath = args[prune ? 2 : 1];
+    const sourcePaths = args.slice(prune ? 3 : 2);
     if (sync !== '--sync' ||
         mappingPath === undefined ||
         mappingPath.startsWith('-') ||
@@ -145,16 +148,23 @@ const runLikeC4MapSync = (args, cwd) => {
                 stderr: '',
             };
         }
+        const graphSubjects = new Set(compilation.graph.subjects.map(({ id }) => id));
+        const staleCount = loaded.mapping.mappings.filter(({ native }) => !graphSubjects.has(native)).length;
         const validation = validateAdapterMapping(compilation.graph, loaded.mapping);
-        if (!validation.ok) {
+        const blockingDiagnostics = validation.ok
+            ? []
+            : validation.diagnostics.filter(({ code }) => code !== 'YM601');
+        if (blockingDiagnostics.length > 0) {
             return {
                 exitCode: 1,
-                stdout: diagnosticJson(validation.diagnostics),
+                stdout: diagnosticJson(blockingDiagnostics),
                 stderr: '',
             };
         }
         const mapped = new Set(loaded.mapping.mappings.map(({ native }) => native));
-        const claimedExternal = new Set(loaded.mapping.mappings.map(({ external }) => external));
+        const claimedExternal = new Set(loaded.mapping.mappings
+            .filter(({ native }) => !prune || graphSubjects.has(native))
+            .map(({ external }) => external));
         const architectureStates = new Set(compilation.graph.claims
             .filter(({ predicate }) => predicate === 'yarramate/state/type')
             .map(({ subject }) => subject));
@@ -180,18 +190,29 @@ const runLikeC4MapSync = (args, cwd) => {
                 type: subject.type,
             };
         });
-        if (additions.length === 0) {
+        if (additions.length === 0 && (!prune || staleCount === 0)) {
             return {
                 exitCode: 0,
-                stdout: `LikeC4 mapping ${mappingPath} is already synchronized\n`,
+                stdout: staleCount === 0
+                    ? `LikeC4 mapping ${mappingPath} is already synchronized\n`
+                    : `LikeC4 mapping ${mappingPath} has ${staleCount} stale ${staleCount === 1 ? 'mapping' : 'mappings'} (use --prune)\n`,
                 stderr: '',
             };
         }
         const document = parseDocument(original);
+        const mappings = document.getIn(['mappings'], true);
+        if (prune && isSeq(mappings)) {
+            const firstMappingWasPruned = mappings.items.length > 0 &&
+                isMap(mappings.items[0]) &&
+                !graphSubjects.has(String(mappings.items[0].get('native')));
+            mappings.items = mappings.items.filter((item) => !isMap(item) ||
+                graphSubjects.has(String(item.get('native'))));
+            if (firstMappingWasPruned)
+                mappings.commentBefore = undefined;
+        }
         for (const addition of additions) {
             document.addIn(['mappings'], addition);
         }
-        const mappings = document.getIn(['mappings'], true);
         if (isSeq(mappings))
             mappings.flow = false;
         const candidate = document.toString({ lineWidth: 0 });
@@ -207,10 +228,13 @@ const runLikeC4MapSync = (args, cwd) => {
             };
         }
         const candidateValidation = validateAdapterMapping(compilation.graph, candidateMapping.mapping);
-        if (!candidateValidation.ok) {
+        const candidateBlockingDiagnostics = candidateValidation.ok
+            ? []
+            : candidateValidation.diagnostics.filter(({ code }) => prune || code !== 'YM601');
+        if (candidateBlockingDiagnostics.length > 0) {
             return {
                 exitCode: 1,
-                stdout: diagnosticJson(candidateValidation.diagnostics),
+                stdout: diagnosticJson(candidateBlockingDiagnostics),
                 stderr: '',
             };
         }
@@ -223,7 +247,14 @@ const runLikeC4MapSync = (args, cwd) => {
         }
         return {
             exitCode: 0,
-            stdout: `Added ${additions.length} LikeC4 mappings to ${mappingPath}\n`,
+            stdout: prune
+                ? additions.length > 0
+                    ? `Added ${additions.length} and pruned ${staleCount} stale LikeC4 ${staleCount === 1 ? 'mapping' : 'mappings'} in ${mappingPath}\n`
+                    : `Pruned ${staleCount} stale LikeC4 ${staleCount === 1 ? 'mapping' : 'mappings'} from ${mappingPath}\n`
+                : `Added ${additions.length} LikeC4 ${additions.length === 1 ? 'mapping' : 'mappings'} to ${mappingPath}` +
+                    (staleCount === 0
+                        ? '\n'
+                        : `; left ${staleCount} stale ${staleCount === 1 ? 'mapping' : 'mappings'} (use --prune)\n`),
             stderr: '',
         };
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yarramate",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Tool-neutral semantic architecture engine and guided methodology",
   "license": "MIT",
   "repository": {

package/skills/yarramate-architecture/references/native-authoring.md

@@ -195,5 +195,15 @@ yarramate-likec4 map --sync \
   .yarramate/workspace.yaml
 ```
 
+Sync preserves and reports mappings for native subjects that no longer exist.
+After confirming that those subjects were intentionally removed or renamed,
+delete the stale entries while adding missing mappings with:
+
+```sh
+yarramate-likec4 map --sync --prune \
+  .yarramate/integrations/likec4/subject-mapping.yaml \
+  .yarramate/workspace.yaml
+```
+
 Treat exit `0` as successful execution, `1` as correctness diagnostics, and
 `2` as invocation or file failure.