yarramate 0.23.0 → 1.0.0

package/dist/adapters/visual/view-identity.d.ts

@@ -0,0 +1,135 @@
+import type { ProjectionDefinition, ProjectionQuery } from "../../projection.js";
+/**
+ * How a saved view gets its id, its path, and its document.
+ *
+ * The browser composes a `write-view` operation now rather than asking the
+ * server to compose one at commit time (ADR 0103): a staged row has to name
+ * the document it will write before it is committed, because that is what the
+ * reviewer reads in the tray and what the digest pins against.
+ *
+ * So this lives where both sides can reach it. No React, no cytoscape, and
+ * nothing from `node:` — the browser bundle imports it for its value, and
+ * `visual-app-browser-safety.test.ts` is what holds that honest. Validation
+ * stays on the server, where the schema and its loader are: composing a
+ * projection is arithmetic, deciding it is acceptable is not.
+ */
+/** Where projections live when nothing says otherwise. */
+export declare const DEFAULT_PROJECTION_DIRECTORY = ".yarramate/projections";
+/**
+ * Turns a view title into a schema-valid projection id: lowercase,
+ * hyphen-separated, letter-led. A title with no letters or digits degrades
+ * to "view" rather than producing an id the schema would reject.
+ */
+export declare const slugify: (title: string) => string;
+/** Appends a numeric suffix only when the base id collides with a known view. */
+export declare const uniqueViewId: (base: string, taken: ReadonlySet<string>) => string;
+/** The id a title should take, given the ids already in use. */
+export declare const viewIdFrom: (title: string, taken: ReadonlySet<string>) => string;
+/**
+ * Where a view's document goes: beside every other one.
+ *
+ * The directory no longer carries meaning. Folders are DECLARED in the
+ * projection now (ADR 0104), so a view files itself with a label and the path
+ * is only an address - which is what makes "New folder" a thing the editor can
+ * do at all. Writing into a subdirectory was the one motion that could put a
+ * projection where the manifest's patterns do not reach (`YMVS315`), and the
+ * editor no longer has a reason to try.
+ */
+export declare const projectionPathFor: (id: string) => string;
+/**
+ * The projection document a saved view is, composed from what the form holds.
+ *
+ * `title` and `description` are presentation fields rather than top-level
+ * ones, which is where `ProjectionDefinition` puts them, and every other
+ * presentation field the active view declared is carried through — dropping
+ * one here is how overwriting a view silently loses its nesting or direction.
+ */
+/** The folder a saved view declares, or `""` for none. */
+export declare const declaredFolder: (view: {
+    readonly presentation: ProjectionDefinition["presentation"];
+}) => string;
+/**
+ * Retitling a view, as a staged write.
+ *
+ * The path and the id do NOT move. A projection's id decides its filename and
+ * also keys its layout sidecar (`.yarramate/visual-layout/<id>.yaml`), so a
+ * rename that carried the id along would silently orphan the positions the
+ * reviewer dragged. Renaming is a change to what the view is called; moving it
+ * is a different motion, and not one #246 asked for.
+ *
+ * Every other presentation field the view declared is carried through by
+ * `composeProjection`, so a rename cannot quietly drop a nesting vocabulary or
+ * a direction the canvas never showed.
+ */
+export declare const renameView: (view: SavedView, title: string) => {
+    readonly path: string;
+    readonly projection: ProjectionDefinition;
+};
+/**
+ * Copying a view into a new document beside it.
+ *
+ * The copy keeps the original's folder, because a duplicate the reviewer then
+ * has to move is a duplicate in the wrong place - and it comes along for free
+ * now that a folder is a declared field `composeProjection` carries with every
+ * other one. It does NOT inherit the layout sidecar: that is keyed by id, and
+ * a copy is a different view that lays itself out.
+ */
+export declare const duplicateView: (view: SavedView, taken: ReadonlySet<string>) => {
+    readonly path: string;
+    readonly projection: ProjectionDefinition;
+};
+/** What these need of a saved view, and nothing about how it is drawn. */
+export interface SavedView {
+    readonly id: string;
+    readonly title: string;
+    readonly description: string;
+    readonly query: ProjectionQuery;
+    readonly presentation: ProjectionDefinition["presentation"];
+    readonly path: string;
+}
+export declare const composeProjection: (input: {
+    readonly id: string;
+    readonly title: string;
+    readonly description: string;
+    readonly query: ProjectionQuery;
+    readonly presentation: ProjectionDefinition["presentation"];
+}) => ProjectionDefinition;
+/**
+ * Whether a view can be told which subjects it holds.
+ *
+ * Only a view that ENUMERATES `subjects:` can. A view that describes its
+ * subjects with facets — a layer, a kind, a state — already includes anything
+ * matching them and excludes anything that does not, so there is nothing for a
+ * membership edit to say to it: the subject is in or out by what it is, and
+ * saying otherwise means editing the query rather than a list (#255).
+ */
+export declare const enumeratesSubjects: (query: ProjectionQuery) => query is ProjectionQuery & {
+    readonly subjects: readonly string[];
+};
+/**
+ * The same view, holding one more subject or one fewer.
+ *
+ * `null` when there is nothing to stage: the view describes its subjects
+ * rather than listing them, or the list already says what was asked for.
+ * Returning the absence rather than an unchanged document is what keeps a
+ * no-op out of the changeset, where a row that writes a file back exactly as
+ * it was is a row the reviewer has to read and discard for nothing.
+ */
+export declare const withMembership: (projection: ProjectionDefinition, subjectId: string, membership: "add" | "remove") => ProjectionDefinition | null;
+/**
+ * What a membership edit did to a view, as the tray reads it: `+id` for a
+ * subject this row adds, `-id` for one it drops, against the document the
+ * workspace holds. Empty when the row changed something else — a title, a
+ * query, a presentation flag — which the row says by other means.
+ */
+export declare const membershipDelta: (saved: ProjectionQuery, staged: ProjectionQuery) => readonly string[];
+/**
+ * Two projection documents, compared by what they SAY rather than by how they
+ * are written.
+ *
+ * Key order is the author's: a document read back off YAML holds its fields in
+ * the order someone wrote them, and one composed here holds them in the order
+ * this file writes them. Comparing the two as text reports every view as
+ * changed the moment anything touches it.
+ */
+export declare const sameDocument: (left: ProjectionDefinition, right: ProjectionDefinition) => boolean;

