clinkx 1.0.0 → 1.1.0

package/dist/context-builder/mutation-lock.js

@@ -0,0 +1,321 @@
+import { lstat as fsLstat, open as fsOpen, rm as fsRm, } from "node:fs/promises";
+import { hostname } from "node:os";
+import { isAbsolute, join, relative, resolve } from "node:path";
+import { ExecutionError } from "../errors.js";
+import { validateCallerRunId } from "./run-id.js";
+const CONTEXT_BUILDER_MUTATION_LOCK_SUFFIX = ".mutation.lock";
+const CONTEXT_BUILDER_MUTATION_LOCK_RECOVERY_SUFFIX = ".recovery";
+const CONTEXT_BUILDER_MUTATION_LOCK_ATTEMPTS = 1_000;
+const CONTEXT_BUILDER_MUTATION_LOCK_RETRY_MS = 10;
+const CONTEXT_BUILDER_STALE_MUTATION_LOCK_MS = 10 * 60 * 1_000;
+/**
+ * Serialize cooperative mutations of one context_builder run. The lock lives
+ * beside the run directory so it also survives removal of that directory.
+ */
+export async function withContextBuilderMutationLock(target, ops, callback, options = {}) {
+    const lockPath = mutationLockPathForTarget(target);
+    const acquired = await acquireContextBuilderMutationLock(lockPath, ops, options);
+    try {
+        return await callback();
+    }
+    finally {
+        await removeMutationLockIfCurrent(lockPath, acquired.fingerprint, ops);
+        await acquired.handle.close().catch(() => { });
+    }
+}
+async function acquireContextBuilderMutationLock(lockPath, ops, options) {
+    const open = ops.open ?? fsOpen;
+    const maxAttempts = resolveMutationLockAttempts(options.maxAttempts);
+    for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
+        try {
+            const handle = await open(lockPath, "wx", 0o600);
+            try {
+                await writeMutationLockMetadata(handle, options.ownerNonce);
+                return {
+                    handle,
+                    fingerprint: await fingerprintOpenHandle(handle),
+                };
+            }
+            catch (error) {
+                const fingerprint = await fingerprintOpenHandle(handle).catch(() => undefined);
+                if (fingerprint !== undefined) {
+                    await removeMutationLockIfCurrent(lockPath, fingerprint, ops);
+                }
+                await handle.close().catch(() => { });
+                throw error;
+            }
+        }
+        catch (error) {
+            if (isNodeError(error) && error.code === "EEXIST") {
+                await options.onContention?.();
+                if (options.canRecoverStale !== undefined
+                    && await breakStaleMutationLock(lockPath, ops, options.canRecoverStale, options.beforeStaleRemoval)) {
+                    continue;
+                }
+                await delay(CONTEXT_BUILDER_MUTATION_LOCK_RETRY_MS);
+                continue;
+            }
+            throw error;
+        }
+    }
+    throw new ExecutionError("context_builder timed out waiting for the run mutation lock");
+}
+function resolveMutationLockAttempts(value) {
+    if (value === undefined) {
+        return CONTEXT_BUILDER_MUTATION_LOCK_ATTEMPTS;
+    }
+    if (!Number.isSafeInteger(value) || value <= 0) {
+        throw new ExecutionError("context_builder mutation lock attempts must be a positive integer");
+    }
+    return value;
+}
+function mutationLockPathForTarget(target) {
+    validateCallerRunId(target.runId);
+    const resolvedRunsDir = resolve(target.runsDir);
+    const resolvedRunDir = resolve(target.runDir);
+    if (!isPathInsideDirectory(resolvedRunDir, resolvedRunsDir)) {
+        throw new ExecutionError("context_builder refused mutation lock outside runs directory");
+    }
+    return join(resolvedRunsDir, `.${target.runId}${CONTEXT_BUILDER_MUTATION_LOCK_SUFFIX}`);
+}
+async function writeMutationLockMetadata(handle, ownerNonce) {
+    const metadata = {
+        pid: process.pid,
+        hostname: hostname(),
+        created_at: new Date().toISOString(),
+        ...(ownerNonce == null ? {} : { owner_nonce: ownerNonce }),
+    };
+    await handle.writeFile(`${JSON.stringify(metadata)}\n`, { encoding: "utf8" });
+}
+async function breakStaleMutationLock(lockPath, ops, canRecoverStale, beforeStaleRemoval) {
+    const candidate = await observeMutationLock(lockPath, ops);
+    if (candidate === undefined) {
+        return false;
+    }
+    try {
+        if (!isRecoverableStaleMutationLock(candidate)) {
+            return false;
+        }
+    }
+    finally {
+        await candidate.handle.close().catch(() => { });
+    }
+    const recoveryGate = await tryAcquireMutationLockRecoveryGate(lockPath, ops);
+    if (recoveryGate === undefined) {
+        return false;
+    }
+    try {
+        const observed = await observeMutationLock(lockPath, ops);
+        if (observed === undefined) {
+            return false;
+        }
+        try {
+            if (!isRecoverableStaleMutationLock(observed)) {
+                return false;
+            }
+            await beforeStaleRemoval?.();
+            if (!await canRecoverStale()) {
+                return false;
+            }
+            return await removeMutationLockIfCurrent(lockPath, observed.fingerprint, ops);
+        }
+        finally {
+            await observed.handle.close().catch(() => { });
+        }
+    }
+    finally {
+        await removeMutationLockIfCurrent(`${lockPath}${CONTEXT_BUILDER_MUTATION_LOCK_RECOVERY_SUFFIX}`, recoveryGate.fingerprint, ops);
+        await recoveryGate.handle.close().catch(() => { });
+    }
+}
+async function tryAcquireMutationLockRecoveryGate(lockPath, ops) {
+    const gatePath = `${lockPath}${CONTEXT_BUILDER_MUTATION_LOCK_RECOVERY_SUFFIX}`;
+    const open = ops.open ?? fsOpen;
+    let handle;
+    try {
+        handle = await open(gatePath, "wx", 0o600);
+    }
+    catch (error) {
+        if (isNodeError(error) && error.code === "EEXIST") {
+            return undefined;
+        }
+        throw error;
+    }
+    try {
+        await writeMutationLockMetadata(handle, undefined);
+        return {
+            handle,
+            fingerprint: await fingerprintOpenHandle(handle),
+        };
+    }
+    catch (error) {
+        const fingerprint = await fingerprintOpenHandle(handle).catch(() => undefined);
+        if (fingerprint !== undefined) {
+            await removeMutationLockIfCurrent(gatePath, fingerprint, ops);
+        }
+        await handle.close().catch(() => { });
+        throw error;
+    }
+}
+async function observeMutationLock(lockPath, ops) {
+    const lstat = ops.lstat ?? fsLstat;
+    const open = ops.open ?? fsOpen;
+    let handle;
+    try {
+        const pathStats = await lstat(lockPath, { bigint: true });
+        if (!pathStats.isFile()) {
+            return undefined;
+        }
+        handle = await open(lockPath, "r");
+        const before = await handle.stat({ bigint: true });
+        if (!before.isFile()
+            || before.nlink === 0n
+            || !sameMutationLockIncarnation(fingerprintFromStats(pathStats), fingerprintFromStats(before))) {
+            return undefined;
+        }
+        const raw = await handle.readFile({ encoding: "utf8" });
+        const after = await handle.stat({ bigint: true });
+        const beforeFingerprint = fingerprintFromStats(before);
+        const afterFingerprint = fingerprintFromStats(after);
+        if (after.nlink === 0n
+            || !mutationLockFingerprintsEqual(beforeFingerprint, afterFingerprint)) {
+            return undefined;
+        }
+        const observed = {
+            handle,
+            fingerprint: afterFingerprint,
+            metadata: parseMutationLockMetadata(raw),
+        };
+        handle = undefined;
+        return observed;
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        await handle?.close().catch(() => { });
+    }
+}
+function isRecoverableStaleMutationLock(observed) {
+    const mtimeMs = Number(observed.fingerprint.mtimeNs / 1000000n);
+    if (Date.now() - mtimeMs < CONTEXT_BUILDER_STALE_MUTATION_LOCK_MS) {
+        return false;
+    }
+    return observed.metadata === "invalid"
+        || isStaleMutationLockMetadata(observed.metadata);
+}
+async function fingerprintOpenHandle(handle) {
+    return fingerprintFromStats(await handle.stat({ bigint: true }));
+}
+async function removeMutationLockIfCurrent(lockPath, expected, ops) {
+    // Node has no portable conditional-unlink primitive. Keeping the admitted
+    // descriptor open prevents inode reuse while this fingerprint recheck rejects
+    // replacements visible before unlink. Ordinary owner and recovery-gate release
+    // are safe under cooperative ownership. Stale main-lock removal holds the
+    // per-run recovery gate across this boundary; that gate is never stale-recovered.
+    const lstat = ops.lstat ?? fsLstat;
+    const rm = ops.rm ?? fsRm;
+    let current;
+    try {
+        current = await lstat(lockPath, { bigint: true });
+    }
+    catch {
+        return false;
+    }
+    if (!current.isFile()
+        || !mutationLockFingerprintsEqual(fingerprintFromStats(current), expected)) {
+        return false;
+    }
+    try {
+        await rm(lockPath, { force: true });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function parseMutationLockMetadata(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return "invalid";
+    }
+    if (parsed === null || typeof parsed !== "object") {
+        return "invalid";
+    }
+    const metadata = parsed;
+    if (typeof metadata.pid !== "number"
+        || !Number.isInteger(metadata.pid)
+        || typeof metadata.hostname !== "string"
+        || typeof metadata.created_at !== "string") {
+        return "invalid";
+    }
+    if (metadata.owner_nonce !== undefined
+        && typeof metadata.owner_nonce !== "string") {
+        return "invalid";
+    }
+    return {
+        pid: metadata.pid,
+        hostname: metadata.hostname,
+        created_at: metadata.created_at,
+        ...(metadata.owner_nonce === undefined
+            ? {}
+            : { owner_nonce: metadata.owner_nonce }),
+    };
+}
+function fingerprintFromStats(stats) {
+    return {
+        dev: stats.dev,
+        ino: stats.ino,
+        mtimeNs: stats.mtimeNs,
+        ctimeNs: stats.ctimeNs,
+        size: stats.size,
+        nlink: stats.nlink,
+    };
+}
+function sameMutationLockIncarnation(left, right) {
+    return left.dev === right.dev && left.ino === right.ino;
+}
+function mutationLockFingerprintsEqual(left, right) {
+    return sameMutationLockIncarnation(left, right)
+        && left.mtimeNs === right.mtimeNs
+        && left.ctimeNs === right.ctimeNs
+        && left.size === right.size
+        && left.nlink === right.nlink;
+}
+function isStaleMutationLockMetadata(metadata) {
+    const createdAtMs = Date.parse(metadata.created_at);
+    if (!Number.isFinite(createdAtMs)
+        || Date.now() - createdAtMs < CONTEXT_BUILDER_STALE_MUTATION_LOCK_MS) {
+        return false;
+    }
+    if (metadata.hostname !== hostname()) {
+        return false;
+    }
+    return !isProcessAlive(metadata.pid);
+}
+function isProcessAlive(pid) {
+    if (pid <= 0) {
+        return false;
+    }
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return !(isNodeError(error) && error.code === "ESRCH");
+    }
+}
+function isNodeError(error) {
+    return error instanceof Error && "code" in error;
+}
+async function delay(ms) {
+    await new Promise((resolveDelay) => setTimeout(resolveDelay, ms));
+}
+function isPathInsideDirectory(candidate, directory) {
+    const relation = relative(directory, candidate);
+    return relation !== "" && !relation.startsWith("..") && !isAbsolute(relation);
+}
+//# sourceMappingURL=mutation-lock.js.map

