yarramate 0.1.0

package/dist/adapters/likec4-export.js

@@ -0,0 +1,204 @@
+import { adapterMappingEntryLocation, adapterMappingLocation, } from '../adapter-mapping.js';
+import { diagnosticOrder } from '../source-document.js';
+const identifier = /^[A-Za-z_][A-Za-z0-9_-]*$/;
+const valueFor = (claims, subject, predicate) => {
+    const object = claims.find((claim) => claim.subject === subject && claim.predicate === predicate)?.object;
+    return object !== undefined && 'value' in object
+        ? object.value
+        : undefined;
+};
+const referencesFor = (claims, subject, predicate) => claims
+    .flatMap((claim) => claim.subject === subject &&
+    claim.predicate === predicate &&
+    'ref' in claim.object
+    ? [claim.object.ref]
+    : [])
+    .sort();
+const sourceForConcept = (claims, subject) => claims.find((claim) => claim.subject === subject &&
+    claim.predicate === 'yarramate/concept/kind')?.source;
+const metadataLines = (entries, indentation) => {
+    const present = entries.filter((entry) => entry[1] !== undefined &&
+        (typeof entry[1] === 'string' || entry[1].length > 0));
+    if (present.length === 0)
+        return [];
+    return [
+        `${indentation}metadata {`,
+        ...present.map(([key, value]) => Array.isArray(value)
+            ? `${indentation}  ${key} [${value.map(quote).join(', ')}]`
+            : `${indentation}  ${key} ${quote(value)}`),
+        `${indentation}}`,
+    ];
+};
+const kindId = (identity) => {
+    const separator = identity.lastIndexOf('#');
+    return separator === -1 ? identity : identity.slice(separator + 1);
+};
+const quote = (value) => `'${value.replaceAll('\\', '\\\\').replaceAll("'", "\\'").replaceAll('\n', '\\n')}'`;
+export function exportLikeC4(projection, mapping, kindMapping, options = {}) {
+    const diagnostics = [];
+    if (mapping.adapter !== 'likec4') {
+        const source = adapterMappingLocation(mapping, 'adapter');
+        diagnostics.push({
+            severity: 'error',
+            code: 'YMLC101',
+            message: `Adapter mapping "${mapping.id}@${mapping.version}" targets "${mapping.adapter}", not "likec4"`,
+            path: source.path,
+            pointer: source.pointer,
+            line: source.line,
+            column: source.column,
+        });
+    }
+    const externalByNative = new Map(mapping.mappings
+        .filter(({ type }) => type === 'concept')
+        .map(({ native, external }) => [native, external]));
+    const externalConceptKind = new Map(kindMapping?.conceptKinds.map(({ native, external }) => [
+        native,
+        external,
+    ]) ?? []);
+    const externalRelationshipKind = new Map(kindMapping?.relationshipKinds.map(({ native, external }) => [
+        native,
+        external,
+    ]) ?? []);
+    const concepts = projection.subjects
+        .filter(({ type }) => type === 'concept')
+        .sort((left, right) => left.id.localeCompare(right.id));
+    const comparisonChange = new Map(options.comparison === undefined
+        ? []
+        : [
+            ...options.comparison.added.map(({ id }) => [id, 'added']),
+            ...options.comparison.removed.map(({ id }) => [id, 'removed']),
+            ...options.comparison.retained.map(({ id }) => [id, 'retained']),
+        ]);
+    for (const concept of concepts) {
+        const external = externalByNative.get(concept.id);
+        if (external === undefined) {
+            const source = sourceForConcept(projection.claims, concept.id);
+            if (source === undefined)
+                continue;
+            diagnostics.push({
+                severity: 'error',
+                code: 'YMLC102',
+                message: `Projected concept "${concept.id}" has no LikeC4 mapping`,
+                subject: concept.id,
+                path: source.path,
+                pointer: source.pointer,
+                line: source.line,
+                column: source.column,
+            });
+        }
+        else if (!identifier.test(external)) {
+            const entry = mapping.mappings.find(({ native, type }) => native === concept.id && type === 'concept');
+            const source = adapterMappingEntryLocation(mapping, entry, 'external');
+            diagnostics.push({
+                severity: 'error',
+                code: 'YMLC103',
+                message: `LikeC4 identity "${external}" is not a valid identifier`,
+                subject: concept.id,
+                path: source.path,
+                pointer: source.pointer,
+                line: source.line,
+                column: source.column,
+            });
+        }
+    }
+    if (diagnostics.length > 0) {
+        return {
+            ok: false,
+            diagnostics: diagnostics.sort(diagnosticOrder),
+        };
+    }
+    const lines = [
+        '// Generated by YarraMate. Edit the native documents, not this file.',
+        'model {',
+    ];
+    for (const concept of concepts) {
+        const external = externalByNative.get(concept.id);
+        const semanticKind = valueFor(projection.claims, concept.id, 'yarramate/concept/kind') ?? 'element';
+        const kind = externalConceptKind.get(semanticKind) ?? kindId(semanticKind);
+        const name = valueFor(projection.claims, concept.id, 'yarramate/concept/name') ?? concept.id;
+        const description = valueFor(projection.claims, concept.id, 'yarramate/concept/description');
+        const metadata = metadataLines([
+            ['yarramateId', concept.id],
+            ['yarramateKind', semanticKind],
+            ['yarramateChange', comparisonChange.get(concept.id)],
+            [
+                'status',
+                valueFor(projection.claims, concept.id, 'yarramate/lifecycle/status'),
+            ],
+            [
+                'owner',
+                referencesFor(projection.claims, concept.id, 'yarramate/ownership/owner')[0],
+            ],
+            [
+                'constraints',
+                referencesFor(projection.claims, concept.id, 'yarramate/constraint/requires'),
+            ],
+        ], '    ');
+        if (description === undefined && metadata.length === 0) {
+            lines.push(`  ${external} = ${kind} ${quote(name)}`);
+        }
+        else {
+            lines.push(`  ${external} = ${kind} ${quote(name)} {`, ...(description === undefined
+                ? []
+                : [`    description ${quote(description)}`]), ...metadata, '  }');
+        }
+    }
+    const relationships = projection.subjects
+        .filter(({ type }) => type === 'relationship')
+        .sort((left, right) => left.id.localeCompare(right.id));
+    if (relationships.length > 0)
+        lines.push('');
+    for (const relationship of relationships) {
+        const structural = projection.claims.find((claim) => claim.id === relationship.id);
+        if (structural === undefined ||
+            !('ref' in structural.object)) {
+            continue;
+        }
+        const source = externalByNative.get(structural.subject);
+        const target = externalByNative.get(structural.object.ref);
+        if (source === undefined || target === undefined)
+            continue;
+        const name = valueFor(projection.claims, relationship.id, 'yarramate/relationship/name');
+        const metadata = metadataLines([
+            ['yarramateId', relationship.id],
+            ['yarramateKind', structural.predicate],
+            ['yarramateChange', comparisonChange.get(relationship.id)],
+            [
+                'status',
+                valueFor(projection.claims, relationship.id, 'yarramate/lifecycle/status'),
+            ],
+            [
+                'mode',
+                valueFor(projection.claims, relationship.id, 'yarramate/access/mode'),
+            ],
+            [
+                'content',
+                valueFor(projection.claims, relationship.id, 'yarramate/flow/content'),
+            ],
+        ], '    ');
+        lines.push(`  ${source} -[${externalRelationshipKind.get(structural.predicate) ?? kindId(structural.predicate)}]-> ${target}${name === undefined ? '' : ` ${quote(name)}`}${metadata.length === 0 ? '' : ' {'}`, ...metadata, ...(metadata.length === 0 ? [] : ['  }']));
+    }
+    const viewId = identifier.test(projection.projection.split('@')[0] ?? '')
+        ? projection.projection.split('@')[0]
+        : 'index';
+    lines.push('}', '', 'views {', `  view ${viewId} {`, ...(projection.presentation?.title === undefined
+        ? []
+        : [`    title ${quote(projection.presentation.title)}`]), ...(projection.presentation?.description === undefined
+        ? []
+        : [
+            `    description ${quote(projection.presentation.description)}`,
+        ]), '    include *', ...(options.comparison === undefined
+        ? []
+        : concepts.map((concept) => {
+            const external = externalByNative.get(concept.id);
+            const change = comparisonChange.get(concept.id);
+            if (change === 'added') {
+                return `    style ${external} { color green }`;
+            }
+            if (change === 'removed') {
+                return `    style ${external} { color red; border dashed }`;
+            }
+            return `    style ${external} { color gray }`;
+        })), '    autoLayout LeftRight', '  }', '}', '');
+    return { ok: true, source: lines.join('\n') };
+}

