yarramate 0.1.0

package/dist/core-contract.d.ts

@@ -0,0 +1,43 @@
+import type { Diagnostic, WorkspaceSource } from './compiler.js';
+export interface CoreContractFormat {
+    readonly id: string;
+    readonly schema: string;
+    readonly packageExport: string;
+}
+export interface CoreContractCommand {
+    readonly name: 'init' | 'add' | 'connect' | 'check' | 'compile' | 'view' | 'context' | 'compare' | 'evidence';
+    readonly binary: 'yarramate';
+    readonly machineFormat?: string;
+}
+export interface CoreContract {
+    readonly format: 'yarramate/core-contract/v1';
+    readonly id: string;
+    readonly version: string;
+    readonly packageManifest: string;
+    readonly formats: readonly CoreContractFormat[];
+    readonly commands: readonly CoreContractCommand[];
+    readonly guarantees: readonly string[];
+    readonly exclusions: readonly string[];
+}
+export type CoreContractLoadResult = {
+    readonly ok: true;
+    readonly contract: CoreContract;
+} | {
+    readonly ok: false;
+    readonly diagnostics: readonly Diagnostic[];
+};
+export interface CoreContractSurface {
+    readonly files: readonly string[];
+    readonly packageManifestValid: boolean;
+    readonly packageExports: Readonly<Record<string, string>>;
+    readonly packageBinaries: readonly string[];
+    readonly schemas?: Readonly<Record<string, {
+        readonly ok: false;
+    } | {
+        readonly ok: true;
+        readonly format?: string;
+        readonly validSchema?: boolean;
+    }>>;
+}
+export declare function loadCoreContract(source: WorkspaceSource): CoreContractLoadResult;
+export declare function checkCoreContract(source: WorkspaceSource, surface: CoreContractSurface): CoreContractLoadResult;

package/dist/core-contract.js

