yarramate 1.6.0 → 1.7.0

package/dist/interrogate-command.js

@@ -451,7 +451,15 @@ const describeCounterparts = (index, question, subjectId) => {
         return name === undefined ? id : `${name} (${id})`;
     });
 };
-export function evaluateCatalogue(catalogue, graph, profileContext, evidence) {
+export function evaluateCatalogue(catalogue, graph, profileContext, evidence, 
+/**
+ * Contributing catalogues, from {@link composeCatalogues}. Composition
+ * happens BEFORE evaluation and hands this function an ordinary catalogue,
+ * so the only thing evaluation learns about composition is what to name in
+ * the report. A fifth optional parameter rather than an options object,
+ * because this signature is published and a consumer already calls it.
+ */
+catalogues) {
     const index = indexGraph(graph);
     let open = 0;
     let openQuestions = 0;
@@ -512,6 +520,11 @@ export function evaluateCatalogue(catalogue, graph, profileContext, evidence) {
     return {
         format: 'yarramate/interrogation-report/v1',
         catalogue: `${catalogue.id}@${catalogue.version}`,
+        // Only when composition actually happened. A single-catalogue report is
+        // byte-identical to what it was before this existed.
+        ...(catalogues === undefined || catalogues.length < 2
+            ? {}
+            : { catalogues }),
         semantics: INTERROGATION_SEMANTICS_VERSION,
         summary: {
             // Questions in OPENED waves only (#334, ADR 0125). A closed wave's
@@ -615,43 +628,196 @@ const unresolvableKinds = (catalogue, profileContext) => {
         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, profileContext) {
-    const loadedCatalogue = loadSourceDocument(catalogueSource, validateCatalogue, 'Question catalogue');
-    if (!loadedCatalogue.ok) {
-        return { ok: false, diagnostics: loadedCatalogue.diagnostics };
+const loadCatalogueDocument = (catalogueSource) => {
+    const loaded = loadSourceDocument(catalogueSource, validateCatalogue, 'Question catalogue');
+    if (!loaded.ok)
+        return { ok: false, diagnostics: loaded.diagnostics };
+    return {
+        ok: true,
+        document: {
+            source: catalogueSource,
+            catalogue: loaded.document.value,
+            locate: (path) => locateSourcePath(catalogueSource.path, loaded.document.yaml, loaded.document.lineCounter, path, `/${path.join('/')}`),
+        },
+    };
+};
+/**
+ * The YM911 undeclared-wave check, against a set of wave ids that may be
+ * WIDER than the catalogue's own.
+ *
+ * That width is the whole of #345. A project catalogue's reason to exist is
+ * adding "one more Assurance question for this client" to a wave the domain
+ * catalogue declared, so checking each file against only its own waves would
+ * refuse precisely the case the feature enables. Composed, the set is the
+ * union; alone, it is the catalogue's own and the check is what it always was.
+ */
+const undeclaredWaveDiagnostics = ({ catalogue, locate }, declaredWaves) => catalogue.questions.flatMap((question, questionIndex) => declaredWaves.has(question.wave)
+    ? []
+    : [
+        {
+            severity: 'error',
+            code: 'YM911',
+            message: `Question "${question.id}" references undeclared wave "${question.wave}"`,
+            ...locate(['questions', questionIndex, 'wave']),
+        },
+    ]);
+const unresolvableKindDiagnostics = ({ catalogue, locate }, profileContext) => 
+// 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.
+profileContext === undefined
+    ? []
+    : unresolvableKinds(catalogue, profileContext).map((reference) => ({
+        severity: 'error',
+        code: 'YM914',
+        message: `Kind "${reference.kind}" is not declared by profile "${reference.kind.slice(0, reference.kind.indexOf('#'))}", which this workspace loads, so the question can never fire`,
+        ...locate(reference.path),
+    }));
+/**
+ * A catalogue is qualified on the way OUT, never in what an author writes.
+ *
+ * The authored schema keeps ids local (`^[a-z][a-z0-9-]*$`) and that does not
+ * change; a consultant writes `regulator-signoff`, not
+ * `consulting#regulator-signoff`. The engine qualifies when it composes, which
+ * is the only moment two catalogues can be confused for each other.
+ *
+ * NO VERSION, and that is the decision rather than an omission (ADR 0129).
+ * `core-enrichment` went 1.0 to 1.3 in a single day renaming nothing; a
+ * versioned identity would have stranded every stored dismissal in every
+ * adopter's database three times that day, for changes that removed no
+ * question. Versioned identity is safe for things that are AUTHORED - a
+ * document keeps naming the version it was written against and an author
+ * updates it deliberately - and unsafe for things that are STORED, because a
+ * row in someone's database has no author to update it.
+ */
+export const qualifiedQuestionId = (catalogueId, questionId) => `${catalogueId}#${questionId}`;
+/**
+ * Compose a base catalogue with the ones a workspace carries (#345, ADR 0129).
+ *
+ * ADDITIVE. `--catalogue` and `MountOptions.catalogue` replace the base; this
+ * adds to it, which is what lets a consultant author a question at any point
+ * in an engagement with no product release.
+ *
+ * A WAVE IS DECLARED EXACTLY ONCE across the resolved set, and any catalogue
+ * may contribute questions to a wave it did not declare. That one rule settles
+ * three questions composition would otherwise raise. Wave identity: a project
+ * catalogue joins a declared wave rather than colliding with it. Ordering:
+ * only a declaration places a wave, so the base's order is untouched and new
+ * waves append. And the `opensWhen` precedence ADR 0125 made load-bearing does
+ * not arise at all, because there is only ever one declarer to ask.
+ *
+ * QUALIFICATION IS A PROPERTY OF COMPOSITION, NOT OF EVALUATION. A caller
+ * that hands `evaluateCatalogue` a catalogue directly still gets local ids,
+ * exactly as before this existed. Route through here even for ONE catalogue -
+ * which is what every CLI verb does - and ids are qualified from the start, so
+ * they do not change later when a workspace first carries a question of its
+ * own. That transition is the one thing an adopter keying stored judgments on
+ * a question id must not experience, and composing unconditionally is how it
+ * is avoided.
+ *
+ * ID COLLISIONS DISSOLVE rather than being resolved. Two catalogues may both
+ * carry `outcome-missing`; qualified, they are two different questions. There
+ * is no merge rule, no last-wins and no refusal, because there is nothing to
+ * merge.
+ */
+export function composeCatalogues(sources, profileContext) {
+    const documents = [];
+    const loadDiagnostics = [];
+    for (const source of sources) {
+        const loaded = loadCatalogueDocument(source);
+        if (loaded.ok)
+            documents.push(loaded.document);
+        else
+            loadDiagnostics.push(...loaded.diagnostics);
+    }
+    if (loadDiagnostics.length > 0) {
+        return { ok: false, diagnostics: loadDiagnostics };
     }
-    const catalogue = loadedCatalogue.document.value;
-    const waveIds = new Set(catalogue.waves.map(({ id }) => id));
-    const waveDiagnostics = catalogue.questions.flatMap((question, questionIndex) => waveIds.has(question.wave)
-        ? []
-        : [
-            {
+    const base = documents[0];
+    if (base === undefined) {
+        // Never reached through the CLI, which always has the shipped catalogue,
+        // but an empty set must not compose into an empty catalogue that reports
+        // a finished interview.
+        return {
+            ok: false,
+            diagnostics: [
+                {
+                    severity: 'error',
+                    code: 'YM915',
+                    message: 'No question catalogue to compose',
+                    path: '',
+                    pointer: '',
+                    line: 1,
+                    column: 1,
+                },
+            ],
+        };
+    }
+    // Declared exactly once. A second declaration is refused rather than merged,
+    // because the two carry independent `opensWhen` gates and silently picking
+    // one would decide when a wave opens by file order.
+    const declaredBy = new Map();
+    const duplicates = [];
+    for (const document of documents) {
+        document.catalogue.waves.forEach((wave, waveIndex) => {
+            const first = declaredBy.get(wave.id);
+            if (first === undefined) {
+                declaredBy.set(wave.id, document);
+                return;
+            }
+            duplicates.push({
                 severity: 'error',
-                code: 'YM911',
-                message: `Question "${question.id}" references undeclared wave "${question.wave}"`,
-                ...locateSourcePath(catalogueSource.path, loadedCatalogue.document.yaml, loadedCatalogue.document.lineCounter, ['questions', questionIndex, 'wave'], `/questions/${questionIndex}/wave`),
+                code: 'YM915',
+                message: `Wave "${wave.id}" is already declared by catalogue "${first.catalogue.id}" ` +
+                    `(${first.source.path}). A wave is declared once and contributed to freely: ` +
+                    'drop the declaration here and questions in this catalogue will join it.',
+                ...document.locate(['waves', waveIndex, 'id']),
+            });
+        });
+    }
+    if (duplicates.length > 0)
+        return { ok: false, diagnostics: duplicates };
+    const declaredWaves = new Set(declaredBy.keys());
+    const crossDiagnostics = documents.flatMap((document) => [
+        ...undeclaredWaveDiagnostics(document, declaredWaves),
+        ...unresolvableKindDiagnostics(document, profileContext),
+    ]);
+    if (crossDiagnostics.length > 0) {
+        return { ok: false, diagnostics: crossDiagnostics };
+    }
+    return {
+        ok: true,
+        composed: {
+            catalogue: {
+                ...base.catalogue,
+                // The base names the composition, which is why the report's
+                // `catalogue` field keeps its value shape while `catalogues` lists
+                // every contributor.
+                waves: documents.flatMap(({ catalogue }) => catalogue.waves),
+                questions: documents.flatMap(({ catalogue }) => catalogue.questions.map((question) => ({
+                    ...question,
+                    id: qualifiedQuestionId(catalogue.id, question.id),
+                }))),
             },
-        ]);
+            catalogues: documents.map(({ catalogue }) => `${catalogue.id}@${catalogue.version}`),
+        },
+    };
+}
+// Shared by interrogate and design: schema validation plus the YM911
+// undeclared-wave check, both source-located against the catalogue file.
+export function loadQuestionCatalogue(catalogueSource, profileContext) {
+    const loaded = loadCatalogueDocument(catalogueSource);
+    if (!loaded.ok)
+        return { ok: false, diagnostics: loaded.diagnostics };
+    const waveDiagnostics = undeclaredWaveDiagnostics(loaded.document, new Set(loaded.document.catalogue.waves.map(({ id }) => id)));
     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('/')}`),
-        }));
+    const kindDiagnostics = unresolvableKindDiagnostics(loaded.document, profileContext);
     if (kindDiagnostics.length > 0) {
         return { ok: false, diagnostics: kindDiagnostics };
     }
-    return { ok: true, catalogue };
+    return { ok: true, catalogue: loaded.document.catalogue };
 }
 // Shared by interrogate and `ask --open`: the wave-by-wave human report.
 export function renderInterrogationReport(report) {

package/dist/interrogation-entry.d.ts

@@ -1 +1 @@
-export { INTERROGATION_SEMANTICS_VERSION, evaluateCatalogue, loadQuestionCatalogue, renderInterrogationReport, renderQuestion, type CatalogueCondition, type CatalogueEvidenceObservation, type CatalogueLoadResult, type CatalogueQuestion, type CatalogueSelector, type InterrogationReport, type InterrogationSummary, type OpenSubject, type QuestionCatalogue, type ReportQuestion, type ReportWave, } from './interrogate-command.js';
+export { INTERROGATION_SEMANTICS_VERSION, composeCatalogues, qualifiedQuestionId, evaluateCatalogue, loadQuestionCatalogue, renderInterrogationReport, renderQuestion, type CatalogueCompositionResult, type ComposedCatalogue, type CatalogueCondition, type CatalogueEvidenceObservation, type CatalogueLoadResult, type CatalogueQuestion, type CatalogueSelector, type InterrogationReport, type InterrogationSummary, type OpenSubject, type QuestionCatalogue, type ReportQuestion, type ReportWave, } from './interrogate-command.js';

package/dist/interrogation-entry.js

@@ -7,4 +7,4 @@
 // alone: catalogue loading takes a WorkspaceSource, evaluation takes an
 // in-memory graph, and a test pins the import graph free of Node builtins.
 // The same shape the visual-graph projector uses (`./adapter/visual-graph`).
-export { INTERROGATION_SEMANTICS_VERSION, evaluateCatalogue, loadQuestionCatalogue, renderInterrogationReport, renderQuestion, } from './interrogate-command.js';
+export { INTERROGATION_SEMANTICS_VERSION, composeCatalogues, qualifiedQuestionId, evaluateCatalogue, loadQuestionCatalogue, renderInterrogationReport, renderQuestion, } from './interrogate-command.js';

package/dist/projection.d.ts

@@ -108,6 +108,53 @@ export interface ProjectionExclusion {
     readonly id: string;
     readonly facet: ConceptFacet;
 }
+/** A query facet naming something the model does not have. */
+export interface UnmatchedSelector {
+    readonly facet: string;
+    readonly value: string;
+    /** The closest name the facet does offer, when one is close enough to be a likely typo. */
+    readonly nearest?: string;
+}
+/**
+ * Every value in a projection query that names nothing.
+ *
+ * A projection is a DOCUMENT, and a query holds references the same way a
+ * relationship does. YarraMate refuses a relationship pointing at a concept
+ * that does not exist; it did not refuse a query naming a state that does not
+ * exist, and the symptom is silent. `states: [target-stat]` selects no state,
+ * which selects no subject, which exports a clean empty artifact with exit 0.
+ * Someone hands that to a client.
+ *
+ * Checked at `check`, not at `export`, because the typo is in a file rather
+ * than in an invocation: CI catches it, and every verb over the same
+ * projection inherits the guard instead of each growing its own.
+ *
+ * ONLY FACETS WITH A CLOSED NAMESPACE ARE CHECKED. `statuses` and
+ * `excludeStatuses` are schema enums, refused upstream before this runs.
+ * Everything else names something: `owners` and `constraints` are REFS to
+ * concepts, which the compiler itself proves by refusing an unresolved owner
+ * with YM304, so their namespace is the subject list like `subjects`.
+ *
+ * Each namespace is derived the way the FILTER derives it, so the check cannot
+ * drift from what it guards: `documents` reads the same provenance the
+ * `documents` facet compares against, and `states` is the same
+ * `yarramate/state/type` scan `conceptSelector` runs.
+ *
+ * A kind whose profile is not loaded is DORMANT rather than wrong, the same
+ * distinction #351 drew for question catalogues, so the kind facets are
+ * checked only when a profile context is present.
+ *
+ * An empty RESULT is not reported here and must not be. A query whose every
+ * name resolves and which selects nothing is a real answer to a real question:
+ * a target state nobody has populated yet is empty, correctly.
+ */
+export declare function unmatchedSelectors(graph: SemanticGraph, projection: ProjectionDefinition, profileContext?: ResolvedProfileContext): readonly UnmatchedSelector[];
+/**
+ * {@link unmatchedSelectors} as diagnostics, built HERE rather than at each
+ * caller so `check`, and anything that adopts this later, refuse in identical
+ * words with an identical code.
+ */
+export declare function projectionReferenceDiagnostics(source: WorkspaceSource, projection: ProjectionDefinition, graph: SemanticGraph, profileContext?: ResolvedProfileContext): readonly Diagnostic[];
 /**
  * Every concept a query leaves out, and the facet that left it out.
  *

package/dist/projection.js

@@ -1,6 +1,7 @@
 import Ajv2020Import from 'ajv/dist/2020.js';
 import { isDeclaredNonGoal } from './brief.js';
 import { loadSourceDocument } from './source-document.js';
+import { similarity } from './subject-identity.js';
 import projectionSchema from '../schema/yarramate-projection.schema.json' with { type: 'json'
 };
 const ajv2020Module = Ajv2020Import;
@@ -182,6 +183,131 @@ const conceptSelector = (graph, projection, profileContext) => {
         },
     };
 };
+/** Below this, a suggestion is noise rather than a hint. */
+const SUGGESTION_THRESHOLD = 0.6;
+/**
+ * Every value in a projection query that names nothing.
+ *
+ * A projection is a DOCUMENT, and a query holds references the same way a
+ * relationship does. YarraMate refuses a relationship pointing at a concept
+ * that does not exist; it did not refuse a query naming a state that does not
+ * exist, and the symptom is silent. `states: [target-stat]` selects no state,
+ * which selects no subject, which exports a clean empty artifact with exit 0.
+ * Someone hands that to a client.
+ *
+ * Checked at `check`, not at `export`, because the typo is in a file rather
+ * than in an invocation: CI catches it, and every verb over the same
+ * projection inherits the guard instead of each growing its own.
+ *
+ * ONLY FACETS WITH A CLOSED NAMESPACE ARE CHECKED. `statuses` and
+ * `excludeStatuses` are schema enums, refused upstream before this runs.
+ * Everything else names something: `owners` and `constraints` are REFS to
+ * concepts, which the compiler itself proves by refusing an unresolved owner
+ * with YM304, so their namespace is the subject list like `subjects`.
+ *
+ * Each namespace is derived the way the FILTER derives it, so the check cannot
+ * drift from what it guards: `documents` reads the same provenance the
+ * `documents` facet compares against, and `states` is the same
+ * `yarramate/state/type` scan `conceptSelector` runs.
+ *
+ * A kind whose profile is not loaded is DORMANT rather than wrong, the same
+ * distinction #351 drew for question catalogues, so the kind facets are
+ * checked only when a profile context is present.
+ *
+ * An empty RESULT is not reported here and must not be. A query whose every
+ * name resolves and which selects nothing is a real answer to a real question:
+ * a target state nobody has populated yet is empty, correctly.
+ */
+export function unmatchedSelectors(graph, projection, profileContext) {
+    const query = projection.query;
+    const found = [];
+    const check = (facet, values, known) => {
+        if (values === undefined)
+            return;
+        for (const value of values) {
+            if (known.has(value))
+                continue;
+            let nearest;
+            let best = 0;
+            for (const candidate of known) {
+                const score = similarity(value, candidate);
+                if (score > best) {
+                    best = score;
+                    nearest = candidate;
+                }
+            }
+            found.push({
+                facet,
+                value,
+                ...(nearest !== undefined && best >= SUGGESTION_THRESHOLD
+                    ? { nearest }
+                    : {}),
+            });
+        }
+    };
+    const subjectIds = new Set(graph.subjects.map(({ id }) => id));
+    check('subjects', query.subjects, subjectIds);
+    check('exclude', query.exclude, subjectIds);
+    // Against the SUBJECT list rather than against owners currently in use: a
+    // team that owns nothing yet is a real concept and selecting it is a real
+    // question with an empty answer, which is exactly what must not be refused.
+    check('owners', query.owners, subjectIds);
+    check('constraints', query.constraints, subjectIds);
+    // The same provenance `documents` filters on: a subject id no longer carries
+    // the document that declared it, so both read it off the kind claim.
+    const documentIds = new Set();
+    for (const claim of graph.claims) {
+        if (claim.predicate !== 'yarramate/concept/kind')
+            continue;
+        const document = claim.source?.document;
+        if (typeof document === 'string')
+            documentIds.add(document);
+    }
+    check('documents', query.documents, documentIds);
+    check('states', query.states, new Set(graph.claims
+        .filter(({ predicate }) => predicate === 'yarramate/state/type')
+        .map(({ subject }) => subject)));
+    if (profileContext !== undefined) {
+        check('kinds', query.kinds, new Set(profileContext.conceptKindLineages.keys()));
+        check('relationshipKinds', query.relationshipKinds, new Set(profileContext.relationshipKindLineages.keys()));
+        check('layers', query.layers, new Set(profileContext.conceptKindLayers.values()));
+    }
+    return found;
+}
+/**
+ * Where a value sits in the projection source, so the diagnostic is clickable.
+ * A query value appears once in a list item, and finding it by text is enough:
+ * the alternative is threading a YAML CST through a check that only needs to
+ * point at a line.
+ */
+const locate = (source, value) => {
+    const lines = source.split('\n');
+    for (let index = 0; index < lines.length; index += 1) {
+        const at = lines[index].indexOf(value);
+        if (at >= 0)
+            return { line: index + 1, column: at + 1 };
+    }
+    return { line: 1, column: 1 };
+};
+/**
+ * {@link unmatchedSelectors} as diagnostics, built HERE rather than at each
+ * caller so `check`, and anything that adopts this later, refuse in identical
+ * words with an identical code.
+ */
+export function projectionReferenceDiagnostics(source, projection, graph, profileContext) {
+    return unmatchedSelectors(graph, projection, profileContext).map(({ facet, value, nearest }) => ({
+        severity: 'error',
+        code: 'YM921',
+        message: `Projection query \`${facet}\` names ${JSON.stringify(value)}, ` +
+            'which this workspace does not have, so it can never match. ' +
+            (nearest === undefined
+                ? 'Check the spelling against the model.'
+                : `Did you mean ${JSON.stringify(nearest)}?`),
+        path: source.path,
+        pointer: `/query/${facet}`,
+        ...locate(source.source, value),
+    }));
+}
 /**
  * Every concept a query leaves out, and the facet that left it out.
  *