@zvndev/darkmown 2.4.0 → 2.5.0

package/types/tools/grammar.d.ts

@@ -0,0 +1,44 @@
+/** @returns {string[]} Every category name, for callers that want to enumerate. */
+export function categoryNames(): string[];
+/**
+ * TOOL ENTRY POINT.
+ *
+ * @param {string[]} [categories] Category names. Omitted or empty means all of
+ *   them, which is the whole cheatsheet and is the thing this tool exists to
+ *   avoid sending.
+ * Failures use the same {ok, text, data} shape as every other tool. It used to
+ * answer {ok: false, error}, which `Session` never reads, so an unknown category
+ * handed the model an undefined message.
+ *
+ * @returns {{ok: boolean, text: string, data: object}}
+ */
+export function grammar(categories?: string[]): {
+    ok: boolean;
+    text: string;
+    data: object;
+};
+/**
+ * How much a slice saves against sending everything.
+ *
+ * The plan claims filtering the cheatsheet is both a context saving and a
+ * hallucination guard. The saving half is measurable, so it gets measured
+ * rather than asserted.
+ *
+ * @param {string[]} categories
+ * @returns {{sliceChars: number, fullChars: number, saved: number, savedPct: number}}
+ */
+export function grammarCost(categories: string[]): {
+    sliceChars: number;
+    fullChars: number;
+    saved: number;
+    savedPct: number;
+};
+export namespace CATEGORIES {
+    let state: string[];
+    let loops: string[];
+    let actions: string[];
+    let forms: string[];
+    let fetch: string[];
+    let structure: string[];
+    let media: string[];
+}

package/types/tools/index.d.ts

@@ -0,0 +1,75 @@
+/**
+ * The tool list rendered for a system prompt.
+ *
+ * Same discipline as the cheatsheet: concrete argument examples, never
+ * `[optional]` bracket notation, because small models copy schematic notation
+ * into their output verbatim.
+ *
+ * @returns {string}
+ */
+export function toolPrompt(): string;
+/**
+ * The tool list as a model should be told about it: name, when to reach for it,
+ * and the exact argument shape. Kept here rather than in a prompt file so the
+ * description can never drift from the dispatcher.
+ */
+export const TOOL_SPECS: {
+    name: string;
+    args: string;
+    use: string;
+}[];
+/**
+ * A working copy of a project plus the tools that operate on it.
+ *
+ * Edits are staged in the session, not written to disk, so a caller can apply,
+ * validate, and roll back without touching a filesystem. `history` exists so a
+ * run can be scored later on how many calls it took, which is the number that
+ * decides whether the tool surface is worth its context budget.
+ */
+export class Session {
+    /**
+     * @param {Record<string, string>} files Project-relative path → contents.
+     * @param {string} entry The file being edited.
+     */
+    constructor(files: Record<string, string>, entry: string);
+    files: {
+        [x: string]: string;
+    };
+    entry: string;
+    original: string;
+    /** @type {{tool: string, args: object, ok: boolean}[]} */
+    history: {
+        tool: string;
+        args: object;
+        ok: boolean;
+    }[];
+    /**
+     * Dispatch one tool call.
+     *
+     * An unknown tool name is answered with the list rather than an exception,
+     * because a model that guessed a name can recover from a list and cannot
+     * recover from a stack trace.
+     *
+     * @param {string} tool
+     * @param {object} [args]
+     * @returns {{ok: boolean, text: string, data?: object}}
+     */
+    call(tool: string, args?: object): {
+        ok: boolean;
+        text: string;
+        data?: object;
+    };
+    /** @returns {string} The current content of the file under edit. */
+    content(): string;
+    /** Discard all staged edits. @returns {void} */
+    reset(): void;
+    #private;
+}
+import { apply } from "./apply.js";
+import { deps } from "./outline.js";
+import { grammar } from "./grammar.js";
+import { outline } from "./outline.js";
+import { parseToolCall } from "./parse.js";
+import { refs } from "./outline.js";
+import { validate } from "./validate.js";
+export { apply, deps, grammar, outline, parseToolCall, refs, validate };

