yarramate 0.1.0

package/dist/profile.js

@@ -0,0 +1,162 @@
+export const layers = [
+    'motivation',
+    'strategy',
+    'business',
+    'application',
+    'technology',
+    'physical',
+    'implementation',
+    'composite',
+];
+export const aspects = [
+    'motivation',
+    'active-structure',
+    'behavior',
+    'passive-structure',
+    'composite',
+];
+const kind = (layer, aspect, entries) => entries.map(([id, name]) => ({
+    id,
+    name,
+    layer,
+    aspect,
+    inspiredBy: `ArchiMate-inspired:${name}`,
+}));
+export const conceptKinds = [
+    ...kind('motivation', 'motivation', [
+        ['stakeholder', 'Stakeholder'],
+        ['driver', 'Driver'],
+        ['assessment', 'Assessment'],
+        ['goal', 'Goal'],
+        ['outcome', 'Outcome'],
+        ['principle', 'Principle'],
+        ['requirement', 'Requirement'],
+        ['constraint', 'Constraint'],
+        ['meaning', 'Meaning'],
+        ['value', 'Value'],
+    ]),
+    ...kind('strategy', 'active-structure', [['resource', 'Resource']]),
+    ...kind('strategy', 'behavior', [
+        ['capability', 'Capability'],
+        ['valueStream', 'Value stream'],
+        ['courseOfAction', 'Course of action'],
+    ]),
+    ...kind('business', 'active-structure', [
+        ['businessActor', 'Business actor'],
+        ['businessRole', 'Business role'],
+        ['businessCollaboration', 'Business collaboration'],
+        ['businessInterface', 'Business interface'],
+    ]),
+    ...kind('business', 'behavior', [
+        ['businessProcess', 'Business process'],
+        ['businessFunction', 'Business function'],
+        ['businessInteraction', 'Business interaction'],
+        ['businessEvent', 'Business event'],
+        ['businessService', 'Business service'],
+    ]),
+    ...kind('business', 'passive-structure', [
+        ['businessObject', 'Business object'],
+        ['contract', 'Contract'],
+        ['representation', 'Representation'],
+        ['product', 'Product'],
+    ]),
+    ...kind('application', 'active-structure', [
+        ['applicationComponent', 'Application component'],
+        ['applicationCollaboration', 'Application collaboration'],
+        ['applicationInterface', 'Application interface'],
+    ]),
+    ...kind('application', 'behavior', [
+        ['applicationFunction', 'Application function'],
+        ['applicationInteraction', 'Application interaction'],
+        ['applicationProcess', 'Application process'],
+        ['applicationEvent', 'Application event'],
+        ['applicationService', 'Application service'],
+    ]),
+    ...kind('application', 'passive-structure', [['dataObject', 'Data object']]),
+    ...kind('technology', 'active-structure', [
+        ['node', 'Node'],
+        ['device', 'Device'],
+        ['systemSoftware', 'System software'],
+        ['technologyCollaboration', 'Technology collaboration'],
+        ['technologyInterface', 'Technology interface'],
+        ['path', 'Path'],
+        ['communicationNetwork', 'Communication network'],
+    ]),
+    ...kind('technology', 'behavior', [
+        ['technologyFunction', 'Technology function'],
+        ['technologyProcess', 'Technology process'],
+        ['technologyInteraction', 'Technology interaction'],
+        ['technologyEvent', 'Technology event'],
+        ['technologyService', 'Technology service'],
+    ]),
+    ...kind('technology', 'passive-structure', [['artifact', 'Artifact']]),
+    ...kind('physical', 'active-structure', [
+        ['equipment', 'Equipment'],
+        ['facility', 'Facility'],
+        ['distributionNetwork', 'Distribution network'],
+    ]),
+    ...kind('physical', 'passive-structure', [['material', 'Material']]),
+    ...kind('implementation', 'behavior', [
+        ['workPackage', 'Work package'],
+        ['implementationEvent', 'Implementation event'],
+    ]),
+    ...kind('implementation', 'passive-structure', [
+        ['deliverable', 'Deliverable'],
+        ['plateau', 'Plateau'],
+        ['gap', 'Gap'],
+    ]),
+    ...kind('composite', 'composite', [
+        ['grouping', 'Grouping'],
+        ['location', 'Location'],
+        ['andJunction', 'AND junction'],
+        ['orJunction', 'OR junction'],
+    ]),
+];
+export const relationshipKinds = [
+    'composition',
+    'aggregation',
+    'assignment',
+    'realization',
+    'serving',
+    'access',
+    'influence',
+    'association',
+    'triggering',
+    'flow',
+    'specialization',
+];
+/**
+ * Safe, intentionally broad semantic constraints. A future licensed
+ * compatibility package may layer an exact external relationship matrix over
+ * these native YarraMate rules.
+ */
+export const relationshipPolicies = [
+    { id: 'composition', intent: 'Strong whole-part structure' },
+    { id: 'aggregation', intent: 'Weak whole-part structure' },
+    {
+        id: 'assignment',
+        intent: 'Allocate an active structure to behavior or responsibility',
+        sourceAspects: ['active-structure'],
+    },
+    { id: 'realization', intent: 'Fulfil a more abstract concept' },
+    { id: 'serving', intent: 'Make behavior or an interface available' },
+    {
+        id: 'access',
+        intent: 'Read, write, create, or use passive structure',
+        targetAspects: ['passive-structure'],
+    },
+    {
+        id: 'influence',
+        intent: 'Affect a motivation concept',
+        targetAspects: ['motivation'],
+    },
+    { id: 'association', intent: 'Relevant connection with no stronger meaning' },
+    {
+        id: 'triggering',
+        intent: 'Express temporal or causal precedence',
+        sourceAspects: ['behavior'],
+        targetAspects: ['behavior'],
+    },
+    { id: 'flow', intent: 'Transfer information, value, goods, or material' },
+    { id: 'specialization', intent: 'Express a more specific form' },
+];

