yarramate 0.2.0 → 0.3.1

package/dist/adapters/likec4-cli.js

@@ -4,8 +4,10 @@ import { resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { createHash, randomUUID } from 'node:crypto';
 import Ajv2020Module from 'ajv/dist/2020.js';
-import { 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';
 import { locateSourcePath } from '../source-document.js';
 import { prepareLikeC4Export, } from './likec4-prepare.js';
 import { exportLikeC4Project, loadLikeC4ProjectDefinition, } from './likec4-project.js';
@@ -71,6 +73,7 @@ const publishFiles = (files) => {
     }
 };
 const usage = 'Usage:\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' +
@@ -86,6 +89,180 @@ const checkJson = (ok, diagnostics) => `${JSON.stringify({
     diagnostics,
 }, null, 2)}\n`;
 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 = 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('-') ||
+        sourcePaths.length === 0 ||
+        sourcePaths.some((path) => path.startsWith('-'))) {
+        return { exitCode: 2, stdout: '', stderr: usage };
+    }
+    try {
+        const resolved = resolveCliWorkspaceSources(sourcePaths, cwd);
+        if (!resolved.ok) {
+            return {
+                exitCode: 1,
+                stdout: diagnosticJson(resolved.diagnostics),
+                stderr: '',
+            };
+        }
+        const compilation = compileWorkspace(resolved.paths.map((path) => ({
+            path,
+            source: readFileSync(resolve(cwd, path), 'utf8'),
+        })));
+        if (!compilation.ok) {
+            return {
+                exitCode: 1,
+                stdout: diagnosticJson(compilation.diagnostics),
+                stderr: '',
+            };
+        }
+        const absoluteMappingPath = resolve(cwd, mappingPath);
+        const original = readFileSync(absoluteMappingPath, 'utf8');
+        const loaded = loadAdapterMapping({
+            path: mappingPath,
+            source: original,
+        });
+        if (!loaded.ok) {
+            return {
+                exitCode: 1,
+                stdout: diagnosticJson(loaded.diagnostics),
+                stderr: '',
+            };
+        }
+        if (loaded.mapping.adapter !== 'likec4') {
+            const location = adapterMappingLocation(loaded.mapping, 'adapter');
+            return {
+                exitCode: 1,
+                stdout: diagnosticJson([{
+                        severity: 'error',
+                        code: 'YMLC101',
+                        message: `Adapter mapping targets "${loaded.mapping.adapter}", not "likec4"`,
+                        ...location,
+                    }]),
+                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);
+        const blockingDiagnostics = validation.ok
+            ? []
+            : validation.diagnostics.filter(({ code }) => code !== 'YM601');
+        if (blockingDiagnostics.length > 0) {
+            return {
+                exitCode: 1,
+                stdout: diagnosticJson(blockingDiagnostics),
+                stderr: '',
+            };
+        }
+        const mapped = new Set(loaded.mapping.mappings.map(({ native }) => native));
+        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));
+        const additions = compilation.graph.subjects
+            .filter(({ id }) => !mapped.has(id) && !architectureStates.has(id))
+            .map((subject) => {
+            const [documentId, localId] = subject.id.split('#');
+            const local = lowerCamel(localId);
+            let external = local;
+            if (claimedExternal.has(external)) {
+                external = `${lowerCamel(documentId)}_${local}`;
+            }
+            let suffix = 2;
+            const base = external;
+            while (claimedExternal.has(external)) {
+                external = `${base}_${suffix}`;
+                suffix += 1;
+            }
+            claimedExternal.add(external);
+            return {
+                native: subject.id,
+                external,
+                type: subject.type,
+            };
+        });
+        if (additions.length === 0 && (!prune || staleCount === 0)) {
+            return {
+                exitCode: 0,
+                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);
+        }
+        if (isSeq(mappings))
+            mappings.flow = false;
+        const candidate = document.toString({ lineWidth: 0 });
+        const candidateMapping = loadAdapterMapping({
+            path: mappingPath,
+            source: candidate,
+        });
+        if (!candidateMapping.ok) {
+            return {
+                exitCode: 1,
+                stdout: diagnosticJson(candidateMapping.diagnostics),
+                stderr: '',
+            };
+        }
+        const candidateValidation = validateAdapterMapping(compilation.graph, candidateMapping.mapping);
+        const candidateBlockingDiagnostics = candidateValidation.ok
+            ? []
+            : candidateValidation.diagnostics.filter(({ code }) => prune || code !== 'YM601');
+        if (candidateBlockingDiagnostics.length > 0) {
+            return {
+                exitCode: 1,
+                stdout: diagnosticJson(candidateBlockingDiagnostics),
+                stderr: '',
+            };
+        }
+        const staged = stageFile(absoluteMappingPath, candidate);
+        try {
+            staged.publish();
+        }
+        finally {
+            staged.cleanup();
+        }
+        return {
+            exitCode: 0,
+            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: '',
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return { exitCode: 2, stdout: '', stderr: `${message}\n` };
+    }
+};
 const publishGeneratedProject = (cwd, outputDirectory, input) => {
     const projectPath = resolve(cwd, outputDirectory);
     const markerPath = resolve(projectPath, 'yarramate.generated.json');
@@ -194,6 +371,9 @@ const publishGeneratedProject = (cwd, outputDirectory, input) => {
     };
 };
 export function runLikeC4Cli(args, cwd = process.cwd()) {
+    if (args[0] === 'map') {
+        return runLikeC4MapSync(args.slice(1), cwd);
+    }
     const [command, projectionPath, mappingPath, ...options] = args;
     let projectDefinitionMode = false;
     if ((command === 'check' || command === 'export-project') &&
@@ -307,25 +487,63 @@ export function runLikeC4Cli(args, cwd = process.cwd()) {
                     stderr: '',
                 };
             }
-            const preparedViews = loadedProject.document.value.views.map((view) => ({
+            const referencedSources = new Map();
+            const referenceDiagnostics = [];
+            const readProjectReference = (path, label, yamlPath, pointer) => {
+                const existing = referencedSources.get(path);
+                if (existing !== undefined)
+                    return existing;
+                try {
+                    const source = {
+                        path,
+                        source: readFileSync(resolve(cwd, path), 'utf8'),
+                    };
+                    referencedSources.set(path, source);
+                    return source;
+                }
+                catch (error) {
+                    const location = locateSourcePath(projectSource.path, loadedProject.document.yaml, loadedProject.document.lineCounter, yamlPath, pointer);
+                    const absent = error instanceof Error &&
+                        'code' in error &&
+                        error.code === 'ENOENT';
+                    referenceDiagnostics.push({
+                        severity: 'error',
+                        code: 'YMLC110',
+                        message: absent
+                            ? `LikeC4 project ${label} "${path}" does not exist`
+                            : `LikeC4 project ${label} "${path}" cannot be read`,
+                        ...location,
+                    });
+                    return undefined;
+                }
+            };
+            const subjectMapping = readProjectReference(loadedProject.document.value.mapping, 'mapping', ['mapping'], '/mapping');
+            const kindMapping = loadedProject.document.value.kindMapping === undefined
+                ? undefined
+                : readProjectReference(loadedProject.document.value.kindMapping, 'kind mapping', ['kindMapping'], '/kindMapping');
+            const projections = loadedProject.document.value.views.map((view, index) => readProjectReference(view.projection, 'projection', ['views', index, 'projection'], `/views/${index}/projection`));
+            if (referenceDiagnostics.length > 0 ||
+                subjectMapping === undefined) {
+                return {
+                    exitCode: 1,
+                    stdout: diagnosticOutput(referenceDiagnostics.sort((left, right) => left.path.localeCompare(right.path) ||
+                        left.line - right.line ||
+                        left.column - right.column ||
+                        left.code.localeCompare(right.code) ||
+                        left.message.localeCompare(right.message))),
+                    stderr: '',
+                };
+            }
+            const preparedViews = loadedProject.document.value.views.map((view, index) => ({
                 view,
                 prepared: prepareLikeC4Export({
                     sources,
-                    projection: {
-                        path: view.projection,
-                        source: readFileSync(resolve(cwd, view.projection), 'utf8'),
-                    },
-                    subjectMapping: {
-                        path: loadedProject.document.value.mapping,
-                        source: readFileSync(resolve(cwd, loadedProject.document.value.mapping), 'utf8'),
-                    },
+                    projection: projections[index],
+                    subjectMapping,
                     ...(loadedProject.document.value.kindMapping === undefined
                         ? {}
                         : {
-                            kindMapping: {
-                                path: loadedProject.document.value.kindMapping,
-                                source: readFileSync(resolve(cwd, loadedProject.document.value.kindMapping), 'utf8'),
-                            },
+                            kindMapping: kindMapping,
                         }),
                     ...(view.compare === undefined
                         ? {}

package/dist/check-command.js

@@ -171,14 +171,28 @@ export function runCheckCommand(options, cwd) {
         const diagnostics = result.ok
             ? optionalDiagnostics
             : result.diagnostics;
+        const counted = result.ok
+            ? (() => {
+                const states = new Set(result.graph.claims
+                    .filter(({ predicate }) => predicate === 'yarramate/state/type')
+                    .map(({ subject }) => subject));
+                return {
+                    documents: result.graph.documents.length,
+                    concepts: result.graph.subjects.filter(({ id, type }) => type === 'concept' && !states.has(id)).length,
+                    relationships: result.graph.subjects.filter(({ type }) => type === 'relationship').length,
+                    states: states.size,
+                };
+            })()
+            : undefined;
         if (json) {
             return {
                 exitCode: ok ? 0 : 1,
-                stdout: checkResultJson(ok, ok ? [] : diagnostics),
+                stdout: checkResultJson(ok, ok ? [] : diagnostics, ok ? counted : undefined),
                 stderr: '',
             };
         }
         if (ok && result.ok) {
+            const successfulCounts = counted;
             const documentCount = result.graph.documents.length;
             const profileCount = coreSources.length - documentCount;
             const mappingCount = mappingSources.length;
@@ -215,7 +229,11 @@ export function runCheckCommand(options, cwd) {
             ].join(' and ');
             return {
                 exitCode: 0,
-                stdout: `Checked ${checked}: no errors\n`,
+                stdout: `Checked ${checked} (` +
+                    `${successfulCounts.concepts} ${successfulCounts.concepts === 1 ? 'concept' : 'concepts'}, ` +
+                    `${successfulCounts.relationships} ${successfulCounts.relationships === 1 ? 'relationship' : 'relationships'}, ` +
+                    `${successfulCounts.states} ${successfulCounts.states === 1 ? 'state' : 'states'}` +
+                    '): no errors\n',
                 stderr: '',
             };
         }

package/dist/cli-support.d.ts

@@ -7,7 +7,12 @@ export interface CliResult {
 export declare const isMainModule: (moduleUrl: string, entrypoint: string | undefined) => boolean;
 export declare const usage = "Usage:\n  yarramate init <directory>\n  yarramate add <document.yaml> --id <id> --kind <kind> --name <name> [--status <status>] [--description <text>] [--owner <ref>] [--constraint <id>=<ref> ...] [--reference <id>=<ref> ...] [--present-in <state-ref> ...] [--source <source.yaml> ...]\n  yarramate connect <document.yaml> --id <id> --kind <kind> --from <ref> --to <ref> [--name <name>] [--description <text>] [--status <status>] [--mode <mode>] [--content <text>] [--reference <id>=<ref> ...] [--present-in <state-ref> ...] [--source <source.yaml> ...]\n  yarramate check <source.yaml> [source.yaml ...] [--json]\n  yarramate compile <source.yaml> [source.yaml ...]\n  yarramate context <projection.yaml> <source.yaml> [source.yaml ...]\n  yarramate view <projection.yaml> <source.yaml> [source.yaml ...]\n  yarramate compare <from-state> <to-state> <source.yaml> [source.yaml ...]\n  yarramate evidence <evidence.yaml> <source.yaml> [source.yaml ...]\n  yarramate reconcile <workspace.yaml>\n";
 export declare const diagnosticJson: (diagnostics: unknown) => string;
-export declare const checkResultJson: (ok: boolean, diagnostics: unknown) => string;
+export declare const checkResultJson: (ok: boolean, diagnostics: unknown, counted?: {
+    readonly documents: number;
+    readonly concepts: number;
+    readonly relationships: number;
+    readonly states: number;
+}) => string;
 export declare const humanDiagnostics: (diagnostics: readonly Pick<Diagnostic, "path" | "line" | "column" | "code" | "message">[]) => string;
 export declare const sortDiagnostics: <T extends Diagnostic>(diagnostics: readonly T[]) => T[];
 export declare const resolveCliWorkspaceSources: (paths: readonly string[], cwd: string, options?: {

package/dist/cli-support.js

@@ -19,10 +19,11 @@ export const diagnosticJson = (diagnostics) => `${JSON.stringify({
     format: 'yarramate/diagnostic-result/v1',
     diagnostics,
 }, null, 2)}\n`;
-export const checkResultJson = (ok, diagnostics) => `${JSON.stringify({
+export const checkResultJson = (ok, diagnostics, counted) => `${JSON.stringify({
     format: 'yarramate/check-result/v1',
     ok,
     diagnostics,
+    ...(counted === undefined ? {} : { counted }),
 }, null, 2)}\n`;
 export const humanDiagnostics = (diagnostics) => diagnostics
     .map((diagnostic) => `${diagnostic.path}:${diagnostic.line}:${diagnostic.column} error ${diagnostic.code} ${diagnostic.message}\n`)

package/package.json

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

package/schema/yarramate-check-result.schema.json

@@ -17,6 +17,9 @@
       "items": {
         "$ref": "#/$defs/diagnostic"
       }
+    },
+    "counted": {
+      "$ref": "#/$defs/counted"
     }
   },
   "allOf": [
@@ -30,6 +33,7 @@
         "required": ["ok"]
       },
       "then": {
+        "required": ["counted"],
         "properties": {
           "diagnostics": {
             "maxItems": 0
@@ -46,6 +50,17 @@
     }
   ],
   "$defs": {
+    "counted": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["documents", "concepts", "relationships", "states"],
+      "properties": {
+        "documents": { "type": "integer", "minimum": 0 },
+        "concepts": { "type": "integer", "minimum": 0 },
+        "relationships": { "type": "integer", "minimum": 0 },
+        "states": { "type": "integer", "minimum": 0 }
+      }
+    },
     "diagnostic": {
       "type": "object",
       "additionalProperties": false,

package/schema/yarramate-likec4-diagnostic-result.schema.json

@@ -34,7 +34,7 @@
                 "const": "error"
               },
               "code": {
-                "enum": ["YMLC101", "YMLC102", "YMLC103", "YMLC104", "YMLC105", "YMLC106"]
+                "enum": ["YMLC101", "YMLC102", "YMLC103", "YMLC104", "YMLC105", "YMLC106", "YMLC107", "YMLC108", "YMLC109", "YMLC110"]
               },
               "message": {
                 "type": "string",

package/schema/yarramate-likec4-project.schema.json

@@ -41,6 +41,7 @@
     },
     "path": {
       "type": "string",
+      "description": "Repository-relative path resolved from the CLI working directory. Parent traversal, absolute paths, and backslashes are rejected.",
       "pattern": "^(?!/)(?!.*(?:^|/)\\.\\.(?:/|$))(?!.*\\\\).+$"
     },
     "subjectIdentity": {

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

@@ -190,6 +190,19 @@ yarramate view <projection.yaml> .yarramate/workspace.yaml
 yarramate compare <from-state> <to-state> .yarramate/workspace.yaml
 yarramate evidence <evidence.yaml> .yarramate/workspace.yaml
 yarramate reconcile .yarramate/workspace.yaml
+yarramate-likec4 map --sync \
+  .yarramate/integrations/likec4/subject-mapping.yaml \
+  .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