yarramate 0.5.0 → 0.7.0

package/dist/brief.d.ts

@@ -0,0 +1,3 @@
+import type { ResolvedProfileContext } from './compiler.js';
+import type { ProjectionResult } from './projection.js';
+export declare function renderBrief(result: ProjectionResult, profileContext?: ResolvedProfileContext, budgetTokens?: number): string;

package/dist/brief.js

@@ -0,0 +1,235 @@
+import { conceptKinds } from './profile.js';
+const coreKindNames = new Map(conceptKinds.map(({ id, name }) => [id, name]));
+const motivationKindIds = new Set(conceptKinds
+    .filter(({ layer }) => layer === 'motivation')
+    .map(({ id }) => id));
+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 claimReferences = (claims, subject, predicate) => claims.flatMap((claim) => claim.subject === subject &&
+    claim.predicate === predicate &&
+    'ref' in claim.object
+    ? [claim.object.ref]
+    : []);
+// Resolve a qualified kind to its nearest core-profile local id through
+// declared lineage, mirroring how `next` orients relationships (ADR 0048).
+const coreLocalKind = (kind, lineages) => {
+    for (const candidate of [kind, ...(lineages?.get(kind) ?? [])]) {
+        const separator = candidate.indexOf('#');
+        if (separator !== -1 && candidate.startsWith('yarramate/core@')) {
+            return candidate.slice(separator + 1);
+        }
+    }
+    return undefined;
+};
+const humanizeKind = (kind) => {
+    const local = kind.slice(kind.indexOf('#') + 1);
+    return local
+        .replaceAll(/([a-z0-9])([A-Z])/g, '$1 $2')
+        .replaceAll('-', ' ')
+        .toLowerCase();
+};
+const article = (reading) => /^[aeiou]/.test(reading) ? 'an' : 'a';
+const sentenceEnd = (text) => /[.!?]["')\]]*$/.test(text.trimEnd()) ? text.trimEnd() : `${text.trimEnd()}.`;
+const listPhrase = (items) => items.length <= 1
+    ? (items[0] ?? '')
+    : `${items.slice(0, -1).join(', ')} and ${items[items.length - 1]}`;
+// Phrase forms are the prose readings of each core relationship kind's
+// declared intent — the same table `next` reads for ordering, spoken
+// from the source's perspective.
+const relationshipPhrase = (coreKind, fallbackKind, mode, content) => {
+    switch (coreKind) {
+        case 'serving':
+            return 'serves';
+        case 'access':
+            return mode === 'read'
+                ? 'reads'
+                : mode === 'write'
+                    ? 'writes'
+                    : mode === 'read-write'
+                        ? 'reads and writes'
+                        : 'accesses';
+        case 'realization':
+            return 'realizes';
+        case 'composition':
+            return 'comprises';
+        case 'aggregation':
+            return 'aggregates';
+        case 'assignment':
+            return 'is assigned to';
+        case 'triggering':
+            return 'triggers';
+        case 'flow':
+            return content === undefined ? 'flows to' : `sends ${content} to`;
+        case 'specialization':
+            return 'specializes';
+        case 'influence':
+            return 'influences';
+        case 'association':
+            return 'is associated with';
+        default:
+            return humanizeKind(fallbackKind);
+    }
+};
+const estimateTokens = (text) => Math.ceil(text.length / 4);
+export function renderBrief(result, profileContext, budgetTokens) {
+    const stateIds = new Set(result.claims
+        .filter(({ predicate }) => predicate === 'yarramate/state/type')
+        .map(({ subject }) => subject));
+    const concepts = result.subjects.filter(({ id, type }) => type === 'concept' && !stateIds.has(id));
+    const nameOf = (id) => claimValue(result.claims, id, 'yarramate/concept/name') ?? id;
+    const kindOf = (id) => claimValue(result.claims, id, 'yarramate/concept/kind');
+    const statusOf = (id) => claimValue(result.claims, id, 'yarramate/lifecycle/status');
+    const descriptionOf = (id) => claimValue(result.claims, id, 'yarramate/concept/description');
+    const kindReading = (kind) => {
+        const core = coreLocalKind(kind, profileContext?.conceptKindLineages);
+        const coreName = core === undefined ? undefined : coreKindNames.get(core);
+        return kind.startsWith('yarramate/core@') && coreName !== undefined
+            ? coreName.toLowerCase()
+            : humanizeKind(kind);
+    };
+    const isMotivation = (id) => {
+        const kind = kindOf(id);
+        if (kind === undefined)
+            return false;
+        const core = coreLocalKind(kind, profileContext?.conceptKindLineages);
+        return core !== undefined && motivationKindIds.has(core);
+    };
+    const outgoing = new Map();
+    for (const subject of result.subjects) {
+        if (subject.type !== 'relationship')
+            continue;
+        const claim = result.claims.find(({ id, object }) => id === subject.id && 'ref' in object);
+        if (claim === undefined || !('ref' in claim.object))
+            continue;
+        const description = claimValue(result.claims, subject.id, 'yarramate/relationship/description');
+        const entry = {
+            phrase: relationshipPhrase(coreLocalKind(claim.predicate, profileContext?.relationshipKindLineages), claim.predicate, claimValue(result.claims, subject.id, 'yarramate/access/mode'), claimValue(result.claims, subject.id, 'yarramate/flow/content')),
+            target: claim.object.ref,
+            ...(description === undefined ? {} : { description }),
+        };
+        outgoing.set(claim.subject, [
+            ...(outgoing.get(claim.subject) ?? []),
+            entry,
+        ]);
+    }
+    const relationshipSentences = (id) => {
+        const entries = outgoing.get(id) ?? [];
+        const grouped = new Map();
+        const sentences = [];
+        for (const entry of entries) {
+            const target = `"${nameOf(entry.target)}"`;
+            if (entry.description !== undefined) {
+                sentences.push(`It ${entry.phrase} ${target} (${entry.description}).`);
+                continue;
+            }
+            grouped.set(entry.phrase, [...(grouped.get(entry.phrase) ?? []), target]);
+        }
+        return [
+            ...[...grouped].map(([phrase, targets]) => `It ${phrase} ${listPhrase(targets)}.`),
+            ...sentences,
+        ];
+    };
+    const supportSentences = (id) => {
+        const sentences = [];
+        const constraints = claimReferences(result.claims, id, 'yarramate/constraint/requires');
+        if (constraints.length > 0) {
+            sentences.push(`Constrained by ${listPhrase(constraints.map((constraint) => `"${nameOf(constraint)}"`))}.`);
+        }
+        const owner = claimReferences(result.claims, id, 'yarramate/ownership/owner')[0];
+        if (owner !== undefined) {
+            sentences.push(`Owned by "${nameOf(owner)}".`);
+        }
+        return sentences;
+    };
+    const motivationParagraph = (id) => {
+        const kind = kindOf(id) ?? '';
+        const reading = kindReading(kind);
+        const label = reading.charAt(0).toUpperCase() + reading.slice(1);
+        const description = descriptionOf(id);
+        const opening = description === undefined
+            ? `${label} "${nameOf(id)}".`
+            : `${label} "${nameOf(id)}": "${description}"`;
+        return [sentenceEnd(opening), ...relationshipSentences(id), ...supportSentences(id)].join(' ');
+    };
+    const workParagraph = (id) => {
+        const kind = kindOf(id) ?? '';
+        const reading = kindReading(kind);
+        const status = statusOf(id);
+        const name = `"${nameOf(id)}"`;
+        const opening = status === 'planned'
+            ? `You are building ${name}, ${article(reading)} ${reading}.`
+            : status === 'current'
+                ? `${name}, ${article(reading)} ${reading}, already exists.`
+                : status === 'retired'
+                    ? `${name}, ${article(reading)} ${reading}, is retired.`
+                    : `${name} is ${article(reading)} ${reading}.`;
+        const description = descriptionOf(id);
+        return [
+            opening,
+            ...(description === undefined ? [] : [sentenceEnd(description)]),
+            ...relationshipSentences(id),
+            ...supportSentences(id),
+        ].join(' ');
+    };
+    // Motivation opens the brief (the interview's waves lead with why), the
+    // planned work follows (it is what the reader came to do), and existing
+    // context comes after; the same order ranks paragraphs under a budget.
+    const statusRank = (id) => {
+        const status = statusOf(id);
+        return status === 'planned' ? 1 : status === 'retired' ? 3 : 2;
+    };
+    const motivation = concepts.filter(({ id }) => isMotivation(id));
+    const work = concepts.filter(({ id }) => !isMotivation(id));
+    const paragraphs = [
+        {
+            heading: '## Why this exists',
+            entries: motivation.map(({ id }) => ({
+                text: motivationParagraph(id),
+                rank: 0,
+            })),
+        },
+        {
+            heading: '## The pieces',
+            entries: work
+                .map(({ id }) => ({ text: workParagraph(id), rank: statusRank(id) }))
+                .sort((a, b) => a.rank - b.rank),
+        },
+    ];
+    const title = result.presentation?.title ?? result.projection;
+    const header = [`# ${title}`];
+    if (result.presentation?.description !== undefined) {
+        header.push('', result.presentation.description);
+    }
+    const budget = budgetTokens ?? Number.POSITIVE_INFINITY;
+    let spent = estimateTokens(header.join('\n'));
+    let omitted = 0;
+    let total = 0;
+    const sections = [];
+    for (const section of paragraphs) {
+        total += section.entries.length;
+        if (section.entries.length === 0)
+            continue;
+        const kept = [];
+        let sectionSpent = estimateTokens(section.heading);
+        for (const entry of section.entries) {
+            const cost = estimateTokens(entry.text);
+            if (spent + sectionSpent + cost > budget) {
+                omitted += 1;
+                continue;
+            }
+            kept.push(entry.text);
+            sectionSpent += cost;
+        }
+        if (kept.length > 0) {
+            sections.push('', section.heading, '', kept.join('\n\n'));
+            spent += sectionSpent;
+        }
+    }
+    const lines = [...header, ...sections];
+    if (omitted > 0) {
+        lines.push('', `[budget ${budgetTokens}: ${omitted} of ${total} paragraphs omitted — raise --budget or use --json for the complete slice]`);
+    }
+    return `${lines.join('\n')}\n`;
+}

package/dist/check-command.js

@@ -8,10 +8,23 @@ import { compileWorkspace } from './compiler.js';
 import { checkCoreContract, loadCoreContract, } from './core-contract.js';
 import { evaluateEvidenceWorkspace, loadEvidence, } from './evidence.js';
 import { loadProjection } from './projection.js';
+import { reconcileEvidenceReports, } from './reconciliation.js';
 const Ajv2020 = Ajv2020Module.default;
+const strictFindingMessage = (finding) => {
+    const observed = finding.evidence.message === undefined
+        ? finding.evidence.uri
+        : `${finding.evidence.uri}: ${finding.evidence.message}`;
+    const assertion = finding.asserted === undefined
+        ? `Evidence contradicts ${finding.target.type} "${finding.target.id}"`
+        : `Evidence contradicts claim "${finding.target.id}": the model asserts ` +
+            `${finding.asserted.from} -> ${finding.asserted.to} (${finding.asserted.kind})`;
+    return (`${assertion}, but provider "${finding.provider}" observed otherwise ` +
+        `(${observed}); align the model or the evidence to pass --strict`);
+};
 export function runCheckCommand(options, cwd) {
     const json = options.includes('--json');
-    const paths = options.filter((option) => option !== '--json');
+    const strict = options.includes('--strict');
+    const paths = options.filter((option) => option !== '--json' && option !== '--strict');
     const unknownOption = paths.find((path) => path.startsWith('-'));
     if (unknownOption !== undefined || paths.length === 0) {
         return { exitCode: 2, stdout: '', stderr: usage };
@@ -171,6 +184,46 @@ export function runCheckCommand(options, cwd) {
         const diagnostics = result.ok
             ? optionalDiagnostics
             : result.diagnostics;
+        // Strict only tightens a passing check: base diagnostics already fail
+        // the gate, so contradictions are folded in only once everything else
+        // holds, and each one is anchored at the claim the model declares.
+        const strictEvaluation = strict && result.ok && ok
+            ? (() => {
+                const reports = evidenceEvaluation !== undefined && evidenceEvaluation.ok
+                    ? evidenceEvaluation.reports
+                    : [];
+                const graph = result.graph;
+                const contradicted = reconcileEvidenceReports('strict', reports, graph).findings.filter(({ result: outcome }) => outcome === 'contradicted');
+                return {
+                    observations: reports.reduce((total, report) => total + report.observations.length, 0),
+                    diagnostics: sortDiagnostics(contradicted.map((finding) => {
+                        const anchor = graph.claims.find(({ id }) => id === finding.target.id) ??
+                            graph.claims.find(({ subject, predicate }) => subject === finding.target.id &&
+                                predicate === 'yarramate/concept/kind') ??
+                            graph.claims.find(({ subject }) => subject === finding.target.id);
+                        return {
+                            severity: 'error',
+                            code: 'YM901',
+                            message: strictFindingMessage(finding),
+                            path: anchor?.source.path ?? finding.evidenceDocument,
+                            pointer: anchor?.source.pointer ?? '/',
+                            line: anchor?.source.line ?? 1,
+                            column: anchor?.source.column ?? 1,
+                        };
+                    })),
+                };
+            })()
+            : undefined;
+        const strictSummary = strictEvaluation === undefined
+            ? undefined
+            : {
+                observations: strictEvaluation.observations,
+                contradicted: strictEvaluation.diagnostics.length,
+            };
+        const strictOk = strictEvaluation === undefined
+            ? true
+            : strictEvaluation.diagnostics.length === 0;
+        const finalOk = ok && strictOk;
         const counted = result.ok
             ? (() => {
                 const states = new Set(result.graph.claims
@@ -186,8 +239,15 @@ export function runCheckCommand(options, cwd) {
             : undefined;
         if (json) {
             return {
-                exitCode: ok ? 0 : 1,
-                stdout: checkResultJson(ok, ok ? [] : diagnostics, ok ? counted : undefined),
+                exitCode: finalOk ? 0 : 1,
+                stdout: checkResultJson(finalOk, finalOk ? [] : ok ? strictEvaluation.diagnostics : diagnostics, finalOk ? counted : undefined, strictSummary),
+                stderr: '',
+            };
+        }
+        if (ok && !strictOk) {
+            return {
+                exitCode: 1,
+                stdout: humanDiagnostics(strictEvaluation.diagnostics),
                 stderr: '',
             };
         }
@@ -227,13 +287,19 @@ export function runCheckCommand(options, cwd) {
                     ]
                     : []),
             ].join(' and ');
+            const strictLine = strictSummary === undefined
+                ? ''
+                : strictSummary.observations === 0
+                    ? 'Strict: no evidence observations to evaluate\n'
+                    : `Strict: ${strictSummary.observations} ${strictSummary.observations === 1 ? 'observation' : 'observations'}, 0 contradicted\n`;
             return {
                 exitCode: 0,
                 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',
+                    '): no errors\n' +
+                    strictLine,
                 stderr: '',
             };
         }

package/dist/cli-support.d.ts

@@ -7,13 +7,16 @@ export interface CliResult {
 export declare const isMainModule: (moduleUrl: string, entrypoint: string | undefined) => boolean;
 export declare const packageVersion: string;
 export declare const versionResult: (binary: string) => CliResult;
-export declare const usage = "Usage:\n  yarramate init <directory> [--no-pointer]\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 new projection <projection.yaml> --id <id> [--version <v>] [--title <text>] [--description <text>] [--document <id> ...] [--subject <ref> ...] [--kind <qualified-kind> ...] [--relationships <mode>]\n  yarramate status <workspace.yaml> [--json]\n  yarramate compile <source.yaml> [source.yaml ...]\n  yarramate context <projection.yaml> <source.yaml> [source.yaml ...] [--budget <tokens>]\n  yarramate context --subject <document-id>#<local-id> [--subject ...] <source.yaml> [source.yaml ...] [--budget <tokens>]\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> [--no-pointer]\n  yarramate design <workspace.yaml> [--subject <document-id>#<local-id>] [--catalogue <catalogue.yaml>] [--json]\n  yarramate apply <operations.yaml> <workspace.yaml> [--json]\n  yarramate ask <workspace.yaml> [--json]\n  yarramate ask <workspace.yaml> \"<free text>\" | <document-id>#<local-id> ... | <projection.yaml> [--budget <tokens>] [--json]\n  yarramate ask <workspace.yaml> --subjects [--kind <term>] [--status <status>] [--json]\n  yarramate ask <workspace.yaml> --kinds [--json]\n  yarramate ask <workspace.yaml> --advise \"<topic>\" [--budget <tokens>] [--catalogue <catalogue.yaml>] [--json]\n  yarramate ask <workspace.yaml> --next [--json]\n  yarramate ask <workspace.yaml> --open [--catalogue <catalogue.yaml>] [--json]\n  yarramate ask <workspace.yaml> --compare <from-state> <to-state> [--json]\n  yarramate check <source.yaml> [source.yaml ...] [--json] [--strict]\n  yarramate reconcile <workspace.yaml>\n  yarramate export graph <workspace.yaml> [--out <file>]\n  yarramate export markdown <projection.yaml> <workspace.yaml> [--out <file>]\n  yarramate export briefs <projection.yaml> <workspace.yaml> --out <directory> [--budget <tokens>]\n  yarramate export likec4 <likec4-project.yaml> <output-dir> <workspace.yaml>\n";
 export declare const diagnosticJson: (diagnostics: unknown) => string;
 export declare const checkResultJson: (ok: boolean, diagnostics: unknown, counted?: {
     readonly documents: number;
     readonly concepts: number;
     readonly relationships: number;
     readonly states: number;
+}, strict?: {
+    readonly observations: number;
+    readonly contradicted: 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[];

package/dist/cli-support.js

@@ -23,16 +23,17 @@ export const versionResult = (binary) => ({
     stdout: `${binary} ${packageVersion}\n`,
     stderr: '',
 });
-export const usage = 'Usage:\n  yarramate init <directory> [--no-pointer]\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 new projection <projection.yaml> --id <id> [--version <v>] [--title <text>] [--description <text>] [--document <id> ...] [--subject <ref> ...] [--kind <qualified-kind> ...] [--relationships <mode>]\n  yarramate status <workspace.yaml> [--json]\n  yarramate compile <source.yaml> [source.yaml ...]\n  yarramate context <projection.yaml> <source.yaml> [source.yaml ...] [--budget <tokens>]\n  yarramate context --subject <document-id>#<local-id> [--subject ...] <source.yaml> [source.yaml ...] [--budget <tokens>]\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> [--no-pointer]\n  yarramate design <workspace.yaml> [--subject <document-id>#<local-id>] [--catalogue <catalogue.yaml>] [--json]\n  yarramate apply <operations.yaml> <workspace.yaml> [--json]\n  yarramate ask <workspace.yaml> [--json]\n  yarramate ask <workspace.yaml> "<free text>" | <document-id>#<local-id> ... | <projection.yaml> [--budget <tokens>] [--json]\n  yarramate ask <workspace.yaml> --subjects [--kind <term>] [--status <status>] [--json]\n  yarramate ask <workspace.yaml> --kinds [--json]\n  yarramate ask <workspace.yaml> --advise "<topic>" [--budget <tokens>] [--catalogue <catalogue.yaml>] [--json]\n  yarramate ask <workspace.yaml> --next [--json]\n  yarramate ask <workspace.yaml> --open [--catalogue <catalogue.yaml>] [--json]\n  yarramate ask <workspace.yaml> --compare <from-state> <to-state> [--json]\n  yarramate check <source.yaml> [source.yaml ...] [--json] [--strict]\n  yarramate reconcile <workspace.yaml>\n  yarramate export graph <workspace.yaml> [--out <file>]\n  yarramate export markdown <projection.yaml> <workspace.yaml> [--out <file>]\n  yarramate export briefs <projection.yaml> <workspace.yaml> --out <directory> [--budget <tokens>]\n  yarramate export likec4 <likec4-project.yaml> <output-dir> <workspace.yaml>\n';
 export const diagnosticJson = (diagnostics) => `${JSON.stringify({
     format: 'yarramate/diagnostic-result/v1',
     diagnostics,
 }, null, 2)}\n`;
-export const checkResultJson = (ok, diagnostics, counted) => `${JSON.stringify({
+export const checkResultJson = (ok, diagnostics, counted, strict) => `${JSON.stringify({
     format: 'yarramate/check-result/v1',
     ok,
     diagnostics,
     ...(counted === undefined ? {} : { counted }),
+    ...(strict === undefined ? {} : { strict }),
 }, null, 2)}\n`;
 export const humanDiagnostics = (diagnostics) => diagnostics
     .map((diagnostic) => `${diagnostic.path}:${diagnostic.line}:${diagnostic.column} error ${diagnostic.code} ${diagnostic.message}\n`)