yarramate 1.4.1 → 1.5.0

package/dist/adapters/visual/session-server.js

@@ -501,8 +501,9 @@ export const startVisualServer = async (options) => {
      * session instead of serving a stale graph.
      */
     const workspaceSources = () => {
+        let reading = "";
         try {
-            return [
+            const paths = [
                 ...resolvedWorkspace.profiles,
                 // Patterns are compiler input like profiles (#268). Without them a
                 // session recompiles a workspace the manifest does not describe: an
@@ -512,18 +513,46 @@ export const startVisualServer = async (options) => {
                 // rather than as a compile that failed.
                 ...resolvedWorkspace.patterns,
                 ...resolvedWorkspace.documents,
-            ].map((path) => ({
-                path,
-                source: readFileSync(resolve(options.cwd, path), "utf8"),
-            }));
+            ];
+            return {
+                ok: true,
+                sources: paths.map((path) => {
+                    reading = path;
+                    return {
+                        path,
+                        source: readFileSync(resolve(options.cwd, path), "utf8"),
+                    };
+                }),
+            };
         }
-        catch {
-            // A source that cannot be read is one whose diagnostics belong to no
-            // subject anyway, so an empty list is the right answer rather than a
-            // throw from a path that is only trying to add detail.
-            return [];
+        catch (cause) {
+            // Never an empty list. Compiling one SUCCEEDS - `compileWorkspaceResolved`
+            // over no sources returns an empty graph, not a failure - so swallowing
+            // the read error here made an unreadable workspace indistinguishable
+            // from an empty one, and the session then served "your model has nothing
+            // in it" as though it were an answer (#349). The older comment defended
+            // the empty list as belonging to a path "only trying to add detail";
+            // this feeds the single compile that produces what the browser draws.
+            return {
+                ok: false,
+                path: reading,
+                reason: cause instanceof Error ? cause.message : String(cause),
+            };
         }
     };
+    /**
+     * The sources, for attaching subjects to a diagnostic that already exists.
+     *
+     * Here an unreadable source really is nothing worth reporting: the caller is
+     * decorating a refusal it has already decided on, so a missing file costs a
+     * subject marker and nothing else. That was the whole of the old
+     * `workspaceSources` contract, and it stayed correct for exactly these two
+     * callers while being wrong for the compile (#349).
+     */
+    const sourcesForDetail = () => {
+        const read = workspaceSources();
+        return read.ok ? read.sources : [];
+    };
     /**
      * The digest of every projection the session knows about, read now.
      *
@@ -549,11 +578,22 @@ export const startVisualServer = async (options) => {
     };
     const recompileWorkspace = () => {
         try {
-            const sources = workspaceSources();
+            const read = workspaceSources();
+            if (!read.ok) {
+                return {
+                    ok: false,
+                    diagnostics: [
+                        serverDiagnostic("YMVS319", `Workspace source ${read.path} cannot be read, so the workspace was not recompiled; the last good model stays as it is: ${read.reason}`),
+                    ],
+                };
+            }
+            const sources = read.sources;
             const compiled = compileWorkspaceWithProfileContext(sources);
             if (!compiled.ok) {
-                compiledWorkspace = undefined;
-                return false;
+                return {
+                    ok: false,
+                    diagnostics: published(compiled.diagnostics, sources),
+                };
             }
             compiledWorkspace = {
                 graph: compiled.graph,
@@ -577,14 +617,36 @@ export const startVisualServer = async (options) => {
             // replacing the identity the session started with.
             views.splice(0, views.length, ...workspaceModel.views);
             rendered = workspaceModel.model;
-            return true;
+            // Recovered: a browser connecting now is not handed a fault that has
+            // been fixed since. The connected ones clear it on the `model` frame
+            // this success is about to broadcast.
+            standingDiagnostics = [];
+            return { ok: true };
         }
-        catch {
-            compiledWorkspace = undefined;
-            return false;
+        catch (cause) {
+            return {
+                ok: false,
+                diagnostics: [
+                    serverDiagnostic("YMVS319", `Workspace could not be recompiled, so the last good model stays as it is: ${cause instanceof Error ? cause.message : String(cause)}`),
+                ],
+            };
         }
     };
-    recompileWorkspace();
+    /**
+     * What the last recompile could not do, held for a browser that is not
+     * connected yet.
+     *
+     * The startup recompile runs before any socket exists, so a failure there
+     * has nobody to tell. Holding it means the first browser to arrive is told
+     * what every later one would have heard, rather than opening onto a session
+     * that looks well and answers nothing.
+     */
+    let standingDiagnostics = [];
+    {
+        const started = recompileWorkspace();
+        if (!started.ok)
+            standingDiagnostics = started.diagnostics;
+    }
     const filterMatchedIds = (query) => compiledWorkspace === undefined
         ? []
         : matchedIdsOf(compiledWorkspace.graph, query, compiledWorkspace.profileContext);
@@ -851,6 +913,36 @@ export const startVisualServer = async (options) => {
         for (const socket of connections.values())
             sendFrame(socket, frame);
     };
+    /**
+     * Tells the browser the workspace no longer compiles, and what said so.
+     *
+     * Journalled as an ordinary `diagnostic` response rather than a new frame
+     * kind, because that is the one the browser already renders - `Faults`
+     * reads `state.diagnostics`, which a `model` frame clears, so a recovered
+     * recompile clears the banner without anyone clearing it (#349). Held in
+     * `standingDiagnostics` too, for the browser that has not connected yet.
+     */
+    const reportRecompileFailure = async (diagnostics, eventId = drawHex(16)) => {
+        standingDiagnostics = diagnostics;
+        const response = {
+            format: "yarramate/visual-response/v1",
+            sessionId,
+            responseId: drawHex(16),
+            eventId,
+            type: "diagnostic",
+            timestamp: stamp(),
+            payload: { diagnostics },
+        };
+        const appended = await appendVisualResponse(paths, response);
+        if (appended.ok) {
+            transcriptBytes = appended.transcriptBytes;
+            recordResponse(response);
+            broadcast({ kind: "response", response });
+        }
+        else if (appended.freeze !== undefined) {
+            freeze(appended.freeze);
+        }
+    };
     const idleDelivery = () => ({
         waiting: true,
         lastSequence,
@@ -1172,8 +1264,17 @@ export const startVisualServer = async (options) => {
                         kind: "apply-result",
                         result: { ok: false, diagnostics: refused },
                     });
-                    if (recompileWorkspace())
+                    const refreshed = recompileWorkspace();
+                    if (refreshed.ok) {
                         broadcast({ kind: "model", model: rendered, views });
+                    }
+                    else {
+                        // Nothing at all reached the browser here before (#349): a refused
+                        // apply whose refresh also failed left the reviewer with a
+                        // refusal about their rows and no word that the workspace itself
+                        // had stopped compiling.
+                        await reportRecompileFailure(refreshed.diagnostics);
+                    }
                     return;
                 }
                 const operationsSource = stringify({
@@ -1193,7 +1294,7 @@ export const startVisualServer = async (options) => {
                         kind: "apply-result",
                         result: {
                             ok: false,
-                            diagnostics: published(loadedWorkspace.diagnostics, workspaceSources()),
+                            diagnostics: published(loadedWorkspace.diagnostics, sourcesForDetail()),
                         },
                     });
                     return;
@@ -1232,7 +1333,7 @@ export const startVisualServer = async (options) => {
                         kind: "apply-result",
                         result: {
                             ok: false,
-                            diagnostics: published(outcome.diagnostics, workspaceSources()),
+                            diagnostics: published(outcome.diagnostics, sourcesForDetail()),
                         },
                     });
                     return;
@@ -1249,7 +1350,8 @@ export const startVisualServer = async (options) => {
                     kind: "apply-result",
                     result: { ok: true, result: outcome.result },
                 });
-                if (recompileWorkspace()) {
+                const recompiled = recompileWorkspace();
+                if (recompiled.ok) {
                     broadcast({ kind: "model", model: rendered, views });
                     return;
                 }
@@ -1257,29 +1359,13 @@ export const startVisualServer = async (options) => {
                 // landed but produced a document Core itself can no longer parse.
                 // The freeze alone only tells the browser input is refused, not why
                 // the graph on screen has gone stale, so a diagnostic response is
-                // journaled alongside it.
-                const diagnosticResponse = {
-                    format: "yarramate/visual-response/v1",
-                    sessionId,
-                    responseId: drawHex(16),
-                    eventId: event.eventId,
-                    type: "diagnostic",
-                    timestamp: stamp(),
-                    payload: {
-                        diagnostics: [
-                            serverDiagnostic("YMVS310", "Workspace failed to recompile after a landed changeset"),
-                        ],
-                    },
-                };
-                const appendedResponse = await appendVisualResponse(paths, diagnosticResponse);
-                if (appendedResponse.ok) {
-                    transcriptBytes = appendedResponse.transcriptBytes;
-                    recordResponse(diagnosticResponse);
-                    broadcast({ kind: "response", response: diagnosticResponse });
-                }
-                else if (appendedResponse.freeze !== undefined) {
-                    freeze(appendedResponse.freeze);
-                }
+                // journaled alongside it - and it carries the compiler's OWN
+                // diagnostics, because YMVS310 by itself names no document, no code
+                // and no line (#349).
+                await reportRecompileFailure([
+                    serverDiagnostic("YMVS310", "Workspace failed to recompile after a landed changeset"),
+                    ...recompiled.diagnostics,
+                ], event.eventId);
                 freeze("recompile-failed");
                 return;
             }
@@ -1431,6 +1517,22 @@ export const startVisualServer = async (options) => {
                 return;
             }
             sendFrame(socket, { kind: "ready", snapshot: snapshot() });
+            // A recompile that failed before this socket existed - the one at
+            // startup, most often - has had nobody to tell until now (#349).
+            if (standingDiagnostics.length > 0) {
+                sendFrame(socket, {
+                    kind: "response",
+                    response: {
+                        format: "yarramate/visual-response/v1",
+                        sessionId,
+                        responseId: drawHex(16),
+                        eventId: drawHex(16),
+                        type: "diagnostic",
+                        timestamp: stamp(),
+                        payload: { diagnostics: standingDiagnostics },
+                    },
+                });
+            }
         });
     };
     // ------------------------------------------------------------- agent routes

