yarramate 0.4.0 → 0.6.0

package/README.md

@@ -119,13 +119,15 @@ node dist/cli.js check .yarramate/workspace.yaml --json
 node dist/cli.js compile .yarramate/workspace.yaml
 node dist/cli.js context .yarramate/projections/context.yaml .yarramate/workspace.yaml
 node dist/cli.js view .yarramate/projections/context.yaml .yarramate/workspace.yaml
+node dist/cli.js next .yarramate/projections/context.yaml .yarramate/workspace.yaml
 node dist/cli.js evidence .yarramate/evidence/repository.yaml .yarramate/workspace.yaml
 node dist/cli.js reconcile .yarramate/workspace.yaml
 ```
 
 `init` creates `.yarramate/architecture/main.yaml` and
 `.yarramate/workspace.yaml`. Commands accept explicit source documents or one
-explicit workspace manifest.
+explicit workspace manifest. `check --strict` additionally fails when any
+evidence observation contradicts the model, for gates that want one knob.
 
 For a local consumer test, create a package artifact:
 

package/dist/adapters/graphify-cli.js

@@ -3,7 +3,7 @@ import { readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { adapterMappingEntryLocation, adapterMappingLocation, loadAdapterMapping, validateAdapterMapping, } from '../adapter-mapping.js';
 import { compileWorkspace } from '../compiler.js';
-import { diagnosticJson, isMainModule, resolveCliWorkspaceSources, } from '../cli-support.js';
+import { diagnosticJson, isMainModule, resolveCliWorkspaceSources, versionResult, } from '../cli-support.js';
 import { observeGraphify, } from './graphify.js';
 const usage = 'Usage:\n' +
     '  yarramate-graphify observe <graph.json> <mapping.yaml> <workspace-or-source...> --id <evidence-id> --version <major.minor>\n';
@@ -35,6 +35,9 @@ const parseOptions = (options) => {
 };
 export function runGraphifyCli(args, cwd = process.cwd()) {
     const [command, ...options] = args;
+    if (command === '--version') {
+        return versionResult('yarramate-graphify');
+    }
     const parsed = command === 'observe' ? parseOptions(options) : undefined;
     if (parsed === undefined ||
         !/^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/.test(parsed.id) ||

package/dist/adapters/likec4-cli.js

@@ -1,11 +1,11 @@
 #!/usr/bin/env node
 import { closeSync, existsSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync, } from 'node:fs';
-import { resolve } from 'node:path';
+import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { createHash, randomUUID } from 'node:crypto';
 import Ajv2020Module from 'ajv/dist/2020.js';
 import { isMap, isSeq, parseDocument } from 'yaml';
-import { isMainModule, resolveCliWorkspaceSources, } from '../cli-support.js';
+import { isMainModule, resolveCliWorkspaceSources, versionResult, } from '../cli-support.js';
 import { compileWorkspace } from '../compiler.js';
 import { adapterMappingLocation, loadAdapterMapping, validateAdapterMapping, } from '../adapter-mapping.js';
 import { locateSourcePath } from '../source-document.js';
@@ -77,8 +77,8 @@ const usage = 'Usage:\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' +
-    '  yarramate-likec4 export-project <projection.yaml> <mapping.yaml> <output-dir> [--kinds <kind-mapping.yaml>] [--compare <from-state> <to-state>] <workspace-or-source...>\n' +
-    '  yarramate-likec4 export-project <likec4-project.yaml> <output-dir> <workspace-or-source...>\n';
+    '  yarramate-likec4 export-project [--check] <projection.yaml> <mapping.yaml> <output-dir> [--kinds <kind-mapping.yaml>] [--compare <from-state> <to-state>] <workspace-or-source...>\n' +
+    '  yarramate-likec4 export-project [--check] <likec4-project.yaml> <output-dir> <workspace-or-source...>\n';
 const diagnosticJson = (diagnostics) => `${JSON.stringify({
     format: 'yarramate/likec4-diagnostic-result/v1',
     diagnostics,
@@ -88,7 +88,36 @@ const checkJson = (ok, diagnostics) => `${JSON.stringify({
     ok,
     diagnostics,
 }, null, 2)}\n`;
-const sameJson = (left, right) => JSON.stringify(left) === JSON.stringify(right);
+const unmappedSubjectPreviewLength = 3;
+const summarizeUnmappedSubjects = (diagnostics) => [
+    ['YMLC102', 'concepts'],
+    ['YMLC111', 'relationships'],
+].reduce((current, [code, noun]) => {
+    const unmapped = current.filter((diagnostic) => diagnostic.code === code);
+    if (unmapped.length <= unmappedSubjectPreviewLength)
+        return current;
+    const preview = unmapped
+        .slice(0, unmappedSubjectPreviewLength)
+        .map((diagnostic) => 'subject' in diagnostic && diagnostic.subject !== undefined
+        ? `"${diagnostic.subject}"`
+        : `"${diagnostic.path}:${diagnostic.line}"`)
+        .join(', ');
+    const summary = {
+        ...unmapped[0],
+        message: `${unmapped.length} projected ${noun} have no LikeC4 mapping ` +
+            `(first: ${preview}); run "yarramate-likec4 map --sync" to add ` +
+            'the missing mappings',
+    };
+    let summarized = false;
+    return current.flatMap((diagnostic) => {
+        if (diagnostic.code !== code)
+            return [diagnostic];
+        if (summarized)
+            return [];
+        summarized = true;
+        return [summary];
+    });
+}, diagnostics);
 const lowerCamel = (value) => value.replaceAll(/-([a-z0-9])/g, (_, character) => character.toUpperCase());
 const runLikeC4MapSync = (args, cwd) => {
     const sync = args[0];
@@ -263,6 +292,33 @@ const runLikeC4MapSync = (args, cwd) => {
         return { exitCode: 2, stdout: '', stderr: `${message}\n` };
     }
 };
+// Ownership fields never gate updates: a marker of either format version
+// plus intact output digests proves the directory is entirely
+// machine-generated, so regenerating after the inputs changed loses nothing.
+const readGeneratedProjectMarker = (markerPath) => {
+    let marker;
+    try {
+        marker = JSON.parse(readFileSync(markerPath, 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+    return validateGeneratedProjectMarker(marker) ||
+        validateGeneratedProjectV2Marker(marker)
+        ? marker
+        : undefined;
+};
+const changedGeneratedFile = (projectPath, marker) => {
+    // Markers written before output digests existed are accepted once and
+    // upgraded on regeneration.
+    if (marker['digests'] === undefined)
+        return undefined;
+    const digests = marker['digests'];
+    return generatedFileNames.find((file) => {
+        const path = resolve(projectPath, file);
+        return (!existsSync(path) || sha256(readFileSync(path)) !== digests[file]);
+    });
+};
 const publishGeneratedProject = (cwd, outputDirectory, input) => {
     const projectPath = resolve(cwd, outputDirectory);
     const markerPath = resolve(projectPath, 'yarramate.generated.json');
@@ -292,37 +348,21 @@ const publishGeneratedProject = (cwd, outputDirectory, input) => {
                 stderr: `Generated project contains an unsafe file: ${unsafeFile}\n`,
             };
         }
-        let marker;
-        try {
-            marker = JSON.parse(readFileSync(markerPath, 'utf8'));
-        }
-        catch {
-            marker = undefined;
-        }
-        if (!input.validateMarker(marker) ||
-            typeof marker !== 'object' ||
-            marker === null ||
-            Object.entries(input.ownership).some(([key, value]) => !sameJson(marker[key], value))) {
+        const marker = readGeneratedProjectMarker(markerPath);
+        if (marker === undefined) {
             return {
                 exitCode: 2,
                 stdout: '',
-                stderr: `Output directory already exists: ${projectPath}\n`,
+                stderr: `Output directory exists but is not a YarraMate-generated project: ${projectPath}\n`,
             };
         }
-        if ('digests' in marker && marker.digests !== undefined) {
-            const digests = marker.digests;
-            const changedFile = generatedFileNames.find((file) => {
-                const path = resolve(projectPath, file);
-                return (!existsSync(path) ||
-                    sha256(readFileSync(path)) !== digests[file]);
-            });
-            if (changedFile !== undefined) {
-                return {
-                    exitCode: 2,
-                    stdout: '',
-                    stderr: `Generated project file has changed: ${resolve(projectPath, changedFile)}\n`,
-                };
-            }
+        const changedFile = changedGeneratedFile(projectPath, marker);
+        if (changedFile !== undefined) {
+            return {
+                exitCode: 2,
+                stdout: '',
+                stderr: `Generated project file has changed: ${resolve(projectPath, changedFile)}\n`,
+            };
         }
     }
     else {
@@ -346,6 +386,7 @@ const publishGeneratedProject = (cwd, outputDirectory, input) => {
             'model.likec4': sha256(input.modelSource),
             'specification.likec4': sha256(specificationSource),
         },
+        inputDigests: input.inputDigests,
     }, null, 2)}\n`;
     publishFiles([
         {
@@ -370,11 +411,96 @@ const publishGeneratedProject = (cwd, outputDirectory, input) => {
         stderr: '',
     };
 };
+// Freshness is a pure digest comparison between the marker and the would-be
+// export; nothing on disk is written or semantically judged.
+const checkGeneratedProject = (cwd, outputDirectory, input) => {
+    const projectPath = resolve(cwd, outputDirectory);
+    if (!existsSync(projectPath)) {
+        return {
+            exitCode: 1,
+            stdout: 'Generated LikeC4 output: absent\n',
+            stderr: '',
+        };
+    }
+    const marker = readGeneratedProjectMarker(resolve(projectPath, 'yarramate.generated.json'));
+    if (marker === undefined) {
+        return {
+            exitCode: 2,
+            stdout: '',
+            stderr: `Output directory exists but is not a YarraMate-generated project: ${projectPath}\n`,
+        };
+    }
+    const changedFile = changedGeneratedFile(projectPath, marker);
+    if (changedFile !== undefined) {
+        return {
+            exitCode: 1,
+            stdout: 'Generated LikeC4 output: modified\n' +
+                'Reason:\n' +
+                `- generated file changed: ${resolve(projectPath, changedFile)}\n` +
+                'Safe to regenerate: no\n',
+            stderr: '',
+        };
+    }
+    const recordedInputs = marker['inputDigests'];
+    const reasons = [];
+    if (recordedInputs === undefined) {
+        reasons.push('marker predates input digests');
+    }
+    else {
+        const inputPaths = [
+            ...new Set([
+                ...Object.keys(recordedInputs),
+                ...Object.keys(input.inputDigests),
+            ]),
+        ].sort();
+        for (const path of inputPaths) {
+            const recorded = recordedInputs[path];
+            const current = input.inputDigests[path];
+            if (recorded === undefined)
+                reasons.push(`input added: ${path}`);
+            else if (current === undefined) {
+                reasons.push(`input removed: ${path}`);
+            }
+            else if (recorded !== current) {
+                reasons.push(`input changed: ${path}`);
+            }
+        }
+    }
+    const digests = marker['digests'];
+    if (digests !== undefined &&
+        sha256(input.modelSource) !== digests['model.likec4']) {
+        reasons.push('model source changed');
+    }
+    if (reasons.length === 0) {
+        return {
+            exitCode: 0,
+            stdout: 'Generated LikeC4 output: fresh\n',
+            stderr: '',
+        };
+    }
+    return {
+        exitCode: 1,
+        stdout: 'Generated LikeC4 output: stale\n' +
+            'Reason:\n' +
+            reasons.map((reason) => `- ${reason}\n`).join('') +
+            'Safe to regenerate: yes\n',
+        stderr: '',
+    };
+};
+const inputDigestsOf = (inputs) => Object.fromEntries(inputs
+    .map(({ path, source }) => [path, sha256(source)])
+    .sort(([left], [right]) => left.localeCompare(right)));
 export function runLikeC4Cli(args, cwd = process.cwd()) {
+    if (args[0] === '--version') {
+        return versionResult('yarramate-likec4');
+    }
     if (args[0] === 'map') {
         return runLikeC4MapSync(args.slice(1), cwd);
     }
-    const [command, projectionPath, mappingPath, ...options] = args;
+    const checkFreshness = args[0] === 'export-project' && args.includes('--check');
+    const [command, projectionPath, mappingPath, ...options] = checkFreshness
+        ? args.filter((argument) => argument !== '--check')
+        : args;
     let projectDefinitionMode = false;
     if ((command === 'check' || command === 'export-project') &&
         projectionPath !== undefined) {
@@ -460,7 +586,11 @@ export function runLikeC4Cli(args, cwd = process.cwd()) {
         sourcePaths.some((argument) => argument.startsWith('-'))) {
         return { exitCode: 2, stdout: '', stderr: usage };
     }
-    const diagnosticOutput = (diagnostics) => (json ? checkJson(false, diagnostics) : diagnosticJson(diagnostics));
+    const diagnosticOutput = (diagnostics) => json
+        ? checkJson(false, diagnostics)
+        : diagnosticJson(command === 'check'
+            ? summarizeUnmappedSubjects(diagnostics)
+            : diagnostics);
     try {
         const resolved = resolveCliWorkspaceSources(sourcePaths, cwd);
         if (!resolved.ok) {
@@ -487,6 +617,7 @@ export function runLikeC4Cli(args, cwd = process.cwd()) {
                     stderr: '',
                 };
             }
+            const projectDirectory = dirname(resolve(cwd, projectionPath));
             const referencedSources = new Map();
             const referenceDiagnostics = [];
             const readProjectReference = (path, label, yamlPath, pointer) => {
@@ -496,7 +627,7 @@ export function runLikeC4Cli(args, cwd = process.cwd()) {
                 try {
                     const source = {
                         path,
-                        source: readFileSync(resolve(cwd, path), 'utf8'),
+                        source: readFileSync(resolve(projectDirectory, path), 'utf8'),
                     };
                     referencedSources.set(path, source);
                     return source;
@@ -549,6 +680,7 @@ export function runLikeC4Cli(args, cwd = process.cwd()) {
                         ? {}
                         : { comparison: view.compare }),
                     vocabulary: 'bundled',
+                    requireMappedRelationships: command === 'check',
                 }),
             }));
             const failed = preparedViews.find(({ prepared }) => !prepared.ok);
@@ -778,6 +910,17 @@ export function runLikeC4Cli(args, cwd = process.cwd()) {
                 ? undefined
                 : `${first.prepared.kindMapping.id}@${first.prepared.kindMapping.version}`;
             const projectIdentity = `${loadedProject.document.value.id}@${loadedProject.document.value.version}`;
+            const inputDigests = inputDigestsOf([
+                projectSource,
+                ...sources,
+                ...referencedSources.values(),
+            ]);
+            if (checkFreshness) {
+                return checkGeneratedProject(cwd, outputDirectory, {
+                    modelSource: exported.source,
+                    inputDigests,
+                });
+            }
             return publishGeneratedProject(cwd, outputDirectory, {
                 projectName: `yarramate-${projectIdentity}`.replaceAll(/[^A-Za-z0-9_-]/g, '-'),
                 title: loadedProject.document.value.title,
@@ -797,29 +940,33 @@ export function runLikeC4Cli(args, cwd = process.cwd()) {
                             : { comparison }),
                     })),
                 },
-                validateMarker: (value) => validateGeneratedProjectV2Marker(value),
+                inputDigests,
             });
         }
+        const projectionSource = {
+            path: projectionPath,
+            source: readFileSync(resolve(cwd, projectionPath), 'utf8'),
+        };
+        const mappingSource = {
+            path: mappingPath,
+            source: readFileSync(resolve(cwd, mappingPath), 'utf8'),
+        };
+        const kindMappingSource = kindMappingPath === undefined
+            ? undefined
+            : {
+                path: kindMappingPath,
+                source: readFileSync(resolve(cwd, kindMappingPath), 'utf8'),
+            };
         const prepared = prepareLikeC4Export({
             sources,
-            projection: {
-                path: projectionPath,
-                source: readFileSync(resolve(cwd, projectionPath), 'utf8'),
-            },
-            subjectMapping: {
-                path: mappingPath,
-                source: readFileSync(resolve(cwd, mappingPath), 'utf8'),
-            },
-            ...(kindMappingPath === undefined
+            projection: projectionSource,
+            subjectMapping: mappingSource,
+            ...(kindMappingSource === undefined
                 ? {}
-                : {
-                    kindMapping: {
-                        path: kindMappingPath,
-                        source: readFileSync(resolve(cwd, kindMappingPath), 'utf8'),
-                    },
-                }),
+                : { kindMapping: kindMappingSource }),
             ...(comparison === undefined ? {} : { comparison }),
             vocabulary: command === 'export' ? 'consumer' : 'bundled',
+            requireMappedRelationships: command === 'check',
         });
         if (!prepared.ok) {
             return {
@@ -846,6 +993,18 @@ export function runLikeC4Cli(args, cwd = process.cwd()) {
             ? undefined
             : `${prepared.kindMapping.id}@${prepared.kindMapping.version}`;
         const comparisonIdentity = comparison;
+        const inputDigests = inputDigestsOf([
+            projectionSource,
+            mappingSource,
+            ...(kindMappingSource === undefined ? [] : [kindMappingSource]),
+            ...sources,
+        ]);
+        if (checkFreshness) {
+            return checkGeneratedProject(cwd, outputDirectory, {
+                modelSource: prepared.source,
+                inputDigests,
+            });
+        }
         return publishGeneratedProject(cwd, outputDirectory, {
             projectName: ['yarramate', projectionIdentity]
                 .join('-')
@@ -864,7 +1023,7 @@ export function runLikeC4Cli(args, cwd = process.cwd()) {
                     ? {}
                     : { comparison: comparisonIdentity }),
             },
-            validateMarker: (value) => validateGeneratedProjectMarker(value),
+            inputDigests,
         });
     }
     catch (error) {

package/dist/adapters/likec4-export.d.ts

@@ -4,7 +4,7 @@ import type { ProjectionResult } from '../projection.js';
 import type { LikeC4KindMapping } from './likec4-kind-mapping.js';
 export interface LikeC4ExportDiagnostic {
     readonly severity: 'error';
-    readonly code: 'YMLC101' | 'YMLC102' | 'YMLC103' | 'YMLC104' | 'YMLC105' | 'YMLC106' | 'YMLC107' | 'YMLC108' | 'YMLC109';
+    readonly code: 'YMLC101' | 'YMLC102' | 'YMLC103' | 'YMLC104' | 'YMLC105' | 'YMLC106' | 'YMLC107' | 'YMLC108' | 'YMLC109' | 'YMLC111';
     readonly message: string;
     readonly subject?: string;
     readonly path: string;

package/dist/adapters/likec4-prepare.d.ts

@@ -13,6 +13,12 @@ export interface LikeC4PreparationInput {
         readonly to: string;
     };
     readonly vocabulary: 'bundled' | 'consumer';
+    /**
+     * Gate mode. Rendering a relationship needs no external identity — views
+     * select it by metadata — but `map --sync` still writes one, so only a
+     * check answering "would sync change anything" requires the entry.
+     */
+    readonly requireMappedRelationships?: boolean;
 }
 export type LikeC4PreparationDiagnostic = Diagnostic | LikeC4ExportDiagnostic;
 export type LikeC4PreparationResult = {

package/dist/adapters/likec4-prepare.js

@@ -70,6 +70,31 @@ const unsupportedBundledKinds = (projection, kindMapping) => {
     }
     return diagnostics.sort(diagnosticOrder);
 };
+const unmappedProjectedRelationships = (projection, mapping) => {
+    const mapped = new Set(mapping.mappings
+        .filter(({ type }) => type === 'relationship')
+        .map(({ native }) => native));
+    return projection.subjects
+        .filter(({ type, id }) => type === 'relationship' && !mapped.has(id))
+        .flatMap(({ id }) => {
+        const source = projection.claims.find((claim) => claim.id === id)?.source;
+        return source === undefined
+            ? []
+            : [
+                {
+                    severity: 'error',
+                    code: 'YMLC111',
+                    message: `Projected relationship "${id}" has no LikeC4 mapping`,
+                    subject: id,
+                    path: source.path,
+                    pointer: source.pointer,
+                    line: source.line,
+                    column: source.column,
+                },
+            ];
+    })
+        .sort(diagnosticOrder);
+};
 export function prepareLikeC4Export(input) {
     const compilation = compileWorkspaceWithProfileContext(input.sources);
     if (!compilation.ok)
@@ -137,11 +162,24 @@ export function prepareLikeC4Export(input) {
         if (diagnostics.length > 0)
             return { ok: false, diagnostics };
     }
+    const unmappedRelationships = input.requireMappedRelationships === true
+        ? unmappedProjectedRelationships(projectionResult, subjectMapping.mapping)
+        : [];
     const exported = exportLikeC4(projectionResult, subjectMapping.mapping, kindMapping?.mapping, comparison === undefined
         ? undefined
         : { comparison: comparison.comparison });
-    if (!exported.ok)
-        return exported;
+    if (!exported.ok) {
+        return {
+            ok: false,
+            diagnostics: [
+                ...exported.diagnostics,
+                ...unmappedRelationships,
+            ].sort(diagnosticOrder),
+        };
+    }
+    if (unmappedRelationships.length > 0) {
+        return { ok: false, diagnostics: unmappedRelationships };
+    }
     return {
         ok: true,
         source: exported.source,

package/dist/adapters/mcp-cli.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { createInterface } from 'node:readline';
-import { isMainModule } from '../cli-support.js';
+import { isMainModule, packageVersion, versionResult, } from '../cli-support.js';
 import { runCli } from '../cli.js';
 const workspaceProperty = {
     workspace: {
@@ -97,7 +97,7 @@ export const handleRequest = (request) => {
         respond(id, {
             protocolVersion: '2025-06-18',
             capabilities: { tools: {} },
-            serverInfo: { name: 'yarramate', version: '0.1' },
+            serverInfo: { name: 'yarramate', version: packageVersion },
             instructions: 'Read-only architecture context for YarraMate workspaces. The native documents in the repository remain canonical; this server never mutates them.',
         });
         return;
@@ -142,24 +142,31 @@ export const handleRequest = (request) => {
     }
 };
 if (isMainModule(import.meta.url, process.argv[1])) {
-    const lines = createInterface({ input: process.stdin });
-    lines.on('line', (line) => {
-        const text = line.trim();
-        if (text.length === 0)
-            return;
-        let request;
-        try {
-            request = JSON.parse(text);
-        }
-        catch {
-            respondError(null, -32700, 'Parse error');
-            return;
-        }
-        try {
-            handleRequest(request);
-        }
-        catch (error) {
-            respondError(request.id ?? null, -32603, error instanceof Error ? error.message : String(error));
-        }
-    });
+    if (process.argv[2] === '--version') {
+        const result = versionResult('yarramate-mcp');
+        process.stdout.write(result.stdout);
+        process.exitCode = result.exitCode;
+    }
+    else {
+        const lines = createInterface({ input: process.stdin });
+        lines.on('line', (line) => {
+            const text = line.trim();
+            if (text.length === 0)
+                return;
+            let request;
+            try {
+                request = JSON.parse(text);
+            }
+            catch {
+                respondError(null, -32700, 'Parse error');
+                return;
+            }
+            try {
+                handleRequest(request);
+            }
+            catch (error) {
+                respondError(request.id ?? null, -32603, error instanceof Error ? error.message : String(error));
+            }
+        });
+    }
 }