@graview/tools 0.1.0

package/dist/plan.js

@@ -0,0 +1,303 @@
+import { beginning, PermissionDeniedError, } from "@graview/core";
+export function isPlanReference(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        typeof value.$plan === "string");
+}
+const refusal = (mutation, message) => ({ mutation, message, wouldNeed: [] });
+/**
+ * Orders and judges a set of proposals.
+ *
+ * Ordering is by what each call NEEDS: a call referring to `{ $plan: "lawn" }`
+ * comes after the call named `lawn`; beyond that, by the declaration's own
+ * chain, so a zone is made before a feature even when nothing in the plan
+ * says so. A reference to a name the plan never makes, and a cycle between
+ * two of them, are refusals rather than a runtime surprise.
+ */
+export function planFrom(store, proposals, options = {}) {
+    const named = new Map();
+    proposals.forEach((call, index) => {
+        if (call.as !== undefined && !named.has(call.as))
+            named.set(call.as, index);
+    });
+    /** The plan-names each call waits for. */
+    const waitsFor = (call) => {
+        const found = [];
+        const walk = (value) => {
+            if (isPlanReference(value))
+                found.push(value.$plan);
+            else if (Array.isArray(value))
+                for (const item of value)
+                    walk(item);
+            else if (value !== null && typeof value === "object") {
+                for (const item of Object.values(value))
+                    walk(item);
+            }
+        };
+        walk(call.args);
+        return found;
+    };
+    /*
+     * THE CHAIN THE DECLARATION STATES, as a tiebreak. Two calls that refer to
+     * nothing still have an order — a zone before a feature — and the app
+     * already said which. Without it a plan that happens to list the feature
+     * first fails on a picker that has nothing in it yet.
+     */
+    const depthOf = new Map();
+    if (options.app) {
+        for (const entry of beginning(options.app).order) {
+            depthOf.set(entry.kind, entry.depth ?? Number.MAX_SAFE_INTEGER);
+        }
+    }
+    const rank = (call) => {
+        let made = [];
+        try {
+            made = (store.mutation(call.mutation).creates ?? []);
+        }
+        catch {
+            return Number.MAX_SAFE_INTEGER;
+        }
+        if (made.length === 0)
+            return Number.MAX_SAFE_INTEGER - 1;
+        return Math.min(...made.map((kind) => depthOf.get(kind) ?? 0));
+    };
+    /* Kahn's, over the plan's own names, with the chain as the tiebreak. */
+    const remaining = proposals.map((call, index) => ({ call, index }));
+    const done = new Set();
+    const ordered = [];
+    const stuck = [];
+    while (remaining.length > 0) {
+        const ready = remaining.filter((entry) => waitsFor(entry.call).every((name) => done.has(name) || !named.has(name)));
+        if (ready.length === 0) {
+            /* A cycle: nothing left can go first. They are refused, not guessed at. */
+            stuck.push(...remaining.map((entry) => entry.call));
+            break;
+        }
+        ready.sort((a, b) => rank(a.call) - rank(b.call) || a.index - b.index);
+        const next = ready[0];
+        ordered.push(next.call);
+        if (next.call.as !== undefined)
+            done.add(next.call.as);
+        remaining.splice(remaining.indexOf(next), 1);
+    }
+    const entries = [...ordered, ...stuck].map((call, at) => {
+        const dependsOn = [...new Set(waitsFor(call).filter((name) => named.has(name)))];
+        const cycled = stuck.includes(call);
+        if (cycled) {
+            return {
+                call,
+                at,
+                dependsOn,
+                refusal: refusal(call.mutation, "This call and another wait for each other, so neither can go first."),
+            };
+        }
+        const dangling = waitsFor(call).filter((name) => !named.has(name));
+        if (dangling.length > 0) {
+            return {
+                call,
+                at,
+                dependsOn,
+                refusal: refusal(call.mutation, `Refers to ${dangling.map((name) => `"${name}"`).join(", ")}, which nothing in this plan makes.`),
+            };
+        }
+        let known = true;
+        try {
+            store.mutation(call.mutation);
+        }
+        catch {
+            known = false;
+        }
+        if (!known) {
+            return {
+                call,
+                at,
+                dependsOn,
+                refusal: refusal(call.mutation, `No act called "${call.mutation}" is registered.`),
+            };
+        }
+        /*
+         * The policy's own answer, asked now rather than at the press. A call
+         * whose arguments still hold plan references cannot be judged on its
+         * subject yet — the node does not exist — so the question asked is the
+         * one that can be: may this seat run this act at all.
+         */
+        if (options.principal) {
+            const verdict = store.permits({ name: call.mutation, args: {} }, options.principal);
+            if (!verdict.ok)
+                return { call, at, dependsOn, refusal: verdict.refusal };
+        }
+        return { call, at, dependsOn };
+    });
+    const makes = {};
+    for (const entry of entries) {
+        if (entry.refusal)
+            continue;
+        let created = [];
+        try {
+            created = (store.mutation(entry.call.mutation).creates ?? []);
+        }
+        catch {
+            created = [];
+        }
+        for (const kind of created)
+            makes[kind] = (makes[kind] ?? 0) + 1;
+    }
+    return {
+        entries,
+        ready: entries.filter((entry) => entry.refusal === undefined),
+        refused: entries.filter((entry) => entry.refusal !== undefined),
+        makes,
+    };
+}
+/**
+ * Applies a plan's ready entries as ONE TURN.
+ *
+ * Sequentially rather than in a single `applyAll`, because a call can refer
+ * to what an earlier one made and those ids do not exist until it has run —
+ * but under one batch, so the activity shows one entry and `store.undo(batch)`
+ * takes the whole seeding back the way it arrived.
+ *
+ * ALL OR NOTHING, and it says where it stopped. A plan that half-applied
+ * leaves a graph nobody meant and an undo nobody trusts, so what the batch
+ * has written is taken back before the error reaches the caller — and the
+ * result names the call that failed and why, because a plan that silently
+ * vanished would be its own kind of wrong. `keepWhatRan` is for a caller who
+ * would rather have the half: a long seeding whose last call was a typo.
+ */
+export function applyPlan(store, plan, options = {}) {
+    const batch = options.batch ?? `plan:${Date.now().toString(36)}`;
+    const made = {};
+    let applied = 0;
+    const resolve = (value) => {
+        if (isPlanReference(value))
+            return made[value.$plan] ?? value.$plan;
+        if (Array.isArray(value))
+            return value.map(resolve);
+        if (value !== null && typeof value === "object") {
+            return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, resolve(item)]));
+        }
+        return value;
+    };
+    for (const entry of plan.ready) {
+        const args = resolve(entry.call.args);
+        options.before?.(entry, args);
+        try {
+            /*
+             * THE LOG KEEPS THE NUMBER. A review shows how sure a proposer was
+             * beside each row and orders by it; the op that lands still records
+             * it in its intent, because the log is the record and "why" without
+             * "how sure" is half a reason.
+             */
+            const sure = entry.call.confidence;
+            const intent = sure !== undefined && !/\d+% sure/.test(entry.call.why ?? "")
+                ? `${entry.call.why ?? ""} (${Math.round(sure * 100)}% sure)`.trim()
+                : (entry.call.why ?? "");
+            // A plan with no `why` keeps the act's own sentence; an empty intent would silence it.
+            const result = store.apply({ name: entry.call.mutation, args }, { ...(options.author ? { author: options.author } : {}), batch, ...(intent ? { intent } : {}) });
+            applied += 1;
+            if (entry.call.as !== undefined) {
+                /* What it made: the one node this call added, if it added one. */
+                const added = result.ops
+                    .flatMap((op) => op.primitives)
+                    .filter((primitive) => primitive.op === "add-node")
+                    .map((primitive) => primitive.node.id);
+                if (added.length === 1)
+                    made[entry.call.as] = added[0];
+            }
+        }
+        catch (error) {
+            const why = error instanceof PermissionDeniedError
+                ? error.refusal.message
+                : error instanceof Error
+                    ? error.message
+                    : String(error);
+            let undone = false;
+            if (!options.keepWhatRan && applied > 0) {
+                store.undo(batch, options.author ? { author: options.author } : {});
+                undone = true;
+            }
+            return {
+                made,
+                batch,
+                applied,
+                stoppedAt: { at: entry.at, why },
+                ...(undone ? { undone: true } : {}),
+                store,
+            };
+        }
+    }
+    return { made, batch, applied, store };
+}
+/**
+ * EVERYTHING THAT GOES IF THIS GOES.
+ *
+ * Declining the area declines the tree standing in it. A review a person
+ * cannot disagree with is not a review — a model confident about eleven
+ * things and wrong about the twelfth is the normal case — and the twelfth
+ * is very often the one the other four point at. Saying so BEFORE the press
+ * is the difference between a review and a surprise.
+ *
+ * Only what POINTS AT it, transitively. A call that merely mentions the same
+ * subject is its own business.
+ */
+export function dependentsOf(plan, name) {
+    const gone = new Set([name]);
+    const going = new Set();
+    for (let grew = true; grew;) {
+        grew = false;
+        for (const entry of plan.entries) {
+            if (going.has(entry))
+                continue;
+            if (!entry.dependsOn.some((wanted) => gone.has(wanted)))
+                continue;
+            going.add(entry);
+            /*
+             * A call that MAKES something carries its own dependents with it; one
+             * that makes nothing is a leaf. Both go, and only the first widens the
+             * set — which is why this is the entries rather than their names: half
+             * of what goes with a thing was never named.
+             */
+            if (entry.call.as !== undefined)
+                gone.add(entry.call.as);
+            grew = true;
+        }
+    }
+    return [...going];
+}
+/**
+ * The plan without those entries, and without anything left pointing at
+ * nothing — the same plan a person is left with after declining one thing.
+ *
+ * Re-planned rather than filtered, so what comes back is ordered, judged and
+ * counted exactly like the plan it came from.
+ */
+export function without(store, plan, declined, options = {}) {
+    const out = new Set();
+    const names = new Set();
+    for (const name of declined) {
+        names.add(name);
+        for (const entry of dependentsOf(plan, name))
+            out.add(entry);
+    }
+    const kept = plan.entries
+        .filter((entry) => entry.call.as === undefined || !names.has(entry.call.as))
+        .filter((entry) => !out.has(entry))
+        .map((entry) => entry.call);
+    return planFrom(store, kept, options);
+}
+/** What a plan would do, in the words a person reviewing it needs. */
+export function describePlan(plan) {
+    const makes = Object.entries(plan.makes)
+        .map(([kind, count]) => `${count} ${kind}${count === 1 ? "" : "s"}`)
+        .join(", ");
+    const lines = [
+        `${plan.ready.length} of ${plan.entries.length} to run${makes ? `, making ${makes}` : ""}.`,
+    ];
+    for (const entry of plan.entries) {
+        lines.push(`${entry.refusal ? "✗" : "→"} ${entry.call.mutation}${entry.call.as ? ` (${entry.call.as})` : ""}` +
+            `${entry.call.why ? ` — ${entry.call.why}` : ""}` +
+            `${entry.refusal ? `  REFUSED: ${entry.refusal.message}` : ""}`);
+    }
+    return lines.join("\n");
+}
+//# sourceMappingURL=plan.js.map

