yarramate 1.2.0 → 1.4.0

package/dist/ask-command.js

@@ -470,7 +470,7 @@ export function runAskCommand(options, cwd) {
             });
             if (!loadedCatalogue.ok)
                 return failed(loadedCatalogue.diagnostics);
-            const report = evaluateCatalogue(loadedCatalogue.catalogue, compilation.graph, compilation.profileContext);
+            const report = evaluateCatalogue(loadedCatalogue.catalogue, compilation.graph, compilation.profileContext, evidenceDocuments.flatMap(({ observations }) => observations));
             const result = {
                 format: 'yarramate/ask-result/v1',
                 workspace: workspace.id,
@@ -500,8 +500,15 @@ export function runAskCommand(options, cwd) {
             if (reconciliation !== undefined) {
                 lines.push(reconciliationLine(reconciliation));
             }
+            // Zero open has two causes and only one is complete (#334): a
+            // catalogue whose waves are all gated shut has asked nothing, and
+            // reporting that as a finished interview is the same empty-set
+            // flattery the wave rail carried.
+            const askedAnything = report.waves.some((wave) => wave.questions.length > 0);
             lines.push(report.summary.open === 0
-                ? `Design interview complete (catalogue ${report.catalogue}): no open questions.`
+                ? askedAnything
+                    ? `Design interview complete (catalogue ${report.catalogue}): no open questions.`
+                    : `Design interview not started (catalogue ${report.catalogue}): no wave has opened yet.`
                 : `Design interview: ${plural(report.summary.open, 'open question')} (catalogue ${report.catalogue}) — continue: yarramate design ${workspacePath}`, '', 'Backlog — planned, dependency order:', ...plannedLines(planned), '', `Current: ${plural(current.length, 'subject')} · Retired: ${retired.length} ` +
                 `(roster: yarramate ask ${workspacePath} --subjects)`);
             return emit(result, `${lines.join('\n')}\n`);
@@ -689,8 +696,21 @@ export function runAskCommand(options, cwd) {
             });
             if (!loadedCatalogue.ok)
                 return failed(loadedCatalogue.diagnostics);
+            // The evidence overlay rides along for the one condition that
+            // reads it (unchallenged-evidence); a workspace declaring no
+            // evidence passes an overlay known to be empty.
+            const evidenceObservations = [];
+            for (const path of workspace.evidence) {
+                const loaded = loadEvidence({
+                    path,
+                    source: readFileSync(resolve(cwd, path), 'utf8'),
+                });
+                if (!loaded.ok)
+                    return failed(loaded.diagnostics);
+                evidenceObservations.push(...loaded.evidence.observations);
+            }
             const report = {
-                ...evaluateCatalogue(loadedCatalogue.catalogue, graph, compilation.profileContext),
+                ...evaluateCatalogue(loadedCatalogue.catalogue, graph, compilation.profileContext, evidenceObservations),
                 workspace: workspace.id,
             };
             const ordered = {
@@ -971,7 +991,20 @@ export function runAskCommand(options, cwd) {
         });
         if (!loadedCatalogue.ok)
             return failed(loadedCatalogue.diagnostics);
-        const report = evaluateCatalogue(loadedCatalogue.catalogue, graph, compilation.profileContext);
+        // Loaded ahead of evaluation so the overlay feeds the one condition
+        // that reads it (unchallenged-evidence), then reused for the
+        // reconciliation summary below.
+        const evidenceDocuments = [];
+        for (const path of workspace.evidence) {
+            const loaded = loadEvidence({
+                path,
+                source: readFileSync(resolve(cwd, path), 'utf8'),
+            });
+            if (!loaded.ok)
+                return failed(loaded.diagnostics);
+            evidenceDocuments.push(loaded.evidence);
+        }
+        const report = evaluateCatalogue(loadedCatalogue.catalogue, graph, compilation.profileContext, evidenceDocuments.flatMap(({ observations }) => observations));
         const openQuestions = [];
         for (const wave of report.waves) {
             for (const question of wave.questions) {
@@ -1003,16 +1036,6 @@ export function runAskCommand(options, cwd) {
         }
         let reconciliation;
         if (workspace.evidence.length > 0) {
-            const evidenceDocuments = [];
-            for (const path of workspace.evidence) {
-                const loaded = loadEvidence({
-                    path,
-                    source: readFileSync(resolve(cwd, path), 'utf8'),
-                });
-                if (!loaded.ok)
-                    return failed(loaded.diagnostics);
-                evidenceDocuments.push(loaded.evidence);
-            }
             const evaluation = evaluateEvidenceWorkspace(graph, evidenceDocuments);
             if (!evaluation.ok)
                 return failed(evaluation.diagnostics);

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 <subject-id>] [--catalogue <catalogue.yaml>] [--facilitate] [--json]\n  yarramate apply <operations.yaml> <workspace.yaml> [--json]\n  yarramate ask <workspace.yaml> [--json]\n  yarramate ask <workspace.yaml> \"<free text>\" | <subject-id> ... | <projection.yaml> [--budget <tokens>] [--neighbours <n>] [--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>] [--neighbours <n>] [--catalogue <catalogue.yaml>] [--json]\n  yarramate ask <workspace.yaml> --where \"<free text>\" | <subject-id> ... [--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>] [--neighbours <n>] [--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 rtm <workspace.yaml> --out <directory>\n  yarramate export likec4 <likec4-project.yaml> <output-dir> <workspace.yaml> [--changed <git-range>]\n";
+export declare const usage = "Usage:\n  yarramate init <directory> [--no-pointer]\n  yarramate design <workspace.yaml> [--subject <subject-id>] [--catalogue <catalogue.yaml>] [--facilitate] [--json]\n  yarramate apply <operations.yaml> <workspace.yaml> [--json]\n  yarramate ask <workspace.yaml> [--json]\n  yarramate ask <workspace.yaml> \"<free text>\" | <subject-id> ... | <projection.yaml> [--budget <tokens>] [--neighbours <n>] [--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>] [--neighbours <n>] [--catalogue <catalogue.yaml>] [--json]\n  yarramate ask <workspace.yaml> --where \"<free text>\" | <subject-id> ... [--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>] [--neighbours <n>] [--json]\n  yarramate check <source.yaml> [source.yaml ...] [--json] [--strict]\n  yarramate reconcile <workspace.yaml> [--json]\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 rtm <workspace.yaml> --out <directory>\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

@@ -22,7 +22,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 <subject-id>] [--catalogue <catalogue.yaml>] [--facilitate] [--json]\n  yarramate apply <operations.yaml> <workspace.yaml> [--json]\n  yarramate ask <workspace.yaml> [--json]\n  yarramate ask <workspace.yaml> "<free text>" | <subject-id> ... | <projection.yaml> [--budget <tokens>] [--neighbours <n>] [--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>] [--neighbours <n>] [--catalogue <catalogue.yaml>] [--json]\n  yarramate ask <workspace.yaml> --where "<free text>" | <subject-id> ... [--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>] [--neighbours <n>] [--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 rtm <workspace.yaml> --out <directory>\n  yarramate export likec4 <likec4-project.yaml> <output-dir> <workspace.yaml> [--changed <git-range>]\n';
+export const usage = 'Usage:\n  yarramate init <directory> [--no-pointer]\n  yarramate design <workspace.yaml> [--subject <subject-id>] [--catalogue <catalogue.yaml>] [--facilitate] [--json]\n  yarramate apply <operations.yaml> <workspace.yaml> [--json]\n  yarramate ask <workspace.yaml> [--json]\n  yarramate ask <workspace.yaml> "<free text>" | <subject-id> ... | <projection.yaml> [--budget <tokens>] [--neighbours <n>] [--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>] [--neighbours <n>] [--catalogue <catalogue.yaml>] [--json]\n  yarramate ask <workspace.yaml> --where "<free text>" | <subject-id> ... [--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>] [--neighbours <n>] [--json]\n  yarramate check <source.yaml> [source.yaml ...] [--json] [--strict]\n  yarramate reconcile <workspace.yaml> [--json]\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 rtm <workspace.yaml> --out <directory>\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/cli.d.ts

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
 import { type CliResult } from './cli-support.js';
 export type { CliResult } from './cli-support.js';
+export declare const deriveInitId: (directory: string) => string;
 export declare function runCli(args: readonly string[], cwd?: string): CliResult;

package/dist/cli.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { existsSync, mkdirSync, readFileSync, writeFileSync, } from 'node:fs';
-import { dirname, relative, resolve } from 'node:path';
+import { basename, dirname, relative, resolve } from 'node:path';
 import { compileWorkspace } from './compiler.js';
 import { diagnosticJson, isMainModule, usage, versionResult, } from './cli-support.js';
 import { runAskCommand } from './ask-command.js';
@@ -13,8 +13,12 @@ import { deriveAttestationStaleness } from './attestation-staleness.js';
 import { reconcileEvidenceReports } from './reconciliation.js';
 import { loadWorkspaceManifest } from './workspace.js';
 const runReconciliation = (options, cwd) => {
-    const [workspacePath] = options;
-    if (options.length !== 1 ||
+    // Bare reconcile already emits JSON, so --json changes nothing — but a
+    // harness scripting "add --json to every verb" must not hit exit 2 on
+    // the one verb that treats it as unknown (#275). Accepted as a no-op.
+    const positional = options.filter((option) => option !== '--json');
+    const [workspacePath] = positional;
+    if (positional.length !== 1 ||
         workspacePath === undefined ||
         workspacePath.startsWith('-')) {
         return { exitCode: 2, stdout: '', stderr: usage };
@@ -89,6 +93,22 @@ const runReconciliation = (options, cwd) => {
         return { exitCode: 2, stdout: '', stderr: `${message}\n` };
     }
 };
+// The id grammar the document and workspace schemas share: a lowercase
+// letter first, then lowercase alphanumerics in single-hyphen segments.
+const initIdPattern = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+// The first check output should say the project's own name, not `main`
+// (#275, ADR 0112): the default id is the target directory's basename,
+// slugified to the shared id grammar. `init .` resolves before deriving,
+// so the cwd's basename is what gets named. `main` remains the fallback
+// when the basename yields nothing the schemas accept ('.', '..',
+// all-symbols, a leading digit).
+export const deriveInitId = (directory) => {
+    const slug = basename(directory)
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+    return initIdPattern.test(slug) ? slug : 'main';
+};
 const runInit = (options, cwd) => {
     const positional = options.filter((option) => option !== '--no-pointer');
     const writePointer = positional.length === options.length;
@@ -114,14 +134,15 @@ const runInit = (options, cwd) => {
             stderr: `${existing.join(' and ')} ${existing.length === 1 ? 'already exists' : 'already exist'}; nothing was changed\n`,
         };
     }
+    const workspaceId = deriveInitId(workspaceRoot);
     mkdirSync(dirname(documentPath), { recursive: true });
     writeFileSync(documentPath, 'format: yarramate/v1\n' +
-        'id: main\n' +
+        `id: ${workspaceId}\n` +
         'profile: yarramate/core@0.1\n' +
         'concepts: []\n' +
         'relationships: []\n', 'utf8');
     writeFileSync(manifestPath, 'format: yarramate/workspace/v1\n' +
-        'id: main\n' +
+        `id: ${workspaceId}\n` +
         'documents:\n' +
         '  - architecture/*.yaml\n' +
         'profiles: []\n' +

package/dist/compiler.d.ts

@@ -74,6 +74,18 @@ export interface ResolvedProfileContext {
     /** Kind identity -> the core kind it resolves to through lineage. */
     readonly conceptKindCoreAncestors: ReadonlyMap<string, CoreConceptKindId>;
     readonly relationshipKindCoreAncestors: ReadonlyMap<string, RelationshipKind>;
+    /**
+     * The core relationship kinds a pattern PORTS for a concept kind (#268
+     * phase 3, ADR 0124), keyed by kind identity. Only kinds that have a
+     * pattern with ports appear.
+     *
+     * A macro edge needs both ends to port its kind, so a consumer offering a
+     * palette between two instances intersects the two sets. Two raw groupings
+     * permit ten of the eleven kinds, which is no narrowing at all; the ports
+     * are what restore the guidance the relationship table gives everywhere
+     * else.
+     */
+    readonly patternPortKinds: ReadonlyMap<string, readonly RelationshipKind[]>;
     /**
      * The core relationship kinds the ArchiMate table permits between two
      * concept kind identities, resolved through lineage; undefined when either
@@ -104,7 +116,7 @@ export type ContextualCompilationResult = {
  */
 export interface ParsedWorkspaceSource {
     readonly source: string;
-    readonly kind: 'profile' | 'document';
+    readonly kind: 'profile' | 'document' | 'pattern';
     readonly value: unknown;
     readonly schemaDiagnostics: readonly Diagnostic[];
     /**