yarramate 0.5.0 → 0.7.0

package/dist/adapters/likec4-cli.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,
@@ -89,10 +89,13 @@ const checkJson = (ok, diagnostics) => `${JSON.stringify({
     diagnostics,
 }, null, 2)}\n`;
 const unmappedSubjectPreviewLength = 3;
-const summarizeUnmappedConcepts = (diagnostics) => {
-    const unmapped = diagnostics.filter((diagnostic) => diagnostic.code === 'YMLC102');
+const summarizeUnmappedSubjects = (diagnostics) => [
+    ['YMLC102', 'concepts'],
+    ['YMLC111', 'relationships'],
+].reduce((current, [code, noun]) => {
+    const unmapped = current.filter((diagnostic) => diagnostic.code === code);
     if (unmapped.length <= unmappedSubjectPreviewLength)
-        return diagnostics;
+        return current;
     const preview = unmapped
         .slice(0, unmappedSubjectPreviewLength)
         .map((diagnostic) => 'subject' in diagnostic && diagnostic.subject !== undefined
@@ -101,21 +104,20 @@ const summarizeUnmappedConcepts = (diagnostics) => {
         .join(', ');
     const summary = {
         ...unmapped[0],
-        message: `${unmapped.length} projected concepts have no LikeC4 mapping ` +
+        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 diagnostics.flatMap((diagnostic) => {
-        if (diagnostic.code !== 'YMLC102')
+    return current.flatMap((diagnostic) => {
+        if (diagnostic.code !== code)
             return [diagnostic];
         if (summarized)
             return [];
         summarized = true;
         return [summary];
     });
-};
-const sameJson = (left, right) => JSON.stringify(left) === JSON.stringify(right);
+}, diagnostics);
 const lowerCamel = (value) => value.replaceAll(/-([a-z0-9])/g, (_, character) => character.toUpperCase());
 const runLikeC4MapSync = (args, cwd) => {
     const sync = args[0];
@@ -290,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');
@@ -319,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 {
@@ -373,6 +386,7 @@ const publishGeneratedProject = (cwd, outputDirectory, input) => {
             'model.likec4': sha256(input.modelSource),
             'specification.likec4': sha256(specificationSource),
         },
+        inputDigests: input.inputDigests,
     }, null, 2)}\n`;
     publishFiles([
         {
@@ -397,6 +411,85 @@ 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');
@@ -404,7 +497,10 @@ export function runLikeC4Cli(args, cwd = process.cwd()) {
     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) {
@@ -493,7 +589,7 @@ export function runLikeC4Cli(args, cwd = process.cwd()) {
     const diagnosticOutput = (diagnostics) => json
         ? checkJson(false, diagnostics)
         : diagnosticJson(command === 'check'
-            ? summarizeUnmappedConcepts(diagnostics)
+            ? summarizeUnmappedSubjects(diagnostics)
             : diagnostics);
     try {
         const resolved = resolveCliWorkspaceSources(sourcePaths, cwd);
@@ -584,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);
@@ -813,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,
@@ -832,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 {
@@ -881,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('-')
@@ -899,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

@@ -10,14 +10,65 @@ const workspaceProperty = {
 };
 const tools = [
     {
-        name: 'yarramate_status',
-        description: 'One-call workspace orientation: check verdict, reconciliation summary, and a titled inventory of documents, states, projections, evidence, and contracts.',
+        name: 'yarramate_ask',
+        description: 'The consumed-now read surface. Without a query: orientation — check verdict, drift summary, open-question count, and the backlog in dependency order. With a query: free text matches concept ids, names, and descriptions and returns the connected slice; exact subject ids (document-id#local-id) and projection paths address precisely. Set mode for the roster (subjects), declarable vocabulary (kinds), build order (next), or the full open-questions report (open).',
         inputSchema: {
             type: 'object',
             required: ['workspace'],
-            properties: workspaceProperty,
+            properties: {
+                ...workspaceProperty,
+                query: {
+                    type: 'string',
+                    description: 'Free text, a globally qualified subject id, or a projection path',
+                },
+                mode: {
+                    type: 'string',
+                    enum: ['subjects', 'kinds', 'next', 'open'],
+                    description: 'Optional flag mode instead of a query: the filterable roster, the declarable kind vocabulary, dependency-ordered planned work, or the open-questions report',
+                },
+                budget: {
+                    type: 'integer',
+                    minimum: 1,
+                    description: 'Approximate token budget for the compact slice rendering (query form only)',
+                },
+            },
+        },
+        arguments: (input) => {
+            const workspace = String(input.workspace);
+            if (typeof input.mode === 'string') {
+                return ['ask', workspace, `--${input.mode}`, '--json'];
+            }
+            if (typeof input.query === 'string' && input.query.length > 0) {
+                const budget = typeof input.budget === 'number'
+                    ? ['--budget', String(input.budget)]
+                    : ['--json'];
+                return ['ask', workspace, input.query, ...budget];
+            }
+            return ['ask', workspace, '--json'];
+        },
+    },
+    {
+        name: 'yarramate_design',
+        description: 'The design interview, one stateless step: the top open question with its subject slice, materiality, and progress. Read-only — answers land through the CLI apply command in the repository, not through this server.',
+        inputSchema: {
+            type: 'object',
+            required: ['workspace'],
+            properties: {
+                ...workspaceProperty,
+                subject: {
+                    type: 'string',
+                    description: 'Optional globally qualified subject id to narrow the interview',
+                },
+            },
         },
-        arguments: (input) => ['status', String(input.workspace), '--json'],
+        arguments: (input) => [
+            'design',
+            String(input.workspace),
+            ...(typeof input.subject === 'string'
+                ? ['--subject', input.subject]
+                : []),
+            '--json',
+        ],
     },
     {
         name: 'yarramate_check',
@@ -39,51 +90,6 @@ const tools = [
         },
         arguments: (input) => ['reconcile', String(input.workspace)],
     },
-    {
-        name: 'yarramate_context',
-        description: 'Bounded architecture context. Provide either a projection path or one or more globally qualified subjects (document-id#local-id) for an ad-hoc connected neighbourhood. Optional token budget switches to a compact ranked rendering.',
-        inputSchema: {
-            type: 'object',
-            required: ['workspace'],
-            properties: {
-                ...workspaceProperty,
-                projection: {
-                    type: 'string',
-                    description: 'Path to an authored projection definition',
-                },
-                subjects: {
-                    type: 'array',
-                    items: { type: 'string' },
-                    description: 'Globally qualified subject identities for ad-hoc context',
-                },
-                budget: {
-                    type: 'integer',
-                    minimum: 1,
-                    description: 'Approximate token budget for the compact rendering',
-                },
-            },
-        },
-        arguments: (input) => {
-            const budget = typeof input.budget === 'number'
-                ? ['--budget', String(input.budget)]
-                : [];
-            if (typeof input.projection === 'string') {
-                return [
-                    'context',
-                    input.projection,
-                    String(input.workspace),
-                    ...budget,
-                ];
-            }
-            const subjects = Array.isArray(input.subjects)
-                ? input.subjects.flatMap((subject) => [
-                    '--subject',
-                    String(subject),
-                ])
-                : [];
-            return ['context', ...subjects, String(input.workspace), ...budget];
-        },
-    },
 ];
 const respond = (id, result) => {
     process.stdout.write(`${JSON.stringify({ jsonrpc: '2.0', id, result })}\n`);

package/dist/apply-command.d.ts

@@ -0,0 +1,2 @@
+import { type CliResult } from './cli-support.js';
+export declare function runApplyCommand(options: readonly string[], cwd: string): CliResult;