yarramate 0.6.0 → 0.7.0

package/dist/design-command.js

@@ -0,0 +1,218 @@
+import { readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseDocument } from 'yaml';
+import { diagnosticJson, humanDiagnostics, usage, } from './cli-support.js';
+import { compileWorkspaceWithProfileContext, } from './compiler.js';
+import { evaluateCatalogue, loadQuestionCatalogue, } from './interrogate-command.js';
+import { evaluateProjection } from './projection.js';
+import { renderBrief } from './brief.js';
+import { loadWorkspaceManifest } from './workspace.js';
+// The catalogue is internal to design: it ships inside the package,
+// versioned with it, and harnesses never pass catalogue paths. The
+// relative hop works from both src/ (dev) and dist/ (shipped).
+const here = dirname(fileURLToPath(import.meta.url));
+const shippedCataloguePath = join(here, '..', 'catalogues', 'core-enrichment.yaml');
+// The top step is the first open question in wave order, then catalogue
+// order within the wave; a subject-scoped question serves its first open
+// subject and reports how many more share it. One question at a time is
+// the discipline; everything else is a read (ask --open).
+const selectStep = (report, subjectFilter) => {
+    for (const wave of report.waves) {
+        for (const question of wave.questions) {
+            if (!question.open)
+                continue;
+            if (question.subjects === undefined) {
+                if (subjectFilter !== undefined)
+                    continue;
+                return {
+                    questionId: question.id,
+                    wave: wave.id,
+                    scope: 'workspace',
+                    authority: question.authority,
+                    question: question.question,
+                    materiality: question.materiality,
+                    resolution: question.resolution,
+                };
+            }
+            const subjects = subjectFilter === undefined
+                ? question.subjects
+                : question.subjects.filter(({ id }) => id === subjectFilter);
+            const first = subjects[0];
+            if (first === undefined)
+                continue;
+            return {
+                questionId: question.id,
+                wave: wave.id,
+                scope: 'subject',
+                authority: question.authority,
+                question: first.question,
+                materiality: question.materiality,
+                resolution: question.resolution,
+                subject: {
+                    id: first.id,
+                    ...(first.name === undefined ? {} : { name: first.name }),
+                },
+                ...(subjects.length > 1
+                    ? { remainingSubjects: subjects.length - 1 }
+                    : {}),
+            };
+        }
+    }
+    return null;
+};
+export function runDesignCommand(options, cwd) {
+    const json = options.includes('--json');
+    let subjectFilter;
+    let cataloguePath;
+    const rest = [];
+    const withoutJson = options.filter((option) => option !== '--json');
+    for (let index = 0; index < withoutJson.length; index += 1) {
+        const option = withoutJson[index];
+        if (option === '--subject' || option === '--catalogue') {
+            const value = withoutJson[index + 1];
+            if (value === undefined || value.startsWith('-')) {
+                return { exitCode: 2, stdout: '', stderr: usage };
+            }
+            if (option === '--subject') {
+                if (subjectFilter !== undefined) {
+                    return { exitCode: 2, stdout: '', stderr: usage };
+                }
+                subjectFilter = value;
+            }
+            else {
+                if (cataloguePath !== undefined) {
+                    return { exitCode: 2, stdout: '', stderr: usage };
+                }
+                cataloguePath = value;
+            }
+            index += 1;
+            continue;
+        }
+        if (option === undefined || option.startsWith('-')) {
+            return { exitCode: 2, stdout: '', stderr: usage };
+        }
+        rest.push(option);
+    }
+    const [workspacePath] = rest;
+    if (rest.length !== 1 || workspacePath === undefined) {
+        return { exitCode: 2, stdout: '', stderr: usage };
+    }
+    try {
+        const manifestSource = readFileSync(resolve(cwd, workspacePath), 'utf8');
+        if (parseDocument(manifestSource).get('format') !== 'yarramate/workspace/v1') {
+            return {
+                exitCode: 2,
+                stdout: '',
+                stderr: 'design requires an explicit workspace manifest (yarramate/workspace/v1)\n',
+            };
+        }
+        const failed = (diagnostics) => ({
+            exitCode: 1,
+            stdout: json
+                ? diagnosticJson(diagnostics)
+                : humanDiagnostics(diagnostics),
+            stderr: '',
+        });
+        const loadedWorkspace = loadWorkspaceManifest({ path: workspacePath, source: manifestSource }, cwd);
+        if (!loadedWorkspace.ok)
+            return failed(loadedWorkspace.diagnostics);
+        const workspace = loadedWorkspace.workspace;
+        const resolvedCataloguePath = cataloguePath === undefined
+            ? shippedCataloguePath
+            : resolve(cwd, cataloguePath);
+        const loadedCatalogue = loadQuestionCatalogue({
+            path: cataloguePath ?? resolvedCataloguePath,
+            source: readFileSync(resolvedCataloguePath, 'utf8'),
+        });
+        if (!loadedCatalogue.ok)
+            return failed(loadedCatalogue.diagnostics);
+        const compilation = compileWorkspaceWithProfileContext([...workspace.profiles, ...workspace.documents].map((path) => ({
+            path,
+            source: readFileSync(resolve(cwd, path), 'utf8'),
+        })));
+        if (!compilation.ok)
+            return failed(compilation.diagnostics);
+        if (subjectFilter !== undefined) {
+            const known = new Set(compilation.graph.subjects.map(({ id }) => id));
+            if (!known.has(subjectFilter)) {
+                return {
+                    exitCode: 1,
+                    stdout: '',
+                    stderr: `Unknown subject identity: ${subjectFilter} (the compiled workspace declares ${known.size} subjects)\n`,
+                };
+            }
+        }
+        const report = evaluateCatalogue(loadedCatalogue.catalogue, compilation.graph, compilation.profileContext);
+        const step = selectStep(report, subjectFilter);
+        let slice;
+        if (step?.subject !== undefined) {
+            const projection = evaluateProjection(compilation.graph, {
+                format: 'yarramate/projection/v1',
+                id: 'design-step',
+                version: '0.0',
+                query: {
+                    subjects: [step.subject.id],
+                    relationships: 'connected',
+                },
+                presentation: {
+                    title: step.subject.name ?? step.subject.id,
+                    description: `The neighbourhood of ${step.subject.id} as declared today.`,
+                },
+            }, compilation.profileContext);
+            slice = renderBrief(projection, compilation.profileContext);
+        }
+        const result = {
+            format: 'yarramate/design-step/v1',
+            workspace: workspace.id,
+            catalogue: report.catalogue,
+            progress: {
+                questions: report.summary.questions,
+                openQuestions: report.summary.openQuestions,
+                open: report.summary.open,
+                waves: report.waves.map((wave) => ({
+                    id: wave.id,
+                    open: wave.questions.reduce((total, question) => total +
+                        (question.open ? (question.subjects?.length ?? 1) : 0), 0),
+                })),
+            },
+            step,
+            ...(slice === undefined ? {} : { slice }),
+        };
+        if (json) {
+            return {
+                exitCode: 0,
+                stdout: `${JSON.stringify(result, null, 2)}\n`,
+                stderr: '',
+            };
+        }
+        const waveSummary = result.progress.waves
+            .map(({ id, open }) => `${id} ${open} open`)
+            .join(' · ');
+        const lines = [
+            `Design interview — workspace ${workspace.id} · catalogue ${report.catalogue}`,
+            `Waves: ${waveSummary}`,
+            '',
+        ];
+        if (step === null) {
+            lines.push(subjectFilter === undefined
+                ? 'Interview complete: no open questions. The model answers everything the catalogue asks.'
+                : `Interview complete for ${subjectFilter}: no open questions touch it.`);
+        }
+        else {
+            lines.push(`Q [${step.wave} · ${step.questionId}] (authority: ${step.authority})`, `  ${step.question}`, `  Why it matters: ${step.materiality}`, `  How to answer: ${step.resolution}`);
+            if (step.remainingSubjects !== undefined) {
+                lines.push(`  (${step.remainingSubjects} more subject${step.remainingSubjects === 1 ? '' : 's'} share${step.remainingSubjects === 1 ? 's' : ''} this question)`);
+            }
+            if (slice !== undefined) {
+                lines.push('', 'Subject slice:', '', slice.trimEnd());
+            }
+            lines.push('', 'Answer by updating the model (one atomic batch):', `  yarramate apply <operations.yaml> ${workspacePath}`, `Then re-run: yarramate design ${workspacePath}`);
+        }
+        return { exitCode: 0, stdout: `${lines.join('\n')}\n`, stderr: '' };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return { exitCode: 2, stdout: '', stderr: `${message}\n` };
+    }
+}