package/dist/plan.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan.js","sourceRoot":"","sources":["../src/plan.ts"],"names":[],"mappings":"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"}

package/dist/providers/insight.d.ts

@@ -0,0 +1,14 @@
+import { type AnySchema } from "@graview/core";
+import type { AffordanceProvider } from "../types.js";
+/**
+ * THE GRAPH ITSELF IS THE FIRST INTELLIGENCE.
+ *
+ * Before any model or key exists, the typed graph already knows things
+ * worth saying: a selected node connected to nothing, one node carrying
+ * most of an edge kind, an empty kind that other kinds declare edges into.
+ * These ship as observations — statements, not suggestions — because their
+ * authority is structural fact, and a fact should not have to dress up as
+ * advice to be seen.
+ */
+export declare function insightProvider<S extends AnySchema>(): AffordanceProvider<S>;
+//# sourceMappingURL=insight.d.ts.map

package/dist/providers/insight.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"insight.d.ts","sourceRoot":"","sources":["../../src/providers/insight.ts"],"names":[],"mappings":"AAAA,OAAO,EAAW,KAAK,SAAS,EAAE,MAAM,eAAe,CAAC;AACxD,OAAO,KAAK,EAAE,kBAAkB,EAAe,MAAM,aAAa,CAAC;AAEnE;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,SAAS,KAAK,kBAAkB,CAAC,CAAC,CAAC,CAiF5E"}

