kibi-cli 0.19.0 → 1.0.1

package/dist/operations/mutation/symbol-compiler-lock.js

@@ -0,0 +1,274 @@
+import { mkdirSync, readFileSync, rmdirSync, unlinkSync, writeFileSync, } from "node:fs";
+import * as path from "node:path";
+/**
+ * Workspace-scoped mutex serializing every writer of the symbol compiler
+ * surface: authored manifest edits, targeted coordinate refresh, full
+ * coordinate refresh, ordinary manifest compilation, and the RDF commit that
+ * consumes them. Atomic rename prevents torn files but not lost updates, so
+ * concurrent read-modify-write cycles must hold this lock across their whole
+ * sequence.
+ */
+const LOCK_FILE_RELATIVE = path.join(".kb", ".symbol-compiler.lock");
+const OWNER_FILE = "owner.json";
+const DEFAULT_TIMEOUT_MS = 15_000;
+const RETRY_INTERVAL_MS = 25;
+const MAX_RELEASE_FILESYSTEM_ATTEMPTS = 3;
+const NODE_FILE_SYSTEM = {
+    mkdirSync: (target, options) => {
+        mkdirSync(target, options);
+    },
+    readFileSync: (target) => readFileSync(target, "utf8"),
+    writeFileSync: (target, data, options) => {
+        writeFileSync(target, data, options);
+    },
+    unlinkSync: (target) => unlinkSync(target),
+    rmdirSync: (target) => rmdirSync(target),
+};
+// implements REQ-generated-coordinate-persistence
+export class SymbolCompilerLockError extends Error {
+    name = "SymbolCompilerLockError";
+}
+function lockPath(workspaceRoot) {
+    return path.join(workspaceRoot, LOCK_FILE_RELATIVE);
+}
+function randomToken() {
+    return `${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
+}
+function readLockRecord(content) {
+    try {
+        const parsed = JSON.parse(content);
+        if (typeof parsed !== "object" ||
+            parsed === null ||
+            typeof parsed.pid !== "number" ||
+            typeof parsed.token !== "string" ||
+            typeof parsed.acquiredAt !== "number") {
+            return null;
+        }
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+function errorDetail(error) {
+    if (!(error instanceof Error))
+        return String(error);
+    const code = error.code;
+    return code === undefined ? error.message : `${code}: ${error.message}`;
+}
+function errorCode(error) {
+    if (typeof error !== "object" || error === null)
+        return undefined;
+    return error.code;
+}
+function isTransientFilesystemError(error) {
+    if (typeof error !== "object" || error === null)
+        return false;
+    const code = error.code;
+    return (code === "EBUSY" ||
+        code === "EAGAIN" ||
+        code === "EINTR" ||
+        code === "EPERM");
+}
+function retryTransientFilesystemOperation(operation, canRetry = () => true) {
+    let attempts = 0;
+    while (attempts < MAX_RELEASE_FILESYSTEM_ATTEMPTS) {
+        attempts += 1;
+        try {
+            return { ok: true, value: operation(), attempts };
+        }
+        catch (error) {
+            if (!isTransientFilesystemError(error) ||
+                attempts === MAX_RELEASE_FILESYSTEM_ATTEMPTS ||
+                !canRetry(error)) {
+                return { ok: false, error, attempts };
+            }
+        }
+    }
+    throw new Error("unreachable retry state");
+}
+function manualCleanupGuidance(target, ownerPath) {
+    return `To clean it manually, verify no operation is active, verify ${ownerPath} and ${target}, then remove ${target}`;
+}
+function removeLockDirectory(fileSystem, target) {
+    const result = retryTransientFilesystemOperation(() => fileSystem.rmdirSync(target));
+    if (result.ok)
+        return;
+    const ownerPath = path.join(target, OWNER_FILE);
+    throw new SymbolCompilerLockError(`failed to remove symbol compiler lock directory at ${target} after ${result.attempts} attempt(s): ${errorDetail(result.error)}; lock remains fail-closed. ${manualCleanupGuidance(target, ownerPath)}`);
+}
+function removeLockOwner(fileSystem, target, ownerPath, ignoreMissing) {
+    const result = retryTransientFilesystemOperation(() => fileSystem.unlinkSync(ownerPath));
+    if (result.ok)
+        return;
+    const code = errorCode(result.error);
+    if (ignoreMissing && code === "ENOENT")
+        return;
+    throw new SymbolCompilerLockError(`failed to remove symbol compiler lock owner at ${ownerPath} after ${result.attempts} attempt(s): ${errorDetail(result.error)}; lock remains fail-closed. ${manualCleanupGuidance(target, ownerPath)}`);
+}
+function existingLockDescription(fileSystem, target, ownerPath) {
+    try {
+        const record = readLockRecord(fileSystem.readFileSync(ownerPath));
+        return record === null
+            ? "lock owner metadata is corrupt"
+            : `held by pid ${record.pid}`;
+    }
+    catch {
+        try {
+            const legacyRecord = readLockRecord(fileSystem.readFileSync(target));
+            return legacyRecord === null
+                ? "legacy or corrupt lock"
+                : `legacy lock held by pid ${legacyRecord.pid}`;
+        }
+        catch {
+            return "lock is initializing or corrupt";
+        }
+    }
+}
+async function defaultSleep(ms) {
+    await new Promise((resolvePromise) => setTimeout(resolvePromise, ms));
+}
+// implements REQ-generated-coordinate-persistence
+export function releaseSymbolCompilerLock(handle, operationFailure) {
+    if (handle === undefined)
+        return;
+    try {
+        handle.release();
+    }
+    catch (releaseError) {
+        if (operationFailure !== undefined) {
+            throw new AggregateError([operationFailure.error, releaseError], "Operation failed and symbol compiler lock release failed");
+        }
+        throw releaseError;
+    }
+}
+/**
+ * Acquire the workspace symbol compiler lock without a callback shape, for
+ * operations whose lock must span several awaits (source publication,
+ * coordinate refresh, canonical re-extraction, and the RDF commit).
+ */
+// implements REQ-generated-coordinate-persistence
+export async function acquireSymbolCompilerLock(workspaceRoot, options = {}) {
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const now = options.now ?? Date.now;
+    const sleep = options.sleep ?? defaultSleep;
+    const fileSystem = options.fileSystem ?? NODE_FILE_SYSTEM;
+    const target = lockPath(workspaceRoot);
+    const ownerPath = path.join(target, OWNER_FILE);
+    const token = randomToken();
+    const deadline = now() + timeoutMs;
+    const parentPath = path.dirname(target);
+    const parentResult = retryTransientFilesystemOperation(() => fileSystem.mkdirSync(parentPath, { recursive: true }));
+    if (!parentResult.ok) {
+        throw new SymbolCompilerLockError(`failed to create symbol compiler lock parent at ${parentPath} after ${parentResult.attempts} attempt(s): ${errorDetail(parentResult.error)}`);
+    }
+    let acquired = false;
+    let lastBlocker = "unknown";
+    while (now() < deadline) {
+        const targetResult = retryTransientFilesystemOperation(() => {
+            // Directory creation is the atomic, cross-platform lock authority.
+            fileSystem.mkdirSync(target);
+        });
+        if (targetResult.ok) {
+            acquired = true;
+            break;
+        }
+        if (errorCode(targetResult.error) !== "EEXIST") {
+            throw new SymbolCompilerLockError(`failed to acquire symbol compiler lock directory at ${target} after ${targetResult.attempts} attempt(s): ${errorDetail(targetResult.error)}`);
+        }
+        lastBlocker = existingLockDescription(fileSystem, target, ownerPath);
+        await sleep(RETRY_INTERVAL_MS);
+    }
+    if (!acquired) {
+        throw new SymbolCompilerLockError(`symbol compiler lock is ${lastBlocker}; refused after ${timeoutMs}ms to avoid a lost update`);
+    }
+    const payload = `${JSON.stringify({
+        pid: process.pid,
+        token,
+        acquiredAt: now(),
+    })}\n`;
+    try {
+        const ownerResult = retryTransientFilesystemOperation(() => fileSystem.writeFileSync(ownerPath, payload, {
+            encoding: "utf8",
+            flag: "wx",
+        }), () => {
+            try {
+                fileSystem.readFileSync(ownerPath);
+                return false;
+            }
+            catch (probeError) {
+                return errorCode(probeError) === "ENOENT";
+            }
+        });
+        if (!ownerResult.ok)
+            throw ownerResult.error;
+    }
+    catch (error) {
+        const cleanupFailures = [];
+        try {
+            removeLockOwner(fileSystem, target, ownerPath, true);
+        }
+        catch (cleanupError) {
+            cleanupFailures.push(`owner cleanup: ${errorDetail(cleanupError)}`);
+        }
+        try {
+            removeLockDirectory(fileSystem, target);
+        }
+        catch (cleanupError) {
+            cleanupFailures.push(`directory cleanup: ${errorDetail(cleanupError)}`);
+        }
+        const cleanupContext = cleanupFailures.length === 0
+            ? "lock directory cleanup completed"
+            : `lock remains fail-closed at ${target}; ${cleanupFailures.join("; ")}`;
+        throw new SymbolCompilerLockError(`failed to initialize symbol compiler lock owner at ${ownerPath}: ${errorDetail(error)}; ${cleanupContext}`);
+    }
+    let releaseState = "owned";
+    return {
+        release: () => {
+            if (releaseState === "released")
+                return;
+            if (releaseState === "owned") {
+                const readResult = retryTransientFilesystemOperation(() => fileSystem.readFileSync(ownerPath));
+                if (!readResult.ok) {
+                    throw new SymbolCompilerLockError(`failed to validate symbol compiler lock owner at ${ownerPath} after ${readResult.attempts} attempt(s): ${errorDetail(readResult.error)}; lock remains fail-closed. ${manualCleanupGuidance(target, ownerPath)}`);
+                }
+                const record = readLockRecord(readResult.value);
+                if (record === null) {
+                    throw new SymbolCompilerLockError(`refused to release symbol compiler lock with corrupt owner metadata at ${ownerPath}; lock remains fail-closed. ${manualCleanupGuidance(target, ownerPath)}`);
+                }
+                if (record.token !== token) {
+                    releaseState = "released";
+                    return;
+                }
+                removeLockOwner(fileSystem, target, ownerPath, false);
+                releaseState = "owner-removed";
+            }
+            removeLockDirectory(fileSystem, target);
+            releaseState = "released";
+        },
+    };
+}
+/**
+ * Run `operation` while holding the workspace symbol compiler lock.
+ *
+ * Atomic directory creation is the lock authority. Owner metadata is
+ * release authorization and diagnostics: every existing target, including a
+ * legacy file or a directory with missing/corrupt metadata, blocks contenders
+ * until timeout.
+ * Release failures propagate so successful work is never reported unlocked.
+ */
+// implements REQ-generated-coordinate-persistence
+export async function withSymbolCompilerLock(workspaceRoot, operation, options = {}) {
+    const handle = await acquireSymbolCompilerLock(workspaceRoot, options);
+    let operationFailure;
+    try {
+        return await operation();
+    }
+    catch (error) {
+        operationFailure = { error };
+        throw error;
+    }
+    finally {
+        releaseSymbolCompilerLock(handle, operationFailure);
+    }
+}

package/dist/operations/mutation/symbol-granularity.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"symbol-granularity.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/symbol-granularity.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0CAA0C,CAAC;AAUjF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAiEpD,wBAAsB,yBAAyB,CAC7C,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACzC,aAAa,EAAE,SAAS,iBAAiB,EAAE,EAC3C,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,IAAI,CAAC,CAqCf"}
+{"version":3,"file":"symbol-granularity.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/symbol-granularity.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0CAA0C,CAAC;AAUjF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AA+FpD,wBAAsB,yBAAyB,CAC7C,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACzC,aAAa,EAAE,SAAS,iBAAiB,EAAE,EAC3C,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,IAAI,CAAC,CAuCf"}

package/dist/operations/mutation/symbol-granularity.js

@@ -1,5 +1,5 @@
 import path from "node:path";
-import { Project, ScriptKind } from "ts-morph";
+import { Project, ScriptKind, SyntaxKind } from "ts-morph";
 import { getBehavioralSymbolNames, getNonBehavioralSymbolNames, inferSymbolRole, isAllowedGranularityReason, isTraceabilityRelationshipType, } from "../../public/symbol-granularity.js";
 function scriptKind(filePath) {
     const extension = path.extname(filePath).toLowerCase();
@@ -36,12 +36,31 @@ function candidates(filePath, content) {
         if (className)
             found.push(candidate(className, "class"));
         for (const method of cls.getMethods()) {
+            if (isPrivateClassMember(method))
+                continue;
             const name = method.getName();
             if (className)
                 found.push(candidate(`${className}.${name}`, "method"));
             bareMethods.set(name, candidate(name, "method"));
             methodCounts.set(name, (methodCounts.get(name) ?? 0) + 1);
         }
+        for (const property of cls.getProperties()) {
+            if (isPrivateClassMember(property))
+                continue;
+            const name = property.getName();
+            if (className)
+                found.push(candidate(`${className}.${name}`, "property"));
+        }
+        for (const accessor of [
+            ...cls.getGetAccessors(),
+            ...cls.getSetAccessors(),
+        ]) {
+            if (isPrivateClassMember(accessor))
+                continue;
+            const name = accessor.getName();
+            if (className)
+                found.push(candidate(`${className}.${name}`, "accessor"));
+        }
     }
     for (const [name, count] of methodCounts) {
         const method = bareMethods.get(name);
@@ -60,8 +79,19 @@ function candidates(filePath, content) {
         if (item.isExported())
             found.push(candidate(item.getName(), "enum"));
     }
+    for (const statement of source.getVariableStatements()) {
+        if (!statement.isExported())
+            continue;
+        for (const declaration of statement.getDeclarations()) {
+            found.push(candidate(declaration.getName(), "variable"));
+        }
+    }
     return found.sort((left, right) => left.name.localeCompare(right.name));
 }
+function isPrivateClassMember(member) {
+    return (member.hasModifier(SyntaxKind.PrivateKeyword) ||
+        member.getName().startsWith("#"));
+}
 function summarized(names) {
     const shown = names.slice(0, 10);
     const hidden = names.length - shown.length;
@@ -96,7 +126,8 @@ export async function validateSymbolGranularity(entity, relationships, context)
         throw error;
     }
     const available = candidates(entity.sourceFile, content);
-    if (available.some(({ name }) => name === entity.title))
+    const exact = available.find(({ name }) => name === entity.title);
+    if (exact && (exact.kind !== "variable" || entity.symbol_role === "config"))
         return;
     const behavioral = getBehavioralSymbolNames(available);
     if (behavioral.length === 0)
@@ -105,5 +136,5 @@ export async function validateSymbolGranularity(entity, relationships, context)
     const ignored = nonBehavioral.length > 0
         ? ` Non-behavioral symbols in the file were ignored for this decision: ${summarized(nonBehavioral)}.`
         : "";
-    throw new Error(`Symbol ${String(entity.id)} links ${entity.sourceFile} coarsely while granular symbols are available (behavioral only): ${summarized(behavioral)}. Move relationships to a behavioral symbol, add a manifest behavioral anchor, or set granularity_reason to config-artifact, module-level-behavior, extractor-miss, or legacy-link.${ignored}`);
+    throw new Error(`Symbol ${String(entity.id)} links ${entity.sourceFile} coarsely while granular symbols are available (behavioral only): ${summarized(behavioral)}. Move relationships to a behavioral symbol, add a manifest behavioral anchor, or set granularity_reason to config-artifact, module-level-behavior, extractor-miss, legacy-link, or test-suite.${ignored}`);
 }

package/dist/operations/mutation/symbol-refresh.d.ts

@@ -1,10 +1,27 @@
 import type { OperationContext } from "../../public/operations/runtime-types.js";
-type RefreshResult = {
+export type TargetedRefreshOutcome = "updated" | "unchanged" | "removed" | "not_found";
+export type RefreshResult = {
     readonly refreshed: boolean;
     readonly found: boolean;
+    readonly outcome?: TargetedRefreshOutcome;
+    readonly publication?: ArtifactPublicationReceipt;
+};
+export type ArtifactPublicationReceipt = {
+    readonly path: string;
+    readonly beforeHash: string | null;
+    readonly afterHash: string;
+    rollback(): void;
 };
 type RefreshImplementation = (symbolId: string, context: OperationContext) => Promise<RefreshResult>;
+/** Targeted coordinate refresh under the workspace symbol compiler lock. */
 export declare function refreshSymbolCoordinates(symbolId: string, context: OperationContext): Promise<RefreshResult>;
+/** Run one refresh step without acquiring the lock (caller holds it). */
+export declare function refreshSymbolCoordinatesUnlocked(symbolId: string, context: OperationContext): Promise<RefreshResult>;
+/**
+ * Refresh against an explicitly authored manifest path (the source-first
+ * write target), not just the canonical lane. Callers hold the compiler lock.
+ */
+export declare function refreshSymbolCoordinatesForManifest(symbolId: string, manifestAbsolutePath: string, context: OperationContext): Promise<RefreshResult>;
 export declare function setSymbolRefreshForTests(refresh: RefreshImplementation | undefined): void;
 export {};
 //# sourceMappingURL=symbol-refresh.d.ts.map

package/dist/operations/mutation/symbol-refresh.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"symbol-refresh.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/symbol-refresh.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0CAA0C,CAAC;AAUjF,KAAK,aAAa,GAAG;IAAE,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAAC;AAC9E,KAAK,qBAAqB,GAAG,CAC3B,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,gBAAgB,KACtB,OAAO,CAAC,aAAa,CAAC,CAAC;AAsH5B,wBAAsB,wBAAwB,CAC5C,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,aAAa,CAAC,CAExB;AAGD,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,qBAAqB,GAAG,SAAS,GACzC,IAAI,CAEN"}
+{"version":3,"file":"symbol-refresh.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/symbol-refresh.ts"],"names":[],"mappings":"AAuBA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0CAA0C,CAAC;AAgBjF,MAAM,MAAM,sBAAsB,GAC9B,SAAS,GACT,WAAW,GACX,SAAS,GACT,WAAW,CAAC;AAGhB,MAAM,MAAM,aAAa,GAAG;IAC1B,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,OAAO,CAAC,EAAE,sBAAsB,CAAC;IAC1C,QAAQ,CAAC,WAAW,CAAC,EAAE,0BAA0B,CAAC;CACnD,CAAC;AAGF,MAAM,MAAM,0BAA0B,GAAG;IACvC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,IAAI,IAAI,CAAC;CAClB,CAAC;AAEF,KAAK,qBAAqB,GAAG,CAC3B,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,gBAAgB,KACtB,OAAO,CAAC,aAAa,CAAC,CAAC;AAqS5B,4EAA4E;AAC5E,wBAAsB,wBAAwB,CAC5C,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,aAAa,CAAC,CASxB;AAED,yEAAyE;AAEzE,wBAAsB,gCAAgC,CACpD,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,aAAa,CAAC,CAGxB;AAED;;;GAGG;AAEH,wBAAsB,mCAAmC,CACvD,QAAQ,EAAE,MAAM,EAChB,oBAAoB,EAAE,MAAM,EAC5B,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,aAAa,CAAC,CAOxB;AAGD,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,qBAAqB,GAAG,SAAS,GACzC,IAAI,CAEN"}