yarramate 0.10.0 → 0.12.0

package/dist/adapters/likec4-cli.js

@@ -6,6 +6,7 @@ import { createHash, randomUUID } from 'node:crypto';
 import Ajv2020Module from 'ajv/dist/2020.js';
 import { isMap, isSeq, parseDocument } from 'yaml';
 import { isMainModule, resolveCliWorkspaceSources, versionResult, } from '../cli-support.js';
+import { deriveChangedSubjects } from '../changed.js';
 import { compileWorkspace } from '../compiler.js';
 import { adapterMappingLocation, loadAdapterMapping, validateAdapterMapping, } from '../adapter-mapping.js';
 import { locateSourcePath } from '../source-document.js';
@@ -78,7 +79,7 @@ const usage = 'Usage:\n' +
     '  yarramate-likec4 check <likec4-project.yaml> [--json] <workspace-or-source...>\n' +
     '  yarramate-likec4 export <projection.yaml> <mapping.yaml> [--kinds <kind-mapping.yaml>] [--compare <from-state> <to-state>] <workspace-or-source...>\n' +
     '  yarramate-likec4 export-project [--check] <projection.yaml> <mapping.yaml> <output-dir> [--kinds <kind-mapping.yaml>] [--compare <from-state> <to-state>] <workspace-or-source...>\n' +
