yarramate 1.27.0 → 1.28.0

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];
+};

package/docs/EVIDENCE.md

@@ -115,6 +115,13 @@ This command evaluates every evidence overlay declared by the manifest and
 emits deterministic `yarramate/reconciliation-report/v1` JSON. Its normative
 schema is `schema/yarramate-reconciliation-report.schema.json`.
 
+`--text` says the same report to a person (ADR 0153): the summary as
+labelled rows, one line per finding with its message beneath, then the
+subjects without evidence, the unclaimed artifacts and the notes, each only
+when it holds something. Nothing is added or judged; the order is the
+report's. The JSON stays the default, and `--json` stays the accepted no-op
+it has been; asking for both at once is refused.
+
 The summary counts all observations. The `findings` array contains only
 `contradicted`, `unknown`, and `not-observed` results, ordered by target and
 provider, plus the `stale-attestation` and `unconfirmed-attestation`

package/package.json

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