package/dist/export-command.d.ts

@@ -0,0 +1,2 @@
+import { type CliResult } from './cli-support.js';
+export declare function runExportCommand(options: readonly string[], cwd: string): CliResult;

package/dist/export-command.js

@@ -0,0 +1,228 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, writeFileSync, } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseDocument } from 'yaml';
+import { renderBrief } from './brief.js';
+import { humanDiagnostics, usage } from './cli-support.js';
+import { compileWorkspaceWithProfileContext, } from './compiler.js';
+import { serializeSemanticGraph } from './graph.js';
+import { evaluateProjection, loadProjection, renderProjectionMarkdown, } from './projection.js';
+import { loadWorkspaceManifest } from './workspace.js';
+// The adapter stays a separate process behind the verb: the core never
+// imports adapter code (the adapter-runtime-dependency exclusion), it
+// hands the invocation to the sibling binary shipped in the same package.
+const here = dirname(fileURLToPath(import.meta.url));
+const likec4AdapterEntry = join(here, 'adapters', 'likec4-cli.js');
+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 briefFileName = (id) => `${id.replaceAll('#', '--')}.md`;
+const parseExportOptions = (options) => {
+    const positionals = [];
+    let out;
+    let budget;
+    let json = false;
+    for (let index = 0; index < options.length; index += 1) {
+        const option = options[index];
+        if (option === '--json') {
+            json = true;
+            continue;
+        }
+        if (option === '--out' || option === '--budget') {
+            const value = options[index + 1];
+            if (value === undefined || value.startsWith('-'))
+                return undefined;
+            if (option === '--out') {
+                if (out !== undefined)
+                    return undefined;
+                out = value;
+            }
+            else {
+                if (budget !== undefined || !/^[1-9][0-9]*$/.test(value)) {
+                    return undefined;
+                }
+                budget = Number(value);
+            }
+            index += 1;
+            continue;
+        }
+        if (option === undefined || option.startsWith('-'))
+            return undefined;
+        positionals.push(option);
+    }
+    return {
+        positionals,
+        ...(out === undefined ? {} : { out }),
+        ...(budget === undefined ? {} : { budget }),
+        json,
+    };
+};
+export function runExportCommand(options, cwd) {
+    const [kind, ...rest] = options;
+    if (kind === undefined ||
+        !['graph', 'markdown', 'briefs', 'likec4'].includes(kind)) {
+        return { exitCode: 2, stdout: '', stderr: usage };
+    }
+    const parsed = parseExportOptions(rest);
+    if (parsed === undefined) {
+        return { exitCode: 2, stdout: '', stderr: usage };
+    }
+    // likec4 delegates whole: <likec4-project.yaml> <output-dir> <workspace>.
+    if (kind === 'likec4') {
+        const [projectDefinition, outputDirectory, workspacePath] = parsed.positionals;
+        if (parsed.positionals.length !== 3 ||
+            projectDefinition === undefined ||
+            outputDirectory === undefined ||
+            workspacePath === undefined ||
+            parsed.out !== undefined ||
+            parsed.budget !== undefined ||
+            parsed.json) {
+            return { exitCode: 2, stdout: '', stderr: usage };
+        }
+        if (!existsSync(likec4AdapterEntry)) {
+            return {
+                exitCode: 2,
+                stdout: '',
+                stderr: `LikeC4 adapter entry not found at ${likec4AdapterEntry}; ` +
+                    'run from the installed package or use the yarramate-likec4 binary directly\n',
+            };
+        }
+        const delegated = spawnSync(process.execPath, [
+            likec4AdapterEntry,
+            'export-project',
+            projectDefinition,
+            outputDirectory,
+            workspacePath,
+        ], { cwd, encoding: 'utf8' });
+        const exitCode = delegated.status === 0 ? 0 : delegated.status === 1 ? 1 : 2;
+        return {
+            exitCode,
+            stdout: delegated.stdout ?? '',
+            stderr: delegated.stderr ?? '',
+        };
+    }
+    const expectedPositionals = kind === 'graph' ? 1 : 2;
+    const workspacePath = parsed.positionals[expectedPositionals - 1];
+    const projectionPath = kind === 'graph' ? undefined : parsed.positionals[0];
+    if (parsed.positionals.length !== expectedPositionals ||
+        workspacePath === undefined ||
+        parsed.json ||
+        (parsed.budget !== undefined && kind !== 'briefs') ||
+        (kind === 'briefs' && parsed.out === undefined)) {
+        return { exitCode: 2, stdout: '', stderr: usage };
+    }
+    try {
+        const manifestSource = readFileSync(resolve(cwd, workspacePath), 'utf8');
+        if (parseDocument(manifestSource).get('format') !== 'yarramate/workspace/v1') {
+            return {
+                exitCode: 2,
+                stdout: '',
+                stderr: 'export requires an explicit workspace manifest (yarramate/workspace/v1)\n',
+            };
+        }
+        const failed = (diagnostics) => ({
+            exitCode: 1,
+            stdout: humanDiagnostics(diagnostics),
+            stderr: '',
+        });
+        const loadedWorkspace = loadWorkspaceManifest({ path: workspacePath, source: manifestSource }, cwd);
+        if (!loadedWorkspace.ok)
+            return failed(loadedWorkspace.diagnostics);
+        const workspace = loadedWorkspace.workspace;
+        const compilation = compileWorkspaceWithProfileContext([...workspace.profiles, ...workspace.documents].map((path) => ({
+            path,
+            source: readFileSync(resolve(cwd, path), 'utf8'),
+        })));
+        if (!compilation.ok)
+            return failed(compilation.diagnostics);
+        if (kind === 'graph') {
+            const serialized = serializeSemanticGraph(compilation.graph);
+            if (parsed.out === undefined) {
+                return { exitCode: 0, stdout: serialized, stderr: '' };
+            }
+            const outPath = resolve(cwd, parsed.out);
+            mkdirSync(dirname(outPath), { recursive: true });
+            writeFileSync(outPath, serialized, 'utf8');
+            return {
+                exitCode: 0,
+                stdout: `Wrote graph to ${parsed.out}\n`,
+                stderr: '',
+            };
+        }
+        const loadedProjection = loadProjection({
+            path: projectionPath,
+            source: readFileSync(resolve(cwd, projectionPath), 'utf8'),
+        });
+        if (!loadedProjection.ok)
+            return failed(loadedProjection.diagnostics);
+        const result = evaluateProjection(compilation.graph, loadedProjection.projection, compilation.profileContext);
+        if (kind === 'markdown') {
+            const rendered = renderProjectionMarkdown(result);
+            if (parsed.out === undefined) {
+                return { exitCode: 0, stdout: rendered, stderr: '' };
+            }
+            const outPath = resolve(cwd, parsed.out);
+            mkdirSync(dirname(outPath), { recursive: true });
+            writeFileSync(outPath, rendered, 'utf8');
+            return {
+                exitCode: 0,
+                stdout: `Wrote markdown to ${parsed.out}\n`,
+                stderr: '',
+            };
+        }
+        // briefs: the handoff bundle — one brief per projected concept, each
+        // the concept's one-hop neighbourhood (ADR 0055), plus an index so N
+        // implementers can each pick up one slice.
+        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))
+            .map(({ id }) => id)
+            .sort((left, right) => left.localeCompare(right));
+        const outDirectory = resolve(cwd, parsed.out);
+        mkdirSync(outDirectory, { recursive: true });
+        const indexLines = [
+            `# Briefs — ${result.presentation?.title ?? result.projection}`,
+            '',
+            `Derived from projection ${result.projection}; one brief per concept,`,
+            'each the concept\'s connected neighbourhood as declared today.',
+            '',
+        ];
+        for (const id of concepts) {
+            const slice = evaluateProjection(compilation.graph, {
+                format: 'yarramate/projection/v1',
+                id: 'export-brief',
+                version: '0.0',
+                query: { subjects: [id], relationships: 'connected' },
+                presentation: {
+                    title: claimValue(result.claims, id, 'yarramate/concept/name') ?? id,
+                    description: `The neighbourhood of ${id} as declared today.`,
+                },
+            }, compilation.profileContext);
+            const brief = renderBrief(slice, compilation.profileContext, parsed.budget);
+            writeFileSync(join(outDirectory, briefFileName(id)), brief, 'utf8');
+            const name = claimValue(result.claims, id, 'yarramate/concept/name');
+            const conceptKind = claimValue(result.claims, id, 'yarramate/concept/kind') ?? 'unknown';
+            const status = claimValue(result.claims, id, 'yarramate/lifecycle/status');
+            indexLines.push(`- [${name ?? id}](${briefFileName(id)}) — ` +
+                `${conceptKind.split('#')[1] ?? conceptKind}` +
+                `${status === undefined ? '' : ` (${status})`} — \`${id}\``);
+        }
+        if (concepts.length === 0) {
+            indexLines.push('No concepts selected by this projection.');
+        }
+        writeFileSync(join(outDirectory, 'INDEX.md'), `${indexLines.join('\n')}\n`, 'utf8');
+        return {
+            exitCode: 0,
+            stdout: `Wrote ${concepts.length} brief${concepts.length === 1 ? '' : 's'} and INDEX.md to ${parsed.out}\n`,
+            stderr: '',
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return { exitCode: 2, stdout: '', stderr: `${message}\n` };
+    }
+}