-    '  yarramate-likec4 export-project [--check] <likec4-project.yaml> <output-dir> <workspace-or-source...>\n';
+    '  yarramate-likec4 export-project [--check] <likec4-project.yaml> <output-dir> [--changed <git-range>] <workspace-or-source...>\n';
 const diagnosticJson = (diagnostics) => `${JSON.stringify({
     format: 'yarramate/likec4-diagnostic-result/v1',
     diagnostics,
@@ -528,6 +529,7 @@ export function runLikeC4Cli(args, cwd = process.cwd()) {
     let invalidOptions = false;
     let kindMappingPath;
     let comparison;
+    let changedRange;
     const sourcePaths = [];
     for (let index = 0; index < sourceOptions.length; index += 1) {
         const option = sourceOptions[index];
@@ -549,6 +551,19 @@ export function runLikeC4Cli(args, cwd = process.cwd()) {
             }
             continue;
         }
+        if (option === '--changed') {
+            const value = sourceOptions[index + 1];
+            if (value === undefined ||
+                value.startsWith('-') ||
+                changedRange !== undefined) {
+                invalidOptions = true;
+            }
+            else {
+                changedRange = value;
+                index += 1;
+            }
+            continue;
+        }
         if (option === '--compare') {
             const from = sourceOptions[index + 1];
             const to = sourceOptions[index + 2];
@@ -581,6 +596,8 @@ export function runLikeC4Cli(args, cwd = process.cwd()) {
         (command === 'export-project' && outputDirectory === undefined) ||
         (projectDefinitionMode &&
             (kindMappingPath !== undefined || comparison !== undefined)) ||
+        (changedRange !== undefined &&
+            !(projectDefinitionMode && command === 'export-project')) ||
         invalidOptions ||
         sourcePaths.length === 0 ||
         sourcePaths.some((argument) => argument.startsWith('-'))) {
@@ -695,6 +712,9 @@ export function runLikeC4Cli(args, cwd = process.cwd()) {
                 ? [
                     {
                         ...(view.id === undefined ? {} : { id: view.id }),
+                        ...(view.folder === undefined
+                            ? {}
+                            : { folder: view.folder }),
                         prepared,
                         ...(view.compare === undefined
                             ? {}
@@ -886,7 +906,32 @@ export function runLikeC4Cli(args, cwd = process.cwd()) {
                 }
                 renderedViewIds.add(renderedId);
             }
-            const exported = exportLikeC4Project(loadedProject.document.value, successfulViews);
+            let gitChange;
+            if (changedRange !== undefined) {
+                const modelDocuments = sources.flatMap((candidate) => {
+                    const parsed = parseDocument(candidate.source);
+                    if (parsed.get('format') !== 'yarramate/v1')
+                        return [];
+                    const documentId = parsed.get('id');
+                    return typeof documentId === 'string'
+                        ? [{ ...candidate, documentId }]
+                        : [];
+                });
+                const derived = deriveChangedSubjects(cwd, changedRange, modelDocuments);
+                if (!derived.ok) {
+                    return { exitCode: 2, stdout: '', stderr: `${derived.message}\n` };
+                }
+                const all = [
+                    ...derived.changed.concepts,
+                    ...derived.changed.relationships,
+                ];
+                gitChange = {
+                    range: derived.changed.range,
+                    added: derived.changed.added,
+                    modified: all.filter((id) => !derived.changed.added.includes(id)),
+                };
+            }
+            const exported = exportLikeC4Project(loadedProject.document.value, successfulViews, gitChange === undefined ? {} : { gitChange });
             if (!exported.ok) {
                 return {
                     exitCode: 1,

package/dist/adapters/likec4-export.d.ts

@@ -21,5 +21,13 @@ export type LikeC4ExportResult = {
 };
 export interface LikeC4ExportOptions {
     readonly comparison?: StateComparison;
+    /** Git-derived review overlay (ADR 0066): subjects new or changed in a
+     *  ref range carry metadata and view styling; nothing is authored. */
+    readonly gitChange?: GitChangeOverlay;
+}
+export interface GitChangeOverlay {
+    readonly range: string;
+    readonly added: readonly string[];
+    readonly modified: readonly string[];
 }
 export declare function exportLikeC4(projection: ProjectionResult, mapping: AdapterMapping, kindMapping?: LikeC4KindMapping, options?: LikeC4ExportOptions): LikeC4ExportResult;

package/dist/adapters/likec4-export.js

@@ -62,6 +62,13 @@ export function exportLikeC4(projection, mapping, kindMapping, options = {}) {
     const concepts = projection.subjects
         .filter(({ type }) => type === 'concept')
         .sort((left, right) => left.id.localeCompare(right.id));
+    const gitChangeOf = (id) => options.gitChange === undefined
+        ? undefined
+        : options.gitChange.added.includes(id)
+            ? 'new'
+            : options.gitChange.modified.includes(id)
+                ? 'changed'
+                : undefined;
     const comparisonChange = new Map(options.comparison === undefined
         ? []
         : [
@@ -121,6 +128,7 @@ export function exportLikeC4(projection, mapping, kindMapping, options = {}) {
             ['yarramateId', concept.id],
             ['yarramateKind', semanticKind],
             ['yarramateChange', comparisonChange.get(concept.id)],
+            ['yarramateGitChange', gitChangeOf(concept.id)],
             [
                 'status',
                 valueFor(projection.claims, concept.id, 'yarramate/lifecycle/status'),
@@ -168,6 +176,7 @@ export function exportLikeC4(projection, mapping, kindMapping, options = {}) {
             ['yarramateId', relationship.id],
             ['yarramateKind', structural.predicate],
             ['yarramateChange', comparisonChange.get(relationship.id)],
+            ['yarramateGitChange', gitChangeOf(relationship.id)],
             [
                 'status',
                 valueFor(projection.claims, relationship.id, 'yarramate/lifecycle/status'),
@@ -212,6 +221,18 @@ export function exportLikeC4(projection, mapping, kindMapping, options = {}) {
                 return `    style ${external} { color red; border dashed }`;
             }
             return `    style ${external} { color gray }`;
+        })), ...(options.gitChange === undefined
+        ? []
+        : concepts.flatMap((concept) => {
+            const external = externalByNative.get(concept.id);
+            const change = gitChangeOf(concept.id);
+            if (change === 'new') {
+                return [`    style ${external} { color green }`];
+            }
+            if (change === 'changed') {
+                return [`    style ${external} { color amber }`];
+            }
+            return [];
         })), '    autoLayout LeftRight', '  }', '}', '');
     return { ok: true, source: lines.join('\n') };
 }

package/dist/adapters/likec4-project.d.ts

@@ -1,6 +1,6 @@
 import type { WorkspaceSource } from '../compiler.js';
 import type { LikeC4PreparationResult } from './likec4-prepare.js';
-import { type LikeC4ExportResult } from './likec4-export.js';
+import { type GitChangeOverlay, type LikeC4ExportResult } from './likec4-export.js';
 export interface LikeC4ProjectDefinition {
     readonly format: 'yarramate/likec4-project/v1';
     readonly id: string;
@@ -11,6 +11,7 @@ export interface LikeC4ProjectDefinition {
     readonly views: ReadonlyArray<{
         readonly id?: string;
         readonly projection: string;
+        readonly folder?: string;
         readonly compare?: {
             readonly from: string;
             readonly to: string;
@@ -40,6 +41,7 @@ export interface LikeC4Deployment {
 export declare const loadLikeC4ProjectDefinition: (source: WorkspaceSource) => import("../source-document.js").SourceDocumentResult<LikeC4ProjectDefinition>;
 export interface PreparedLikeC4ProjectView {
     readonly id?: string;
+    readonly folder?: string;
     readonly prepared: Extract<LikeC4PreparationResult, {
         readonly ok: true;
     }>;
@@ -55,4 +57,7 @@ export interface PreparedLikeC4ProjectView {
     };
     readonly deployment?: LikeC4Deployment;
 }
-export declare function exportLikeC4Project(project: LikeC4ProjectDefinition, views: readonly PreparedLikeC4ProjectView[]): LikeC4ExportResult;
+export interface LikeC4ProjectExportOptions {
+    readonly gitChange?: GitChangeOverlay;
+}
+export declare function exportLikeC4Project(project: LikeC4ProjectDefinition, views: readonly PreparedLikeC4ProjectView[], options?: LikeC4ProjectExportOptions): LikeC4ExportResult;

package/dist/adapters/likec4-project.js

@@ -8,6 +8,15 @@ const Ajv2020 = Ajv2020Module.default;
 const validateLikeC4Project = new Ajv2020({ allErrors: true }).compile(likeC4ProjectSchema);
 export const loadLikeC4ProjectDefinition = (source) => loadSourceDocument(source, validateLikeC4Project, 'LikeC4 project');
 const quote = (value) => `'${value.replaceAll('\\', '\\\\').replaceAll("'", "\\'").replaceAll('\n', '\\n')}'`;
+// A folder files the view in LikeC4's sidebar tree: the title becomes a
+// path ('Folder / Title') whose last segment is the displayed title (ADR
+// 0067). A view without a declared title still needs a title line to
+// carry the path, so the view id stands in as the leaf.
+const titleLines = (folder, title, viewId) => folder === undefined
+    ? title === undefined
+        ? []
+        : [`    title ${quote(title)}`]
+    : [`    title ${quote(`${folder} / ${title ?? viewId}`)}`];
 const unionProjection = (project, views) => ({
     format: 'yarramate/projection-result/v1',
     projection: `${project.id}@${project.version}`,
@@ -28,7 +37,7 @@ const unionProjection = (project, views) => ({
         ...new Map(views.flatMap(({ prepared }) => prepared.projection.claims.map((claim) => [claim.id, claim]))).values(),
     ].sort((left, right) => left.id.localeCompare(right.id)),
 });
-const viewBody = ({ id, prepared, dynamic, deployment, }) => {
+const viewBody = ({ id, folder, prepared, dynamic, deployment, }, gitChange) => {
     const source = prepared.source;
     const startToken = '\nviews {\n';
     const start = source.indexOf(startToken);
@@ -58,9 +67,7 @@ const viewBody = ({ id, prepared, dynamic, deployment, }) => {
         const viewId = id ?? prepared.projection.projection.split('@')[0];
         return [
             `  deployment view ${viewId} {`,
-            ...(prepared.projection.presentation?.title === undefined
-                ? []
-                : [`    title ${quote(prepared.projection.presentation.title)}`]),
+            ...titleLines(folder, prepared.projection.presentation?.title, viewId),
             ...(prepared.projection.presentation?.description === undefined
                 ? []
                 : [
@@ -105,9 +112,7 @@ const viewBody = ({ id, prepared, dynamic, deployment, }) => {
         const viewId = id ?? prepared.projection.projection.split('@')[0];
         return [
             `  dynamic view ${viewId} {`,
-            ...(prepared.projection.presentation?.title === undefined
-                ? []
-                : [`    title ${quote(prepared.projection.presentation.title)}`]),
+            ...titleLines(folder, prepared.projection.presentation?.title, viewId),
             ...(prepared.projection.presentation?.description === undefined
                 ? []
                 : [
@@ -117,15 +122,40 @@ const viewBody = ({ id, prepared, dynamic, deployment, }) => {
             '  }',
         ].join('\n');
     }
+    const overlayRules = gitChange === undefined
+        ? []
+        : prepared.projection.subjects
+            .filter(({ type }) => type === 'concept')
+            .flatMap(({ id: nativeId }) => {
+            const external = externalByNative.get(nativeId);
+            if (external === undefined)
+                return [];
+            if (gitChange.added.includes(nativeId)) {
+                return [`    style ${external} { color green }`];
+            }
+            if (gitChange.modified.includes(nativeId)) {
+                return [`    style ${external} { color amber }`];
+            }
+            return [];
+        })
+            .sort();
     const membershipRules = [
         includeRule,
         '    exclude * -> *',
         ...relationshipRules,
+        ...overlayRules,
     ].join('\n');
-    return source
+    const viewId = id ?? prepared.projection.projection.split('@')[0];
+    const body = source
         .slice(start + startToken.length, end)
-        .replace(/^  view [A-Za-z_][A-Za-z0-9_-]* \{/, `  view ${id ?? prepared.projection.projection.split('@')[0]} {`)
+        .replace(/^  view [A-Za-z_][A-Za-z0-9_-]* \{/, `  view ${viewId} {`)
         .replace('    include *', membershipRules);
+    if (folder === undefined)
+        return body;
+    const title = prepared.projection.presentation?.title;
+    return title === undefined
+        ? body.replace(`  view ${viewId} {`, `  view ${viewId} {\n${titleLines(folder, undefined, viewId).join('\n')}`)
+        : body.replace(`    title ${quote(title)}`, titleLines(folder, title, viewId).join('\n'));
 };
 const deploymentBody = ({ deployment, prepared, }) => {
     if (deployment === undefined)
@@ -168,12 +198,48 @@ const deploymentBody = ({ deployment, prepared, }) => {
         '}',
     ].join('\n');
 };
-export function exportLikeC4Project(project, views) {
+// The synthetic review view (ADR 0066): every changed subject with its
+// highlight, and a description that doubles as the legend.
+const reviewChangesView = (views, gitChange) => {
+    const externalByNative = new Map(views.flatMap((view) => view.prepared.subjectMapping.mappings
+        .filter(({ type }) => type === 'concept')
+        .map(({ native, external }) => [native, external])));
+    const changedConcepts = [
+        ...new Set([...gitChange.added, ...gitChange.modified].flatMap((nativeId) => {
+            const external = externalByNative.get(nativeId);
+            return external === undefined ? [] : [external];
+        })),
+    ].sort();
+    if (changedConcepts.length === 0)
+        return undefined;
+    const changedRelationships = [
+        ...new Set([...gitChange.added, ...gitChange.modified].filter((nativeId) => !externalByNative.has(nativeId))),
+    ].sort();
+    const styles = changedConcepts.map((external) => {
+        const nativeId = [...externalByNative.entries()].find(([, candidate]) => candidate === external)[0];
+        return gitChange.added.includes(nativeId)
+            ? `    style ${external} { color green }`
+            : `    style ${external} { color amber }`;
+    });
+    return [
+        '  view review-changes {',
+        `    title ${quote(`Review: ${gitChange.range}`)}`,
+        `    description ${quote(`Subjects touched in ${gitChange.range}. Legend: green = new, amber = changed; connected context unhighlighted. Derived from git - nothing here is authored (ADR 0066).`)}`,
+        `    include ${changedConcepts.join(', ')}`,
+        ...changedRelationships.map((id) => `    include * -> * where metadata.yarramateId is '${id}'`),
+        ...styles,
+        '    autoLayout LeftRight',
+        '  }',
+    ].join('\n');
+};
+export function exportLikeC4Project(project, views, options = {}) {
     const first = views[0];
     if (first === undefined) {
         throw new Error('LikeC4 project requires at least one view');
     }
-    const model = exportLikeC4(unionProjection(project, views), first.prepared.subjectMapping, first.prepared.kindMapping);
+    const model = exportLikeC4(unionProjection(project, views), first.prepared.subjectMapping, first.prepared.kindMapping, options.gitChange === undefined
+        ? {}
+        : { gitChange: options.gitChange });
     if (!model.ok)
         return model;
     const startToken = '\nviews {\n';
@@ -182,9 +248,13 @@ export function exportLikeC4Project(project, views) {
         const rendered = deploymentBody(view);
         return rendered === undefined ? [] : [rendered];
     });
-    const renderedViews = views.map(viewBody);
+    const renderedViews = views.map((view) => viewBody(view, options.gitChange));
+    const review = options.gitChange === undefined
+        ? undefined
+        : reviewChangesView(views, options.gitChange);
+    const allViews = review === undefined ? renderedViews : [...renderedViews, review];
     return {
         ok: true,
-        source: `${model.source.slice(0, modelEnd)}${deployments.length === 0 ? '' : `\n${deployments.join('\n')}\n`}\nviews {\n${renderedViews.join('\n')}\n}\n`,
+        source: `${model.source.slice(0, modelEnd)}${deployments.length === 0 ? '' : `\n${deployments.join('\n')}\n`}\nviews {\n${allViews.join('\n')}\n}\n`,
     };
 }

package/dist/changed.d.ts

@@ -2,6 +2,9 @@ export interface ChangedSubjects {
     readonly range: string;
     readonly concepts: readonly string[];
     readonly relationships: readonly string[];
+    /** Subjects whose entire declaration is new in the range (subset of
+     *  concepts + relationships); the rest changed in place. */
+    readonly added: readonly string[];
 }
 export type ChangedResult = {
     readonly ok: true;

package/dist/changed.js

@@ -52,16 +52,21 @@ const itemSpans = (source) => {
     }
     return spans;
 };
-// New-side line ranges from `git diff --unified=0`. A pure deletion has a
-// zero count; it still touches the position it collapsed onto.
 const changedLineRanges = (diff) => {
-    const ranges = [];
-    for (const match of diff.matchAll(/^@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@/gm)) {
-        const start = Number(match[1]);
-        const count = match[2] === undefined ? 1 : Number(match[2]);
-        ranges.push(count === 0 ? [Math.max(start, 1), Math.max(start, 1)] : [start, start + count - 1]);
+    const touched = [];
+    const inserted = [];
+    for (const match of diff.matchAll(/^@@ -\d+(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/gm)) {
+        const oldCount = match[1] === undefined ? 1 : Number(match[1]);
+        const start = Number(match[2]);
+        const count = match[3] === undefined ? 1 : Number(match[3]);
+        const range = count === 0
+            ? [Math.max(start, 1), Math.max(start, 1)]
+            : [start, start + count - 1];
+        touched.push(range);
+        if (oldCount === 0 && count > 0)
+            inserted.push(range);
     }
-    return ranges;
+    return { touched, inserted };
 };
 export function deriveChangedSubjects(cwd, range, documents) {
     const probe = spawnSync('git', ['-C', cwd, 'rev-parse', '--git-dir'], {
@@ -75,6 +80,7 @@ export function deriveChangedSubjects(cwd, range, documents) {
     }
     const concepts = new Set();
     const relationships = new Set();
+    const added = new Set();
     for (const document of documents) {
         const diffed = spawnSync('git', ['-C', cwd, 'diff', '--unified=0', range, '--', document.path], { encoding: 'utf8' });
         if (diffed.status !== 0) {
@@ -84,13 +90,13 @@ export function deriveChangedSubjects(cwd, range, documents) {
             };
         }
         const ranges = changedLineRanges(diffed.stdout ?? '');
-        if (ranges.length === 0)
+        if (ranges.touched.length === 0)
             continue;
         const spans = itemSpans(document.source);
         for (const span of spans) {
             if (span.collection === 'states')
                 continue;
-            const touched = ranges.some(([from, to]) => from <= span.endLine && to >= span.startLine);
+            const touched = ranges.touched.some(([from, to]) => from <= span.endLine && to >= span.startLine);
             if (!touched)
                 continue;
             const qualified = `${document.documentId}#${span.id}`;
@@ -98,6 +104,9 @@ export function deriveChangedSubjects(cwd, range, documents) {
                 concepts.add(qualified);
             else
                 relationships.add(qualified);
+            const whollyInserted = ranges.inserted.some(([from, to]) => from <= span.startLine && to >= span.endLine);
+            if (whollyInserted)
+                added.add(qualified);
         }
     }
     return {
@@ -106,6 +115,7 @@ export function deriveChangedSubjects(cwd, range, documents) {
             range,
             concepts: [...concepts].sort(),
             relationships: [...relationships].sort(),
+            added: [...added].sort(),
         },
     };
 }

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 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 ask <workspace.yaml> --changed <git-range> [--budget <tokens>] [--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 markdown --changed <git-range> <workspace.yaml> [--out <file>]\n  yarramate export briefs <projection.yaml> <workspace.yaml> --out <directory> [--budget <tokens>]\n  yarramate export briefs --changed <git-range> <workspace.yaml> --out <directory> [--budget <tokens>]\n  yarramate export likec4 <likec4-project.yaml> <output-dir> <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 ask <workspace.yaml> --changed <git-range> [--budget <tokens>] [--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 markdown --changed <git-range> <workspace.yaml> [--out <file>]\n  yarramate export briefs <projection.yaml> <workspace.yaml> --out <directory> [--budget <tokens>]\n  yarramate export briefs --changed <git-range> <workspace.yaml> --out <directory> [--budget <tokens>]\n  yarramate export likec4 <likec4-project.yaml> <output-dir> <workspace.yaml> [--changed <git-range>]\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 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 ask <workspace.yaml> --changed <git-range> [--budget <tokens>] [--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 markdown --changed <git-range> <workspace.yaml> [--out <file>]\n  yarramate export briefs <projection.yaml> <workspace.yaml> --out <directory> [--budget <tokens>]\n  yarramate export briefs --changed <git-range> <workspace.yaml> --out <directory> [--budget <tokens>]\n  yarramate export likec4 <likec4-project.yaml> <output-dir> <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 ask <workspace.yaml> --changed <git-range> [--budget <tokens>] [--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 markdown --changed <git-range> <workspace.yaml> [--out <file>]\n  yarramate export briefs <projection.yaml> <workspace.yaml> --out <directory> [--budget <tokens>]\n  yarramate export briefs --changed <git-range> <workspace.yaml> --out <directory> [--budget <tokens>]\n  yarramate export likec4 <likec4-project.yaml> <output-dir> <workspace.yaml> [--changed <git-range>]\n';
 export const diagnosticJson = (diagnostics) => `${JSON.stringify({
     format: 'yarramate/diagnostic-result/v1',
     diagnostics,

package/dist/export-command.js

@@ -91,6 +91,7 @@ export function runExportCommand(options, cwd) {
             parsed.json) {
             return { exitCode: 2, stdout: '', stderr: usage };
         }
+        const changedArguments = parsed.changed === undefined ? [] : ['--changed', parsed.changed];
         if (!existsSync(likec4AdapterEntry)) {
             return {
                 exitCode: 2,
@@ -105,6 +106,7 @@ export function runExportCommand(options, cwd) {
             projectDefinition,
             outputDirectory,
             workspacePath,
+            ...changedArguments,
         ], { cwd, encoding: 'utf8' });
         const exitCode = delegated.status === 0 ? 0 : delegated.status === 1 ? 1 : 2;
         return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yarramate",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "description": "Tool-neutral semantic architecture engine and guided methodology",
   "license": "MIT",
   "repository": {

package/schema/yarramate-ask-result.schema.json

@@ -231,6 +231,13 @@
                 "type": "string",
                 "minLength": 1
               }
+            },
+            "added": {
+              "type": "array",
+              "items": {
+                "type": "string",
+                "minLength": 1
+              }
             }
           },
           "additionalProperties": false

package/schema/yarramate-likec4-project.schema.json

@@ -72,6 +72,11 @@
         "projection": {
           "$ref": "#/$defs/path"
         },
+        "folder": {
+          "type": "string",
+          "description": "Sidebar folder for the rendered view, emitted as a LikeC4 title path ('Folder / Title'). Nest with '/' separators; folders appear in the order their first view appears in the views list.",
+          "pattern": "^[^/]+(?:/[^/]+)*$"
+        },
         "compare": {
           "$ref": "#/$defs/comparison"
         },