package/dist/adapters/visual/view-identity.js

@@ -0,0 +1,200 @@
+/**
+ * How a saved view gets its id, its path, and its document.
+ *
+ * The browser composes a `write-view` operation now rather than asking the
+ * server to compose one at commit time (ADR 0103): a staged row has to name
+ * the document it will write before it is committed, because that is what the
+ * reviewer reads in the tray and what the digest pins against.
+ *
+ * So this lives where both sides can reach it. No React, no cytoscape, and
+ * nothing from `node:` — the browser bundle imports it for its value, and
+ * `visual-app-browser-safety.test.ts` is what holds that honest. Validation
+ * stays on the server, where the schema and its loader are: composing a
+ * projection is arithmetic, deciding it is acceptable is not.
+ */
+/** Where projections live when nothing says otherwise. */
+export const DEFAULT_PROJECTION_DIRECTORY = ".yarramate/projections";
+/**
+ * Turns a view title into a schema-valid projection id: lowercase,
+ * hyphen-separated, letter-led. A title with no letters or digits degrades
+ * to "view" rather than producing an id the schema would reject.
+ */
+export const slugify = (title) => {
+    const cleaned = title
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+    if (cleaned.length === 0)
+        return "view";
+    return /^[a-z]/.test(cleaned) ? cleaned : `view-${cleaned}`;
+};
+/** Appends a numeric suffix only when the base id collides with a known view. */
+export const uniqueViewId = (base, taken) => {
+    if (!taken.has(base))
+        return base;
+    let suffix = 2;
+    while (taken.has(`${base}-${suffix}`))
+        suffix += 1;
+    return `${base}-${suffix}`;
+};
+/** The id a title should take, given the ids already in use. */
+export const viewIdFrom = (title, taken) => uniqueViewId(slugify(title), taken);
+/**
+ * Where a view's document goes: beside every other one.
+ *
+ * The directory no longer carries meaning. Folders are DECLARED in the
+ * projection now (ADR 0104), so a view files itself with a label and the path
+ * is only an address - which is what makes "New folder" a thing the editor can
+ * do at all. Writing into a subdirectory was the one motion that could put a
+ * projection where the manifest's patterns do not reach (`YMVS315`), and the
+ * editor no longer has a reason to try.
+ */
+export const projectionPathFor = (id) => `${DEFAULT_PROJECTION_DIRECTORY}/${id}.yaml`;
+/**
+ * The projection document a saved view is, composed from what the form holds.
+ *
+ * `title` and `description` are presentation fields rather than top-level
+ * ones, which is where `ProjectionDefinition` puts them, and every other
+ * presentation field the active view declared is carried through — dropping
+ * one here is how overwriting a view silently loses its nesting or direction.
+ */
+/** The folder a saved view declares, or `""` for none. */
+export const declaredFolder = (view) => view.presentation?.folder ?? "";
+/**
+ * Retitling a view, as a staged write.
+ *
+ * The path and the id do NOT move. A projection's id decides its filename and
+ * also keys its layout sidecar (`.yarramate/visual-layout/<id>.yaml`), so a
+ * rename that carried the id along would silently orphan the positions the
+ * reviewer dragged. Renaming is a change to what the view is called; moving it
+ * is a different motion, and not one #246 asked for.
+ *
+ * Every other presentation field the view declared is carried through by
+ * `composeProjection`, so a rename cannot quietly drop a nesting vocabulary or
+ * a direction the canvas never showed.
+ */
+export const renameView = (view, title) => ({
+    path: view.path,
+    projection: composeProjection({
+        id: view.id,
+        title,
+        description: view.description,
+        query: view.query,
+        presentation: view.presentation,
+    }),
+});
+/**
+ * Copying a view into a new document beside it.
+ *
+ * The copy keeps the original's folder, because a duplicate the reviewer then
+ * has to move is a duplicate in the wrong place - and it comes along for free
+ * now that a folder is a declared field `composeProjection` carries with every
+ * other one. It does NOT inherit the layout sidecar: that is keyed by id, and
+ * a copy is a different view that lays itself out.
+ */
+export const duplicateView = (view, taken) => {
+    const title = `${view.title} copy`;
+    const id = viewIdFrom(title, taken);
+    return {
+        path: projectionPathFor(id),
+        projection: composeProjection({
+            id,
+            title,
+            description: view.description,
+            query: view.query,
+            presentation: view.presentation,
+        }),
+    };
+};
+export const composeProjection = (input) => ({
+    format: "yarramate/projection/v1",
+    id: input.id,
+    version: "1.0",
+    query: input.query,
+    presentation: {
+        ...(input.presentation ?? {}),
+        title: input.title,
+        description: input.description,
+    },
+});
+/**
+ * Whether a view can be told which subjects it holds.
+ *
+ * Only a view that ENUMERATES `subjects:` can. A view that describes its
+ * subjects with facets — a layer, a kind, a state — already includes anything
+ * matching them and excludes anything that does not, so there is nothing for a
+ * membership edit to say to it: the subject is in or out by what it is, and
+ * saying otherwise means editing the query rather than a list (#255).
+ */
+export const enumeratesSubjects = (query) => query.subjects !== undefined;
+/**
+ * The same view, holding one more subject or one fewer.
+ *
+ * `null` when there is nothing to stage: the view describes its subjects
+ * rather than listing them, or the list already says what was asked for.
+ * Returning the absence rather than an unchanged document is what keeps a
+ * no-op out of the changeset, where a row that writes a file back exactly as
+ * it was is a row the reviewer has to read and discard for nothing.
+ */
+export const withMembership = (projection, subjectId, membership) => {
+    if (!enumeratesSubjects(projection.query))
+        return null;
+    const subjects = projection.query.subjects;
+    const holds = subjects.includes(subjectId);
+    if (membership === "add" ? holds : !holds)
+        return null;
+    return {
+        ...projection,
+        query: {
+            ...projection.query,
+            subjects: membership === "add"
+                ? // Appended rather than sorted in: the list is the author's, and
+                    // reordering it would rewrite lines nobody touched.
+                    [...subjects, subjectId]
+                : subjects.filter((id) => id !== subjectId),
+        },
+    };
+};
+/**
+ * What a membership edit did to a view, as the tray reads it: `+id` for a
+ * subject this row adds, `-id` for one it drops, against the document the
+ * workspace holds. Empty when the row changed something else — a title, a
+ * query, a presentation flag — which the row says by other means.
+ */
+export const membershipDelta = (saved, staged) => {
+    if (!enumeratesSubjects(saved) || !enumeratesSubjects(staged))
+        return [];
+    return [
+        ...staged.subjects
+            .filter((id) => !saved.subjects.includes(id))
+            .map((id) => `+${id}`),
+        ...saved.subjects
+            .filter((id) => !staged.subjects.includes(id))
+            .map((id) => `-${id}`),
+    ];
+};
+/**
+ * Two projection documents, compared by what they SAY rather than by how they
+ * are written.
+ *
+ * Key order is the author's: a document read back off YAML holds its fields in
+ * the order someone wrote them, and one composed here holds them in the order
+ * this file writes them. Comparing the two as text reports every view as
+ * changed the moment anything touches it.
+ */
+export const sameDocument = (left, right) => canonical(left) === canonical(right);
+const canonical = (value) => {
+    if (Array.isArray(value)) {
+        // Order is meaningful inside a list - a subjects list is the author's own
+        // ordering - so only object keys are sorted.
+        return `[${value.map(canonical).join(",")}]`;
+    }
+    if (value !== null && typeof value === "object") {
+        return `{${Object.entries(value)
+            .filter(([, entry]) => entry !== undefined)
+            .sort(([a], [b]) => (a < b ? -1 : 1))
+            .map(([key, entry]) => `${JSON.stringify(key)}:${canonical(entry)}`)
+            .join(",")}}`;
+    }
+    return JSON.stringify(value) ?? "null";
+};