package/dist/adapters/likec4-kind-mapping.d.ts

@@ -0,0 +1,22 @@
+import type { Diagnostic, WorkspaceSource } from '../compiler.js';
+import { type SourceLocation } from '../source-document.js';
+export interface LikeC4KindEntry {
+    readonly native: string;
+    readonly external: string;
+}
+export interface LikeC4KindMapping {
+    readonly format: 'yarramate/likec4-kind-mapping/v1';
+    readonly id: string;
+    readonly version: string;
+    readonly conceptKinds: readonly LikeC4KindEntry[];
+    readonly relationshipKinds: readonly LikeC4KindEntry[];
+}
+export type LikeC4KindMappingLoadResult = {
+    readonly ok: true;
+    readonly mapping: LikeC4KindMapping;
+} | {
+    readonly ok: false;
+    readonly diagnostics: readonly Diagnostic[];
+};
+export declare function loadLikeC4KindMapping(source: WorkspaceSource): LikeC4KindMappingLoadResult;
+export declare function likeC4KindMappingExternalLocation(mapping: LikeC4KindMapping, category: 'conceptKinds' | 'relationshipKinds', native: string): SourceLocation | undefined;

package/dist/adapters/likec4-kind-mapping.js

@@ -0,0 +1,60 @@
+import Ajv2020Module from 'ajv/dist/2020.js';
+import { diagnosticOrder, loadSourceDocument, locateSourcePath, } from '../source-document.js';
+import kindMappingSchema from '../../schema/yarramate-likec4-kind-mapping.schema.json' with {
+    type: 'json'
+};
+const Ajv2020 = Ajv2020Module.default;
+const validateSchema = new Ajv2020({ allErrors: true }).compile(kindMappingSchema);
+const kindMappingLocations = new WeakMap();
+const entryOrder = (left, right) => left.native.localeCompare(right.native) ||
+    left.external.localeCompare(right.external);
+export function loadLikeC4KindMapping(source) {
+    const loaded = loadSourceDocument(source, validateSchema, 'LikeC4 kind mapping');
+    if (!loaded.ok)
+        return loaded;
+    const { value, yaml, lineCounter } = loaded.document;
+    const diagnostics = [];
+    const checkDuplicates = (field, label) => {
+        const seen = new Set();
+        for (const [index, entry] of value[field].entries()) {
+            if (seen.has(entry.native)) {
+                const location = locateSourcePath(source.path, yaml, lineCounter, [field, index, 'native'], `/${field}/${index}/native`);
+                diagnostics.push({
+                    severity: 'error',
+                    code: 'YMLC201',
+                    message: `Native ${label} kind "${entry.native}" is mapped more than once`,
+                    ...location,
+                });
+            }
+            seen.add(entry.native);
+        }
+    };
+    checkDuplicates('conceptKinds', 'concept');
+    checkDuplicates('relationshipKinds', 'relationship');
+    if (diagnostics.length > 0) {
+        return {
+            ok: false,
+            diagnostics: diagnostics.sort(diagnosticOrder),
+        };
+    }
+    const mapping = {
+        ...value,
+        conceptKinds: [...value.conceptKinds].sort(entryOrder),
+        relationshipKinds: [...value.relationshipKinds].sort(entryOrder),
+    };
+    const locateExternal = (field, entry) => {
+        const authoredIndex = value[field].indexOf(entry);
+        return locateSourcePath(source.path, yaml, lineCounter, [field, authoredIndex, 'external'], `/${field}/${authoredIndex}/external`);
+    };
+    kindMappingLocations.set(mapping, {
+        conceptKinds: mapping.conceptKinds.map((entry) => locateExternal('conceptKinds', entry)),
+        relationshipKinds: mapping.relationshipKinds.map((entry) => locateExternal('relationshipKinds', entry)),
+    });
+    return { ok: true, mapping };
+}
+export function likeC4KindMappingExternalLocation(mapping, category, native) {
+    const index = mapping[category].findIndex((entry) => entry.native === native);
+    return index === -1
+        ? undefined
+        : kindMappingLocations.get(mapping)?.[category][index];
+}

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

