yarramate 1.3.0 → 1.4.1

package/catalogues/core-enrichment.yaml

@@ -1,6 +1,6 @@
 format: yarramate/question-catalogue/v1
 id: core-enrichment
-version: "1.2"
+version: "1.3"
 profile: yarramate/core@0.1
 presentation:
   title: Core enrichment interview
@@ -25,27 +25,39 @@ waves:
       Load-bearing hops: the behavior a component is assigned to or the
       interface it composes, the serving/triggering/flow mechanism,
       payload, trust, reliability, and capacity. Hygiene waits.
+    opensWhen:
+      - condition: has-any-subject
   - id: business
     name: Business
     description: Who acts, what is served, and what information matters.
+    opensWhen:
+      - condition: has-any-subject
   - id: application
     name: Application
     description: >-
       How declared services are realized, performed, and fed with
       information.
+    opensWhen:
+      - condition: has-any-subject
   - id: technology
     name: Technology
     description: >-
       Where the declared applications actually run and what materializes
       them.
+    opensWhen:
+      - condition: has-any-subject
   - id: implementation
     name: Implementation
     description: >-
       How the planned architecture becomes real: work, deliverables, and
       the plateaus between here and there.
+    opensWhen:
+      - condition: has-any-subject
   - id: hygiene
     name: Model hygiene
     description: Cross-cutting completeness that keeps every wave honest.
+    opensWhen:
+      - condition: has-any-subject
 
 questions:
   # ---- motivation ----------------------------------------------------------

package/dist/adapters/visual/request.js

