yarramate 0.9.0 → 0.11.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('-'))) {
@@ -886,7 +903,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;
@@ -55,4 +55,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

@@ -28,7 +28,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, prepared, dynamic, deployment, }, gitChange) => {
     const source = prepared.source;
     const startToken = '\nviews {\n';
     const start = source.indexOf(startToken);
@@ -117,10 +117,28 @@ 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
         .slice(start + startToken.length, end)
@@ -168,12 +186,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 +236,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/dist/projection.d.ts

@@ -9,6 +9,7 @@ export interface ProjectionDefinition {
         readonly documents?: readonly string[];
         readonly kinds?: readonly string[];
         readonly statuses?: readonly LifecycleStatus[];
+        readonly excludeStatuses?: readonly LifecycleStatus[];
         readonly states?: readonly string[];
         readonly owners?: readonly string[];
         readonly constraints?: readonly string[];

package/dist/projection.js

@@ -65,6 +65,9 @@ export function evaluateProjection(graph, projection, profileContext) {
             (projection.query.statuses === undefined ||
                 (status !== undefined &&
                     projection.query.statuses.includes(status))) &&
+            (projection.query.excludeStatuses === undefined ||
+                status === undefined ||
+                !projection.query.excludeStatuses.includes(status)) &&
             (projection.query.owners === undefined ||
                 (owner !== undefined &&
                     projection.query.owners.includes(owner))) &&
@@ -80,8 +83,12 @@ export function evaluateProjection(graph, projection, profileContext) {
             if (subject.type !== 'relationship')
                 continue;
             const relationship = graph.claims.find((claim) => claim.id === subject.id);
+            const relationshipStatus = claimValue(graph.claims, subject.id, 'yarramate/lifecycle/status');
             if (relationship === undefined ||
                 !('ref' in relationship.object) ||
+                (projection.query.excludeStatuses !== undefined &&
+                    relationshipStatus !== undefined &&
+                    projection.query.excludeStatuses.includes(relationshipStatus)) ||
                 (projection.query.relationshipKinds !== undefined &&
                     !projection.query.relationshipKinds.some((selectedKind) => selectedKind === relationship.predicate ||
                         (projection.query.kindMatching === 'descendants' &&
@@ -93,6 +100,20 @@ export function evaluateProjection(graph, projection, profileContext) {
             }
             const sourceSelected = initiallySelectedConceptIds.has(relationship.subject);
             const targetSelected = initiallySelectedConceptIds.has(relationship.object.ref);
+            // excludeStatuses also vetoes connected expansion: an excluded
+            // concept is never pulled in as a neighbour, and edges touching
+            // one are dropped rather than left dangling.
+            const endpointExcluded = (id) => {
+                if (projection.query.excludeStatuses === undefined)
+                    return false;
+                const endpointStatus = claimValue(graph.claims, id, 'yarramate/lifecycle/status');
+                return (endpointStatus !== undefined &&
+                    projection.query.excludeStatuses.includes(endpointStatus));
+            };
+            if (endpointExcluded(relationship.subject) ||
+                endpointExcluded(relationship.object.ref)) {
+                continue;
+            }
             if ((relationshipMode === 'between' &&
                 sourceSelected &&
                 targetSelected) ||

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yarramate",
-  "version": "0.9.0",
+  "version": "0.11.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-projection.schema.json

@@ -49,6 +49,14 @@
             "enum": ["planned", "current", "retired"]
           }
         },
+        "excludeStatuses": {
+          "description": "Drop concepts carrying one of these lifecycle statuses while keeping concepts that declare no status at all - 'everything except retired' for viewpoint projections, where a bare statuses filter would wrongly drop unstatused actors and motivation elements.",
+          "type": "array",
+          "uniqueItems": true,
+          "items": {
+            "enum": ["planned", "current", "retired"]
+          }
+        },
         "states": {
           "type": "array",
           "minItems": 1,