@@ -0,0 +1,28 @@
+import { type AdapterMapping } from '../adapter-mapping.js';
+import { type Diagnostic, type WorkspaceSource } from '../compiler.js';
+import { type ProjectionResult } from '../projection.js';
+import { type LikeC4ExportDiagnostic } from './likec4-export.js';
+import { type LikeC4KindMapping } from './likec4-kind-mapping.js';
+export interface LikeC4PreparationInput {
+    readonly sources: readonly WorkspaceSource[];
+    readonly projection: WorkspaceSource;
+    readonly subjectMapping: WorkspaceSource;
+    readonly kindMapping?: WorkspaceSource;
+    readonly comparison?: {
+        readonly from: string;
+        readonly to: string;
+    };
+    readonly vocabulary: 'bundled' | 'consumer';
+}
+export type LikeC4PreparationDiagnostic = Diagnostic | LikeC4ExportDiagnostic;
+export type LikeC4PreparationResult = {
+    readonly ok: true;
+    readonly source: string;
+    readonly projection: ProjectionResult;
+    readonly subjectMapping: AdapterMapping;
+    readonly kindMapping?: LikeC4KindMapping;
+} | {
+    readonly ok: false;
+    readonly diagnostics: readonly LikeC4PreparationDiagnostic[];
+};
+export declare function prepareLikeC4Export(input: LikeC4PreparationInput): LikeC4PreparationResult;