package/dist/ask-command.js

@@ -471,7 +471,7 @@ export function runAskCommand(options, cwd) {
             const loadedCatalogue = loadQuestionCatalogue({
                 path: shippedCataloguePath,
                 source: readFileSync(shippedCataloguePath, 'utf8'),
-            });
+            }, compilation.profileContext);
             if (!loadedCatalogue.ok)
                 return failed(loadedCatalogue.diagnostics);
             const report = evaluateCatalogue(loadedCatalogue.catalogue, compilation.graph, compilation.profileContext, evidenceDocuments.flatMap(({ observations }) => observations));
@@ -701,7 +701,7 @@ export function runAskCommand(options, cwd) {
             const loadedCatalogue = loadQuestionCatalogue({
                 path: cataloguePath ?? resolvedCataloguePath,
                 source: readFileSync(resolvedCataloguePath, 'utf8'),
-            });
+            }, compilation.profileContext);
             if (!loadedCatalogue.ok)
                 return failed(loadedCatalogue.diagnostics);
             // The evidence overlay rides along for the one condition that
@@ -996,7 +996,7 @@ export function runAskCommand(options, cwd) {
         const loadedCatalogue = loadQuestionCatalogue({
             path: cataloguePath ?? resolvedCataloguePath,
             source: readFileSync(resolvedCataloguePath, 'utf8'),
-        });
+        }, compilation.profileContext);
         if (!loadedCatalogue.ok)
             return failed(loadedCatalogue.diagnostics);
         // Loaded ahead of evaluation so the overlay feeds the one condition