package/dist/projection.d.ts

@@ -0,0 +1,42 @@
+import type { Diagnostic, GraphClaim, ResolvedProfileContext, SemanticGraph, WorkspaceSource } from './compiler.js';
+export type LifecycleStatus = 'planned' | 'current' | 'retired';
+export interface ProjectionDefinition {
+    readonly format: 'yarramate/projection/v1';
+    readonly id: string;
+    readonly version: string;
+    readonly query: {
+        readonly subjects?: readonly string[];
+        readonly documents?: readonly string[];
+        readonly kinds?: readonly string[];
+        readonly statuses?: readonly LifecycleStatus[];
+        readonly states?: readonly string[];
+        readonly owners?: readonly string[];
+        readonly constraints?: readonly string[];
+        readonly relationshipKinds?: readonly string[];
+        readonly kindMatching?: 'exact' | 'descendants';
+        readonly relationships?: 'between' | 'connected' | 'none';
+        readonly isolatedConcepts?: 'include' | 'exclude';
+    };
+    readonly presentation?: {
+        readonly title?: string;
+        readonly description?: string;
+    };
+}
+export interface ProjectionResult {
+    readonly format: 'yarramate/projection-result/v1';
+    readonly projection: string;
+    readonly presentation?: ProjectionDefinition['presentation'];
+    readonly documents: SemanticGraph['documents'];
+    readonly subjects: SemanticGraph['subjects'];
+    readonly claims: readonly GraphClaim[];
+}
+export type ProjectionLoadResult = {
+    readonly ok: true;
+    readonly projection: ProjectionDefinition;
+} | {
+    readonly ok: false;
+    readonly diagnostics: readonly Diagnostic[];
+};
+export declare function loadProjection(source: WorkspaceSource): ProjectionLoadResult;
+export declare function evaluateProjection(graph: SemanticGraph, projection: ProjectionDefinition, profileContext?: ResolvedProfileContext): ProjectionResult;
+export declare function renderProjectionMarkdown(result: ProjectionResult): string;

package/dist/projection.js

