yarramate 1.4.1 → 1.6.0

package/dist/import-command.js

@@ -0,0 +1,156 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { runApplyCommand } from './apply-cli.js';
+import { humanDiagnostics, packageVersion, usage } from './cli-support.js';
+import { compileWorkspaceWithProfileContext } from './compiler.js';
+import { evaluateProjection } from './projection.js';
+import { loadWorkspaceManifest } from './workspace.js';
+import { buildWorkbookSheets } from './workbook.js';
+import { baselineSheets, mergeWorkbook } from './workbook-merge.js';
+import { operationsFrom, operationsDocument } from './workbook-operations.js';
+import { readWorkbook } from './workbook-read.js';
+import { writeFileSync, mkdtempSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { stringify } from 'yaml';
+/**
+ * `yarramate import xlsx <file> <workspace.yaml>` (#355, ADR 0127).
+ *
+ * The workbook carries its own ancestor, so this is a three-way merge rather
+ * than an overwrite: the author's edits are measured against `~Baseline`, the
+ * repository's drift is measured against the same, and only a field both moved
+ * is refused. Everything the author changed that the repository left alone
+ * merges cleanly, which is what makes a week-long workbook cycle usable.
+ *
+ * Edits land as `yarramate/operations/v1` through `apply`, so untouched YAML
+ * keeps its comments, key order and formatting, and the whole import passes
+ * the atomic compile gate. A workbook that would produce an uncompilable model
+ * is refused whole rather than half written.
+ */
+export async function runImportCommand(options, cwd) {
+    const [kind, ...rest] = options;
+    if (kind !== 'xlsx')
+        return { exitCode: 2, stdout: '', stderr: usage };
+    const json = rest.includes('--json');
+    const positionals = rest.filter((option) => option !== '--json');
+    const [workbookPath, workspacePath] = positionals;
+    if (positionals.length !== 2 ||
+        workbookPath === undefined ||
+        workspacePath === undefined) {
+        return { exitCode: 2, stdout: '', stderr: usage };
+    }
+    const manifestPath = resolve(cwd, workspacePath);
+    let manifestSource;
+    let workbookBytes;
+    try {
+        manifestSource = readFileSync(manifestPath, 'utf8');
+        workbookBytes = new Uint8Array(readFileSync(resolve(cwd, workbookPath)));
+    }
+    catch (cause) {
+        return {
+            exitCode: 1,
+            stdout: '',
+            stderr: `${cause instanceof Error ? cause.message : String(cause)}\n`,
+        };
+    }
+    const loaded = loadWorkspaceManifest({ path: workspacePath, source: manifestSource }, cwd);
+    if (!loaded.ok) {
+        return {
+            exitCode: 1,
+            stdout: '',
+            stderr: humanDiagnostics(loaded.diagnostics),
+        };
+    }
+    const workspace = loaded.workspace;
+    const sources = [
+        ...workspace.profiles,
+        ...workspace.patterns,
+        ...workspace.documents,
+    ].map((path) => ({ path, source: readFileSync(resolve(cwd, path), 'utf8') }));
+    const compilation = compileWorkspaceWithProfileContext(sources);
+    if (!compilation.ok) {
+        return {
+            exitCode: 1,
+            stdout: '',
+            stderr: humanDiagnostics(compilation.diagnostics),
+        };
+    }
+    const read = await readWorkbook(workbookBytes);
+    if (!read.ok) {
+        return { exitCode: 1, stdout: '', stderr: `${read.reason}\n` };
+    }
+    const baselineRows = read.sheets.get('~Baseline');
+    if (baselineRows === undefined) {
+        // Without the ancestor there is no way to tell the author's edit from the
+        // repository's drift, and guessing would silently discard one of them.
+        return {
+            exitCode: 1,
+            stdout: '',
+            stderr: 'This workbook carries no ~Baseline sheet, so it was not produced by ' +
+                '`yarramate export xlsx` and there is no ancestor to merge against.\n',
+        };
+    }
+    const projectionId = read.sheets.get('~Meta')?.find((row) => row[0] === 'Projection')?.[1];
+    const result = evaluateProjection(compilation.graph, {
+        format: 'yarramate/projection/v1',
+        id: projectionId ?? 'imported',
+        version: '1.0',
+        query: {},
+    }, compilation.profileContext);
+    const current = buildWorkbookSheets(result, {
+        workspace: workspace.id,
+        yarramateVersion: packageVersion,
+        sourceDigests: {},
+        conceptKinds: [],
+        relationshipKinds: [],
+        statuses: [],
+    });
+    const report = mergeWorkbook(read.sheets, baselineSheets(baselineRows), current);
+    const planned = operationsFrom(report, read.sheets);
+    if (report.conflicts.length > 0) {
+        const lines = report.conflicts.map(({ sheet, id, column, from, to, theirs }) => `  ${sheet} "${id}" ${column}: you wrote ${JSON.stringify(to)}, ` +
+            `the workspace now has ${JSON.stringify(theirs)}, both from ${JSON.stringify(from)}`);
+        return {
+            exitCode: 1,
+            stdout: '',
+            stderr: `${report.conflicts.length} field${report.conflicts.length === 1 ? '' : 's'} changed in the workbook and in the workspace since the workbook was made. ` +
+                'Nothing was written.\n' +
+                `${lines.join('\n')}\n`,
+        };
+    }
+    const notes = [
+        ...planned.refusals.map((reason) => `  not imported: ${reason}`),
+        ...report.missing.map(({ sheet, id }) => `  not imported: ${sheet} "${id}" is absent from the workbook; ` +
+            'a missing row is never a deletion'),
+    ];
+    if (planned.operations.length === 0) {
+        const summary = `Nothing to import: the workbook matches the workspace.\n`;
+        return {
+            exitCode: 0,
+            stdout: json
+                ? `${JSON.stringify({ format: 'yarramate/import-result/v1', operations: 0, notes }, null, 2)}\n`
+                : summary + (notes.length > 0 ? `${notes.join('\n')}\n` : ''),
+            stderr: '',
+        };
+    }
+    // Handed to `apply` rather than written directly: one mutation path, one
+    // atomic gate, and the surgical YAML editing that keeps comments.
+    const scratch = mkdtempSync(join(tmpdir(), 'yarramate-import-'));
+    const operationsPath = join(scratch, 'operations.yaml');
+    writeFileSync(operationsPath, stringify(operationsDocument(planned.operations)), 'utf8');
+    const applied = runApplyCommand([operationsPath, workspacePath], cwd);
+    if (applied.exitCode !== 0)
+        return applied;
+    const summary = `Imported ${planned.operations.length} change${planned.operations.length === 1 ? '' : 's'} from ${workbookPath}\n`;
+    return {
+        exitCode: 0,
+        stdout: json
+            ? `${JSON.stringify({
+                format: 'yarramate/import-result/v1',
+                operations: planned.operations.length,
+                notes,
+            }, null, 2)}\n`
+            : summary + (notes.length > 0 ? `${notes.join('\n')}\n` : ''),
+        stderr: '',
+    };
+}

package/dist/interrogate-command.d.ts

@@ -203,5 +203,5 @@ export type CatalogueLoadResult = {
     readonly ok: false;
     readonly diagnostics: readonly Diagnostic[];
 };
-export declare function loadQuestionCatalogue(catalogueSource: WorkspaceSource): CatalogueLoadResult;
+export declare function loadQuestionCatalogue(catalogueSource: WorkspaceSource, profileContext?: ResolvedProfileContext): CatalogueLoadResult;
 export declare function renderInterrogationReport(report: InterrogationReport): string;

package/dist/interrogate-command.js

@@ -527,9 +527,97 @@ export function evaluateCatalogue(catalogue, graph, profileContext, evidence) {
         waves,
     };
 }
