yarramate 1.27.0 → 1.29.0

package/dist/adapters/visual/wire.d.ts

@@ -37,6 +37,20 @@ export interface VisualQuestionEntry {
      */
     readonly trigger?: readonly CatalogueCondition[];
 }
+/**
+ * The next load-bearing open question (#534, ADR 0154): the row `design`
+ * would serve first, by design's own rule (the first open question in wave
+ * order, then catalogue order within the wave; a subject-scoped question
+ * names the first open subject it is open for). Computed host-side beside
+ * the overlay so both hosts and the browser agree on which row it is, and
+ * nobody re-derives the rule from the lists.
+ */
+export interface VisualNextQuestion extends VisualQuestionEntry {
+    readonly wave: string;
+    /** The subject it is open for; absent for a workspace-scoped question. */
+    readonly subjectId?: string;
+    readonly subjectName?: string;
+}
 /**
  * The interrogation report, folded for drawing (#292).
  *
@@ -56,6 +70,12 @@ export interface VisualInterrogationOverlay {
     readonly workspace: readonly VisualQuestionEntry[];
     /** Open questions per qualified subject id — `CanvasNode.id`'s space. */
     readonly subjects: Readonly<Record<string, readonly VisualQuestionEntry[]>>;
+    /**
+     * The one to ask next (#534). Absent when nothing is open, or when the
+     * host that built this overlay predates the field: a reader treats absence
+     * as "no next question", never as a fault.
+     */
+    readonly next?: VisualNextQuestion;
 }
 /** The resolved graph a session renders, as the browser receives it. */
 export interface VisualRenderedModel {

package/dist/adapters/visual/workspace-model.js

@@ -132,6 +132,10 @@ dismissed = []) => {
         .map(({ questionId, subject }) => `${questionId}\u0000${subject}`));
     const workspace = [];
     const subjects = {};
+    // The first row kept is the next question (#534): the loop already walks
+    // waves in order and questions in catalogue order, which is `design`'s
+    // rule, so "first kept" is the rule and not a second one.
+    let next;
     for (const wave of report.waves) {
         for (const question of wave.questions) {
             if (!question.open)
@@ -149,22 +153,31 @@ dismissed = []) => {
                 trigger: question.trigger,
             };
             if (question.subjects === undefined) {
-                workspace.push({
+                const row = {
                     ...base,
                     scope: "workspace",
                     question: question.question,
-                });
+                };
+                workspace.push(row);
+                next ??= { ...row, wave: wave.id };
                 continue;
             }
             for (const subject of question.subjects) {
                 if (dismissedForSubject.has(`${question.id}\u0000${subject.id}`)) {
                     continue;
                 }
-                (subjects[subject.id] ??= []).push({
+                const row = {
                     ...base,
                     scope: "subject",
                     question: subject.question,
-                });
+                };
+                (subjects[subject.id] ??= []).push(row);
+                next ??= {
+                    ...row,
+                    wave: wave.id,
+                    subjectId: subject.id,
+                    ...(subject.name === undefined ? {} : { subjectName: subject.name }),
+                };
             }
         }
     }
@@ -173,6 +186,7 @@ dismissed = []) => {
         semantics: report.semantics,
         workspace,
         subjects,
+        ...(next === undefined ? {} : { next }),
     };
 };
 /**

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> [--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 xlsx <projection.yaml> <workspace.yaml> --out <file>\n  yarramate import xlsx <workbook.xlsx> <workspace.yaml> [--json]\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 | --text]\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 xlsx <projection.yaml> <workspace.yaml> --out <file>\n  yarramate import xlsx <workbook.xlsx> <workspace.yaml> [--json]\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> [--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 xlsx <projection.yaml> <workspace.yaml> --out <file>\n  yarramate import xlsx <workbook.xlsx> <workspace.yaml> [--json]\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 | --text]\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 xlsx <projection.yaml> <workspace.yaml> --out <file>\n  yarramate import xlsx <workbook.xlsx> <workspace.yaml> [--json]\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.js

@@ -13,16 +13,22 @@ import { evaluateEvidenceWorkspace, loadEvidence, } from './evidence.js';
 import { deriveArtifactCoverage } from './artifact-coverage.js';
 import { deriveAttestationStaleness } from './attestation-staleness.js';
 import { reconcileEvidenceReports } from './reconciliation.js';
+import { reconciliationReportText } from './reconciliation-text.js';
 import { loadWorkspaceManifest } from './workspace.js';
 const runReconciliation = (options, cwd) => {
     // 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');
+    // --text is the same report for a person (#526, ADR 0153); asking for
+    // both shapes at once names no output, so it is refused like any other
+    // malformed call.
+    const text = options.includes('--text');
+    const positional = options.filter((option) => option !== '--json' && option !== '--text');
     const [workspacePath] = positional;
     if (positional.length !== 1 ||
         workspacePath === undefined ||
-        workspacePath.startsWith('-')) {
+        workspacePath.startsWith('-') ||
+        (text && options.includes('--json'))) {
         return { exitCode: 2, stdout: '', stderr: usage };
     }
     try {
@@ -89,9 +95,12 @@ const runReconciliation = (options, cwd) => {
         // cwd, so the same command reports the same coverage wherever it was
         // invoked (ADR 0130).
         const coverage = deriveArtifactCoverage(dirname(resolve(cwd, workspacePath)), loadedWorkspace.manifest.coverage);
+        const report = reconcileEvidenceReports(loadedWorkspace.workspace.id, evaluation.reports, compilation.graph, staleness, coverage);
         return {
             exitCode: 0,
-            stdout: `${JSON.stringify(reconcileEvidenceReports(loadedWorkspace.workspace.id, evaluation.reports, compilation.graph, staleness, coverage), null, 2)}\n`,
+            stdout: text
+                ? reconciliationReportText(report)
+                : `${JSON.stringify(report, null, 2)}\n`,
             stderr: '',
         };
     }

package/dist/reconciliation-text.d.ts

@@ -0,0 +1,13 @@
+import type { ReconciliationReport } from './reconciliation.js';
+/**
+ * The reconciliation report for a person (#526, ADR 0153).
+ *
+ * The JSON report is the contract (EVIDENCE.md) and stays the verb's
+ * default; this is the same report said in lines, in the same order, with
+ * nothing added and nothing judged. Every count the summary carries is on
+ * the first lines; every finding is one line, plus its message where the
+ * provider left one; the lists that follow appear only when they hold
+ * something, and the notes close, because they are what the report says
+ * about its own limits.
+ */
+export declare const reconciliationReportText: (report: ReconciliationReport) => string;