package/types/tools/outline.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Compile and return one symbol per source construct, with every line resolved.
+ *
+ * Two foldings happen here, both forced by how the compiler works rather than by
+ * taste. A statically-unrolled `@loop` recompiles its body once per row, so a
+ * directive inside it records N identical symbols at one `file:line`; and a prose
+ * read inside such a loop records N line-less reads. Both collapse to one.
+ *
+ * The `compiled` half is the compiler's own result, derived from the function
+ * rather than restated here: widening it to `object` compiled fine while these
+ * lived under bench/, and silently lost every property check the moment they
+ * became part of the package.
+ *
+ * @typedef {ReturnType<typeof compileFromMemory>} Compiled
+ * @typedef {import("../compiler/context.js").Symbol} Symbol
+ *
+ * @param {Record<string, string>} files
+ * @param {string} entry
+ * @returns {{ok: true, symbols: Symbol[], compiled: Compiled} | {ok: false, error: string}}
+ */
+export function symbolsOf(files: Record<string, string>, entry: string): {
+    ok: true;
+    symbols: Symbol[];
+    compiled: Compiled;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * TOOL ENTRY POINT: outline(files, entry)
+ *
+ * @param {Record<string, string>} files
+ * @param {string} entry
+ * @returns {{ok: boolean, text: string, data: object}}
+ */
+export function outline(files: Record<string, string>, entry: string): {
+    ok: boolean;
+    text: string;
+    data: object;
+};
+/**
+ * TOOL ENTRY POINT: refs(files, entry, name)
+ *
+ * Every place a symbol is declared, written, or read, across the entry and
+ * everything it includes. This is the query behind impact expansion: "what else
+ * needs to change" is a lookup, not something a model should be recalling.
+ *
+ * @param {Record<string, string>} files
+ * @param {string} entry
+ * @param {string} [name] Symbol name, e.g. `cart`. Missing is reported, not thrown.
+ * @returns {{ok: boolean, text: string, data: object}}
+ */
+export function refs(files: Record<string, string>, entry: string, name?: string): {
+    ok: boolean;
+    text: string;
+    data: object;
+};
+/**
+ * TOOL ENTRY POINT: deps(files, entry)
+ *
+ * What this page pulls in (includes, data files, collections) and, for any other
+ * page in the project, whether it pulls in the same thing. The reverse direction
+ * is what makes "I changed a partial, what breaks" answerable.
+ *
+ * @param {Record<string, string>} files
+ * @param {string} entry
+ * @returns {{ok: boolean, text: string, data: object}}
+ */
+export function deps(files: Record<string, string>, entry: string): {
+    ok: boolean;
+    text: string;
+    data: object;
+};
+/**
+ * Compile and return one symbol per source construct, with every line resolved.
+ *
+ * Two foldings happen here, both forced by how the compiler works rather than by
+ * taste. A statically-unrolled `@loop` recompiles its body once per row, so a
+ * directive inside it records N identical symbols at one `file:line`; and a prose
+ * read inside such a loop records N line-less reads. Both collapse to one.
+ *
+ * The `compiled` half is the compiler's own result, derived from the function
+ * rather than restated here: widening it to `object` compiled fine while these
+ * lived under bench/, and silently lost every property check the moment they
+ * became part of the package.
+ */
+export type Compiled = ReturnType<typeof compileFromMemory>;
+/**
+ * Compile and return one symbol per source construct, with every line resolved.
+ *
+ * Two foldings happen here, both forced by how the compiler works rather than by
+ * taste. A statically-unrolled `@loop` recompiles its body once per row, so a
+ * directive inside it records N identical symbols at one `file:line`; and a prose
+ * read inside such a loop records N line-less reads. Both collapse to one.
+ *
+ * The `compiled` half is the compiler's own result, derived from the function
+ * rather than restated here: widening it to `object` compiled fine while these
+ * lived under bench/, and silently lost every property check the moment they
+ * became part of the package.
+ */
+export type Symbol = import("../compiler/context.js").Symbol;
+import { compileFromMemory } from "../compiler.js";

package/types/tools/parse.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @typedef {object} ToolCall
+ * @property {string} tool
+ * @property {object} args
+ */
+/**
+ * Pull the first complete JSON object out of a reply.
+ *
+ * Scans with a brace counter that is string- and escape-aware, because the one
+ * thing a Darkmown edit reliably contains is `{ count }`, and a naive
+ * `indexOf("}")` truncates exactly the calls that matter most.
+ *
+ * @param {string} reply
+ * @returns {{ok: true, call: ToolCall} | {ok: false, error: string}}
+ */
+export function parseToolCall(reply: string): {
+    ok: true;
+    call: ToolCall;
+} | {
+    ok: false;
+    error: string;
+};
+export type ToolCall = {
+    tool: string;
+    args: object;
+};

package/types/tools/validate.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Reduce any path the compiler hands back to the caller's own key form.
+ *
+ * The caller addresses files with POSIX keys (`site/pages/index.wd`), but
+ * `compileFromMemory` resolves them against its virtual root with
+ * `path.resolve`, which is PLATFORM-NATIVE: on Windows the same file comes back
+ * as `C:\site\pages\index.wd`. Comparing that to the caller's keys matches
+ * nothing, so every symbol gets filed under a path that is not in the project
+ * and every symbol-targeted edit fails. The virtual root is not a real
+ * filesystem and its separator is an accident of the host, so normalising here
+ * is the fix rather than a workaround.
+ *
+ * @param {string} p
+ * @returns {string}
+ */
+export function posixKey(p: string): string;
+/**
+ * Shorten a virtual absolute path to what the author would call the file.
+ * The model never saw `/site/pages/`, so echoing it back is noise it may copy.
+ * @param {string} p
+ * @returns {string}
+ */
+export function shortPath(p: string): string;
+/**
+ * TOOL ENTRY POINT.
+ *
+ * @param {Record<string, string>} files Project-relative path → contents, e.g.
+ *   `{"site/pages/index.wd": "---\ntitle: X\n---\n"}`.
+ * @param {string} entry Which file to compile, in the same key form.
+ * @returns {{ok: boolean, text: string, data: object}}
+ */
+export function validate(files: Record<string, string>, entry: string): {
+    ok: boolean;
+    text: string;
+    data: object;
+};