@intentius/chant 0.124.13 → 0.124.14

package/dist/lifecycle/work-lease.js

@@ -0,0 +1,393 @@
+/**
+ * The work lease (#2732, ws-055 option a): who is working on which work item,
+ * as a lease beside the operator lease.
+ *
+ * A work item's lease is the operator lease (./lease.ts) under the key
+ * `work/<id>`, so its ref is `refs/chant/lease/work/<id>`, or
+ * `refs/chant/lease/_members/<member>/work/<id>` in a workspace member's
+ * ledger (#2524 D7). It keeps every property the operator lease has: a claim
+ * is one compare-and-set of that ref, the record carries a fencing token that
+ * changes only when the lease changes hands, it expires after its time to
+ * live, and it is pushed to and fetched from the project's remote. Unlike the
+ * operator's, a work lease counts only once the remote has taken it
+ * (`requirePush`), so two workers in separate clones cannot both hold one
+ * item.
+ *
+ * The ref holds only the live lease. Every claim, renew and release also
+ * appends a line to `_leases/<id>.jsonl` on `chant/lifecycle`, the same
+ * append-only shape as `_gates/<op>.jsonl` (./gate-ledger.ts), so the history
+ * of an item's leases is a ledger like the others.
+ *
+ * The lease is coordination, not a record of work: it never touches the
+ * working branch, so it stays out of a release's nothing-to-ship test and out
+ * of the write-scope checks (ws-055, and chud's own leases.mjs before it).
+ *
+ * Which ledger an item's lease lives in is decided by the caller through
+ * `cwd`: `chant workspace work` passes the directory of the work kind file,
+ * so the member owning the kind owns its items' leases wherever the command
+ * runs from.
+ */
+import { sortedJsonReplacer } from "../utils.js";
+import { getRuntime } from "../runtime-adapter.js";
+import { acquireLease, leaseRef, LEASE_REF_PREFIX, LEASE_REMOTE_TRACKING_PREFIX, readLease, releaseLease, } from "./lease.js";
+import { fetchLifecycleStatus, pushLifecycle, readBlobBySha, readBlobFromPath, readPathSha, RefCASConflictError, writeBlobToPath, } from "./git.js";
+import { dirname } from "node:path";
+import { resolveMemberLedger } from "./member-ledger.js";
+import { WORK_ITEM_ID_PATTERN, isWorkItemId, workItemIdProblem } from "./work-item-id.js";
+/** The key prefix of a work lease under the operator lease's ref namespace. */
+export const WORK_LEASE_KEY_PREFIX = "work/";
+/** The directory on `chant/lifecycle` that holds lease histories, under a member's prefix when it has one. */
+export const LEASES_DIR = "_leases";
+/** How long a claim lasts unless renewed: chud's default, which its dispatcher renews at a third of. */
+export const DEFAULT_WORK_LEASE_TTL_MS = 10 * 60000;
+export { WORK_ITEM_ID_PATTERN, isWorkItemId, workItemIdProblem };
+/** How long a claim waits out another process's lock on the ref before calling it stale. */
+const LOCK_WAIT_MS = 2000;
+const APPEND_RETRY_ATTEMPTS = 5;
+/** The lease key of work item `id`. */
+export function workLeaseKey(id) {
+    return `${WORK_LEASE_KEY_PREFIX}${id}`;
+}
+/** The lease ref of work item `id` in the ledger with `memberPrefix`. */
+export function workLeaseRef(id, memberPrefix = "") {
+    return leaseRef(workLeaseKey(id), memberPrefix);
+}
+/** The path of work item `id`'s lease history on `chant/lifecycle`. */
+export function leaseHistoryPath(id, memberPrefix = "") {
+    return `${memberPrefix}${LEASES_DIR}/${id}.jsonl`;
+}
+/**
+ * How a work lease can end (#3147): the closed list of outcomes a release
+ * records. A new outcome is a contract change. Readers of an older history
+ * may still find free text from before the list was closed, which counts as
+ * an attempt (see {@link outcomeCountsAsAttempt}).
+ */
+export const WORK_LEASE_OUTCOMES = [
+    /** The work was finished: built, checked and recorded. */
+    "done",
+    /** A build ran and did not finish, or the run failed. Counts as an attempt. */
+    "not_done",
+    /** An expired lease closed out by someone other than its holder: the worker went away. Counts as an attempt. */
+    "abandoned",
+    /** The run stopped at a gate, waiting for an approval. */
+    "gated",
+    /** The run stopped on a decision point's open question, waiting for a person. */
+    "waiting",
+    /** The item was dropped, such as by a refuse at the understand point. Nothing was built. */
+    "dropped",
+    /** The understand point answered redraft: the item goes back to its author. Nothing was built. */
+    "redraft",
+    /** The understand point answered ask: the item waits on a question to its author. Nothing was built. */
+    "ask",
+];
+/** The outcomes that count toward an item's attempt limit. */
+export const ATTEMPT_OUTCOMES = ["not_done", "abandoned"];
+/** Whether `value` is one of {@link WORK_LEASE_OUTCOMES}. */
+export function isWorkLeaseOutcome(value) {
+    return typeof value === "string" && WORK_LEASE_OUTCOMES.includes(value);
+}
+/**
+ * Whether a release with `outcome` counts toward the item's attempt limit:
+ * `not_done` and `abandoned` do, and so does a release that gave no outcome
+ * or one outside the closed list (free text written before #3147), since
+ * nothing says the work got anywhere.
+ */
+export function outcomeCountsAsAttempt(outcome) {
+    if (!isWorkLeaseOutcome(outcome))
+        return true;
+    return ATTEMPT_OUTCOMES.includes(outcome);
+}
+/** The ref prefix that keeps an unfinished attempt's work (#3147). */
+export const KEPT_REF_PREFIX = "refs/chant/kept/";
+/**
+ * Where the work of an attempt that ended `not_done` is kept: one ref per
+ * lease token, `refs/chant/kept/[<member>/...]<item>/<token>`, scoped by the
+ * members the way the work branch `chant/work/[<member>/]<item>` is.
+ */
+export function keptAttemptRef(id, token, members = []) {
+    return `${keptAttemptPrefix(id, members)}${token}`;
+}
+/** The prefix under which every kept attempt of item `id` sits. */
+export function keptAttemptPrefix(id, members = []) {
+    return `${KEPT_REF_PREFIX}${members.length ? `${members.join("/")}/` : ""}${id}/`;
+}
+/** Every kept attempt of item `id`, from the local refs, sorted by ref. Empty outside git. */
+export async function listKeptAttempts(id, opts) {
+    const prefix = keptAttemptPrefix(id, opts.members ?? []);
+    const out = await getRuntime().spawn(["git", "for-each-ref", "--format=%(refname) %(objectname)", prefix], { cwd: opts.cwd });
+    if (out.exitCode !== 0)
+        return [];
+    return out.stdout
+        .split("\n")
+        .filter(Boolean)
+        .map((line) => {
+        const [ref, commit] = line.split(" ");
+        return { token: ref.slice(prefix.length), ref, commit };
+    })
+        .filter((k) => k.token !== "" && !k.token.includes("/"))
+        .sort((a, b) => (a.ref < b.ref ? -1 : a.ref > b.ref ? 1 : 0));
+}
+/** Why a claim, renew or release was refused. Closed: a new code is a contract change. */
+export const WORK_LEASE_REFUSALS = [
+    /** Someone holds the lease live: another worker, or, for a claim, the same one. */
+    "lease-held",
+    /** Nobody holds it live: it expired, was released or was never claimed. */
+    "lease-not-held",
+    /** The live lease has another token than the one given. */
+    "lease-token-mismatch",
+    /** Another writer changed the lease between the read and the write. */
+    "lease-race",
+    /** The remote refused the push: another clone got there first, or it could not be reached. */
+    "lease-push-rejected",
+];
+function toWorkLease(item, r) {
+    return { item, holder: r.holder, token: r.token, acquiredAt: r.acquiredAt, expiresAt: r.expiresAt };
+}
+function checkId(id) {
+    const problem = workItemIdProblem(id);
+    if (problem)
+        throw new Error(problem);
+}
+const REASONS = {
+    held: "lease-held",
+    "not-held": "lease-not-held",
+    "token-mismatch": "lease-token-mismatch",
+    race: "lease-race",
+    "push-rejected": "lease-push-rejected",
+};
+function refusalMessage(id, reason, heldBy) {
+    const by = heldBy ? `${heldBy.holder} until ${heldBy.expiresAt}` : undefined;
+    switch (reason) {
+        case "lease-held":
+            return `${id} is held by ${by}`;
+        case "lease-not-held":
+            return `${id} is not held${heldBy ? ` by the caller: ${by}` : ""}; claim it again`;
+        case "lease-token-mismatch":
+            return `${id} is held with another token (${heldBy?.token}) by ${by}`;
+        case "lease-race":
+            return `${id} changed while it was being written${by ? `: it is held by ${by}` : ""}`;
+        case "lease-push-rejected":
+            return `the remote refused the lease on ${id}${by ? `: it is held there by ${by}` : ", or could not be reached"}`;
+    }
+}
+/**
+ * Claim work item `id` for `holder` for `ttlMs`. Refused with `lease-held`,
+ * naming the holder, when anyone holds it live, `holder` included; an expired
+ * lease does not refuse a claim, and the new claim gets a new token.
+ */
+export async function claimWorkLease(id, holder, opts) {
+    checkId(id);
+    const result = await acquireLease(workLeaseKey(id), holder, {
+        cwd: opts.cwd,
+        ttlMs: opts.ttlMs ?? DEFAULT_WORK_LEASE_TTL_MS,
+        now: opts.now,
+        mode: "claim",
+        requirePush: true,
+        lockWaitMs: LOCK_WAIT_MS,
+    });
+    return finish(id, "claim", holder, result, opts);
+}
+/**
+ * Move the expiry of `holder`'s live lease on `id` to `ttlMs` from now,
+ * keeping its token. With `token`, the live lease must carry it. Refused with
+ * `lease-not-held` once the lease has expired or was released: the holder
+ * claims it again, and gets a new token.
+ */
+export async function renewWorkLease(id, holder, opts) {
+    checkId(id);
+    const result = await acquireLease(workLeaseKey(id), holder, {
+        cwd: opts.cwd,
+        ttlMs: opts.ttlMs ?? DEFAULT_WORK_LEASE_TTL_MS,
+        now: opts.now,
+        mode: "renew",
+        token: opts.token,
+        requirePush: true,
+        lockWaitMs: LOCK_WAIT_MS,
+    });
+    return finish(id, "renew", holder, result, opts);
+}
+async function finish(id, event, holder, result, opts) {
+    if (!result.acquired || !result.lease) {
+        const reason = REASONS[result.reason ?? "race"];
+        const heldBy = result.heldBy ? toWorkLease(id, result.heldBy) : undefined;
+        return { ok: false, reason, message: refusalMessage(id, reason, heldBy), ...(heldBy ? { heldBy } : {}) };
+    }
+    const lease = toWorkLease(id, result.lease);
+    const now = opts.now?.() ?? new Date();
+    const history = await appendLeaseHistory({ version: 1, event, item: id, holder, by: holder, token: lease.token, acquiredAt: lease.acquiredAt, expiresAt: lease.expiresAt, timestamp: now.toISOString(), ...(opts.note ? { note: opts.note } : {}) }, opts);
+    return { ok: true, lease, history };
+}
+/**
+ * Give the lease on `id` back. The holder releases a live lease (with
+ * `token`, only that one); anyone may release an expired one, which is how an
+ * abandoned claim is closed out. `outcome` says how the work ended, from the
+ * closed list {@link WORK_LEASE_OUTCOMES}; any other value throws. Refused
+ * with `lease-not-held` when there is no lease, and `lease-held` when someone
+ * else holds it live.
+ */
+export async function releaseWorkLease(id, by, opts) {
+    checkId(id);
+    if (opts.outcome !== undefined && !isWorkLeaseOutcome(opts.outcome)) {
+        throw new Error(`${JSON.stringify(opts.outcome)} is not a work lease outcome: use one of ${WORK_LEASE_OUTCOMES.join(", ")}`);
+    }
+    const key = workLeaseKey(id);
+    const now = opts.now?.() ?? new Date();
+    const { record } = await readLease(key, { cwd: opts.cwd });
+    if (!record)
+        return { ok: false, reason: "lease-not-held", message: refusalMessage(id, "lease-not-held", undefined) };
+    const current = toWorkLease(id, record);
+    const live = new Date(record.expiresAt).getTime() > now.getTime();
+    if (live && record.holder !== by)
+        return { ok: false, reason: "lease-held", message: refusalMessage(id, "lease-held", current), heldBy: current };
+    if (opts.token !== undefined && record.token !== opts.token) {
+        return { ok: false, reason: "lease-token-mismatch", message: refusalMessage(id, "lease-token-mismatch", current), heldBy: current };
+    }
+    if (!(await releaseLease(key, record.holder, record.token, { cwd: opts.cwd }))) {
+        const after = (await readLease(key, { cwd: opts.cwd })).record;
+        const heldBy = after ? toWorkLease(id, after) : undefined;
+        return { ok: false, reason: "lease-race", message: refusalMessage(id, "lease-race", heldBy), ...(heldBy ? { heldBy } : {}) };
+    }
+    const history = await appendLeaseHistory({
+        version: 1,
+        event: "release",
+        item: id,
+        holder: record.holder,
+        by,
+        token: record.token,
+        acquiredAt: record.acquiredAt,
+        expiresAt: record.expiresAt,
+        timestamp: now.toISOString(),
+        ...(opts.outcome ? { outcome: opts.outcome } : {}),
+        ...(opts.note ? { note: opts.note } : {}),
+    }, opts);
+    return { ok: true, lease: current, history };
+}
+/**
+ * Append one line to `_leases/<id>.jsonl`, with the same read-then-CAS retry
+ * the gate ledger's appends use, then push `chant/lifecycle`. The branch is
+ * fetched first when it fast-forwards, and the push is best-effort: the lease
+ * ref is what coordinates, and a history that did not reach the remote is
+ * reported as `pushed: false` rather than failing a lease that was taken.
+ */
+async function appendLeaseHistory(record, opts) {
+    await fetchLifecycleStatus(opts).catch(() => undefined);
+    const file = `${record.item}.jsonl`;
+    const json = JSON.stringify(record, sortedJsonReplacer);
+    let commit;
+    let lastErr;
+    for (let attempt = 1; attempt <= APPEND_RETRY_ATTEMPTS && commit === undefined; attempt++) {
+        try {
+            const priorSha = await readPathSha(LEASES_DIR, file, opts);
+            const existing = priorSha ? await readBlobBySha(priorSha, opts) : null;
+            const content = `${existing ? `${existing.replace(/\n$/, "")}\n` : ""}${json}\n`;
+            commit = await writeBlobToPath(LEASES_DIR, file, content, `Work lease ${record.event}: ${record.item} (${record.holder})`, {
+                ...opts,
+                expectPriorPathSha: priorSha,
+            });
+        }
+        catch (err) {
+            if (!(err instanceof RefCASConflictError))
+                throw err;
+            lastErr = err;
+        }
+    }
+    if (commit === undefined)
+        throw lastErr;
+    const pushed = await pushLifecycle(opts).catch(() => false);
+    const { prefix } = await resolveMemberLedger(opts.cwd);
+    return { path: leaseHistoryPath(record.item, prefix), commit, pushed };
+}
+/** Parse the text of a lease history file, oldest first. Malformed lines are counted and skipped. */
+export function parseLeaseHistory(content) {
+    const records = [];
+    let malformed = 0;
+    for (const line of content.split("\n").map((l) => l.trim()).filter(Boolean)) {
+        try {
+            const r = JSON.parse(line);
+            const ok = r.version === 1 &&
+                (r.event === "claim" || r.event === "renew" || r.event === "release") &&
+                [r.item, r.holder, r.by, r.token, r.acquiredAt, r.expiresAt, r.timestamp].every((v) => typeof v === "string");
+            if (ok)
+                records.push(r);
+            else
+                malformed++;
+        }
+        catch {
+            malformed++;
+        }
+    }
+    return { records, malformed };
+}
+/** Read work item `id`'s lease history in the ledger of the project at `opts.cwd`. Empty when it has none. */
+export async function readLeaseHistory(id, opts) {
+    checkId(id);
+    const content = await readBlobFromPath(LEASES_DIR, `${id}.jsonl`, opts);
+    return content ? parseLeaseHistory(content) : { records: [], malformed: 0 };
+}
+function parseRecord(raw) {
+    try {
+        const v = JSON.parse(raw);
+        return typeof v.holder === "string" && typeof v.token === "string" && typeof v.acquiredAt === "string" && typeof v.expiresAt === "string"
+            ? v
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Every work lease in the ledger with `memberPrefix`, read from the local
+ * refs only: the lease refs this clone wrote, and the remote's as last
+ * fetched (`refs/chant/lease-remote/`), the fresher of the two per item, as
+ * `readLease` picks. It never fetches, so a read-only report stays off the
+ * network; a claim or renew fetches before it decides. Released leases have
+ * no ref and are not listed; expired ones are, with `state: "expired"`.
+ * Sorted by item.
+ */
+export async function listWorkLeases(opts) {
+    const rt = getRuntime();
+    const now = (opts.now ?? new Date()).getTime();
+    const local = `${LEASE_REF_PREFIX}${opts.memberPrefix}${WORK_LEASE_KEY_PREFIX}`;
+    const remote = `${LEASE_REMOTE_TRACKING_PREFIX}${opts.memberPrefix}${WORK_LEASE_KEY_PREFIX}`;
+    const out = await rt.spawn(["git", "for-each-ref", "--format=%(refname) %(objectname)", local, remote], { cwd: opts.cwd });
+    if (out.exitCode !== 0)
+        return [];
+    const best = new Map();
+    for (const line of out.stdout.split("\n").filter(Boolean)) {
+        const [ref, sha] = line.split(" ");
+        const id = ref.startsWith(local) ? ref.slice(local.length) : ref.slice(remote.length);
+        if (!WORK_ITEM_ID_PATTERN.test(id))
+            continue;
+        const record = parseRecord((await readBlobBySha(sha, opts)) ?? "");
+        if (!record)
+            continue;
+        const prior = best.get(id);
+        const key = (r) => `${r.acquiredAt} ${r.expiresAt}`;
+        if (!prior || key(record) > key(prior) || (key(record) === key(prior) && ref.startsWith(local)))
+            best.set(id, record);
+    }
+    return [...best.entries()]
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+        .map(([id, r]) => ({
+        ...toWorkLease(id, r),
+        state: new Date(r.expiresAt).getTime() > now ? "active" : "expired",
+        ref: workLeaseRef(id, opts.memberPrefix),
+    }));
+}
+/**
+ * The active lease of each work item of the kind at `kindFile`, by item id,
+ * for `chant workspace records --json`. Read from the local refs of the
+ * ledger owning the kind file's directory, without fetching. Empty when
+ * nothing can be read.
+ */
+export async function activeWorkLeases(kindFile, now = new Date()) {
+    const cwd = dirname(kindFile);
+    try {
+        const { prefix } = await resolveMemberLedger(cwd);
+        const leases = await listWorkLeases({ cwd, memberPrefix: prefix, now });
+        return new Map(leases.filter((l) => l.state === "active").map((l) => [l.item, { holder: l.holder, token: l.token, acquiredAt: l.acquiredAt, expiresAt: l.expiresAt }]));
+    }
+    catch {
+        return new Map();
+    }
+}

package/dist/lint/component-checks.js

@@ -0,0 +1,87 @@
+/**
+ * Component composition checks — the COMP* rule family (#562, epic #551).
+ *
+ * COR/EVL rules (./rule.ts, ./engine.ts) check one `ts.SourceFile`'s AST in
+ * isolation, synchronously — no execution, no cross-file knowledge. A COMP*
+ * rule cannot work that way: "publishes but never applies", "`imageRef`
+ * points at a nonexistent phase", and "identical composition repeated across
+ * components" are all properties of the *discovered component graph*, which
+ * only exists after `*.component.ts` files are actually imported (mirroring
+ * `../components/discover.ts`'s `discoverComponents`, itself async for the
+ * same reason `../discovery/index.ts`'s `discover()` is).
+ *
+ * Rather than stretch `LintRule.check(context)` (sync, single-file, AST-only)
+ * to cover this, COMP* rules follow the precedent chant already has for
+ * "check something that needs real, resolved, whole-project data":
+ * `./post-synth.ts`'s `PostSynthCheck`/`PostSynthContext`/`runPostSynthChecks`,
+ * which wraps a real (async) build result for a sync `check(ctx)` call. This
+ * module is that same shape, one layer earlier in the pipeline — over the
+ * discovered `Component` graph instead of serialized resource output — so
+ * `chant lint` (not just `chant build`) can run it. See
+ * ../components/discover.ts's own docstring for why `Component` gets a
+ * parallel, purpose-built convention rather than reusing `Declarable`'s.
+ */
+import { discoverComponents } from "../components/discover.js";
+/**
+ * Discover every component under `path` and run every `ComponentCheck`
+ * against the resulting graph. Mirrors `runPostSynthChecks`'s shape
+ * (async discovery/build once, then every check runs sync over the result),
+ * except the input is `discoverComponents`'s result rather than a build's
+ * serialized output.
+ *
+ * Discovery errors (e.g. a duplicate component name, a `*.component.ts` file
+ * that throws on import) are surfaced as a single synthetic diagnostic per
+ * error under the pseudo-check id "COMP000" rather than silently dropped —
+ * matching how `discoverComponents`'s caller (`../components/cli-support.ts`)
+ * always surfaces `result.errors` rather than ignoring them.
+ *
+ * `sandbox` (chant #1051, `chant lint --sandbox`) is threaded straight
+ * through to `discoverComponents` — `chant lint`'s own AST-only rule engine
+ * never executes project source (see this module's own doc comment), but
+ * COMP* checks exist precisely because they need the discovered `Component`
+ * graph, which does mean importing `*.component.ts` files.
+ */
+export async function runComponentChecks(path, checks, registryContext, sandbox, buildParams) {
+    if (checks.length === 0)
+        return [];
+    // #1490 — this import runs BEFORE the caller's own component discovery, and
+    // an ES module is evaluated once per path. Whatever parameters are in effect
+    // here are the ones every later reader sees, however carefully that reader
+    // resolves its own. Passing them at the second call and not this one left
+    // the graph on defaults while the CLI reported the values it had resolved.
+    const result = await discoverComponents(path, { sandbox, buildParams });
+    const diagnostics = [];
+    for (const err of result.errors) {
+        diagnostics.push({
+            checkId: "COMP000",
+            severity: "error",
+            message: `Component discovery error: ${err.message}`,
+            file: err.file,
+            component: "(unknown)",
+        });
+    }
+    const components = new Map();
+    for (const [name, discovered] of result.components) {
+        components.set(name, { component: discovered.component, filePath: discovered.filePath });
+    }
+    const ctx = {
+        components,
+        knownKinds: registryContext?.knownKinds,
+        rollbackPolicies: registryContext?.rollbackPolicies,
+    };
+    for (const check of checks) {
+        diagnostics.push(...check.check(ctx));
+    }
+    return diagnostics;
+}
+/** Structural type guard, mirroring `isPostSynthCheck` — used by rule discovery/registry code. */
+export function isComponentCheck(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const v = value;
+    return (typeof v.id === "string" &&
+        typeof v.description === "string" &&
+        typeof v.severity === "string" &&
+        typeof v.category === "string" &&
+        typeof v.check === "function");
+}