@omgbase/core 0.15.0 → 0.21.0

package/dist/src/mutate/canonical.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Canonical JSON (§11.5): no whitespace; object keys sorted by their UTF-8
+ * bytes; members whose value is `undefined` omitted (an optional key absent is
+ * absent, never `null`; a JSON `null` value stays `null`); strings escaped only
+ * as JSON requires — `"`, `\`, and U+0000–U+001F (`\b \f \n \r \t`, else
+ * `\u00xx` lower-case) — everything else literal UTF-8; a number that is
+ * integral with |n| < 2^53 printed as a plain integer (`-0` as `0`), any other
+ * finite number by ECMAScript `Number::toString` (shortest round-trip digits);
+ * `true`/`false`/`null`.
+ */
+export declare function canonicalJson(v: unknown): string;
+/** A `plan` / `apply` / `execute` request as the caller gave it: `select`, `effects`, `expect` (each only when present). */
+export interface FixRequest {
+    select?: unknown;
+    effects: unknown;
+    expect?: unknown;
+}
+/** The `fix` for a request to the SAME tool: the corrected arguments, canonical JSON. */
+export declare function fixRequest(req: FixRequest): string;
+/** The `fix` naming another tool: `<tool> <canonical args>`. */
+export declare function fixTool(tool: string, args: unknown): string;
+/** The selector that names exactly one row: the request narrowed to `from <root> where id == "<id>"` with `expect.max: 1` (the fix of a cross-hit collision or an ambiguous target under a selector). */
+export declare function narrowedTo(root: "docs" | "blocks" | "nodes", id: string): string;
+/** The root a row id belongs to, by its prefix (`d_` / `b_` / `n_`). */
+export declare function rootOfId(id: string): "docs" | "blocks" | "nodes";
+/** `value` with the member at `path` (keys and array indices) replaced; a copy, the input untouched. */
+export declare function withMember(value: unknown, path: readonly string[], replacement: unknown): unknown;

package/dist/src/mutate/canonical.js

@@ -0,0 +1,138 @@
+import { MutationError } from "./tree.js";
+/** The argument-shape error of the surface (`effects.ts` `effectInvalid`), spelled here to avoid the module cycle. */
+function effectInvalid(message) {
+    return new MutationError("filter_invalid", message, { reason: message, hint: "arguments" });
+}
+// Canonical JSON (spec/mutate §11.5): the text a plan's digest is taken over,
+// and since 3.3 the text every error `fix` and every `summary` value is spelled
+// in — one serialization both engines produce byte for byte. Kept apart from
+// `plan.ts` so the compile (`select.ts`) and the lowering (`effects.ts`) can use
+// it without a module cycle.
+function cmpUtf8(a, b) {
+    return Buffer.compare(Buffer.from(a, "utf8"), Buffer.from(b, "utf8"));
+}
+// A lone surrogate has no UTF-8 encoding: it cannot be digested (nor sent as JSON text).
+function isWellFormed(s) {
+    for (let i = 0; i < s.length; i++) {
+        const c = s.charCodeAt(i);
+        if (c >= 0xd800 && c <= 0xdbff) {
+            const n = s.charCodeAt(i + 1);
+            if (!(n >= 0xdc00 && n <= 0xdfff))
+                return false;
+            i++;
+        }
+        else if (c >= 0xdc00 && c <= 0xdfff)
+            return false;
+    }
+    return true;
+}
+function canonicalString(s) {
+    if (!isWellFormed(s))
+        throw effectInvalid("strings must be well-formed Unicode (a lone surrogate cannot be digested)");
+    let out = '"';
+    for (let i = 0; i < s.length; i++) {
+        const c = s.charCodeAt(i);
+        switch (c) {
+            case 0x22:
+                out += '\\"';
+                break;
+            case 0x5c:
+                out += "\\\\";
+                break;
+            case 0x08:
+                out += "\\b";
+                break;
+            case 0x0c:
+                out += "\\f";
+                break;
+            case 0x0a:
+                out += "\\n";
+                break;
+            case 0x0d:
+                out += "\\r";
+                break;
+            case 0x09:
+                out += "\\t";
+                break;
+            default:
+                out += c < 0x20 ? `\\u${c.toString(16).padStart(4, "0")}` : s[i];
+        }
+    }
+    return out + '"';
+}
+function canonicalNumber(n) {
+    if (!Number.isFinite(n))
+        throw effectInvalid("a number in a plan must be finite");
+    if (Number.isInteger(n) && Math.abs(n) < 2 ** 53)
+        return String(n === 0 ? 0 : n);
+    return String(n);
+}
+/**
+ * Canonical JSON (§11.5): no whitespace; object keys sorted by their UTF-8
+ * bytes; members whose value is `undefined` omitted (an optional key absent is
+ * absent, never `null`; a JSON `null` value stays `null`); strings escaped only
+ * as JSON requires — `"`, `\`, and U+0000–U+001F (`\b \f \n \r \t`, else
+ * `\u00xx` lower-case) — everything else literal UTF-8; a number that is
+ * integral with |n| < 2^53 printed as a plain integer (`-0` as `0`), any other
+ * finite number by ECMAScript `Number::toString` (shortest round-trip digits);
+ * `true`/`false`/`null`.
+ */
+export function canonicalJson(v) {
+    if (v === null)
+        return "null";
+    switch (typeof v) {
+        case "boolean":
+            return v ? "true" : "false";
+        case "number":
+            return canonicalNumber(v);
+        case "string":
+            return canonicalString(v);
+        case "object": {
+            if (Array.isArray(v))
+                return `[${v.map((x) => canonicalJson(x === undefined ? null : x)).join(",")}]`;
+            const o = v;
+            const keys = Object.keys(o).filter((k) => o[k] !== undefined).sort(cmpUtf8);
+            return `{${keys.map((k) => `${canonicalString(k)}:${canonicalJson(o[k])}`).join(",")}}`;
+        }
+        default:
+            throw effectInvalid(`a ${typeof v} cannot be digested`);
+    }
+}
+/** The `fix` for a request to the SAME tool: the corrected arguments, canonical JSON. */
+export function fixRequest(req) {
+    return canonicalJson({
+        ...(req.select !== undefined ? { select: req.select } : {}),
+        effects: req.effects,
+        ...(req.expect !== undefined ? { expect: req.expect } : {}),
+    });
+}
+/** The `fix` naming another tool: `<tool> <canonical args>`. */
+export function fixTool(tool, args) {
+    return `${tool} ${canonicalJson(args)}`;
+}
+/** The selector that names exactly one row: the request narrowed to `from <root> where id == "<id>"` with `expect.max: 1` (the fix of a cross-hit collision or an ambiguous target under a selector). */
+export function narrowedTo(root, id) {
+    return `from ${root} where id == ${JSON.stringify(id)}`;
+}
+/** The root a row id belongs to, by its prefix (`d_` / `b_` / `n_`). */
+export function rootOfId(id) {
+    if (id.startsWith("d_"))
+        return "docs";
+    if (id.startsWith("n_"))
+        return "nodes";
+    return "blocks";
+}
+/** `value` with the member at `path` (keys and array indices) replaced; a copy, the input untouched. */
+export function withMember(value, path, replacement) {
+    if (path.length === 0)
+        return replacement;
+    const [head, ...rest] = path;
+    if (Array.isArray(value)) {
+        const copy = [...value];
+        copy[Number(head)] = withMember(copy[Number(head)], rest, replacement);
+        return copy;
+    }
+    const o = (typeof value === "object" && value !== null ? value : {});
+    return { ...o, [head]: withMember(o[head], rest, replacement) };
+}
+//# sourceMappingURL=canonical.js.map