@@ -0,0 +1,183 @@
+import Ajv2020Module from 'ajv/dist/2020.js';
+import { loadSourceDocument } from './source-document.js';
+import projectionSchema from '../schema/yarramate-projection.schema.json' with {
+    type: 'json'
+};
+const Ajv2020 = Ajv2020Module.default;
+const validateProjection = new Ajv2020({ allErrors: true }).compile(projectionSchema);
+export function loadProjection(source) {
+    const loaded = loadSourceDocument(source, validateProjection, 'Projection');
+    return loaded.ok
+        ? { ok: true, projection: loaded.document.value }
+        : loaded;
+}
+const claimValue = (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 claimReference = (claims, subject, predicate) => {
+    const object = claims.find((claim) => claim.subject === subject && claim.predicate === predicate)?.object;
+    return object !== undefined && 'ref' in object ? object.ref : undefined;
+};
+const claimReferences = (claims, subject, predicate) => claims.flatMap((claim) => claim.subject === subject &&
+    claim.predicate === predicate &&
+    'ref' in claim.object
+    ? [claim.object.ref]
+    : []);
+export function evaluateProjection(graph, projection, profileContext) {
+    const architectureStateIds = new Set(graph.claims
+        .filter(({ predicate }) => predicate === 'yarramate/state/type')
+        .map(({ subject }) => subject));
+    const selectedStateIds = projection.query.states === undefined
+        ? undefined
+        : projection.query.states.filter((state) => architectureStateIds.has(state));
+    const participatesInSelectedState = (subject) => {
+        if (selectedStateIds === undefined)
+            return true;
+        if (selectedStateIds.length === 0)
+            return false;
+        const presence = claimReferences(graph.claims, subject, 'yarramate/state/present-in');
+        return (presence.length === 0 ||
+            presence.some((state) => selectedStateIds.includes(state)));
+    };
+    const initiallySelectedConceptIds = new Set(graph.subjects
+        .filter(({ type }) => type === 'concept')
+        .filter(({ id }) => {
+        const documentId = id.slice(0, id.indexOf('#'));
+        const kind = claimValue(graph.claims, id, 'yarramate/concept/kind');
+        const status = claimValue(graph.claims, id, 'yarramate/lifecycle/status');
+        const owner = claimReference(graph.claims, id, 'yarramate/ownership/owner');
+        const constraints = claimReferences(graph.claims, id, 'yarramate/constraint/requires');
+        return ((projection.query.states === undefined ||
+            (!architectureStateIds.has(id) &&
+                participatesInSelectedState(id))) &&
+            (projection.query.subjects === undefined ||
+                projection.query.subjects.includes(id)) &&
+            (projection.query.documents === undefined ||
+                projection.query.documents.includes(documentId)) &&
+            (projection.query.kinds === undefined ||
+                (kind !== undefined &&
+                    projection.query.kinds.some((selectedKind) => selectedKind === kind ||
+                        (projection.query.kindMatching === 'descendants' &&
+                            profileContext?.conceptKindLineages
+                                .get(kind)
+                                ?.includes(selectedKind) === true)))) &&
+            (projection.query.statuses === undefined ||
+                (status !== undefined &&
+                    projection.query.statuses.includes(status))) &&
+            (projection.query.owners === undefined ||
+                (owner !== undefined &&
+                    projection.query.owners.includes(owner))) &&
+            (projection.query.constraints === undefined ||
+                constraints.some((constraint) => projection.query.constraints?.includes(constraint))));
+    })
+        .map(({ id }) => id));
+    const selectedConceptIds = new Set(initiallySelectedConceptIds);
+    const selectedRelationshipIds = new Set();
+    const relationshipMode = projection.query.relationships ?? 'between';
+    if (relationshipMode !== 'none') {
+        for (const subject of graph.subjects) {
+            if (subject.type !== 'relationship')
+                continue;
+            const relationship = graph.claims.find((claim) => claim.id === subject.id);
+            if (relationship === undefined ||
+                !('ref' in relationship.object) ||
+                (projection.query.relationshipKinds !== undefined &&
+                    !projection.query.relationshipKinds.some((selectedKind) => selectedKind === relationship.predicate ||
+                        (projection.query.kindMatching === 'descendants' &&
+                            profileContext?.relationshipKindLineages
+                                .get(relationship.predicate)
+                                ?.includes(selectedKind) === true))) ||
+                !participatesInSelectedState(subject.id)) {
+                continue;
+            }
+            const sourceSelected = initiallySelectedConceptIds.has(relationship.subject);
+            const targetSelected = initiallySelectedConceptIds.has(relationship.object.ref);
+            if ((relationshipMode === 'between' &&
+                sourceSelected &&
+                targetSelected) ||
+                (relationshipMode === 'connected' &&
+                    (sourceSelected || targetSelected))) {
+                selectedRelationshipIds.add(subject.id);
+                if (relationshipMode === 'connected') {
+                    selectedConceptIds.add(relationship.subject);
+                    selectedConceptIds.add(relationship.object.ref);
+                }
+            }
+        }
+    }
+    if (projection.query.isolatedConcepts === 'exclude') {
+        const relationshipEndpoints = new Set();
+        for (const relationshipId of selectedRelationshipIds) {
+            const relationship = graph.claims.find(({ id, object }) => id === relationshipId && 'ref' in object);
+            if (relationship !== undefined && 'ref' in relationship.object) {
+                relationshipEndpoints.add(relationship.subject);
+                relationshipEndpoints.add(relationship.object.ref);
+            }
+        }
+        for (const conceptId of selectedConceptIds) {
+            if (!relationshipEndpoints.has(conceptId)) {
+                selectedConceptIds.delete(conceptId);
+            }
+        }
+    }
+    const selectedSubjectIds = new Set([
+        ...selectedConceptIds,
+        ...selectedRelationshipIds,
+    ]);
+    const relationshipIds = new Set(graph.subjects
+        .filter(({ type }) => type === 'relationship')
+        .map(({ id }) => id));
+    const subjects = graph.subjects.filter(({ id }) => selectedSubjectIds.has(id));
+    const claims = graph.claims.filter((claim) => (selectedConceptIds.has(claim.subject) &&
+        !relationshipIds.has(claim.id)) ||
+        selectedRelationshipIds.has(claim.subject) ||
+        selectedRelationshipIds.has(claim.id));
+    const selectedDocuments = new Set([...selectedConceptIds].map((id) => id.slice(0, id.indexOf('#'))));
+    return {
+        format: 'yarramate/projection-result/v1',
+        projection: `${projection.id}@${projection.version}`,
+        ...(projection.presentation === undefined
+            ? {}
+            : {
+                presentation: {
+                    ...(projection.presentation.title === undefined
+                        ? {}
+                        : { title: projection.presentation.title }),
+                    ...(projection.presentation.description === undefined
+                        ? {}
+                        : { description: projection.presentation.description }),
+                },
+            }),
+        documents: graph.documents.filter(({ id }) => selectedDocuments.has(id)),
+        subjects,
+        claims,
+    };
+}
+const markdownText = (value) => value.replaceAll('\n', ' ').replaceAll('`', '\\`');
+export function renderProjectionMarkdown(result) {
+    const title = result.presentation?.title ?? result.projection;
+    const concepts = result.subjects.filter(({ type }) => type === 'concept');
+    const relationships = result.subjects.filter(({ type }) => type === 'relationship');
+    const lines = [`# ${markdownText(title)}`, ''];
+    if (result.presentation?.description !== undefined) {
+        lines.push(markdownText(result.presentation.description), '');
+    }
+    lines.push('## Concepts', '');
+    for (const concept of concepts) {
+        const name = claimValue(result.claims, concept.id, 'yarramate/concept/name') ??
+            concept.id;
+        const kind = claimValue(result.claims, concept.id, 'yarramate/concept/kind') ??
+            'unknown';
+        const status = claimValue(result.claims, concept.id, 'yarramate/lifecycle/status');
+        lines.push(`- ${markdownText(name)} (\`${concept.id}\`) — \`${kind}\`${status === undefined ? '' : ` — ${status}`}`);
+    }
+    lines.push('', '## Relationships', '');
+    for (const relationship of relationships) {
+        const claim = result.claims.find(({ id, object }) => id === relationship.id && 'ref' in object);
+        if (claim !== undefined && 'ref' in claim.object) {
+            lines.push(`- \`${claim.subject}\` — \`${claim.predicate}\` → \`${claim.object.ref}\` (\`${relationship.id}\`)`);
+        }
+    }
+    return `${lines.join('\n')}\n`;
+}

package/dist/reconciliation.d.ts

@@ -0,0 +1,26 @@
+import type { EvidenceLocator, EvidenceReport, EvidenceResult } from './evidence.js';
+export interface ReconciliationFinding {
+    readonly target: {
+        readonly type: 'subject' | 'claim';
+        readonly id: string;
+    };
+    readonly result: Exclude<EvidenceResult, 'confirmed'>;
+    readonly provider: string;
+    readonly evidenceDocument: string;
+    readonly evidence: EvidenceLocator;
+}
+export interface ReconciliationReport {
+    readonly format: 'yarramate/reconciliation-report/v1';
+    readonly workspace: string;
+    readonly summary: {
+        readonly evidenceDocuments: number;
+        readonly observations: number;
+        readonly confirmed: number;
+        readonly findings: number;
+        readonly contradicted: number;
+        readonly unknown: number;
+        readonly notObserved: number;
+    };
+    readonly findings: readonly ReconciliationFinding[];
+}
+export declare function reconcileEvidenceReports(workspace: string, reports: readonly EvidenceReport[]): ReconciliationReport;

package/dist/reconciliation.js

@@ -0,0 +1,47 @@
+export function reconcileEvidenceReports(workspace, reports) {
+    const summary = {
+        evidenceDocuments: reports.length,
+        observations: 0,
+        confirmed: 0,
+        findings: 0,
+        contradicted: 0,
+        unknown: 0,
+        notObserved: 0,
+    };
+    const findings = [];
+    for (const report of reports) {
+        summary.observations += report.observations.length;
+        for (const observation of report.observations) {
+            if (observation.result === 'confirmed') {
+                summary.confirmed += 1;
+                continue;
+            }
+            if (observation.result === 'not-observed') {
+                summary.notObserved += 1;
+            }
+            else {
+                summary[observation.result] += 1;
+            }
+            findings.push({
+                target: 'subject' in observation
+                    ? { type: 'subject', id: observation.subject }
+                    : { type: 'claim', id: observation.claim },
+                result: observation.result,
+                provider: report.provider,
+                evidenceDocument: report.evidence,
+                evidence: observation.evidence,
+            });
+        }
+    }
+    findings.sort((left, right) => left.target.id.localeCompare(right.target.id) ||
+        left.target.type.localeCompare(right.target.type) ||
+        left.provider.localeCompare(right.provider) ||
+        left.evidenceDocument.localeCompare(right.evidenceDocument));
+    summary.findings = findings.length;
+    return {
+        format: 'yarramate/reconciliation-report/v1',
+        workspace,
+        summary,
+        findings,
+    };
+}

package/dist/source-document.d.ts

@@ -0,0 +1,24 @@
+import type { ValidateFunction } from 'ajv';
+import { LineCounter, parseDocument } from 'yaml';
+import type { Diagnostic, WorkspaceSource } from './compiler.js';
+export interface SourceLocation {
+    readonly path: string;
+    readonly pointer: string;
+    readonly line: number;
+    readonly column: number;
+}
+export interface ValidatedSourceDocument<T> {
+    readonly value: T;
+    readonly yaml: ReturnType<typeof parseDocument>;
+    readonly lineCounter: LineCounter;
+}
+export type SourceDocumentResult<T> = {
+    readonly ok: true;
+    readonly document: ValidatedSourceDocument<T>;
+} | {
+    readonly ok: false;
+    readonly diagnostics: readonly Diagnostic[];
+};
+export declare const diagnosticOrder: (left: Diagnostic, right: Diagnostic) => number;
+export declare function locateSourcePath(sourcePath: string, yaml: ReturnType<typeof parseDocument>, lineCounter: LineCounter, yamlPath: readonly (string | number)[], pointer: string): SourceLocation;
+export declare function loadSourceDocument<T>(source: WorkspaceSource, validate: ValidateFunction, schemaLabel: string): SourceDocumentResult<T>;

package/dist/source-document.js

@@ -0,0 +1,80 @@
+import { LineCounter, parseDocument } from 'yaml';
+export const diagnosticOrder = (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);
+export function locateSourcePath(sourcePath, yaml, lineCounter, yamlPath, pointer) {
+    const node = yaml.getIn(yamlPath, true);
+    const offset = typeof node === 'object' &&
+        node !== null &&
+        'range' in node &&
+        Array.isArray(node.range)
+        ? node.range[0]
+        : 0;
+    const position = lineCounter.linePos(offset);
+    return {
+        path: sourcePath,
+        pointer,
+        line: position.line,
+        column: position.col,
+    };
+}
+export function loadSourceDocument(source, validate, schemaLabel) {
+    const lineCounter = new LineCounter();
+    const yaml = parseDocument(source.source, { lineCounter });
+    if (yaml.errors.length > 0) {
+        return {
+            ok: false,
+            diagnostics: yaml.errors.map((error) => {
+                const position = error.linePos?.[0] ?? { line: 1, col: 1 };
+                return {
+                    severity: 'error',
+                    code: 'YM101',
+                    message: error.message.split(' at line ')[0] ?? error.message,
+                    path: source.path,
+                    pointer: '/',
+                    line: position.line,
+                    column: position.col,
+                };
+            }),
+        };
+    }
+    const value = yaml.toJS();
+    if (!validate(value)) {
+        return {
+            ok: false,
+            diagnostics: (validate.errors ?? [])
+                .map((error) => {
+                const property = error.keyword === 'additionalProperties'
+                    ? String(error.params.additionalProperty)
+                    : undefined;
+                const pointer = property
+                    ? `${error.instancePath}/${property}`
+                    : error.instancePath || '/';
+                const yamlPath = pointer
+                    .split('/')
+                    .slice(1)
+                    .map((segment) => /^\d+$/.test(segment) ? Number(segment) : segment);
+                const location = locateSourcePath(source.path, yaml, lineCounter, yamlPath, pointer);
+                return {
+                    severity: 'error',
+                    code: 'YM201',
+                    message: property
+                        ? `Property "${property}" is not allowed`
+                        : `${schemaLabel} schema violation: ${error.message ?? error.keyword}`,
+                    ...location,
+                };
+            })
+                .sort(diagnosticOrder),
+        };
+    }
+    return {
+        ok: true,
+        document: {
+            value: value,
+            yaml,
+            lineCounter,
+        },
+    };
+}

package/dist/workspace.d.ts

@@ -0,0 +1,29 @@
+import type { Diagnostic, WorkspaceSource } from './compiler.js';
+export interface WorkspaceManifest {
+    readonly format: 'yarramate/workspace/v1';
+    readonly id: string;
+    readonly documents: readonly string[];
+    readonly profiles: readonly string[];
+    readonly projections: readonly string[];
+    readonly adapterMappings: readonly string[];
+    readonly evidence?: readonly string[];
+    readonly contracts?: readonly string[];
+}
+export interface ResolvedWorkspace {
+    readonly id: string;
+    readonly documents: readonly string[];
+    readonly profiles: readonly string[];
+    readonly projections: readonly string[];
+    readonly adapterMappings: readonly string[];
+    readonly evidence: readonly string[];
+    readonly contracts: readonly string[];
+}
+export type WorkspaceManifestResult = {
+    readonly ok: true;
+    readonly manifest: WorkspaceManifest;
+    readonly workspace: ResolvedWorkspace;
+} | {
+    readonly ok: false;
+    readonly diagnostics: readonly Diagnostic[];
+};
+export declare function loadWorkspaceManifest(source: WorkspaceSource, cwd: string): WorkspaceManifestResult;