package/dist/adapters/visual/wire.d.ts

@@ -1,5 +1,5 @@
 import type { CanvasGraph } from '../../graph-projection.js';
-import type { VISUAL_PROTOCOL_VERSION, VisualApplyResultPayload, VisualAuthority, VisualBrowserInput, VisualCapabilities, VisualChoicePresentPayload, VisualDiagnostic, VisualFilterResultPayload, VisualFreezeReason, VisualKindOption, VisualLayoutPositions, VisualLayoutSaveResultPayload, VisualResponse, VisualTerminationReason, VisualViewSaveResultPayload, VisualViewSummary } from './protocol-contract.js';
+import type { VISUAL_PROTOCOL_VERSION, VisualApplyResultPayload, VisualAuthority, VisualBrowserInput, VisualCapabilities, VisualChoicePresentPayload, VisualDiagnostic, VisualFilterResultPayload, VisualFreezeReason, VisualKindOption, VisualLayoutPositions, VisualLayoutSaveResultPayload, VisualResponse, VisualTerminationReason, VisualViewSummary } from './protocol-contract.js';
 /**
  * Transport shapes the session server and the browser application both speak.
  *
@@ -32,6 +32,17 @@ export interface VisualRenderedModel {
      * can state what it rendered when it asks for a commit.
      */
     readonly sourceDigests: Readonly<Record<string, string>>;