package/dist/providers/insight.js

@@ -0,0 +1,81 @@
+import { labelOf } from "@graview/core";
+/**
+ * THE GRAPH ITSELF IS THE FIRST INTELLIGENCE.
+ *
+ * Before any model or key exists, the typed graph already knows things
+ * worth saying: a selected node connected to nothing, one node carrying
+ * most of an edge kind, an empty kind that other kinds declare edges into.
+ * These ship as observations — statements, not suggestions — because their
+ * authority is structural fact, and a fact should not have to dress up as
+ * advice to be seen.
+ */
+export function insightProvider() {
+    return {
+        name: "insight",
+        derive({ store, nodes, kindSelection }) {
+            const observations = [];
+            const name = (node) => labelOf(store.schema.tryDefinition(node.kind), node);
+            for (const node of nodes) {
+                // ------------------------------------------------------- an island
+                const degree = [...store.schema.edgeKinds].reduce((count, edgeKind) => count +
+                    store.graph.out(node.id, edgeKind).length +
+                    store.graph.in(node.id, edgeKind).length, 0);
+                if (degree === 0) {
+                    observations.push({
+                        id: `insight:island:${node.id}`,
+                        text: `${name(node)} is connected to nothing yet`,
+                        nodeIds: [node.id],
+                    });
+                    continue;
+                }
+                /*
+                 * ------------------------------------------------- a concentration
+                 * One node holding most of an edge kind is the structural shape of
+                 * overload — "Ana carries 5 of 6 runs" — derivable with no idea
+                 * what a run is.
+                 */
+                for (const edgeKind of store.schema.edgeKinds) {
+                    const mine = store.graph.in(node.id, edgeKind).length;
+                    if (mine < 3)
+                        continue;
+                    const everywhere = [...store.graph.allEdges()].filter((edge) => edge.kind === edgeKind).length;
+                    if (everywhere >= 4 && mine / everywhere > 0.6) {
+                        observations.push({
+                            id: `insight:load:${node.id}:${edgeKind}`,
+                            text: `${name(node)} holds ${mine} of ${everywhere} "${edgeKind}" — most of them`,
+                            nodeIds: [node.id],
+                        });
+                    }
+                }
+            }
+            // ------------------------------------------------------------- a gap
+            for (const kind of kindSelection) {
+                if (store.graph.nodesOfKind(kind).length > 0)
+                    continue;
+                const expectedBy = store.schema.definitions
+                    /*
+                     * OTHER kinds, and only other kinds.
+                     *
+                     * A first kind with an edge to itself — which is what a scaffolded
+                     * project starts with — made this say "Nothing here yet, though
+                     * Items expect to connect to these" on an empty graph: the
+                     * expectant party was the absent kind itself, so the sentence
+                     * named no one and pointed at nothing. A gap is only worth
+                     * stating when somebody ELSE is waiting on it.
+                     */
+                    .filter((definition) => definition.kind !== kind)
+                    .filter((definition) => Object.values(definition.edges).some((edge) => edge.to !== "*" && edge.to.includes(kind)))
+                    .map((definition) => definition.plural ?? `${definition.kind}s`);
+                if (expectedBy.length > 0) {
+                    observations.push({
+                        id: `insight:gap:${kind}`,
+                        text: `Nothing here yet, though ${expectedBy.join(" and ")} expect to connect to these`,
+                        nodeIds: [],
+                    });
+                }
+            }
+            return { observations };
+        },
+    };
+}
+//# sourceMappingURL=insight.js.map