package/dist/reconciliation-text.js

@@ -0,0 +1,76 @@
+/**
+ * The reconciliation report for a person (#526, ADR 0153).
+ *
+ * The JSON report is the contract (EVIDENCE.md) and stays the verb's
+ * default; this is the same report said in lines, in the same order, with
+ * nothing added and nothing judged. Every count the summary carries is on
+ * the first lines; every finding is one line, plus its message where the
+ * provider left one; the lists that follow appear only when they hold
+ * something, and the notes close, because they are what the report says
+ * about its own limits.
+ */
+export const reconciliationReportText = (report) => {
+    const { summary } = report;
+    const lines = [];
+    const row = (label, ...cells) => {
+        lines.push(`${label.padEnd(16)}${cells.join('  ')}`);
+    };
+    row('reconciliation', report.workspace);
+    row('observations', String(summary.observations), `confirmed ${summary.confirmed}`, `contradicted ${summary.contradicted}`, `unknown ${summary.unknown}`, `not observed ${summary.notObserved}`, ...(summary.unsupportedAbsences === undefined
+        ? []
+        : [`unsupported absences ${summary.unsupportedAbsences}`]));
+    if (summary.staleAttestations !== undefined ||
+        summary.unconfirmedAttestations !== undefined) {
+        row('attestations', `stale ${summary.staleAttestations ?? 0}`, `unconfirmed ${summary.unconfirmedAttestations ?? 0}`);
+    }
+    row('expectations', `compared ${summary.expectationsCompared}`, `without observation ${summary.expectationsWithoutObservation}`);
+    row('subjects', `without evidence ${summary.subjectsWithoutEvidence}`);
+    row('artifacts', ...(summary.artifactsInScope === undefined
+        ? ['not assessed']
+        : [
+            `in scope ${summary.artifactsInScope}`,
+            `unclaimed ${summary.unclaimedArtifacts ?? 0}`,
+        ]));
+    row('findings', String(summary.findings));
+    const section = (title, body) => {
+        if (body.length === 0)
+            return;
+        lines.push('', title);
+        lines.push(...body);
+    };
+    section('Findings', report.findings.flatMap((finding) => findingLines(finding)));
+    section('Subjects without evidence', (report.unobservedSubjects ?? []).map((id) => `  ${id}`));
+    section('Expectations without observation', (report.unobservedExpectations ?? []).map((expectation) => `  ${expectation.subject}  ${expectation.provider}/${expectation.key} expected ${expectation.expected}  ${expectation.declared.path}:${expectation.declared.line}`));
+    section('Unclaimed artifacts', (report.unclaimedArtifacts ?? []).map((path) => `  ${path}`));
+    section('Coverage scope', (report.coverageScope ?? []).map((pattern) => `  ${pattern}`));
+    section('Notes', (report.notes ?? []).map((note) => `  ${note}`));
+    return `${lines.join('\n')}\n`;
+};
+const findingLines = (finding) => {
+    const label = finding.result.replace(/-/g, ' ').padEnd(24);
+    if (finding.result === 'stale-attestation') {
+        const changed = finding.changedAt === undefined
+            ? ''
+            : `; the subject's wording changed ${finding.changedAt}`;
+        return [
+            `  ${label}${finding.target.id}  ${finding.attestation.topic}, by ${finding.attestation.by} on ${finding.attestation.on}${changed}  ${finding.evidence.uri}`,
+        ];
+    }
+    if (finding.result === 'unconfirmed-attestation') {
+        return [
+            `  ${label}${finding.target.id}  ${finding.attestation.topic}, by ${finding.attestation.by}, recorded by ${finding.attestation.recordedBy} on ${finding.attestation.on}  ${finding.declared.path}:${finding.declared.line}`,
+        ];
+    }
+    const head = `  ${label}${finding.target.type === 'claim' ? 'claim ' : ''}${finding.target.id}  ${finding.provider}, ${finding.evidenceDocument}  ${finding.evidence.uri}`;
+    const detail = [];
+    if (finding.asserted !== undefined) {
+        detail.push(`    asserts ${finding.asserted.from} -${finding.asserted.kind}-> ${finding.asserted.to}`);
+    }
+    if (finding.expectation !== undefined) {
+        detail.push(`    expected ${finding.expectation.key} = ${finding.expectation.expected}, observed ${finding.expectation.observed}  ${finding.expectation.declared.path}:${finding.expectation.declared.line}`);
+    }
+    if (finding.evidence.message !== undefined) {
+        detail.push(`    ${finding.evidence.message}`);
+    }
+    return [head, ...detail];
+};