package/dist/adapters/likec4-prepare.js

@@ -0,0 +1,154 @@
+import { LineCounter, parseDocument } from 'yaml';
+import { loadAdapterMapping, validateAdapterMapping, } from '../adapter-mapping.js';
+import { compileWorkspaceWithProfileContext, } from '../compiler.js';
+import { compareArchitectureStates } from '../architecture-state.js';
+import { conceptKinds, relationshipPolicies } from '../profile.js';
+import { evaluateProjection, loadProjection, } from '../projection.js';
+import { diagnosticOrder, locateSourcePath, } from '../source-document.js';
+import { exportLikeC4, } from './likec4-export.js';
+import { likeC4KindMappingExternalLocation, loadLikeC4KindMapping, } from './likec4-kind-mapping.js';
+const terminalKind = (identity) => {
+    const separator = identity.lastIndexOf('#');
+    return separator === -1 ? identity : identity.slice(separator + 1);
+};
+const unsupportedBundledKinds = (projection, kindMapping) => {
+    const supportedConceptKinds = new Set(conceptKinds.map(({ id }) => id));
+    const supportedRelationshipKinds = new Set(relationshipPolicies.map(({ id }) => id));
+    const mappedConceptKinds = new Map(kindMapping?.conceptKinds.map(({ native, external }) => [
+        native,
+        external,
+    ]) ?? []);
+    const mappedRelationshipKinds = new Map(kindMapping?.relationshipKinds.map(({ native, external }) => [
+        native,
+        external,
+    ]) ?? []);
+    const diagnostics = [];
+    for (const subject of projection.subjects) {
+        const semanticKind = subject.type === 'concept'
+            ? projection.claims.find((claim) => claim.subject === subject.id &&
+                claim.predicate === 'yarramate/concept/kind' &&
+                'value' in claim.object)?.object
+            : projection.claims.find((claim) => claim.id === subject.id)
+                ?.predicate;
+        const identity = typeof semanticKind === 'string'
+            ? semanticKind
+            : semanticKind !== undefined && 'value' in semanticKind
+                ? semanticKind.value
+                : undefined;
+        if (identity === undefined)
+            continue;
+        const external = subject.type === 'concept'
+            ? (mappedConceptKinds.get(identity) ?? terminalKind(identity))
+            : (mappedRelationshipKinds.get(identity) ?? terminalKind(identity));
+        const supported = subject.type === 'concept'
+            ? supportedConceptKinds.has(external)
+            : supportedRelationshipKinds.has(external);
+        if (!supported) {
+            const mappedSource = kindMapping === undefined
+                ? undefined
+                : likeC4KindMappingExternalLocation(kindMapping, subject.type === 'concept'
+                    ? 'conceptKinds'
+                    : 'relationshipKinds', identity);
+            const sourceClaim = subject.type === 'concept'
+                ? projection.claims.find((claim) => claim.subject === subject.id &&
+                    claim.predicate === 'yarramate/concept/kind')
+                : projection.claims.find((claim) => claim.id === subject.id);
+            const source = mappedSource ?? sourceClaim?.source;
+            if (source === undefined)
+                continue;
+            diagnostics.push({
+                severity: 'error',
+                code: 'YMLC104',
+                message: `Semantic ${subject.type} kind "${identity}" resolves to unsupported bundled LikeC4 kind "${external}"`,
+                subject: subject.id,
+                path: source.path,
+                pointer: source.pointer,
+                line: source.line,
+                column: source.column,
+            });
+        }
+    }
+    return diagnostics.sort(diagnosticOrder);
+};
+export function prepareLikeC4Export(input) {
+    const compilation = compileWorkspaceWithProfileContext(input.sources);
+    if (!compilation.ok)
+        return compilation;
+    const projection = loadProjection(input.projection);
+    if (!projection.ok)
+        return projection;
+    const projectionStateLocation = (state) => {
+        const states = projection.projection.query.states ?? [];
+        const index = states.indexOf(state);
+        const pointer = index === -1 ? '/query/states' : `/query/states/${index}`;
+        const lineCounter = new LineCounter();
+        const yaml = parseDocument(input.projection.source, {
+            lineCounter,
+        });
+        return locateSourcePath(input.projection.path, yaml, lineCounter, index === -1 ? ['query', 'states'] : ['query', 'states', index], pointer);
+    };
+    const subjectMapping = loadAdapterMapping(input.subjectMapping);
+    if (!subjectMapping.ok)
+        return subjectMapping;
+    const subjectValidation = validateAdapterMapping(compilation.graph, subjectMapping.mapping);
+    if (!subjectValidation.ok)
+        return subjectValidation;
+    const kindMapping = input.kindMapping === undefined
+        ? undefined
+        : loadLikeC4KindMapping(input.kindMapping);
+    if (kindMapping !== undefined && !kindMapping.ok)
+        return kindMapping;
+    if (input.comparison !== undefined) {
+        const selectedStates = projection.projection.query.states ?? [];
+        const omittedStates = [
+            ...new Set([input.comparison.from, input.comparison.to]),
+        ].filter((state) => !selectedStates.includes(state));
+        if (omittedStates.length > 0) {
+            return {
+                ok: false,
+                diagnostics: omittedStates.map((state) => ({
+                    severity: 'error',
+                    code: 'YMLC106',
+                    message: `Comparison state "${state}" is not selected by projection "${projection.projection.id}@${projection.projection.version}"`,
+                    subject: state,
+                    ...projectionStateLocation(state),
+                })),
+            };
+        }
+    }
+    const projectionResult = evaluateProjection(compilation.graph, projection.projection, compilation.profileContext);
+    const comparison = input.comparison === undefined
+        ? undefined
+        : compareArchitectureStates(compilation.graph, input.comparison.from, input.comparison.to);
+    if (comparison !== undefined && !comparison.ok) {
+        return {
+            ok: false,
+            diagnostics: comparison.issues.map((issue) => ({
+                severity: 'error',
+                code: 'YMLC105',
+                message: issue.message,
+                subject: issue.state,
+                ...projectionStateLocation(issue.state),
+            })),
+        };
+    }
+    if (input.vocabulary === 'bundled') {
+        const diagnostics = unsupportedBundledKinds(projectionResult, kindMapping?.mapping);
+        if (diagnostics.length > 0)
+            return { ok: false, diagnostics };
+    }
+    const exported = exportLikeC4(projectionResult, subjectMapping.mapping, kindMapping?.mapping, comparison === undefined
+        ? undefined
+        : { comparison: comparison.comparison });
+    if (!exported.ok)
+        return exported;
+    return {
+        ok: true,
+        source: exported.source,
+        projection: projectionResult,
+        subjectMapping: subjectMapping.mapping,
+        ...(kindMapping === undefined
+            ? {}
+            : { kindMapping: kindMapping.mapping }),
+    };
+}

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

