yarramate 0.6.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/cli-support.d.ts

@@ -7,7 +7,7 @@ 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] [--strict]\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 next <projection.yaml> <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;

package/dist/cli-support.js

@@ -23,7 +23,7 @@ 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] [--strict]\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 next <projection.yaml> <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,