@@ -0,0 +1,162 @@
+import Ajv2020Module from 'ajv/dist/2020.js';
+import { LineCounter, parseDocument } from 'yaml';
+import { diagnosticOrder, loadSourceDocument, locateSourcePath, } from './source-document.js';
+import coreContractSchema from '../schema/yarramate-core-contract.schema.json' with {
+    type: 'json'
+};
+const Ajv2020 = Ajv2020Module.default;
+const validateCoreContract = new Ajv2020({ allErrors: true }).compile(coreContractSchema);
+export function loadCoreContract(source) {
+    const loaded = loadSourceDocument(source, validateCoreContract, 'Core contract');
+    if (!loaded.ok)
+        return loaded;
+    const { value, yaml, lineCounter } = loaded.document;
+    const diagnostics = [];
+    const formatIds = new Set();
+    value.formats.forEach((format, index) => {
+        if (formatIds.has(format.id)) {
+            diagnostics.push({
+                severity: 'error',
+                code: 'YMC101',
+                message: `Core contract format "${format.id}" is declared more than once`,
+                ...locateSourcePath(source.path, yaml, lineCounter, ['formats', index, 'id'], `/formats/${index}/id`),
+            });
+        }
+        formatIds.add(format.id);
+    });
+    const commandNames = new Set();
+    value.commands.forEach((command, index) => {
+        if (commandNames.has(command.name)) {
+            diagnostics.push({
+                severity: 'error',
+                code: 'YMC102',
+                message: `Core contract command "${command.name}" is declared more than once`,
+                ...locateSourcePath(source.path, yaml, lineCounter, ['commands', index, 'name'], `/commands/${index}/name`),
+            });
+        }
+        commandNames.add(command.name);
+        if (command.machineFormat !== undefined &&
+            !formatIds.has(command.machineFormat)) {
+            diagnostics.push({
+                severity: 'error',
+                code: 'YMC103',
+                message: `Command "${command.name}" references undeclared machine format "${command.machineFormat}"`,
+                ...locateSourcePath(source.path, yaml, lineCounter, ['commands', index, 'machineFormat'], `/commands/${index}/machineFormat`),
+            });
+        }
+    });
+    return diagnostics.length === 0
+        ? { ok: true, contract: value }
+        : { ok: false, diagnostics: diagnostics.sort(diagnosticOrder) };
+}
+export function checkCoreContract(source, surface) {
+    const loaded = loadCoreContract(source);
+    if (!loaded.ok)
+        return loaded;
+    const lineCounter = new LineCounter();
+    const yaml = parseDocument(source.source, { lineCounter });
+    const files = new Set(surface.files);
+    const binaries = new Set(surface.packageBinaries);
+    const diagnostics = [];
+    if (!files.has(loaded.contract.packageManifest)) {
+        diagnostics.push({
+            severity: 'error',
+            code: 'YMC204',
+            message: `Package manifest "${loaded.contract.packageManifest}" does not exist`,
+            ...locateSourcePath(source.path, yaml, lineCounter, ['packageManifest'], '/packageManifest'),
+        });
+    }
+    else if (!surface.packageManifestValid) {
+        diagnostics.push({
+            severity: 'error',
+            code: 'YMC205',
+            message: `Package manifest "${loaded.contract.packageManifest}" is not a valid JSON object`,
+            ...locateSourcePath(source.path, yaml, lineCounter, ['packageManifest'], '/packageManifest'),
+        });
+    }
+    diagnostics.push(...loaded.contract.formats.flatMap((format, index) => {
+        const missingSchema = files.has(format.schema)
+            ? []
+            : [
+                {
+                    severity: 'error',
+                    code: 'YMC201',
+                    message: `Schema file "${format.schema}" does not exist`,
+                    ...locateSourcePath(source.path, yaml, lineCounter, ['formats', index, 'schema'], `/formats/${index}/schema`),
+                },
+            ];
+        const schemaSurface = surface.schemas?.[format.schema];
+        const invalidSchema = files.has(format.schema) &&
+            schemaSurface !== undefined &&
+            !schemaSurface.ok
+            ? [
+                {
+                    severity: 'error',
+                    code: 'YMC206',
+                    message: `Schema file "${format.schema}" is not valid JSON`,
+                    ...locateSourcePath(source.path, yaml, lineCounter, ['formats', index, 'schema'], `/formats/${index}/schema`),
+                },
+            ]
+            : [];
+        const mismatchedFormat = files.has(format.schema) &&
+            schemaSurface?.ok === true &&
+            schemaSurface.format !== format.id
+            ? [
+                {
+                    severity: 'error',
+                    code: 'YMC207',
+                    message: schemaSurface.format === undefined
+                        ? `Schema file "${format.schema}" does not declare contracted format "${format.id}"`
+                        : `Schema file "${format.schema}" declares format "${schemaSurface.format}" instead of "${format.id}"`,
+                    ...locateSourcePath(source.path, yaml, lineCounter, ['formats', index, 'id'], `/formats/${index}/id`),
+                },
+            ]
+            : [];
+        const invalidJsonSchema = files.has(format.schema) &&
+            schemaSurface?.ok === true &&
+            schemaSurface.validSchema === false
+            ? [
+                {
+                    severity: 'error',
+                    code: 'YMC208',
+                    message: `Schema file "${format.schema}" is not valid JSON Schema 2020-12`,
+                    ...locateSourcePath(source.path, yaml, lineCounter, ['formats', index, 'schema'], `/formats/${index}/schema`),
+                },
+            ]
+            : [];
+        const expected = `./${format.schema}`;
+        const invalidExport = !surface.packageManifestValid
+            ? []
+            : surface.packageExports[format.packageExport] === expected
+                ? []
+                : [
+                    {
+                        severity: 'error',
+                        code: 'YMC202',
+                        message: `Package export "${format.packageExport}" does not resolve to "${format.schema}"`,
+                        ...locateSourcePath(source.path, yaml, lineCounter, ['formats', index, 'packageExport'], `/formats/${index}/packageExport`),
+                    },
+                ];
+        return [
+            ...missingSchema,
+            ...invalidSchema,
+            ...mismatchedFormat,
+            ...invalidJsonSchema,
+            ...invalidExport,
+        ];
+    }));
+    loaded.contract.commands.forEach((command, index) => {
+        if (surface.packageManifestValid &&
+            !binaries.has(command.binary)) {
+            diagnostics.push({
+                severity: 'error',
+                code: 'YMC203',
+                message: `Package binary "${command.binary}" is not declared`,
+                ...locateSourcePath(source.path, yaml, lineCounter, ['commands', index, 'binary'], `/commands/${index}/binary`),
+            });
+        }
+    });
+    return diagnostics.length === 0
+        ? loaded
+        : { ok: false, diagnostics: diagnostics.sort(diagnosticOrder) };
+}

package/dist/evidence.d.ts