package/dist/context-builder/mutation-lock.js.map

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

package/dist/context-builder/review-coverage.d.ts

@@ -58,6 +58,7 @@ type ReviewSliceInput = ReviewCandidateInput & ContextReviewRange & {
     source: "focus" | "search";
     search_term_index?: number;
 };
+export declare const MAX_REGRESSION_HEAD_SLICE_TARGETS = 24;
 export declare function contextReviewCandidateId(rootIndex: number, path: string): string;
 export declare function buildContextReviewObligations(input: {
     candidates: readonly ReviewCandidateInput[];
@@ -66,6 +67,37 @@ export declare function buildContextReviewObligations(input: {
     slices: readonly ReviewSliceInput[];
     policy: ContextCoveragePolicy | undefined;
 }): ContextReviewObligationModel | undefined;
+/**
+ * Picks exact-stem regression tests that would link confidently but cannot,
+ * only because discovery produced no usable slice for them (typically a capped
+ * search on generic terms, or a search hit whose slice was pruned). Linkage
+ * needs a range, so without one the target reports a false "no confident
+ * regression link". Discovery synthesizes one bounded head slice per returned
+ * test and rebuilds the obligations.
+ *
+ * Deliberately narrower than linkage itself: exact stem only (no proximity or
+ * search-token links), the same ambiguity/generic-stem confidence rules, never
+ * for non-source targets (docs/config have no regression obligation), and
+ * skipped whenever the test is already linked to ANY target, because then
+ * linkage is already decided by real evidence. `searchRecords`/`slices` are
+ * kept in the input for call-site stability; eligibility no longer reads them.
+ */
+export declare function planRegressionHeadSliceCandidates(input: {
+    candidates: readonly (ReviewCandidateInput & {
+        line_count: number;
+    })[];
+    searchRecords: readonly ReviewSearchInput[];
+    slices: readonly ReviewCandidateInput[];
+    obligations: ContextReviewObligationModel;
+}): ReviewCandidateInput[];
+/**
+ * Docs, data, and config-format files carry no regression-test obligation, so
+ * an unlinked one reports regression "unavailable" instead of degrading the
+ * review. A denylist on purpose: unknown extensions stay source, so a new
+ * language is never silently exempted. Not `isGenericConfigPath`, which also
+ * matches source modules such as `config.ts`.
+ */
+export declare function isNonSourceReviewPath(path: string): boolean;
 export declare function resolveContextCoveragePolicy(profile: ContextBuilderIntentProfile | undefined): ContextCoveragePolicy;
 export declare function evaluateContextCoverage(input: {
     policy: ContextCoveragePolicy;

package/dist/context-builder/review-coverage.js

@@ -9,6 +9,10 @@ export const CONTEXT_EVIDENCE_CLASS_ORDER = [
 ];
 const REVIEW_LINK_MAX_DIRECTORY_DISTANCE = 2;
 const GENERIC_REVIEW_STEMS = new Set(["index", "config", "types", "utils"]);
+// Bounds the synthesized regression head slices discovery may add: at most one
+// per unlinked target and this many overall, so a wide focus directory cannot
+// turn stem linkage into bulk test ingestion.
+export const MAX_REGRESSION_HEAD_SLICE_TARGETS = 24;
 export function contextReviewCandidateId(rootIndex, path) {
     return `c:${String(rootIndex)}:${path}`;
 }
@@ -132,13 +136,14 @@ export function buildContextReviewObligations(input) {
                 : [];
             const hasAnyDistinguishingSearch = ambiguousStem &&
                 sameStemTargets.some((target) => targetDistinguishingSearchRecords(testSearch, target, sameStemTargets).length > 0);
-            const linkingSearchIndexes = requiresDistinguishingSearch
-                ? new Set(distinguishingSearchRecords.map((record) => record.search_term_index))
-                : new Set(testSearch
-                    .filter((record) => targetStem.length > 0 &&
+            const stemLinkingRecords = requiresDistinguishingSearch
+                ? []
+                : testSearch.filter((record) => targetStem.length > 0 &&
                     (record.search_term.toLowerCase().includes(targetStem) ||
-                        record.preview.toLowerCase().includes(targetStem)))
-                    .map((record) => record.search_term_index));
+                        record.preview.toLowerCase().includes(targetStem)));
+            const linkingSearchIndexes = new Set((requiresDistinguishingSearch
+                ? distinguishingSearchRecords
+                : stemLinkingRecords).map((record) => record.search_term_index));
             const confidentProximity = nearby &&
                 !hasAnyDistinguishingSearch &&
                 (!ambiguousStem ||
@@ -149,20 +154,31 @@ export function buildContextReviewObligations(input) {
                 continue;
             }
             const testSlices = slicesByCandidateForLinking.get(testId) ?? [];
-            const candidateSlices = linkingSearchIndexes.size > 0
-                ? testSlices.filter((slice) => {
-                    if (slice.search_term_index == null ||
-                        !linkingSearchIndexes.has(slice.search_term_index)) {
-                        return false;
-                    }
-                    return (!requiresDistinguishingSearch ||
-                        distinguishingSearchRecords.some((record) => record.search_term_index === slice.search_term_index &&
-                            record.line >= slice.start_line &&
-                            record.line <= slice.end_line));
-                })
-                : confidentStem || confidentProximity
-                    ? [...testSlices].sort(compareReviewSlices).slice(0, 1)
-                    : [];
+            const firstSlice = () => [...testSlices].sort(compareReviewSlices).slice(0, 1);
+            let candidateSlices;
+            if (linkingSearchIndexes.size === 0) {
+                candidateSlices = confidentStem || confidentProximity ? firstSlice() : [];
+            }
+            else if (requiresDistinguishingSearch) {
+                candidateSlices = testSlices.filter((slice) => slice.search_term_index != null &&
+                    linkingSearchIndexes.has(slice.search_term_index) &&
+                    distinguishingSearchRecords.some((record) => record.search_term_index === slice.search_term_index &&
+                        record.line >= slice.start_line &&
+                        record.line <= slice.end_line));
+            }
+            else {
+                // Overlapping search slices are merged under one retained
+                // search_term_index, so a slice that physically contains a stem hit
+                // links even when it carries a different term index. A confident
+                // exact-stem test with no containing slice still links through its
+                // first slice rather than reporting a false "no link".
+                candidateSlices = testSlices.filter((slice) => (slice.search_term_index != null &&
+                    linkingSearchIndexes.has(slice.search_term_index)) ||
+                    stemLinkingRecords.some((record) => record.line >= slice.start_line && record.line <= slice.end_line));
+                if (candidateSlices.length === 0 && confidentStem) {
+                    candidateSlices = firstSlice();
+                }
+            }
             const ranges = mergeReviewRanges(candidateSlices);
             if (ranges.length > 0) {
                 regressionLinks.push({
@@ -183,15 +199,106 @@ export function buildContextReviewObligations(input) {
             classification_reason: classificationReason,
             regression_availability: regressionLinks.length > 0
                 ? "available"
-                : rootsWithTests.has(candidate.root_index)
-                    ? "unclassifiable"
-                    : "unavailable",
+                : isNonSourceReviewPath(candidate.path)
+                    ? "unavailable"
+                    : rootsWithTests.has(candidate.root_index)
+                        ? "unclassifiable"
+                        : "unavailable",
             regression_links: regressionLinks.sort((left, right) => left.candidate_id.localeCompare(right.candidate_id)),
         };
         targetById.set(target.target_id, target);
     }
     return { targets: [...targetById.values()] };
 }
+/**
+ * Picks exact-stem regression tests that would link confidently but cannot,
+ * only because discovery produced no usable slice for them (typically a capped
+ * search on generic terms, or a search hit whose slice was pruned). Linkage
+ * needs a range, so without one the target reports a false "no confident
+ * regression link". Discovery synthesizes one bounded head slice per returned
+ * test and rebuilds the obligations.
+ *
+ * Deliberately narrower than linkage itself: exact stem only (no proximity or
+ * search-token links), the same ambiguity/generic-stem confidence rules, never
+ * for non-source targets (docs/config have no regression obligation), and
+ * skipped whenever the test is already linked to ANY target, because then
+ * linkage is already decided by real evidence. `searchRecords`/`slices` are
+ * kept in the input for call-site stability; eligibility no longer reads them.
+ */
+export function planRegressionHeadSliceCandidates(input) {
+    const linkedTestIds = new Set(input.obligations.targets.flatMap((target) => target.regression_links.map((link) => link.candidate_id)));
+    const testsByRootAndStem = new Map();
+    for (const candidate of input.candidates) {
+        if (!isTestPath(candidate.path) || candidate.line_count <= 0) {
+            continue;
+        }
+        appendIndexedCandidate(testsByRootAndStem, rootAndStemKey(candidate), candidate);
+    }
+    const targetCountByRootAndStem = new Map();
+    for (const target of input.obligations.targets) {
+        const key = rootAndStemKey(target);
+        targetCountByRootAndStem.set(key, (targetCountByRootAndStem.get(key) ?? 0) + 1);
+    }
+    const planned = [];
+    const plannedIds = new Set();
+    for (const target of [...input.obligations.targets].sort((left, right) => left.target_id.localeCompare(right.target_id))) {
+        if (planned.length >= MAX_REGRESSION_HEAD_SLICE_TARGETS) {
+            break;
+        }
+        if (target.regression_links.length > 0 || isNonSourceReviewPath(target.path)) {
+            continue;
+        }
+        const key = rootAndStemKey(target);
+        if ((targetCountByRootAndStem.get(key) ?? 0) > 1) {
+            continue;
+        }
+        const targetStem = normalizedPathStem(target.path).toLowerCase();
+        const genericStem = GENERIC_REVIEW_STEMS.has(targetStem);
+        const eligible = (testsByRootAndStem.get(key) ?? []).filter((test) => {
+            const testId = contextReviewCandidateId(test.root_index, test.path);
+            const nearby = directoryDistance(target.path, test.path) <=
+                REVIEW_LINK_MAX_DIRECTORY_DISTANCE;
+            return (!genericStem || nearby) && !linkedTestIds.has(testId);
+        });
+        const chosen = eligible.sort((left, right) => directoryDistance(target.path, left.path) -
+            directoryDistance(target.path, right.path) ||
+            left.path.localeCompare(right.path))[0];
+        if (chosen == null) {
+            continue;
+        }
+        const chosenId = contextReviewCandidateId(chosen.root_index, chosen.path);
+        if (plannedIds.has(chosenId)) {
+            continue;
+        }
+        plannedIds.add(chosenId);
+        planned.push({ root_index: chosen.root_index, path: chosen.path });
+    }
+    return planned;
+}
+const NON_SOURCE_REVIEW_EXTENSIONS = new Set([
+    ".md", ".mdx", ".markdown", ".txt", ".rst", ".adoc",
+    ".json", ".jsonc", ".yaml", ".yml", ".toml", ".ini", ".cfg", ".conf",
+    ".lock", ".csv", ".tsv", ".xml", ".po", ".pot", ".mo",
+]);
+// Exact extensionless names only: `README.md`/`LICENSE.txt` are already caught
+// by the extension denylist, and a prefix match would exempt source files such
+// as `readme_helper.ts`.
+const NON_SOURCE_REVIEW_BASENAME = /^(?:license|licence|copying|changelog|readme)$/i;
+/**
+ * Docs, data, and config-format files carry no regression-test obligation, so
+ * an unlinked one reports regression "unavailable" instead of degrading the
+ * review. A denylist on purpose: unknown extensions stay source, so a new
+ * language is never silently exempted. Not `isGenericConfigPath`, which also
+ * matches source modules such as `config.ts`.
+ */
+export function isNonSourceReviewPath(path) {
+    const basename = path.slice(path.lastIndexOf("/") + 1);
+    if (NON_SOURCE_REVIEW_BASENAME.test(basename)) {
+        return true;
+    }
+    const dot = basename.lastIndexOf(".");
+    return dot > 0 && NON_SOURCE_REVIEW_EXTENSIONS.has(basename.slice(dot).toLowerCase());
+}
 export function resolveContextCoveragePolicy(profile) {
     if (profile !== "review_deep") {
         return {