+/**
+ * Every qualified kind a catalogue names, from all three fields that carry
+ * one.
+ *
+ * All three die the same way when the kind does not resolve, and two of them
+ * are easy to forget. A trigger's kind never matches, so the question never
+ * opens. A subject selector's kind selects nothing, so the question is scoped
+ * to an empty set. A wave gate's kind never holds, so after #334 the whole
+ * wave never opens and carries no questions at all - one typo silently
+ * retiring a wave (#351).
+ */
+const kindReferencesOf = (catalogue) => {
+    const found = [];
+    const fromCondition = (condition, path) => {
+        if (typeof condition !== 'object' || condition === null)
+            return;
+        for (const field of ['kinds', 'counterpartKinds']) {
+            const value = condition[field];
+            if (!Array.isArray(value))
+                continue;
+            value.forEach((kind, index) => {
+                if (typeof kind === 'string')
+                    found.push({ kind, path: [...path, field, index] });
+            });
+        }
+    };
+    catalogue.waves.forEach((wave, waveIndex) => {
+        ;
+        (wave.opensWhen ?? []).forEach((condition, conditionIndex) => {
+            fromCondition(condition, ['waves', waveIndex, 'opensWhen', conditionIndex]);
+        });
+    });
+    catalogue.questions.forEach((question, questionIndex) => {
+        ;
+        (question.subjects?.kinds ?? []).forEach((kind, index) => {
+            found.push({
+                kind,
+                path: ['questions', questionIndex, 'subjects', 'kinds', index],
+            });
+        });
+        question.trigger.forEach((condition, conditionIndex) => {
+            fromCondition(condition, [
+                'questions',
+                questionIndex,
+                'trigger',
+                conditionIndex,
+            ]);
+        });
+    });
+    return found;
+};
+/**
+ * Kinds this catalogue names that the profile they belong to does not have.
+ *
+ * The check is deliberately narrow, and the narrowness is the design (#351).
+ * A kind is reported ONLY when its profile is loaded and the kind is absent
+ * from it, which is unambiguously a typo. A kind whose profile is not loaded
+ * at all is left alone, because that is a legitimately dormant cross-profile
+ * question rather than a mistake: `core-enrichment` names four
+ * `yarramate/policy@0.1` constraint kinds, and `yarramate/policy@0.1` loads
+ * only when a document selects it or a profile extends it. Reporting those
+ * four would put four false positives on the catalogue this repository ships,
+ * and a check that cries wolf on its own catalogue gets turned off.
+ *
+ * Resolution is tested against the kind maps rather than a declared-kinds
+ * list, so a kind inherited through `extends` counts. A profile that declares
+ * no kinds of its own and inherits every one of them is the case a
+ * declared-kinds check would call entirely missing.
+ */
+const unresolvableKinds = (catalogue, profileContext) => {
+    const known = new Set([
+        ...profileContext.conceptKindLineages.keys(),
+        ...profileContext.relationshipKindLineages.keys(),
+    ]);
+    const loadedProfiles = new Set();
+    for (const identity of known) {
+        const hash = identity.indexOf('#');
+        if (hash > 0)
+            loadedProfiles.add(identity.slice(0, hash));
+    }
+    return kindReferencesOf(catalogue).filter(({ kind }) => {
+        if (known.has(kind))
+            return false;
+        const hash = kind.indexOf('#');
+        // Profile absent entirely: dormant, not wrong.
+        return hash > 0 && loadedProfiles.has(kind.slice(0, hash));
+    });
+};
 // Shared by interrogate and design: schema validation plus the YM911
 // undeclared-wave check, both source-located against the catalogue file.