@@ -0,0 +1,58 @@
+import type { Diagnostic, SemanticGraph, WorkspaceSource } from './compiler.js';
+export type EvidenceResult = 'confirmed' | 'contradicted' | 'unknown' | 'not-observed';
+export interface EvidenceLocator {
+    readonly uri: string;
+    readonly message?: string;
+}
+export type EvidenceObservation = {
+    readonly subject: string;
+    readonly result: EvidenceResult;
+    readonly evidence: EvidenceLocator;
+} | {
+    readonly claim: string;
+    readonly result: EvidenceResult;
+    readonly evidence: EvidenceLocator;
+};
+export interface EvidenceDocument {
+    readonly format: 'yarramate/evidence/v1';
+    readonly id: string;
+    readonly version: string;
+    readonly provider: string;
+    readonly observations: readonly EvidenceObservation[];
+}
+export interface EvidenceReport {
+    readonly format: 'yarramate/evidence-report/v1';
+    readonly evidence: string;
+    readonly provider: string;
+    readonly summary: {
+        readonly confirmed: number;
+        readonly contradicted: number;
+        readonly unknown: number;
+        readonly notObserved: number;
+    };
+    readonly observations: readonly EvidenceObservation[];
+}
+export type EvidenceLoadResult = {
+    readonly ok: true;
+    readonly evidence: EvidenceDocument;
+} | {
+    readonly ok: false;
+    readonly diagnostics: readonly Diagnostic[];
+};
+export type EvidenceEvaluationResult = {
+    readonly ok: true;
+    readonly report: EvidenceReport;
+} | {
+    readonly ok: false;
+    readonly diagnostics: readonly Diagnostic[];
+};
+export type EvidenceWorkspaceEvaluationResult = {
+    readonly ok: true;
+    readonly reports: readonly EvidenceReport[];
+} | {
+    readonly ok: false;
+    readonly diagnostics: readonly Diagnostic[];
+};
+export declare function loadEvidence(source: WorkspaceSource): EvidenceLoadResult;
+export declare function evaluateEvidence(graph: SemanticGraph, evidence: EvidenceDocument): EvidenceEvaluationResult;
+export declare function evaluateEvidenceWorkspace(graph: SemanticGraph, evidenceDocuments: readonly EvidenceDocument[]): EvidenceWorkspaceEvaluationResult;

package/dist/evidence.js