@@ -58,7 +58,14 @@ export const buildVisualSessionRequest = (options) => {
     const workspace = loaded.workspace;
     // Same order the session's own recompile uses, so the request's graph and
     // every graph the session rebuilds after a commit come from one input list.
-    const sourcePaths = [...workspace.profiles, ...workspace.documents];
+    // Patterns are compiler input like profiles (#268). Omitting them compiled a
+    // different workspace than the manifest describes, and an instance binding
+    // parts then failed YM419 for a pattern the manifest declared.
+    const sourcePaths = [
+        ...workspace.profiles,
+        ...workspace.patterns,
+        ...workspace.documents,
+    ];
     const sources = [];
     for (const path of sourcePaths) {
         try {

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

@@ -504,6 +504,13 @@ export const startVisualServer = async (options) => {
         try {
             return [
                 ...resolvedWorkspace.profiles,
+                // Patterns are compiler input like profiles (#268). Without them a
+                // session recompiles a workspace the manifest does not describe: an
+                // instance binding parts fails YM419, `compiledWorkspace` becomes
+                // undefined, and every view's filter then matches nothing while the
+                // rail still shows the initial model - which reads as a filter bug
+                // rather than as a compile that failed.
+                ...resolvedWorkspace.patterns,
                 ...resolvedWorkspace.documents,
             ].map((path) => ({
                 path,

package/dist/adapters/visual/workspace-model.d.ts

@@ -49,13 +49,25 @@ export declare const conceptCountOf: (graph: SemanticGraph, query: ProjectionQue
  * Subject ids come from the same compiled graph as `CanvasNode.id`, so the
  * join in the browser is a plain lookup.
  */
+export interface DismissedQuestion {
+    readonly questionId: string;
+    /** Absent dismisses the question wherever it appears. */
+    readonly subject?: string;
+}
 export declare const interrogationOverlayOf: (compiled: {
     readonly graph: SemanticGraph;
     readonly profileContext: ResolvedProfileContext;
 }, catalogue: {
     readonly path: string;
     readonly source: string;
-}) => VisualInterrogationOverlay | undefined;
+}, 
+/**
+ * What the host has already dealt with (#328). Evaluation is unchanged and
+ * the model is untouched: this decides only what the pane draws, because a
+ * question set aside in the host's own product should not be asked again by
+ * a pane embedded in it.
+ */
+dismissed?: readonly DismissedQuestion[]) => VisualInterrogationOverlay | undefined;
 /**
  * Rebuilds the shared editor workspace from one successful compile.
  *
@@ -71,7 +83,7 @@ export declare const renderedWorkspaceOf: (compiled: {
 }, views: readonly VisualViewSummary[], metadata: Omit<VisualRenderedModel, "graph" | "vocabulary" | "interrogation">, catalogue?: {
     readonly path: string;
     readonly source: string;
-}) => {
+}, dismissed?: readonly DismissedQuestion[]) => {
     readonly model: VisualRenderedModel;
     readonly views: readonly VisualViewSummary[];
 };

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

@@ -46,25 +46,32 @@ export const kindOptionsOf = (lineages) => [...lineages.keys()].map((id) => ({
  * them would read as five, and the reviewer counting boxes would find three.
  */
 export const conceptCountOf = (graph, query, profileContext) => evaluateProjection(graph, adHoc(query), profileContext).subjects.filter(({ type }) => type === "concept").length;
+export const interrogationOverlayOf = (compiled, catalogue, 
 /**
- * Folds one interrogation report into what the canvas draws (#292).
- *
- * Undefined — never a throw — when the catalogue does not load: the overlay
- * is a garnish on the model, and a model frame must not be blocked by it.
- * Subject ids come from the same compiled graph as `CanvasNode.id`, so the
- * join in the browser is a plain lookup.
+ * What the host has already dealt with (#328). Evaluation is unchanged and
+ * the model is untouched: this decides only what the pane draws, because a
+ * question set aside in the host's own product should not be asked again by
+ * a pane embedded in it.
  */
-export const interrogationOverlayOf = (compiled, catalogue) => {
+dismissed = []) => {
     const loaded = loadQuestionCatalogue(catalogue);
     if (!loaded.ok)
         return undefined;
     const report = evaluateCatalogue(loaded.catalogue, compiled.graph, compiled.profileContext);
+    const dismissedEverywhere = new Set(dismissed
+        .filter(({ subject }) => subject === undefined)
+        .map(({ questionId }) => questionId));
+    const dismissedForSubject = new Set(dismissed
+        .filter(({ subject }) => subject !== undefined)
+        .map(({ questionId, subject }) => `${questionId}\u0000${subject}`));
     const workspace = [];
     const subjects = {};
     for (const wave of report.waves) {
         for (const question of wave.questions) {
             if (!question.open)
                 continue;
+            if (dismissedEverywhere.has(question.id))
+                continue;
             const base = {
                 questionId: question.id,
                 authority: question.authority,
@@ -75,6 +82,9 @@ export const interrogationOverlayOf = (compiled, catalogue) => {
                 continue;
             }
             for (const subject of question.subjects) {
+                if (dismissedForSubject.has(`${question.id}\u0000${subject.id}`)) {
+                    continue;
+                }
                 (subjects[subject.id] ??= []).push({
                     ...base,
                     question: subject.question,
@@ -98,14 +108,14 @@ export const interrogationOverlayOf = (compiled, catalogue) => {
  * is the question catalogue's bytes — this module cannot read files, so
  * whoever can hands them over; omitting it ships a model with no overlay.
  */
-export const renderedWorkspaceOf = (compiled, views, metadata, catalogue) => {
+export const renderedWorkspaceOf = (compiled, views, metadata, catalogue, dismissed) => {
     const refreshedViews = views.map((view) => ({
         ...view,
         subjectCount: conceptCountOf(compiled.graph, view.query, compiled.profileContext),
     }));
     const interrogation = catalogue === undefined
         ? undefined
-        : interrogationOverlayOf(compiled, catalogue);
+        : interrogationOverlayOf(compiled, catalogue, dismissed);
     return {
         model: {
             ...metadata,

package/dist/apply-command.js

@@ -719,6 +719,10 @@ export const applyOperations = (input) => {
     // single byte is written; any diagnostic rejects the entire batch.
     const compiled = [
         ...resolvedWorkspace.profiles,
+        // Without patterns this gate compiles a workspace the manifest does not
+        // describe, so every commit against a workspace holding pattern instances
+        // was refused with YM419 for a pattern that was declared (#268).
+        ...resolvedWorkspace.patterns,
         ...resolvedWorkspace.documents,
     ].map((path) => ({
         path,
@@ -832,6 +836,9 @@ export const planOperations = (store, input) => {
         // workspace that declares a profile died on it. No operation can target a
         // profile, so they are read to be COMPILED against, never to be written.
         ...input.workspace.profiles,
+        // Patterns are compiled against too, and are no more writable than a
+        // profile: no operation can target one.
+        ...input.workspace.patterns,
         ...input.workspace.documents,
         ...input.workspace.projections,
         ...input.workspace.evidence,

package/dist/ask-command.js

@@ -432,7 +432,11 @@ export function runAskCommand(options, cwd) {
                 return emit(result, `Workspace ${workspace.id}: check failing\n` +
                     `Diagnostics: ${plural(checkPayload.diagnostics.length, 'error')}; run \`yarramate check ${workspacePath}\` for details\n`, 1);
             }
-            const compilation = compileWorkspaceWithProfileContext([...workspace.profiles, ...workspace.documents].map((path) => ({
+            const compilation = compileWorkspaceWithProfileContext([
+                ...workspace.profiles,
+                ...workspace.patterns,
+                ...workspace.documents,
+            ].map((path) => ({
                 path,
                 source: readFileSync(resolve(cwd, path), 'utf8'),
             })));
@@ -500,14 +504,25 @@ export function runAskCommand(options, cwd) {
             if (reconciliation !== undefined) {
                 lines.push(reconciliationLine(reconciliation));
             }
+            // Zero open has two causes and only one is complete (#334): a
+            // catalogue whose waves are all gated shut has asked nothing, and
+            // reporting that as a finished interview is the same empty-set
+            // flattery the wave rail carried.
+            const askedAnything = report.waves.some((wave) => wave.questions.length > 0);
             lines.push(report.summary.open === 0
-                ? `Design interview complete (catalogue ${report.catalogue}): no open questions.`
+                ? askedAnything
+                    ? `Design interview complete (catalogue ${report.catalogue}): no open questions.`
+                    : `Design interview not started (catalogue ${report.catalogue}): no wave has opened yet.`
                 : `Design interview: ${plural(report.summary.open, 'open question')} (catalogue ${report.catalogue}) — continue: yarramate design ${workspacePath}`, '', 'Backlog — planned, dependency order:', ...plannedLines(planned), '', `Current: ${plural(current.length, 'subject')} · Retired: ${retired.length} ` +
                 `(roster: yarramate ask ${workspacePath} --subjects)`);
             return emit(result, `${lines.join('\n')}\n`);
         }
         // Every other mode reads the compiled model directly.
-        const compilation = compileWorkspaceWithProfileContext([...workspace.profiles, ...workspace.documents].map((path) => ({
+        const compilation = compileWorkspaceWithProfileContext([
+            ...workspace.profiles,
+            ...workspace.patterns,
+            ...workspace.documents,
+        ].map((path) => ({
             path,
             source: readFileSync(resolve(cwd, path), 'utf8'),
         })));

package/dist/check-command.js

@@ -274,7 +274,11 @@ export function runCheckCommand(options, cwd) {
         if (ok && result.ok) {
             const successfulCounts = counted;
             const documentCount = result.graph.documents.length;
-            const profileCount = coreSources.length - documentCount;
+            const patternCount = resolved.patterns.length;
+            // Everything in `coreSources` that is not a document was a profile until
+            // patterns joined the source list (#268), and counting them as profiles
+            // said "2 profiles" about a workspace with one.
+            const profileCount = coreSources.length - documentCount - patternCount;
             const mappingCount = mappingSources.length;
             const projectionCount = resolved.projections.length;
             const evidenceCount = resolved.evidence.length;
@@ -286,6 +290,11 @@ export function runCheckCommand(options, cwd) {
                         `${profileCount} ${profileCount === 1 ? 'profile' : 'profiles'}`,
                     ]
                     : []),
+                ...(patternCount > 0
+                    ? [
+                        `${patternCount} ${patternCount === 1 ? 'pattern' : 'patterns'}`,
+                    ]
+                    : []),
                 ...(mappingCount > 0
                     ? [
                         `${mappingCount} ${mappingCount === 1 ? 'adapter mapping' : 'adapter mappings'}`,

package/dist/cli-support.d.ts

@@ -28,6 +28,8 @@ export declare const resolveCliWorkspaceSources: (paths: readonly string[], cwd:
     readonly projections: readonly string[];
     readonly evidence: readonly string[];
     readonly contracts: readonly string[];
+    /** Pattern documents, which ride in `paths` and are not documents. */
+    readonly patterns: readonly string[];
 } | {
     readonly ok: false;
     readonly diagnostics: readonly Diagnostic[];

package/dist/cli-support.js

@@ -50,6 +50,7 @@ export const resolveCliWorkspaceSources = (paths, cwd, options = {}) => {
             projections: [],
             evidence: [],
             contracts: [],
+            patterns: [],
         };
     }
     const manifestPath = paths[0];
@@ -60,6 +61,7 @@ export const resolveCliWorkspaceSources = (paths, cwd, options = {}) => {
             projections: [],
             evidence: [],
             contracts: [],
+            patterns: [],
         };
     }
     const source = readFileSync(resolve(cwd, manifestPath), 'utf8');
@@ -70,6 +72,7 @@ export const resolveCliWorkspaceSources = (paths, cwd, options = {}) => {
             projections: [],
             evidence: [],
             contracts: [],
+            patterns: [],
         };
     }
     const loaded = loadWorkspaceManifest({ path: manifestPath, source }, cwd);
@@ -78,6 +81,15 @@ export const resolveCliWorkspaceSources = (paths, cwd, options = {}) => {
             ok: true,
             paths: [
                 ...loaded.workspace.profiles,
+                // Patterns are compiler input like profiles, and were resolved from
+                // the manifest without ever being handed over (#268): a pattern
+                // document a workspace declared was silently ignored by every verb,
+                // and an instance binding parts then failed YM419 for a pattern that
+                // was sitting right there in the manifest. Every test passed because
+                // each hands the compiler an explicit source list rather than
+                // resolving a workspace - the check that passes was not the check
+                // that mattered.
+                ...loaded.workspace.patterns,
                 ...loaded.workspace.documents,
                 ...(options.includeAdapterMappings === true
                     ? loaded.workspace.adapterMappings
@@ -86,6 +98,7 @@ export const resolveCliWorkspaceSources = (paths, cwd, options = {}) => {
             projections: loaded.workspace.projections,
             evidence: loaded.workspace.evidence,
             contracts: loaded.workspace.contracts,
+            patterns: loaded.workspace.patterns,
         }
         : { ok: false, diagnostics: loaded.diagnostics };
 };

package/dist/cli.js

@@ -37,6 +37,7 @@ const runReconciliation = (options, cwd) => {
         }
         const sourcePaths = [
             ...loadedWorkspace.workspace.profiles,
+            ...loadedWorkspace.workspace.patterns,
             ...loadedWorkspace.workspace.documents,
         ];
         const compilation = compileWorkspace(sourcePaths.map((path) => ({

package/dist/compiler.d.ts

@@ -74,6 +74,18 @@ export interface ResolvedProfileContext {
     /** Kind identity -> the core kind it resolves to through lineage. */
     readonly conceptKindCoreAncestors: ReadonlyMap<string, CoreConceptKindId>;
     readonly relationshipKindCoreAncestors: ReadonlyMap<string, RelationshipKind>;
+    /**
+     * The core relationship kinds a pattern PORTS for a concept kind (#268
+     * phase 3, ADR 0124), keyed by kind identity. Only kinds that have a
+     * pattern with ports appear.
+     *
+     * A macro edge needs both ends to port its kind, so a consumer offering a
+     * palette between two instances intersects the two sets. Two raw groupings
+     * permit ten of the eleven kinds, which is no narrowing at all; the ports
+     * are what restore the guidance the relationship table gives everywhere
+     * else.
+     */
+    readonly patternPortKinds: ReadonlyMap<string, readonly RelationshipKind[]>;
     /**
      * The core relationship kinds the ArchiMate table permits between two
      * concept kind identities, resolved through lineage; undefined when either
@@ -104,7 +116,7 @@ export type ContextualCompilationResult = {
  */
 export interface ParsedWorkspaceSource {
     readonly source: string;
-    readonly kind: 'profile' | 'document';
+    readonly kind: 'profile' | 'document' | 'pattern';
     readonly value: unknown;
     readonly schemaDiagnostics: readonly Diagnostic[];
     /**