yarramate 0.1.1 → 0.3.0

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 { 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 <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,149 @@ 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, mappingPath, ...sourcePaths] = args;
+    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 validation = validateAdapterMapping(compilation.graph, loaded.mapping);
+        if (!validation.ok) {
+            return {
+                exitCode: 1,
+                stdout: diagnosticJson(validation.diagnostics),
+                stderr: '',
+            };
+        }
+        const mapped = new Set(loaded.mapping.mappings.map(({ native }) => native));
+        const claimedExternal = new Set(loaded.mapping.mappings.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) {
+            return {
+                exitCode: 0,
+                stdout: `LikeC4 mapping ${mappingPath} is already synchronized\n`,
+                stderr: '',
+            };
+        }
+        const document = parseDocument(original);
+        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 });
+        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);
+        if (!candidateValidation.ok) {
+            return {
+                exitCode: 1,
+                stdout: diagnosticJson(candidateValidation.diagnostics),
+                stderr: '',
+            };
+        }
+        const staged = stageFile(absoluteMappingPath, candidate);
+        try {
+            staged.publish();
+        }
+        finally {
+            staged.cleanup();
+        }
+        return {
+            exitCode: 0,
+            stdout: `Added ${additions.length} LikeC4 mappings to ${mappingPath}\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');
@@ -151,7 +297,7 @@ const publishGeneratedProject = (cwd, outputDirectory, input) => {
     else {
         mkdirSync(projectPath, { recursive: true });
     }
-    const specificationSource = readFileSync(fileURLToPath(new URL('../../.yarramate/integrations/likec4/prototype/specification.likec4', import.meta.url)));
+    const specificationSource = readFileSync(fileURLToPath(new URL('../../assets/likec4/specification.likec4', import.meta.url)));
     const configSource = `${JSON.stringify({
         $schema: 'https://likec4.dev/schemas/config.json',
         name: input.projectName,
@@ -194,6 +340,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 +456,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/adapters/likec4-export.js

@@ -133,6 +133,10 @@ export function exportLikeC4(projection, mapping, kindMapping, options = {}) {
                 'constraints',
                 referencesFor(projection.claims, concept.id, 'yarramate/constraint/requires'),
             ],
+            [
+                'references',
+                referencesFor(projection.claims, concept.id, 'yarramate/reference/refers-to'),
+            ],
         ], '    ');
         if (description === undefined && metadata.length === 0) {
             lines.push(`  ${external} = ${kind} ${quote(name)}`);
@@ -159,6 +163,7 @@ export function exportLikeC4(projection, mapping, kindMapping, options = {}) {
         if (source === undefined || target === undefined)
             continue;
         const name = valueFor(projection.claims, relationship.id, 'yarramate/relationship/name');
+        const description = valueFor(projection.claims, relationship.id, 'yarramate/relationship/description');
         const metadata = metadataLines([
             ['yarramateId', relationship.id],
             ['yarramateKind', structural.predicate],
@@ -175,8 +180,16 @@ export function exportLikeC4(projection, mapping, kindMapping, options = {}) {
                 'content',
                 valueFor(projection.claims, relationship.id, 'yarramate/flow/content'),
             ],
+            [
+                'references',
+                referencesFor(projection.claims, relationship.id, 'yarramate/reference/refers-to'),
+            ],
         ], '    ');
-        lines.push(`  ${source} -[${externalRelationshipKind.get(structural.predicate) ?? kindId(structural.predicate)}]-> ${target}${name === undefined ? '' : ` ${quote(name)}`}${metadata.length === 0 ? '' : ' {'}`, ...metadata, ...(metadata.length === 0 ? [] : ['  }']));
+        lines.push(`  ${source} -[${externalRelationshipKind.get(structural.predicate) ?? kindId(structural.predicate)}]-> ${target}${name === undefined ? '' : ` ${quote(name)}`}${description === undefined && metadata.length === 0 ? '' : ' {'}`, ...(description === undefined
+            ? []
+            : [`    description ${quote(description)}`]), ...metadata, ...(description === undefined && metadata.length === 0
+            ? []
+            : ['  }']));
     }
     const viewId = identifier.test(projection.projection.split('@')[0] ?? '')
         ? projection.projection.split('@')[0]

package/dist/adapters/likec4-project.js

@@ -73,7 +73,7 @@ const viewBody = ({ id, prepared, dynamic, deployment, }) => {
     }
     if (dynamic !== undefined) {
         const claimsById = new Map(prepared.projection.claims.map((claim) => [claim.id, claim]));
-        const lines = dynamic.steps.map((step) => {
+        const lines = dynamic.steps.flatMap((step) => {
             const structural = claimsById.get(step.relationship);
             const source = externalByNative.get(structural.subject);
             const target = 'ref' in structural.object
@@ -86,7 +86,21 @@ const viewBody = ({ id, prepared, dynamic, deployment, }) => {
                 (declaredTitle !== undefined && 'value' in declaredTitle.object
                     ? declaredTitle.object.value
                     : undefined);
-            return `    ${source} -> ${target}${title === undefined ? '' : ` ${quote(title)}`}`;
+            const declaredDescription = prepared.projection.claims.find((claim) => claim.subject === step.relationship &&
+                claim.predicate === 'yarramate/relationship/description' &&
+                'value' in claim.object);
+            const description = declaredDescription !== undefined &&
+                'value' in declaredDescription.object
+                ? declaredDescription.object.value
+                : undefined;
+            const statement = `    ${source} -> ${target}${title === undefined ? '' : ` ${quote(title)}`}`;
+            return description === undefined
+                ? [statement]
+                : [
+                    `${statement} {`,
+                    `      description ${quote(description)}`,
+                    '    }',
+                ];
         });
         const viewId = id ?? prepared.projection.projection.split('@')[0];
         return [

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

@@ -5,9 +5,14 @@ export interface CliResult {
     readonly stderr: string;
 }
 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> ...] [--present-in <state-ref> ...] [--source <source.yaml> ...]\n  yarramate connect <document.yaml> --id <id> --kind <kind> --from <ref> --to <ref> [--name <name>] [--status <status>] [--mode <mode>] [--content <text>] [--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 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

@@ -14,15 +14,16 @@ export const isMainModule = (moduleUrl, entrypoint) => {
         return false;
     }
 };
-export 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> ...] [--present-in <state-ref> ...] [--source <source.yaml> ...]\n  yarramate connect <document.yaml> --id <id> --kind <kind> --from <ref> --to <ref> [--name <name>] [--status <status>] [--mode <mode>] [--content <text>] [--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 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 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/dist/cli.js

@@ -301,6 +301,7 @@ const oneFlag = (flags, flag) => {
 };
 const hasRepeatedSingletonFlag = (flags) => [...flags.entries()].some(([flag, values]) => flag !== '--source' &&
     flag !== '--constraint' &&
+    flag !== '--reference' &&
     flag !== '--present-in' &&
     values.length !== 1);
 const appendBlockItem = (document, collection, item) => {
@@ -310,6 +311,20 @@ const appendBlockItem = (document, collection, item) => {
         sequence.flow = false;
     }
 };
+const identifiedReferences = (values) => {
+    const parsed = values.map((value) => {
+        const separator = value.indexOf('=');
+        return separator <= 0 || separator === value.length - 1
+            ? undefined
+            : {
+                id: value.slice(0, separator),
+                ref: value.slice(separator + 1),
+            };
+    });
+    return parsed.some((reference) => reference === undefined)
+        ? undefined
+        : parsed;
+};
 const runAdd = (options, cwd) => {
     const parsed = parseFlags(options);
     if (parsed === undefined) {
@@ -323,6 +338,7 @@ const runAdd = (options, cwd) => {
         '--description',
         '--owner',
         '--constraint',
+        '--reference',
         '--present-in',
         '--source',
     ]);
@@ -336,16 +352,9 @@ const runAdd = (options, cwd) => {
     if (id === undefined || kind === undefined || name === undefined) {
         return { exitCode: 2, stdout: '', stderr: usage };
     }
-    const constraints = (parsed.flags.get('--constraint') ?? []).map((value) => {
-        const separator = value.indexOf('=');
-        return separator <= 0 || separator === value.length - 1
-            ? undefined
-            : {
-                id: value.slice(0, separator),
-                ref: value.slice(separator + 1),
-            };
-    });
-    if (constraints.some((constraint) => constraint === undefined)) {
+    const constraints = identifiedReferences(parsed.flags.get('--constraint') ?? []);
+    const references = identifiedReferences(parsed.flags.get('--reference') ?? []);
+    if (constraints === undefined || references === undefined) {
         return { exitCode: 2, stdout: '', stderr: usage };
     }
     try {
@@ -365,6 +374,7 @@ const runAdd = (options, cwd) => {
                 ? {}
                 : { owner: oneFlag(parsed.flags, '--owner') }),
             ...(constraints.length === 0 ? {} : { constraints }),
+            ...(references.length === 0 ? {} : { references }),
             ...(parsed.flags.get('--present-in') === undefined
                 ? {}
                 : { presentIn: parsed.flags.get('--present-in') }),
@@ -417,9 +427,11 @@ const runConnect = (options, cwd) => {
         '--from',
         '--to',
         '--name',
+        '--description',
         '--status',
         '--mode',
         '--content',
+        '--reference',
         '--present-in',
         '--source',
     ]);
@@ -437,6 +449,10 @@ const runConnect = (options, cwd) => {
         to === undefined) {
         return { exitCode: 2, stdout: '', stderr: usage };
     }
+    const references = identifiedReferences(parsed.flags.get('--reference') ?? []);
+    if (references === undefined) {
+        return { exitCode: 2, stdout: '', stderr: usage };
+    }
     try {
         const absolutePath = resolve(cwd, parsed.path);
         const document = parseDocument(readFileSync(absolutePath, 'utf8'));
@@ -448,6 +464,9 @@ const runConnect = (options, cwd) => {
             ...(oneFlag(parsed.flags, '--name') === undefined
                 ? {}
                 : { name: oneFlag(parsed.flags, '--name') }),
+            ...(oneFlag(parsed.flags, '--description') === undefined
+                ? {}
+                : { description: oneFlag(parsed.flags, '--description') }),
             ...(oneFlag(parsed.flags, '--status') === undefined
                 ? {}
                 : { status: oneFlag(parsed.flags, '--status') }),
@@ -457,6 +476,7 @@ const runConnect = (options, cwd) => {
             ...(oneFlag(parsed.flags, '--content') === undefined
                 ? {}
                 : { content: oneFlag(parsed.flags, '--content') }),
+            ...(references.length === 0 ? {} : { references }),
             ...(parsed.flags.get('--present-in') === undefined
                 ? {}
                 : { presentIn: parsed.flags.get('--present-in') }),