+    /**
+     * The sha256 of every projection this session knows about, keyed by
+     * manifest-relative path.
+     *
+     * Kept apart from `sourceDigests` rather than folded into it: that map means
+     * what the GRAPH was compiled from, which `YMVS112` requires a canonical
+     * model to state, and a projection is not part of it. A staged view
+     * operation pins against this one instead (ADR 0103), and a path absent from
+     * it is a projection the commit will create.
+     */
+    readonly projectionDigests: Readonly<Record<string, string>>;
 }
 /**
  * One line of the conversation, as plain text.
@@ -108,12 +119,16 @@ export type VisualServerFrame = {
 } | {
     readonly kind: 'model';
     readonly model: VisualRenderedModel;
+    /**
+     * The saved views again, because a recompile moves what their queries
+     * match and the tree states those counts. Required rather than optional:
+     * a recompile that shipped a graph without them would leave every count
+     * beside it describing the model before the commit.
+     */
+    readonly views: readonly VisualViewSummary[];
 } | {
     readonly kind: 'filter-result';
     readonly result: VisualFilterResultPayload;
-} | {
-    readonly kind: 'view-save-result';
-    readonly result: VisualViewSaveResultPayload;
 } | {
     readonly kind: 'apply-result';
     readonly result: VisualApplyResultPayload;

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

@@ -0,0 +1,116 @@
+import type { Diagnostic } from "../../compiler.js";
+import type { PendingWrite, SourceStore } from "../../source-store.js";
+import type { ResolvedWorkspace } from "../../workspace.js";
+import type { VisualDiagnostic, VisualViewOperation } from "./protocol-contract.js";
+import type { ProjectionDefinition, ProjectionExclusion, ProjectionQuery } from "../../projection.js";
+import type { ResolvedProfileContext, SemanticGraph } from "../../compiler.js";
+import type { VisualKindOption, VisualViewSummary } from "./protocol-contract.js";
+import type { VisualRenderedModel } from "./wire.js";
+/**
+ * What a workspace looks like to the editor, however the editor is being run
+ * (#252).
+ *
+ * These were the session server's, and the session server is one host now: an
+ * embedder mounting the editor over its own store computes the same model, the
+ * same vocabulary and the same view counts, and two definitions of any of them
+ * would be two answers to the same question. So the arithmetic lives here and
+ * the orchestration - which bytes to read, which digests to pin, what a layout
+ * sidecar says - stays with whoever owns those.
+ *
+ * Browser-safe: no `node:`, no filesystem, no session. Everything is a pure
+ * function of a compile result.
+ */
+/**
+ * The kinds a browser may offer, each with the core kind it descends from.
+ *
+ * `[0]` is the nearest declared ancestor, the same reading
+ * `projectGraphForCanvas` gives an authored subject its `coreKindLabel`. A kind
+ * with no lineage IS a core kind and stands for itself. Without the core label
+ * an editor can read a palette but cannot judge it: the ArchiMate table is
+ * keyed on core kinds, so offering an extension kind unchecked puts a `YM404`
+ * one click away.
+ */
+export declare const kindOptionsOf: (lineages: ReadonlyMap<string, readonly string[]>) => readonly VisualKindOption[];
+/**
+ * How many SUBJECTS a query matches, which is not the size of its match set.
+ *
+ * A `SemanticGraph`'s subjects are concepts and relationships together, so the
+ * match set returns both — right for narrowing a canvas that draws edges as
+ * well as nodes, and wrong for a number sitting beside a view called its
+ * subject count. A view over three components with two relationships between
+ * them would read as five, and the reviewer counting boxes would find three.
+ */
+export declare const conceptCountOf: (graph: SemanticGraph, query: ProjectionQuery, profileContext: ResolvedProfileContext) => number;
+/**
+ * Rebuilds the shared editor workspace from one successful compile.
+ *
+ * The caller owns metadata which cannot be inferred from a graph (authority,
+ * source revisions, layouts, and initial view); this helper owns all derived
+ * canvas, vocabulary, and view-count arithmetic.
+ */
+export declare const renderedWorkspaceOf: (compiled: {
+    readonly graph: SemanticGraph;
+    readonly profileContext: ResolvedProfileContext;
+}, views: readonly VisualViewSummary[], metadata: Omit<VisualRenderedModel, "graph" | "vocabulary">) => {
+    readonly model: VisualRenderedModel;
+    readonly views: readonly VisualViewSummary[];
+};
+/** Every subject a query draws, concepts and relationships alike. */
+export declare const matchedIdsOf: (graph: SemanticGraph, query: ProjectionQuery, profileContext: ResolvedProfileContext) => readonly string[];
+/** Every concept a query dropped, and the facet that dropped it (#248). */
+export declare const exclusionsOf: (graph: SemanticGraph, query: ProjectionQuery, profileContext: ResolvedProfileContext) => readonly ProjectionExclusion[];
+/**
+ * One saved view, as the rail reads it. `subjectCount` is the caller's,
+ * because counting needs a compiled graph and a session builds its first list
+ * before it has one.
+ */
+export declare const viewSummaryOf: (projection: ProjectionDefinition, path: string, subjectCount?: number) => VisualViewSummary;
+/**
+ * Applies a landed view batch to a host-owned list.
+ *
+ * Writes are read back through the callback, so a malformed or otherwise
+ * unreadable landed document cannot become a fabricated summary.
+ */
+export declare const adoptLandedViews: (views: readonly VisualViewSummary[], operations: readonly VisualViewOperation[], readSummary: (path: string) => VisualViewSummary | undefined) => readonly VisualViewSummary[];
+/**
+ * The document a diagnostic the runtime minted itself points at. Not a file:
+ * these are about the session rather than about anything the workspace holds.
+ */
+export declare const VISUAL_SERVER_DOCUMENT = "visual-session-server";
+export declare const published: (diagnostics: readonly Diagnostic[], sources: readonly {
+    readonly path: string;
+    readonly source: string;
+}[]) => readonly VisualDiagnostic[];
+export declare const serverDiagnostic: (code: string, message: string, pointer?: string) => VisualDiagnostic;
+/**
+ * Whether the workspace would load a projection written at this path.
+ *
+ * This is a DIRECTORY check, not a pattern match, and deliberately so: ADR
+ * 0100 recorded that the manifest's pattern dialect has never been named - it
+ * is whatever `globSync` happens to support, undocumented and untested past
+ * one wildcard - so a matcher written here would be inventing the dialect
+ * rather than honouring it. A directory that already holds a projection the
+ * manifest resolved is a directory the manifest demonstrably reaches.
+ *
+ * A workspace with no projections at all has nothing to demonstrate, so the
+ * default directory is allowed: refusing there would make the first view in a
+ * fresh workspace impossible to create.
+ */
+export declare const projectionDirectoryIsCovered: (path: string, workspace: ResolvedWorkspace) => boolean;
+/**
+ * Turns staged view operations into pending writes, refusing before anything
+ * is written (ADR 0103).
+ *
+ * A `write-view` is validated through the same `loadProjection` the CLI's own
+ * projection writes go through, so a document the schema would reject never
+ * reaches the store. A `delete-view` names a revision, which is what makes a
+ * removal refusable rather than a silent success on a file someone else
+ * already changed.
+ */
+export declare const planViewWrites: (operations: readonly VisualViewOperation[], workspace: ResolvedWorkspace, store: SourceStore) => {
+    readonly ok: true;
+    readonly writes: readonly PendingWrite[];
+} | {
+    readonly ok: false;
+    readonly diagnostics: readonly VisualDiagnostic[];
+};