package/dist/src/mutate/effects.d.ts

@@ -8,7 +8,10 @@ import { type LinkRepairCount, type RetargetHit } from "./macros.js";
 import type { At, Expect } from "./ops.js";
 import type { IdentityPreview } from "./opset.js";
 import { MutationError } from "./tree.js";
-/** What an effect addresses. `section` is a derived range (ADR-005), never a stored id. */
+import { type FixRequest } from "./canonical.js";
+/** What an effect addresses. `section` is a derived range (ADR-005), never a stored id.
+ *  `symbol` (3.2, §11.8 "Sugar"): a bare `"$new.n"` target whose kind — document or block — the
+ *  symbol table decides when the effect is resolved; it never reaches a resolved effect. */
 export type EffectTarget = {
     kind: "document";
     id?: string;
@@ -22,6 +25,9 @@ export type EffectTarget = {
 } | {
     kind: "section";
     heading_id: string;
+} | {
+    kind: "symbol";
+    id: string;
 };
 export type EffectAt = At;
 /** Guards: the kernel's two CAS fields plus the document's `current_rev` at plan time. */
@@ -167,12 +173,46 @@ export type ResolvedEffect = {
     }[];
     path_glob?: string;
 };
-/** The argument-shape error of the surface, thrown from the planner: `filter_invalid { reason, hint: "arguments" }`. */
-export declare function effectInvalid(message: string): MutationError;
-/** The shape check of one effect (§11.1). `i` names it in the message (`effects[i]`). */
-export declare function validateEffect(v: unknown, i: number): Effect;
+/** The argument-shape error of the surface, thrown from the planner: `filter_invalid { reason, hint: "arguments" }` — with a `fix` (3.4, §8) when the shape check can spell the corrected call. */
+export declare function effectInvalid(message: string, fix?: string): MutationError;
+/**
+ * What the shape check needs to spell a `fix` for the shape errors of §8
+ * (3.4): the request as given (the corrected call is that request with the
+ * offending effect rewritten — the effect at `effects[i]` AS WRITTEN, before
+ * any desugaring) and a live-row lookup for the one fix that needs the store:
+ * `parentOf(block id)` → the block's parent id (`null` at the top level) and
+ * its document's path (storage form), or `null` when no live block has the id
+ * (then there is no fix). The planner's compile (`select.ts`) supplies it; a
+ * library call without it gets the same errors with no `fix`.
+ */
+export interface ShapeFixContext {
+    request: FixRequest;
+    parentOf: (blockId: string) => {
+        parent: string | null;
+        path: string;
+    } | null;
+}
+/** The `-> ` leader (3.2, §11.8 "Sugar"): a string beginning exactly so is an OQX expression, the rest of the string. */
+export declare const EXPRESSION_LEADER = "-> ";
+/** A path-looking string: contains `/` or ends `.md` (the bare document target of §11.8 "Sugar"). */
+export declare function looksLikePath(s: string): boolean;
+/** A bare id of the three target kinds (§11.8 "Sugar"). */
+export declare function isTargetId(s: string): boolean;
+/**
+ * A bare string where a target object is expected (3.2, §11.8 "Sugar"): a
+ * path-looking string → `{ kind: "document", path }`; a `b_`/`d_`/`n_` id →
+ * that kind; `$new.n` → `{ kind: "symbol", id }` (its kind is the symbol
+ * table's at resolution); a `#` locator → `filter_invalid` with a `fix`;
+ * anything else is no target. A `-> ` leader never reaches here from the
+ * planner (`select.ts` desugars it first); as a library input it is refused
+ * the same way, naming the planner.
+ */
+export declare function bareTarget(ref: string, here: string): EffectTarget;
+export declare function validateTarget(v: unknown, here: string, kinds: readonly EffectTarget["kind"][]): EffectTarget;
+/** The shape check of one effect (§11.1). `i` names it in the message (`effects[i]`); `fix` (3.4) lets the shape errors of §8 carry their corrected call. */
+export declare function validateEffect(v: unknown, i: number, fix?: ShapeFixContext): Effect;
 /** The whole list; a non-array or an empty list is a shape error too. */
