@astrosheep/keiyaku 4.0.1 → 4.0.2

package/build/src/task/query.js

@@ -0,0 +1,279 @@
+import { formatTaskId, parseTaskId, sameNamespace } from "./identity.js";
+import { taskDisposition } from "./board.js";
+export const DEFAULT_TASK_LIMIT = 100;
+export const MAX_TASK_LIMIT = 1_000;
+const states = ["open", "in_progress", "on_hold", "done", "drop"];
+const comparisons = ["=", "!=", "<", "<=", ">", ">=", "~"];
+function fail(message) { throw new TypeError(message); }
+function object(value, label) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        fail(`${label} must be an object`);
+    return value;
+}
+function closed(value, fields, label) {
+    for (const key of Object.keys(value))
+        if (!fields.includes(key))
+            fail(`${label} has unknown field: ${key}`);
+}
+function taskId(value, label) {
+    if (typeof value !== "string")
+        fail(`${label} must be a TaskId`);
+    try {
+        const coordinate = parseTaskId(value);
+        if (formatTaskId(coordinate) !== value)
+            fail(`${label} must be a canonical TaskId`);
+    }
+    catch {
+        fail(`${label} must be a canonical TaskId`);
+    }
+    return value;
+}
+function comparison(value) {
+    if (typeof value !== "string" || !comparisons.includes(value))
+        fail("query operator is invalid");
+    return value;
+}
+function timestamp(value, field) {
+    if (typeof value !== "string" || !Number.isFinite(Date.parse(value)) || new Date(Date.parse(value)).toISOString() !== value) {
+        fail(`${field} must be a canonical UTC ISO timestamp`);
+    }
+    return value;
+}
+function equalityOperator(operator, field) {
+    if (operator !== "=" && operator !== "!=")
+        fail(`${field} supports only = and !=`);
+    return operator;
+}
+function orderedOperator(operator, field) {
+    if (operator === "~")
+        fail(`${field} does not support ~`);
+    return operator;
+}
+function normalizeStatePredicate(input, operator) {
+    if (typeof input.value !== "string" || !states.includes(input.value))
+        fail("state value is invalid");
+    return { field: "state", operator: equalityOperator(operator, "state"), value: input.value };
+}
+function normalizePriorityPredicate(input, operator) {
+    if (typeof input.value !== "number" || !Number.isInteger(input.value) || input.value < 0 || input.value > 3) {
+        fail("priority value must be 0..3");
+    }
+    return { field: "priority", operator: orderedOperator(operator, "priority"), value: input.value };
+}
+function normalizeTextPredicate(input, field, operator) {
+    if (typeof input.value !== "string" || input.value.length === 0)
+        fail(`${field} value must be nonblank`);
+    if (operator !== "=" && operator !== "!=" && operator !== "~")
+        fail(`${field} supports only =, !=, and ~`);
+    if (field === "id" && operator !== "~")
+        taskId(input.value, "id value");
+    return { field, operator, value: input.value };
+}
+function normalizeParentPredicate(input, operator) {
+    const value = input.value === null ? null : taskId(input.value, "parent value");
+    return { field: "parent", operator: equalityOperator(operator, "parent"), value };
+}
+function normalizeRelationPredicate(input, field, operator) {
+    return { field, operator: equalityOperator(operator, field), value: taskId(input.value, `${field} value`) };
+}
+function normalizeBooleanPredicate(input, field, operator) {
+    if (typeof input.value !== "boolean")
+        fail(`${field} value must be boolean`);
+    return { field, operator: equalityOperator(operator, field), value: input.value };
+}
+function normalizeTimestampPredicate(input, field, operator) {
+    return { field, operator: orderedOperator(operator, field), value: timestamp(input.value, `${field} value`) };
+}
+function predicate(value) {
+    const input = object(value, "query predicate");
+    closed(input, ["field", "operator", "value"], "query predicate");
+    const field = input.field;
+    if (typeof field !== "string")
+        fail("query predicate field is required");
+    const operator = comparison(input.operator);
+    switch (field) {
+        case "state": return normalizeStatePredicate(input, operator);
+        case "priority": return normalizePriorityPredicate(input, operator);
+        case "title": return normalizeTextPredicate(input, "title", operator);
+        case "id": return normalizeTextPredicate(input, "id", operator);
+        case "parent": return normalizeParentPredicate(input, operator);
+        case "under": return normalizeRelationPredicate(input, "under", operator);
+        case "needs": return normalizeRelationPredicate(input, "needs", operator);
+        case "blocks": return normalizeRelationPredicate(input, "blocks", operator);
+        case "ready": return normalizeBooleanPredicate(input, "ready", operator);
+        case "blocked": return normalizeBooleanPredicate(input, "blocked", operator);
+        case "created": return normalizeTimestampPredicate(input, "created", operator);
+        case "updated": return normalizeTimestampPredicate(input, "updated", operator);
+        default: return fail(`unknown query field: ${field}`);
+    }
+}
+export function normalizeTaskQuery(value) {
+    const input = object(value, "query expression");
+    if (input.kind === "predicate") {
+        closed(input, ["kind", "predicate"], "query expression");
+        return { kind: "predicate", predicate: predicate(input.predicate) };
+    }
+    if (input.kind === "not") {
+        closed(input, ["kind", "term"], "query expression");
+        return { kind: "not", term: normalizeTaskQuery(input.term) };
+    }
+    if (input.kind === "and" || input.kind === "or") {
+        closed(input, ["kind", "terms"], "query expression");
+        if (!Array.isArray(input.terms) || input.terms.length === 0)
+            fail(`${input.kind} query requires terms`);
+        return { kind: input.kind, terms: input.terms.map((term) => normalizeTaskQuery(term)) };
+    }
+    fail("query expression kind is invalid");
+}
+function compare(left, operator, right) {
+    if (operator === "=")
+        return left === right;
+    if (operator === "!=")
+        return left !== right;
+    if (operator === "<")
+        return left < right;
+    if (operator === "<=")
+        return left <= right;
+    if (operator === ">")
+        return left > right;
+    return left >= right;
+}
+function membership(left, operator, right) { return operator === "=" ? left === right : left !== right; }
+function indexChildren(board) {
+    const children = new Map();
+    for (const task of board.tasks.values()) {
+        if (task.parent === null)
+            continue;
+        const siblings = children.get(task.parent) ?? [];
+        siblings.push(task.id);
+        children.set(task.parent, siblings);
+    }
+    return children;
+}
+function indexReverseNeeds(board) {
+    const reverse = new Map();
+    for (const task of board.tasks.values()) {
+        for (const need of task.needs) {
+            const blockers = reverse.get(need) ?? new Set();
+            blockers.add(task.id);
+            reverse.set(need, blockers);
+        }
+    }
+    return reverse;
+}
+function descendants(children, parent) {
+    const result = new Set(), pending = [parent];
+    while (pending.length > 0) {
+        const current = pending.shift();
+        for (const child of children.get(current) ?? []) {
+            if (result.has(child))
+                continue;
+            result.add(child);
+            pending.push(child);
+        }
+    }
+    return result;
+}
+function relation(board, reverseNeeds, id, field, target) {
+    const task = board.tasks.get(id);
+    if (task === undefined)
+        return false;
+    return field === "needs" ? task.needs.includes(target) : reverseNeeds.get(target)?.has(id) === true;
+}
+function matchText(left, operator, right) {
+    return operator === "~" ? left.includes(right) : compare(left, operator, right);
+}
+function matchRelation(selected, operator) {
+    return operator === "=" ? selected : !selected;
+}
+function isBlocked(board, task) {
+    const active = task.state === "open" || task.state === "in_progress";
+    return active && task.needs.some((need) => {
+        const target = board.tasks.get(need);
+        return target === undefined || (target.state !== "done" && target.state !== "drop");
+    });
+}
+function taskRef(board, id) {
+    const task = board.tasks.get(id);
+    return task === undefined ? { id, title: null, state: "missing" } : { id, title: task.title, state: task.state };
+}
+function matchesPredicate(board, reverseNeeds, task, value, under) {
+    switch (value.field) {
+        case "state": return compare(task.state, value.operator, value.value);
+        case "priority": return compare(task.priority, value.operator, value.value);
+        case "title": return matchText(task.title, value.operator, value.value);
+        case "id": return matchText(task.id, value.operator, value.value);
+        case "parent": return compare(task.parent ?? "", value.operator, value.value ?? "");
+        case "under": return matchRelation(under.get(value.value)?.has(task.id) === true, value.operator);
+        case "needs": return matchRelation(relation(board, reverseNeeds, task.id, "needs", value.value), value.operator);
+        case "blocks": return matchRelation(relation(board, reverseNeeds, task.id, "blocks", value.value), value.operator);
+        case "ready": return membership(taskDisposition(board, task) === "ready", value.operator, value.value);
+        case "blocked": return membership(isBlocked(board, task), value.operator, value.value);
+        case "created": return compare(task.createdAt, value.operator, value.value);
+        case "updated": return compare(task.updatedAt, value.operator, value.value);
+    }
+}
+function matches(board, reverseNeeds, task, expression, under) {
+    if (expression.kind === "not")
+        return !matches(board, reverseNeeds, task, expression.term, under);
+    if (expression.kind !== "predicate") {
+        return expression.kind === "and"
+            ? expression.terms.every((term) => matches(board, reverseNeeds, task, term, under))
+            : expression.terms.some((term) => matches(board, reverseNeeds, task, term, under));
+    }
+    return matchesPredicate(board, reverseNeeds, task, expression.predicate, under);
+}
+function row(board, reverseNeeds, task) {
+    return {
+        id: task.id, title: task.title, state: task.state, priority: task.priority, disposition: taskDisposition(board, task),
+        parent: task.parent,
+        needs: task.needs.map((need) => taskRef(board, need)),
+        blocks: [...(reverseNeeds.get(task.id) ?? [])]
+            .sort((left, right) => Buffer.compare(Buffer.from(left), Buffer.from(right)))
+            .map((id) => taskRef(board, id)),
+        createdAt: task.createdAt, updatedAt: task.updatedAt,
+    };
+}
+function sortTasks(tasks, sort) {
+    return [...tasks].sort((left, right) => {
+        const tie = Buffer.compare(Buffer.from(left.id), Buffer.from(right.id));
+        if (sort === "id")
+            return tie;
+        if (sort === "priority")
+            return left.priority - right.priority || tie;
+        const compared = left[sort === "created" ? "createdAt" : "updatedAt"].localeCompare(right[sort === "created" ? "createdAt" : "updatedAt"]);
+        return (sort === "updated" ? -compared : compared) || tie;
+    });
+}
+export function projectQuery(board, scope, expression, sort = "priority", limit = DEFAULT_TASK_LIMIT) {
+    const children = indexChildren(board);
+    const reverseNeeds = indexReverseNeeds(board);
+    const under = new Map(queryUnderTargets(expression).map((target) => [target, descendants(children, target)]));
+    const selected = sortTasks([...board.tasks.values()].filter((task) => scope === null || sameNamespace(parseTaskId(task.id).namespace, scope))
+        .filter((task) => matches(board, reverseNeeds, task, expression, under)), sort);
+    const rows = selected.slice(0, limit).map((task) => row(board, reverseNeeds, task));
+    return { rows, total: selected.length, returned: rows.length, truncated: rows.length < selected.length };
+}
+export function projectPage(rows, limit = DEFAULT_TASK_LIMIT) {
+    const visible = rows.slice(0, limit);
+    return { rows: visible, total: rows.length, returned: visible.length, truncated: visible.length < rows.length };
+}
+export function underExpression(parent) {
+    return { kind: "predicate", predicate: { field: "under", operator: "=", value: parent } };
+}
+export function queryUnderTargets(expression) {
+    const targets = new Set();
+    function collect(value) {
+        if (value.kind === "predicate" && value.predicate.field === "under")
+            targets.add(value.predicate.value);
+        else if (value.kind === "not")
+            collect(value.term);
+        else if (value.kind !== "predicate")
+            value.terms.forEach(collect);
+    }
+    collect(expression);
+    return [...targets];
+}
+export function isValidTaskLimit(value) {
+    return Number.isInteger(value) && value > 0 && value <= MAX_TASK_LIMIT;
+}