@@ -0,0 +1,58 @@
+import type { WorkspaceSource } from '../compiler.js';
+import type { LikeC4PreparationResult } from './likec4-prepare.js';
+import { type LikeC4ExportResult } from './likec4-export.js';
+export interface LikeC4ProjectDefinition {
+    readonly format: 'yarramate/likec4-project/v1';
+    readonly id: string;
+    readonly version: string;
+    readonly title: string;
+    readonly mapping: string;
+    readonly kindMapping?: string;
+    readonly views: ReadonlyArray<{
+        readonly id?: string;
+        readonly projection: string;
+        readonly compare?: {
+            readonly from: string;
+            readonly to: string;
+        };
+        readonly dynamic?: {
+            readonly steps: ReadonlyArray<{
+                readonly relationship: string;
+                readonly title?: string;
+            }>;
+        };
+        readonly deployment?: LikeC4Deployment;
+    }>;
+}
+export interface LikeC4Deployment {
+    readonly nodes: ReadonlyArray<{
+        readonly id: string;
+        readonly kind: 'environment' | 'zone' | 'host' | 'runtime';
+        readonly name: string;
+        readonly parent?: string;
+    }>;
+    readonly instances: ReadonlyArray<{
+        readonly id: string;
+        readonly subject: string;
+        readonly node: string;
+    }>;
+}
+export declare const loadLikeC4ProjectDefinition: (source: WorkspaceSource) => import("../source-document.js").SourceDocumentResult<LikeC4ProjectDefinition>;
+export interface PreparedLikeC4ProjectView {
+    readonly id?: string;
+    readonly prepared: Extract<LikeC4PreparationResult, {
+        readonly ok: true;
+    }>;
+    readonly comparison?: {
+        readonly from: string;
+        readonly to: string;
+    };
+    readonly dynamic?: {
+        readonly steps: ReadonlyArray<{
+            readonly relationship: string;
+            readonly title?: string;
+        }>;
+    };
+    readonly deployment?: LikeC4Deployment;
+}
+export declare function exportLikeC4Project(project: LikeC4ProjectDefinition, views: readonly PreparedLikeC4ProjectView[]): LikeC4ExportResult;