package/dist/interrogate-command.d.ts

@@ -0,0 +1,104 @@
+import { type Diagnostic, type ResolvedProfileContext, type SemanticGraph, type WorkspaceSource } from './compiler.js';
+interface CatalogueSelector {
+    readonly kinds: readonly string[];
+    readonly kindMatching?: 'exact' | 'descendants';
+    readonly statuses?: readonly string[];
+    readonly documents?: readonly string[];
+}
+type CatalogueCondition = {
+    readonly condition: 'missing-claim';
+    readonly predicate: string;
+} | {
+    readonly condition: 'missing-relationship';
+    readonly kinds: readonly string[];
+    readonly direction: 'incoming' | 'outgoing' | 'any';
+    readonly kindMatching?: 'exact' | 'descendants';
+} | {
+    readonly condition: 'isolated';
+} | {
+    readonly condition: 'no-subject-of-kind';
+    readonly kinds: readonly string[];
+} | {
+    readonly condition: 'no-state-defined';
+} | {
+    readonly condition: 'missing-linkage';
+    readonly kinds: readonly string[];
+    readonly direction: 'incoming' | 'outgoing';
+    readonly counterpartKinds: readonly string[];
+    readonly kindMatching?: 'exact' | 'descendants';
+} | {
+    readonly condition: 'missing-reference';
+    readonly predicate: string;
+    readonly direction: 'incoming' | 'outgoing';
+} | {
+    readonly condition: 'missing-attestation';
+    readonly topic: string;
+};
+export interface CatalogueQuestion {
+    readonly id: string;
+    readonly wave: string;
+    readonly scope: 'workspace' | 'subject';
+    readonly subjects?: CatalogueSelector;
+    readonly trigger: readonly CatalogueCondition[];
+    readonly question: string;
+    readonly materiality: string;
+    readonly resolution: string;
+    readonly authority: 'human' | 'agent' | 'either';
+}
+export interface QuestionCatalogue {
+    readonly format: 'yarramate/question-catalogue/v1';
+    readonly id: string;
+    readonly version: string;
+    readonly profile: string;
+    readonly presentation?: {
+        readonly title?: string;
+        readonly description?: string;
+    };
+    readonly waves: readonly {
+        readonly id: string;
+        readonly name: string;
+        readonly description?: string;
+    }[];
+    readonly questions: readonly CatalogueQuestion[];
+}
+interface OpenSubject {
+    readonly id: string;
+    readonly name?: string;
+    readonly question: string;
+}
+interface ReportQuestion {
+    readonly id: string;
+    readonly scope: 'workspace' | 'subject';
+    readonly authority: 'human' | 'agent' | 'either';
+    readonly open: boolean;
+    readonly question: string;
+    readonly materiality: string;
+    readonly resolution: string;
+    readonly subjects?: readonly OpenSubject[];
+}
+export interface InterrogationReport {
+    readonly format: 'yarramate/interrogation-report/v1';
+    readonly workspace: string;
+    readonly catalogue: string;
+    readonly summary: {
+        readonly questions: number;
+        readonly openQuestions: number;
+        readonly open: number;
+    };
+    readonly waves: readonly {
+        readonly id: string;
+        readonly name: string;
+        readonly questions: readonly ReportQuestion[];
+    }[];
+}
+export declare function evaluateCatalogue(catalogue: QuestionCatalogue, graph: SemanticGraph, profileContext?: ResolvedProfileContext): Omit<InterrogationReport, 'workspace'>;
+export type CatalogueLoadResult = {
+    readonly ok: true;
+    readonly catalogue: QuestionCatalogue;
+} | {
+    readonly ok: false;
+    readonly diagnostics: readonly Diagnostic[];
+};
+export declare function loadQuestionCatalogue(catalogueSource: WorkspaceSource): CatalogueLoadResult;
+export declare function renderInterrogationReport(report: InterrogationReport): string;
+export {};