package/build/src/task/store.d.ts

@@ -5,12 +5,12 @@ export type BoardSnapshot = Readonly<{
     board: TaskBoard;
     bytes: ReadonlyMap<TaskId, Uint8Array>;
 }>;
-export declare function readBoard(world: WorldRoot): BoardSnapshot;
+export declare function readBoard(world: WorldRoot): Promise<BoardSnapshot>;
 export declare function replaceAuthority(input: Readonly<{
     path: string;
     expected: Uint8Array | null;
     next: Uint8Array;
-}>): "replaced" | "concurrent-modification";
+}>): Promise<"replaced" | "concurrent-modification">;
 export declare function withTaskLocks<T>(input: Readonly<{
     world: WorldRoot;
     allocation: boolean;

package/build/src/task/store.js

@@ -1,18 +1,37 @@
 import { randomBytes } from "node:crypto";
-import { closeSync, existsSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, readdirSync, renameSync, unlinkSync, writeFileSync, } from "node:fs";
+import { closeSync, fsyncSync, openSync, renameSync, writeFileSync, } from "node:fs";
+import { lstat, mkdir, readFile, readdir, unlink } from "node:fs/promises";
 import { dirname, relative, resolve, sep } from "node:path";
 import { acquireSqliteTransactionLock, SqliteTransactionLockError } from "../coordination/sqlite-transaction-lock.js";
 import { parseTaskDocument } from "./document.js";
 import { formatTaskId, parseTaskId, taskAuthorityPath } from "./identity.js";
+function syncTaskDirectory(path) {
+    if (process.platform === "win32")
+        return;
+    const directory = openSync(path, "r");
+    try {
+        fsyncSync(directory);
+    }
+    finally {
+        closeSync(directory);
+    }
+}
 function tasksDirectory(world) { return resolve(world, ".keiyaku", "tasks"); }
-function authorityFiles(directory) {
-    if (!existsSync(directory))
-        return [];
+async function authorityFiles(directory) {
     const files = [];
-    for (const entry of readdirSync(directory, { withFileTypes: true })) {
+    let entries;
+    try {
+        entries = await readdir(directory, { withFileTypes: true });
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return [];
+        throw error;
+    }
+    for (const entry of entries) {
         const path = resolve(directory, entry.name);
         if (entry.isDirectory())
-            files.push(...authorityFiles(path));
+            files.push(...await authorityFiles(path));
         else if (entry.isFile() && entry.name.endsWith(".md"))
             files.push(path);
         else
@@ -26,16 +45,18 @@ function coordinateFromPath(tasksDirectory, path) {
         throw new Error(`invalid Task authority path: ${path}`);
     return parseTaskId(`task/${local.slice(0, -3).split(sep).join("/")}`);
 }
-export function readBoard(world) {
+export async function readBoard(world) {
     const directory = tasksDirectory(world);
-    const tasks = new Map(), bytes = new Map();
-    for (const path of authorityFiles(directory)) {
-        const stat = lstatSync(path);
-        if (!stat.isFile() || stat.isSymbolicLink())
+    const tasks = new Map();
+    const bytes = new Map();
+    for (const path of await authorityFiles(directory)) {
+        const stat = await lstat(path);
+        if (!stat.isFile() || stat.isSymbolicLink()) {
             throw new Error(`Task authority is not a regular file: ${path}`);
+        }
         const coordinate = coordinateFromPath(directory, path);
         const id = formatTaskId(coordinate);
-        const source = readFileSync(path);
+        const source = await readFile(path);
         tasks.set(id, parseTaskDocument(source, coordinate));
         bytes.set(id, source);
     }
@@ -44,9 +65,9 @@ export function readBoard(world) {
 function equal(left, right) {
     return left === null || right === null ? left === right : Buffer.from(left).equals(Buffer.from(right));
 }
-function currentBytes(path) {
+async function currentBytes(path) {
     try {
-        return readFileSync(path);
+        return await readFile(path);
     }
     catch (error) {
         if (error.code === "ENOENT")
@@ -54,9 +75,9 @@ function currentBytes(path) {
         throw error;
     }
 }
-export function replaceAuthority(input) {
+export async function replaceAuthority(input) {
     const parent = dirname(input.path);
-    mkdirSync(parent, { recursive: true });
+    await mkdir(parent, { recursive: true });
     const temporary = resolve(parent, `.tmp-${randomBytes(8).toString("hex")}`);
     let descriptor;
     try {
@@ -65,23 +86,17 @@ export function replaceAuthority(input) {
         fsyncSync(descriptor);
         closeSync(descriptor);
         descriptor = undefined;
-        if (!equal(currentBytes(input.path), input.expected))
+        if (!equal(await currentBytes(input.path), input.expected))
             return "concurrent-modification";
         renameSync(temporary, input.path);
-        const directoryDescriptor = openSync(parent, "r");
-        try {
-            fsyncSync(directoryDescriptor);
-        }
-        finally {
-            closeSync(directoryDescriptor);
-        }
+        syncTaskDirectory(parent);
         return "replaced";
     }
     finally {
         if (descriptor !== undefined)
             closeSync(descriptor);
         try {
-            unlinkSync(temporary);
+            await unlink(temporary);
         }
         catch { /* renamed or best effort */ }
     }

package/build/src/verification/execution.d.ts

@@ -8,6 +8,8 @@ type VerificationVerdict = "satisfied" | "unsatisfied";
 export type VerificationTerminalOutcome = Readonly<{
     kind: "terminal";
     verdict: VerificationVerdict;
+    passed: number;
+    total: number;
     summary?: string;
 }>;
 export type VerificationNonterminalOutcome = Readonly<{
@@ -40,8 +42,8 @@ export type ExecuteVerificationInput = Readonly<{
     candidate: SnapshotId;
     declarations: readonly VerificationDeclaration[];
     environment: NodeJS.ProcessEnv;
-    materializeScratchCandidate: (repository: GitRepository, candidate: SnapshotId) => MaterializedScratchCandidate;
-    projectSettings: (root: string) => Settings;
+    materializeScratchCandidate: (repository: GitRepository, candidate: SnapshotId) => Promise<MaterializedScratchCandidate>;
+    projectSettings: (root: string) => Promise<Settings>;
     signal?: AbortSignal;
 }>;
 /** Execute one disposable Verification attempt over the exact integration snapshot. */

package/build/src/verification/execution.js

@@ -29,6 +29,8 @@ function appendSummary(current, diagnostic) {
 }
 async function executeDeclarations(input) {
     let verdict = "satisfied";
+    let passed = 0;
+    const total = input.declarations.length;
     let summary;
     for (const [index, declaration] of input.declarations.entries()) {
         const outcome = await runProcess({
@@ -45,17 +47,19 @@ async function executeDeclarations(input) {
         }
         if (outcome.kind === "spawn-error" || outcome.kind === "unknown-exit" || outcome.kind === "cancelled")
             return outcome;
-        if (outcome.code !== 0)
+        if (outcome.code === 0)
+            passed += 1;
+        else
             verdict = "unsatisfied";
         summary = appendSummary(summary, processDiagnostic(declaration, index, outcome));
     }
-    return { kind: "terminal", verdict, ...(summary === undefined ? {} : { summary }) };
+    return { kind: "terminal", verdict, passed, total, ...(summary === undefined ? {} : { summary }) };
 }
 /** Execute one disposable Verification attempt over the exact integration snapshot. */
 export async function executeVerification(input) {
     let scratch;
     try {
-        scratch = input.materializeScratchCandidate(input.repository, input.candidate);
+        scratch = await input.materializeScratchCandidate(input.repository, input.candidate);
     }
     catch (error) {
         return { outcome: { kind: "candidate-unavailable", diagnostic: error instanceof Error ? error.message : String(error) } };
@@ -66,7 +70,7 @@ export async function executeVerification(input) {
     let destroy;
     try {
         try {
-            const hooks = worktreeHooksFrom({ settings: input.projectSettings(scratch.cwd) });
+            const hooks = worktreeHooksFrom({ settings: await input.projectSettings(scratch.cwd) });
             destroy = hooks.destroy;
             const readiness = await runHookCommands(scratch.cwd, hooks.create, input.signal);
             outcome = readiness.kind === "cancelled"
@@ -92,7 +96,7 @@ export async function executeVerification(input) {
             if (result.kind === "failed")
                 cleanup = { phase: "destroy", command: result.command, detail: result.failure };
         }
-        leak = scratch.dispose();
+        leak = await scratch.dispose();
     }
     if (outcome === undefined)
         throw new Error("Verification ended without an outcome");

package/build/src/workspace-place.d.ts

@@ -0,0 +1,41 @@
+import { type ContractId } from "./core/facts/types.js";
+import type { GitRepository } from "./git/repository.js";
+export declare const CONTRACT_PLACES: readonly string[];
+export type Place = string & {
+    readonly [placeBrand]: "Place";
+};
+declare const placeBrand: unique symbol;
+export type PlaceAppointment = Readonly<{
+    place: Place;
+    contract: ContractId;
+}>;
+export type PlaceRegister = Readonly<{
+    appointments: readonly PlaceAppointment[];
+    byPlace: ReadonlyMap<Place, PlaceAppointment>;
+    byContract: ReadonlyMap<ContractId, PlaceAppointment>;
+}>;
+export type ManagedWorktreeAppointment = Readonly<{
+    kind: "appointed";
+    place: Place;
+    path: string;
+}> | Readonly<{
+    kind: "unappointed";
+}> | Readonly<{
+    kind: "failed";
+    diagnostic: string;
+}>;
+export declare function placeRegisterPath(repository: GitRepository): string;
+export declare function place(value: string): Place;
+export declare function nextPlace(current?: Place): Place;
+export declare function firstFreePlace(register: PlaceRegister): Place;
+export declare function canonicalPlaceRegister(register: PlaceRegister): string;
+export declare function decodePlaceRegister(path: string, bytes: string): PlaceRegister;
+export declare function emptyPlaceRegister(): PlaceRegister;
+export declare function readPlaceRegister(repository: GitRepository): Promise<PlaceRegister>;
+export declare function appointmentFor(register: PlaceRegister, contract: ContractId): PlaceAppointment | undefined;
+export declare function appointManagedWorktrees(repository: GitRepository, contracts: readonly ContractId[]): Promise<PlaceRegister>;
+export declare function appointManagedWorktree(repository: GitRepository, contract: ContractId): Promise<PlaceAppointment>;
+export declare function releaseManagedWorktrees(repository: GitRepository, contracts: readonly ContractId[]): Promise<void>;
+export declare function releaseManagedWorktree(repository: GitRepository, contract: ContractId): Promise<void>;
+export declare function readManagedWorktreeAppointment(repository: GitRepository, contract: ContractId, register?: PlaceRegister): Promise<ManagedWorktreeAppointment>;
+export {};