-export declare function validateEffects(v: unknown): Effect[];
+export declare function validateEffects(v: unknown, fix?: ShapeFixContext): Effect[];
 export declare const FRONTMATTER_FIELD: RegExp;
 /** The focus a conflict names: `{ kind, target, field? }`. */
 export interface Focus {
@@ -304,6 +344,8 @@ export interface LoweringContext {
     canonical: (v: unknown) => string;
     /** the resolved effects kept (dropped duplicates excluded) */
     resolved: ResolvedEffect[];
+    /** `preview.summary` (3.3, §11.9): one line in words per resolved effect, in order */
+    summary: string[];
 }
 /** Resolve a document target: an existing document's `{ id, path }`, or a `$new.n` document this plan creates. */
 export declare function resolveDocumentTarget(ctx: LoweringContext, t: Extract<EffectTarget, {
@@ -311,8 +353,16 @@ export declare function resolveDocumentTarget(ctx: LoweringContext, t: Extract<E
 }>): Extract<ResolvedTarget, {
     kind: "document";
 }>;
-/** Resolve one validated effect's targets (§11.4): documents to `{ id, path }`, defaults made explicit. */
-export declare function resolveEffect(ctx: LoweringContext, e: Effect): ResolvedEffect;
+/** An existing document's `{ id, path }` for a literal document target (`doc_missing`; `filter_invalid` when `id` and `path` disagree). */
+export declare function findDocumentTarget(store: Store, repoId: string, t: Extract<EffectTarget, {
+    kind: "document";
+}>): Extract<ResolvedTarget, {
+    kind: "document";
+}>;
+/** `1 block` / `2 blocks` (an `s` on every noun of the table). */
+export declare function plural(n: number, noun: string): string;
+/** Resolve one validated effect's targets (§11.4): documents to `{ id, path }`, defaults made explicit; `i` names the effect in messages. */
+export declare function resolveEffect(ctx: LoweringContext, e: Effect, i?: number): ResolvedEffect;
 /** Shift a kernel op's `$n.ids[i]` placeholders by `offset` (an opset planned alone, spliced into a longer op list). */
 export declare function shiftPlaceholders(op: Op, offset: number): Op;
 /**