@@ -0,0 +1,161 @@
+import Ajv2020Module from 'ajv/dist/2020.js';
+import { diagnosticOrder, loadSourceDocument, locateSourcePath, } from './source-document.js';
+import evidenceSchema from '../schema/yarramate-evidence.schema.json' with {
+    type: 'json'
+};
+const Ajv2020 = Ajv2020Module.default;
+const validateEvidenceSchema = new Ajv2020({ allErrors: true }).compile(evidenceSchema);
+const evidenceLocations = new WeakMap();
+const observationTarget = (observation) => 'subject' in observation ? observation.subject : observation.claim;
+export function loadEvidence(source) {
+    const loaded = loadSourceDocument(source, validateEvidenceSchema, 'Evidence');
+    if (!loaded.ok)
+        return loaded;
+    const { value, yaml, lineCounter } = loaded.document;
+    const orderedObservations = value.observations
+        .map((observation, authoredIndex) => ({
+        authoredIndex,
+        observation: {
+            ...('subject' in observation
+                ? { subject: observation.subject }
+                : { claim: observation.claim }),
+            result: observation.result,
+            evidence: {
+                uri: observation.evidence.uri,
+                ...(observation.evidence.message === undefined
+                    ? {}
+                    : { message: observation.evidence.message }),
+            },
+        },
+    }))
+        .sort((left, right) => observationTarget(left.observation).localeCompare(observationTarget(right.observation)));
+    const evidence = {
+        format: value.format,
+        id: value.id,
+        version: value.version,
+        provider: value.provider,
+        observations: orderedObservations.map(({ observation }) => observation),
+    };
+    evidenceLocations.set(evidence, {
+        id: locateSourcePath(source.path, yaml, lineCounter, ['id'], '/id'),
+        observations: orderedObservations.map(({ observation, authoredIndex }) => {
+            const field = 'subject' in observation ? 'subject' : 'claim';
+            return locateSourcePath(source.path, yaml, lineCounter, ['observations', authoredIndex, field], `/observations/${authoredIndex}/${field}`);
+        }),
+    });
+    return { ok: true, evidence };
+}
+export function evaluateEvidence(graph, evidence) {
+    const subjectIds = new Set(graph.subjects.map(({ id }) => id));
+    const claimIds = new Set(graph.claims.map(({ id }) => id));
+    const locations = evidenceLocations.get(evidence)?.observations ?? [];
+    const diagnostics = [];
+    const seenTargets = new Set();
+    for (const [index, observation] of evidence.observations.entries()) {
+        const location = locations[index] ?? {
+            path: `${evidence.id}.evidence.yaml`,
+            pointer: `/observations/${index}/${'subject' in observation ? 'subject' : 'claim'}`,
+            line: 1,
+            column: 1,
+        };
+        if ('subject' in observation &&
+            !subjectIds.has(observation.subject)) {
+            diagnostics.push({
+                severity: 'error',
+                code: 'YM801',
+                message: `Evidence subject "${observation.subject}" does not exist`,
+                ...location,
+            });
+        }
+        if ('claim' in observation && !claimIds.has(observation.claim)) {
+            diagnostics.push({
+                severity: 'error',
+                code: 'YM802',
+                message: `Evidence claim "${observation.claim}" does not exist`,
+                ...location,
+            });
+        }
+        const target = observationTarget(observation);
+        const targetKey = `${'subject' in observation ? 'subject' : 'claim'}:${target}`;
+        if (seenTargets.has(targetKey)) {
+            diagnostics.push({
+                severity: 'error',
+                code: 'YM803',
+                message: `Evidence target "${target}" is evaluated more than once`,
+                ...location,
+            });
+        }
+        seenTargets.add(targetKey);
+    }
+    if (diagnostics.length > 0) {
+        return {
+            ok: false,
+            diagnostics: diagnostics.sort(diagnosticOrder),
+        };
+    }
+    const summary = {
+        confirmed: 0,
+        contradicted: 0,
+        unknown: 0,
+        notObserved: 0,
+    };
+    for (const observation of evidence.observations) {
+        if (observation.result === 'not-observed') {
+            summary.notObserved += 1;
+        }
+        else {
+            summary[observation.result] += 1;
+        }
+    }
+    return {
+        ok: true,
+        report: {
+            format: 'yarramate/evidence-report/v1',
+            evidence: `${evidence.id}@${evidence.version}`,
+            provider: evidence.provider,
+            summary,
+            observations: evidence.observations,
+        },
+    };
+}
+export function evaluateEvidenceWorkspace(graph, evidenceDocuments) {
+    const ordered = [...evidenceDocuments].sort((left, right) => {
+        const identityOrder = `${left.id}@${left.version}`.localeCompare(`${right.id}@${right.version}`);
+        if (identityOrder !== 0)
+            return identityOrder;
+        const leftPath = evidenceLocations.get(left)?.id.path ?? '';
+        const rightPath = evidenceLocations.get(right)?.id.path ?? '';
+        return leftPath.localeCompare(rightPath);
+    });
+    const diagnostics = [];
+    const reports = [];
+    const seenIdentities = new Set();
+    for (const evidence of ordered) {
+        const identity = `${evidence.id}@${evidence.version}`;
+        if (seenIdentities.has(identity)) {
+            const location = evidenceLocations.get(evidence)?.id ?? {
+                path: `${evidence.id}.evidence.yaml`,
+                pointer: '/id',
+                line: 1,
+                column: 1,
+            };
+            diagnostics.push({
+                severity: 'error',
+                code: 'YM804',
+                message: `Evidence document "${identity}" is declared more than once`,
+                ...location,
+            });
+        }
+        seenIdentities.add(identity);
+        const evaluation = evaluateEvidence(graph, evidence);
+        if (evaluation.ok) {
+            reports.push(evaluation.report);
+        }
+        else {
+            diagnostics.push(...evaluation.diagnostics);
+        }
+    }
+    return diagnostics.length === 0
+        ? { ok: true, reports }
+        : { ok: false, diagnostics: diagnostics.sort(diagnosticOrder) };
+}

package/dist/graph.d.ts

@@ -0,0 +1,2 @@
+import type { SemanticGraph } from './compiler.js';
+export declare function serializeSemanticGraph(graph: SemanticGraph): string;

package/dist/graph.js