package/dist/design-command.js

@@ -191,12 +191,10 @@ export function runDesignCommand(options, cwd) {
         const resolvedCataloguePath = cataloguePath === undefined
             ? shippedCataloguePath
             : resolve(cwd, cataloguePath);
-        const loadedCatalogue = loadQuestionCatalogue({
-            path: cataloguePath ?? resolvedCataloguePath,
-            source: readFileSync(resolvedCataloguePath, 'utf8'),
-        });
-        if (!loadedCatalogue.ok)
-            return failed(loadedCatalogue.diagnostics);
+        // Compiled BEFORE the catalogue loads, so the catalogue can be checked
+        // against the vocabulary its kinds are written against (#351). A
+        // catalogue naming a kind its own profile does not have loads clean
+        // otherwise, and the question it names is dead on arrival.
         const compilation = compileWorkspaceWithProfileContext([
             ...workspace.profiles,
             ...workspace.patterns,
@@ -207,6 +205,12 @@ export function runDesignCommand(options, cwd) {
         })));
         if (!compilation.ok)
             return failed(compilation.diagnostics);
+        const loadedCatalogue = loadQuestionCatalogue({
+            path: cataloguePath ?? resolvedCataloguePath,
+            source: readFileSync(resolvedCataloguePath, 'utf8'),
+        }, compilation.profileContext);
+        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 empty overlay — known to be empty, which keeps that

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.