package/dist/providers/insight.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"insight.js","sourceRoot":"","sources":["../../src/providers/insight.ts"],"names":[],"mappings":"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"}

package/dist/providers/invariant.d.ts

@@ -0,0 +1,14 @@
+import { type AnySchema } from "@graview/core";
+import type { AffordanceProvider } from "../types.js";
+/**
+ * Violations touching the selection, and the repairs that would resolve them.
+ *
+ * This is why `repairs` exists on a violation at all: the invariant engine
+ * already knows both the problem and the mutations that would fix it, so a
+ * repair reaches the interface without anyone writing a rule to connect them.
+ * Repairs outrank every other provider — a thing that is currently broken is
+ * more interesting than a thing you could do.
+ */
+export declare function invariantProvider<S extends AnySchema>(): AffordanceProvider<S>;
+/** A node's own label, falling back to its id. */
+//# sourceMappingURL=invariant.d.ts.map

package/dist/providers/invariant.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"invariant.d.ts","sourceRoot":"","sources":["../../src/providers/invariant.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkC,KAAK,SAAS,EAAE,MAAM,eAAe,CAAC;AAC/E,OAAO,KAAK,EAAc,kBAAkB,EAAe,MAAM,aAAa,CAAC;AAI/E;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,SAAS,KAAK,kBAAkB,CAAC,CAAC,CAAC,CAsH9E;AAED,kDAAkD"}

package/dist/providers/invariant.js