@@ -0,0 +1,37 @@
+const compareText = (left, right) => left.localeCompare(right);
+const canonicalClaim = (claim) => ({
+    id: claim.id,
+    subject: claim.subject,
+    predicate: claim.predicate,
+    object: 'ref' in claim.object
+        ? { ref: claim.object.ref }
+        : { value: claim.object.value },
+    origin: claim.origin,
+    source: {
+        document: claim.source.document,
+        path: claim.source.path,
+        pointer: claim.source.pointer,
+        line: claim.source.line,
+        column: claim.source.column,
+    },
+});
+export function serializeSemanticGraph(graph) {
+    const canonical = {
+        format: 'yarramate/graph/v2',
+        profiles: [...graph.profiles].sort(compareText),
+        documents: [...graph.documents]
+            .sort((left, right) => compareText(left.id, right.id) ||
+            compareText(left.source, right.source))
+            .map(({ id, source }) => ({ id, source })),
+        subjects: [...graph.subjects]
+            .sort((left, right) => compareText(left.id, right.id) ||
+            compareText(left.type, right.type))
+            .map(({ id, type }) => ({ id, type })),
+        claims: [...graph.claims]
+            .sort((left, right) => compareText(left.id, right.id) ||
+            compareText(left.subject, right.subject) ||
+            compareText(left.predicate, right.predicate))
+            .map(canonicalClaim),
+    };
+    return `${JSON.stringify(canonical, null, 2)}\n`;
+}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export { compileWorkspace, compileWorkspaceWithProfileContext, } from './compiler.js';
+export { serializeSemanticGraph } from './graph.js';
+export { checkCoreContract, loadCoreContract, type CoreContract, type CoreContractCommand, type CoreContractFormat, type CoreContractLoadResult, type CoreContractSurface, } from './core-contract.js';
+export { compareArchitectureStates, type StateComparison, type StateComparisonIssue, type StateComparisonResult, } from './architecture-state.js';
+export { loadWorkspaceManifest, type ResolvedWorkspace, type WorkspaceManifest, type WorkspaceManifestResult, } from './workspace.js';
+export { evaluateEvidence, evaluateEvidenceWorkspace, loadEvidence, type EvidenceDocument, type EvidenceEvaluationResult, type EvidenceLoadResult, type EvidenceLocator, type EvidenceObservation, type EvidenceReport, type EvidenceResult, type EvidenceWorkspaceEvaluationResult, } from './evidence.js';
+export { reconcileEvidenceReports, type ReconciliationFinding, type ReconciliationReport, } from './reconciliation.js';
+export type { CompilationResult, ContextualCompilationResult, Diagnostic, GraphClaim, GraphSource, SemanticGraph, ResolvedProfileContext, WorkspaceSource, } from './compiler.js';
+export { evaluateProjection, loadProjection, renderProjectionMarkdown, } from './projection.js';
+export { loadAdapterMapping, validateAdapterMapping, validateAdapterMappings, type AdapterMapping, type AdapterMappingLoadResult, type AdapterMappingValidationResult, type AdapterMappingsValidationResult, type AdapterSubjectMapping, } from './adapter-mapping.js';
+export type { LifecycleStatus, ProjectionDefinition, ProjectionLoadResult, ProjectionResult, } from './projection.js';

package/dist/index.js

@@ -0,0 +1,9 @@
+export { compileWorkspace, compileWorkspaceWithProfileContext, } from './compiler.js';
+export { serializeSemanticGraph } from './graph.js';
+export { checkCoreContract, loadCoreContract, } from './core-contract.js';
+export { compareArchitectureStates, } from './architecture-state.js';
+export { loadWorkspaceManifest, } from './workspace.js';
+export { evaluateEvidence, evaluateEvidenceWorkspace, loadEvidence, } from './evidence.js';
+export { reconcileEvidenceReports, } from './reconciliation.js';
+export { evaluateProjection, loadProjection, renderProjectionMarkdown, } from './projection.js';
+export { loadAdapterMapping, validateAdapterMapping, validateAdapterMappings, } from './adapter-mapping.js';

package/dist/profile.d.ts

@@ -0,0 +1,30 @@
+export declare const layers: readonly ["motivation", "strategy", "business", "application", "technology", "physical", "implementation", "composite"];
+export declare const aspects: readonly ["motivation", "active-structure", "behavior", "passive-structure", "composite"];
+export type Layer = (typeof layers)[number];
+export type Aspect = (typeof aspects)[number];
+export interface ConceptKind {
+    readonly id: string;
+    readonly name: string;
+    readonly layer: Layer;
+    readonly aspect: Aspect;
+    /**
+     * A compatibility pointer, not a claim of standards conformance.
+     * Exact external identifiers can be added after licensing review.
+     */
+    readonly inspiredBy: string;
+}
+export declare const conceptKinds: readonly ConceptKind[];
+export declare const relationshipKinds: readonly ["composition", "aggregation", "assignment", "realization", "serving", "access", "influence", "association", "triggering", "flow", "specialization"];
+export type RelationshipKind = (typeof relationshipKinds)[number];
+export interface RelationshipPolicy {
+    readonly id: RelationshipKind;
+    readonly intent: string;
+    readonly sourceAspects?: readonly Aspect[];
+    readonly targetAspects?: readonly Aspect[];
+}
+/**
+ * Safe, intentionally broad semantic constraints. A future licensed
+ * compatibility package may layer an exact external relationship matrix over
+ * these native YarraMate rules.
+ */
+export declare const relationshipPolicies: readonly RelationshipPolicy[];