-export function loadQuestionCatalogue(catalogueSource) {
+export function loadQuestionCatalogue(catalogueSource, profileContext) {
     const loadedCatalogue = loadSourceDocument(catalogueSource, validateCatalogue, 'Question catalogue');
     if (!loadedCatalogue.ok) {
         return { ok: false, diagnostics: loadedCatalogue.diagnostics };
@@ -549,6 +637,20 @@ export function loadQuestionCatalogue(catalogueSource) {
     if (waveDiagnostics.length > 0) {
         return { ok: false, diagnostics: waveDiagnostics };
     }
+    // Only when a caller has a compiled workspace to check against. Without one
+    // there is no way to tell a typo from a kind whose profile simply is not
+    // here, and guessing would be the false positive this check exists to avoid.
+    const kindDiagnostics = profileContext === undefined
+        ? []
+        : unresolvableKinds(catalogue, profileContext).map(({ kind, path }) => ({
+            severity: 'error',
+            code: 'YM914',
+            message: `Kind "${kind}" is not declared by profile "${kind.slice(0, kind.indexOf('#'))}", which this workspace loads, so the question can never fire`,
+            ...locateSourcePath(catalogueSource.path, loadedCatalogue.document.yaml, loadedCatalogue.document.lineCounter, path, `/${path.join('/')}`),
+        }));
+    if (kindDiagnostics.length > 0) {
+        return { ok: false, diagnostics: kindDiagnostics };
+    }
     return { ok: true, catalogue };
 }
 // Shared by interrogate and `ask --open`: the wave-by-wave human report.