@@ -0,0 +1,123 @@
+import { argShape, labelOf, nodeRefArgs } from "@graview/core";
+const REPAIR_SCORE = 100;
+/**
+ * Violations touching the selection, and the repairs that would resolve them.
+ *
+ * This is why `repairs` exists on a violation at all: the invariant engine
+ * already knows both the problem and the mutations that would fix it, so a
+ * repair reaches the interface without anyone writing a rule to connect them.
+ * Repairs outrank every other provider — a thing that is currently broken is
+ * more interesting than a thing you could do.
+ */
+export function invariantProvider() {
+    return {
+        name: "invariant",
+        derive({ store, selection, nodes, violations }) {
+            // A node's name as its kind says it, not its label field alone.
+            const named = (node) => labelOf(store.schema.tryDefinition(node.kind), node);
+            const selected = new Set(selection);
+            const touching = violations.filter((violation) => violation.nodeIds.some((id) => selected.has(id)) ||
+                (violation.subjectId !== undefined && selected.has(violation.subjectId)));
+            const affordances = [];
+            const observations = [];
+            touching.forEach((violation, index) => {
+                observations.push({
+                    id: `violation:${violation.invariant}:${index}`,
+                    text: violation.message,
+                    nodeIds: violation.nodeIds,
+                });
+                violation.repairs.forEach((repair, repairIndex) => {
+                    affordances.push({
+                        id: `invariant:${violation.invariant}:${index}:${repairIndex}`,
+                        label: repair.label,
+                        provider: "invariant",
+                        mutation: repair.mutation,
+                        args: repair.args ?? {},
+                        /*
+                         * A repair names the mutation it would run, so everything the
+                         * schema provider derives applies here too: what sort of answer
+                         * the argument wants, and — when it names a node — which nodes
+                         * would actually fit.
+                         *
+                         * The candidates were missing, and the omission only showed up
+                         * in a second app: a repair saying "cover this in a section"
+                         * with `sectionId` unanswered rendered as a free text box asking
+                         * for a node id. Every repair that needed a node was unusable,
+                         * and the household example never noticed because its repairs happened to
+                         * carry their node arguments pre-filled.
+                         */
+                        open: (repair.missing ?? []).map((name) => {
+                            const mutation = store
+                                .allMutations()
+                                .find((candidate) => candidate.name === repair.mutation);
+                            if (!mutation)
+                                return { name };
+                            const ref = nodeRefArgs(mutation.input).find((arg) => arg.name === name);
+                            const candidates = ref
+                                ? ref.kinds.includes("*")
+                                    ? store.graph.allNodes().map((node) => node.id)
+                                    : ref.kinds.flatMap((kind) => store.graph.nodesOfKind(kind).map((node) => node.id))
+                                : undefined;
+                            return {
+                                name,
+                                shape: argShape(mutation.input, name),
+                                ...(ref ? { kinds: ref.kinds } : {}),
+                                ...(candidates ? { candidates } : {}),
+                            };
+                        }),
+                        // A repair that needs nothing more is the readiest thing here.
+                        score: REPAIR_SCORE - repairIndex - (repair.missing?.length ?? 0),
+                        why: violation.message,
+                        nodeIds: violation.nodeIds,
+                        // Carried so the ranking can lead with the repairs of the RULE
+                        // you clicked, the same way it leads with a task's own.
+                        ...(violation.subjectId === undefined ? {} : { subjectId: violation.subjectId }),
+                    });
+                });
+            });
+            /*
+             * A rule that is HOLDING says so, rather than showing nothing.
+             *
+             * A rule node has no edges, so selecting one used to change nothing on
+             * screen and read as broken. Lighting what it judges fixed half of
+             * that; the other half is the case where it judges everything
+             * correctly — silence there is indistinguishable from a rule that does
+             * not work, and "nothing is wrong" is an answer.
+             *
+             * Which nodes are rules is derivable: an invariant declares the kind it
+             * is scoped to, and a kind may declare the invariant it requires.
+             * Nothing is authored per app.
+             */
+            for (const node of nodes) {
+                const judged = store
+                    .allInvariants()
+                    .filter((invariant) => {
+                    if (invariant.scope === "graph")
+                        return false;
+                    const scope = invariant.scope;
+                    if (scope.kind !== node.kind)
+                        return false;
+                    return scope.match ? scope.match(node) : true;
+                });
+                if (judged.length === 0)
+                    continue;
+                /*
+                 * Not while ANY rule names it. A song implicated in its single's
+                 * rule — the subject is the single — read "Kerosene holds — nothing
+                 * currently breaks it" directly above the rule saying what was wrong
+                 * with it.
+                 */
+                if (touching.some((violation) => violation.subjectId === node.id || violation.nodeIds.includes(node.id)))
+                    continue;
+                observations.push({
+                    id: `holds:${node.id}`,
+                    text: `${named(node)} holds — nothing currently breaks ${judged.length === 1 ? "it" : `any of its ${judged.length} rules`}`,
+                    nodeIds: [node.id],
+                });
+            }
+            return { affordances, observations };
+        },
+    };
+}
+/** A node's own label, falling back to its id. */
+//# sourceMappingURL=invariant.js.map

package/dist/providers/invariant.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"invariant.js","sourceRoot":"","sources":["../../src/providers/invariant.ts"],"names":[],"mappings":"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"}