ast-mcp-server 0.9.2 → 0.11.0

package/dist/services/managed-bundle.js

@@ -0,0 +1,145 @@
+import path from "node:path";
+import { applyManagedFilePlan, canonicalizeFuturePath, captureManagedFilePreimage, captureManagedFileSnapshot, createManagedFileApplyContext, hashBytes, ManagedFileApplyError, rollbackManagedFilePlan, snapshotsEqual, verifyManagedFilePostimage, } from "./managed-file.js";
+export class ManagedBundleConflictError extends Error {
+    destination;
+    constructor(destination) {
+        super(`Managed bundle destination already exists with different content: ${destination}`);
+        this.destination = destination;
+        this.name = "ManagedBundleConflictError";
+    }
+}
+function validateRelease(release) {
+    const paths = new Set();
+    for (const file of release.files) {
+        if (file.path.includes("\\") ||
+            path.posix.isAbsolute(file.path) ||
+            path.win32.isAbsolute(file.path) ||
+            path.posix.normalize(file.path) !== file.path ||
+            file.path.startsWith("../") ||
+            file.path === ".") {
+            throw new Error(`Managed bundle contains an unsafe path: ${file.path}`);
+        }
+        if (paths.has(file.path))
+            throw new Error(`Managed bundle contains a duplicate path: ${file.path}`);
+        paths.add(file.path);
+    }
+}
+export async function planManagedBundle(options) {
+    validateRelease(options.current);
+    for (const predecessor of options.predecessors)
+        validateRelease(predecessor);
+    const signatures = [options.current, ...options.predecessors].map((release) => release.files
+        .map((file) => `${file.path}:${file.sha256}`)
+        .sort()
+        .join("\n"));
+    if (new Set(signatures).size !== signatures.length) {
+        throw new Error("Managed bundle contains a duplicate release digest.");
+    }
+    const currentPaths = new Set(options.current.files.map((file) => file.path));
+    if (options.predecessors.some((release) => release.files.some((file) => !currentPaths.has(file.path)))) {
+        throw new Error("Managed bundle predecessor contains an unmanaged current path.");
+    }
+    for (const file of options.current.files) {
+        if (hashBytes(file.content) !== file.sha256) {
+            throw new Error(`Managed bundle digest does not match source asset: ${file.path}`);
+        }
+    }
+    const canonicalRoot = path.dirname(await canonicalizeFuturePath(path.join(options.destinationRoot, ".managed-bundle-root")));
+    const destinations = await Promise.all(options.current.files.map(async (file) => ({
+        file,
+        destination: await canonicalizeFuturePath(path.join(options.destinationRoot, file.path)),
+    })));
+    for (const { destination } of destinations) {
+        const relative = path.relative(canonicalRoot, destination);
+        if (relative === "" ||
+            relative === ".." ||
+            relative.startsWith(`..${path.sep}`) ||
+            path.isAbsolute(relative)) {
+            throw new Error(`Managed bundle destination is outside the bundle root: ${destination}`);
+        }
+    }
+    if (new Set(destinations.map((entry) => entry.destination)).size !== destinations.length) {
+        throw new Error("Managed bundle contains a duplicate canonical destination.");
+    }
+    const entries = await Promise.all(destinations.map(async ({ file, destination }) => ({
+        file,
+        destination,
+        snapshot: await captureManagedFileSnapshot(destination),
+    })));
+    const exactCurrent = entries.every(({ file, snapshot }) => snapshot.exists && snapshot.sha256 === file.sha256);
+    const empty = entries.every(({ snapshot }) => !snapshot.exists);
+    const exactPredecessor = options.predecessors.some((release) => entries.every(({ file, snapshot }) => {
+        const predecessor = release.files.find((candidate) => candidate.path === file.path);
+        return predecessor === undefined
+            ? !snapshot.exists
+            : snapshot.exists && snapshot.sha256 === predecessor.sha256;
+    }));
+    if (!exactCurrent && !empty && !exactPredecessor && options.force !== true) {
+        throw new ManagedBundleConflictError(entries.find(({ snapshot }) => snapshot.exists)?.destination ?? options.destinationRoot);
+    }
+    return {
+        status: exactCurrent ? "unchanged" : empty ? "installed" : "updated",
+        files: entries.map(({ file, destination, snapshot }) => ({
+            path: destination,
+            snapshot,
+            postimage: file.content,
+            postimageSha256: file.sha256,
+            status: snapshot.exists && snapshot.sha256 === file.sha256
+                ? "unchanged"
+                : snapshot.exists
+                    ? "updated"
+                    : "installed",
+        })),
+    };
+}
+export async function applyManagedBundle(plan, onApplied, context = createManagedFileApplyContext(), hooks = {}) {
+    const preimages = new Map();
+    for (const file of plan.files) {
+        const preimage = await captureManagedFilePreimage(file.path);
+        if (!snapshotsEqual(preimage.snapshot, file.snapshot)) {
+            throw new Error(`Managed file changed after preflight: ${file.path}`);
+        }
+        preimages.set(file, preimage);
+    }
+    const authenticated = [];
+    const mutated = [];
+    let active;
+    try {
+        for (const file of plan.files) {
+            active = file;
+            for (const current of authenticated)
+                await verifyManagedFilePostimage(current, context);
+            await applyManagedFilePlan(file, context, hooks);
+            authenticated.push(file);
+            if (file.status !== "unchanged")
+                mutated.push(file);
+            await onApplied?.(file);
+            active = undefined;
+        }
+        for (const current of authenticated)
+            await verifyManagedFilePostimage(current, context);
+    }
+    catch (error) {
+        if (active !== undefined &&
+            active.status !== "unchanged" &&
+            error instanceof ManagedFileApplyError &&
+            !mutated.includes(active)) {
+            mutated.push(active);
+        }
+        const failures = [];
+        for (const file of mutated.reverse()) {
+            try {
+                await rollbackManagedFilePlan(file, preimages.get(file), context);
+            }
+            catch (rollbackError) {
+                failures.push(rollbackError);
+            }
+        }
+        if (failures.length) {
+            throw new AggregateError([error, ...failures], "Managed bundle rollback was incomplete.", {
+                cause: error,
+            });
+        }
+        throw error;
+    }
+}

package/dist/services/managed-file.js

@@ -499,6 +499,43 @@ export async function verifyManagedFilePostimage(plan, context) {
         await directory.close();
     }
 }
+export async function rollbackManagedFilePlan(plan, preimage, context) {
+    await verifyManagedFilePostimage(plan, context);
+    if (preimage.snapshot.exists) {
+        if (preimage.content === undefined) {
+            throw new Error(`Managed file rollback preimage is unavailable: ${plan.path}`);
+        }
+        const current = await captureManagedFileSnapshot(plan.path);
+        await applyManagedFilePlan({
+            path: plan.path,
+            snapshot: current,
+            postimage: preimage.content,
+            postimageSha256: preimage.snapshot.sha256,
+            status: "updated",
+        }, createManagedFileApplyContext());
+        return;
+    }
+    const directory = await openBoundDirectory(plan.snapshot.directory, false, context);
+    try {
+        const key = managedFileKey(plan);
+        let expected = context.authenticatedFiles.get(key);
+        if (expected === undefined) {
+            const current = await captureManagedFileSnapshot(plan.path);
+            if (!current.exists || current.sha256 !== plan.postimageSha256) {
+                throw new Error(`Managed installed file rollback postimage is unavailable: ${plan.path}`);
+            }
+            expected = { dev: current.dev, ino: current.ino };
+            context.authenticatedFiles.set(key, expected);
+        }
+        if ((await removePathIfOwned(directory, path.basename(plan.path), expected)) !== "removed") {
+            throw new Error(`Managed installed file could not be rolled back safely: ${plan.path}`);
+        }
+        context.authenticatedFiles.delete(key);
+    }
+    finally {
+        await directory.close();
+    }
+}
 export async function applyManagedFilePlan(plan, context = createManagedFileApplyContext(), hooks = {}) {
     if (plan.status === "unchanged") {
         await revalidateManagedFilePlan(plan);

package/dist/services/project.js

@@ -62,8 +62,7 @@ function fallbackToMemory(session, reason) {
     session.context = {
         ...session.context,
         status: transitionProjectStatus(session.context.status, {
-            type: "index_failed",
-            error: boundedReason,
+            type: "index_disabled",
         }),
         symbolIndex: new InMemorySymbolIndex(),
         symbolIndexBackend: "memory",
@@ -124,6 +123,10 @@ async function ensureSessionSymbolIndex(session, requestContext) {
             symbolIndexObservability: createInitialSymbolIndexRuntimeObservability(policy),
         };
     }
+    if (session.context.symbolIndexFallbackReason === "capability_unavailable" ||
+        (session.context.symbolIndexFallbackReason !== null && policy.backend === "memory")) {
+        return;
+    }
     if (policy.backend === "memory") {
         if (policy.mode === "enabled" || policy.mode === "canary") {
             fallbackToMemory(session, policy.reason);
@@ -234,11 +237,36 @@ function createSessionWatcher(getSession, projectRoot, directories) {
         directories,
         onChange: (files) => {
             const session = getSession();
+            const cachePath = symbolIndexCachePath(session.symbolIndexPolicy, session.context.status.project);
+            let sourceFiles = files;
+            if (cachePath) {
+                const relativeCachePath = path
+                    .relative(session.context.projectRoot, cachePath)
+                    .split(path.sep)
+                    .join("/");
+                if (!relativeCachePath.startsWith("../") && !path.isAbsolute(relativeCachePath)) {
+                    const relativeCacheDirectory = path.posix.dirname(relativeCachePath);
+                    const quarantinePrefix = `${relativeCachePath}.corrupt-`;
+                    sourceFiles = files.filter((file) => {
+                        if (relativeCacheDirectory !== "." && file === relativeCacheDirectory)
+                            return false;
+                        if (file === relativeCachePath ||
+                            file === `${relativeCachePath}-wal` ||
+                            file === `${relativeCachePath}-shm`) {
+                            return false;
+                        }
+                        return !(file.startsWith(quarantinePrefix) &&
+                            /^\d+-\d+$/u.test(file.slice(quarantinePrefix.length)));
+                    });
+                }
+            }
+            if (sourceFiles.length === 0)
+                return;
             session.context = {
                 ...session.context,
                 status: transitionProjectStatus(session.context.status, {
                     type: "source_changed",
-                    files,
+                    files: sourceFiles,
                 }),
             };
         },
@@ -299,32 +327,22 @@ function assertProjectRuntimeAdmissionOpen() {
         throw new ProjectOperationSchedulerError("SERVER_SHUTTING_DOWN");
     }
 }
-function getOrCreateSession(projectRoot, requestContext = NO_REQUEST_CONTEXT) {
-    assertProjectRuntimeAdmissionOpen();
+function createProjectSession(projectRoot, runtimePolicy, symbolIndexPolicy, requestContext, lastAccessSequence) {
     requestContext.checkpoint();
     const tsConfigFilePath = resolveTsConfigPath(projectRoot);
-    const existing = projectSessions.get(tsConfigFilePath);
-    if (existing)
-        return existing;
-    const runtimePolicy = getProjectRuntimePolicy();
-    ensureProjectSessionCapacity(runtimePolicy.maxProjectSessions);
-    const symbolIndexPolicy = readSymbolIndexPersistencePolicy();
-    requestContext.checkpoint();
     const baseContext = buildProjectContext(tsConfigFilePath);
     const context = {
         ...baseContext,
         symbolIndexObservability: createInitialSymbolIndexRuntimeObservability(symbolIndexPolicy),
     };
     const watchDirectories = selectProjectWatchDirectories(context.projectRoot, context.project.getSourceFiles().map((sourceFile) => sourceFile.getFilePath()));
-    const watcher = createSessionWatcher(() => session, context.projectRoot, watchDirectories);
+    const owner = {};
+    const watcher = createSessionWatcher(() => owner.session, context.projectRoot, watchDirectories);
     const session = {
         context,
         watcher,
         watchDirectories,
-        configDigest: (() => {
-            requestContext.checkpoint();
-            return createConfigSnapshot(tsConfigFilePath).digest;
-        })(),
+        configDigest: createConfigSnapshot(tsConfigFilePath).digest,
         fingerprints: new Map(),
         compilerStateUntrusted: false,
         scheduler: new ProjectOperationScheduler({
@@ -332,12 +350,12 @@ function getOrCreateSession(projectRoot, requestContext = NO_REQUEST_CONTEXT) {
             queueWaitTimeoutMs: runtimePolicy.queueWaitTimeoutMs,
             operationDeadlineMs: runtimePolicy.operationDeadlineMs,
         }),
-        lastAccessSequence: nextProjectSessionAccessSequence(),
+        lastAccessSequence,
         symbolIndexPolicy,
     };
-    projectSessions.set(tsConfigFilePath, session);
-    session.watcher.start();
-    if (session.watcher.snapshot().state === "ready") {
+    owner.session = session;
+    watcher.start();
+    if (watcher.snapshot().state === "ready") {
         session.context = {
             ...session.context,
             status: transitionProjectStatus(session.context.status, { type: "watcher_recovered" }),
@@ -345,6 +363,20 @@ function getOrCreateSession(projectRoot, requestContext = NO_REQUEST_CONTEXT) {
     }
     return session;
 }
+function getOrCreateSession(projectRoot, requestContext = NO_REQUEST_CONTEXT) {
+    assertProjectRuntimeAdmissionOpen();
+    requestContext.checkpoint();
+    const tsConfigFilePath = resolveTsConfigPath(projectRoot);
+    const existing = projectSessions.get(tsConfigFilePath);
+    if (existing)
+        return existing;
+    const runtimePolicy = getProjectRuntimePolicy();
+    ensureProjectSessionCapacity(runtimePolicy.maxProjectSessions);
+    const symbolIndexPolicy = readSymbolIndexPersistencePolicy();
+    const session = createProjectSession(projectRoot, runtimePolicy, symbolIndexPolicy, requestContext, nextProjectSessionAccessSequence());
+    projectSessions.set(tsConfigFilePath, session);
+    return session;
+}
 function getQueueStatus(session) {
     const snapshot = session.scheduler.snapshot();
     return projectOperationQueueToProjection(snapshot, snapshot.queue_capacity);
@@ -648,9 +680,7 @@ export async function withProjectOperation(projectRoot, operation, requestContex
         return operation(operationContext);
     }, { signal: requestContext.signal });
 }
-export async function getProjectStatus(projectRoot, requestContext = NO_REQUEST_CONTEXT) {
-    requestContext.checkpoint();
-    const session = getOrCreateSession(projectRoot, requestContext);
+function readProjectStatus(session, requestContext) {
     return runSessionWithSyncPolicy(session, async (context, operationContext) => {
         let effectiveContext = context;
         let indexedCount = 0;
@@ -678,6 +708,55 @@ export async function getProjectStatus(projectRoot, requestContext = NO_REQUEST_
         };
     }, true, requestContext);
 }
+function peekSessionStatus(session) {
+    const context = session.context;
+    return {
+        ...projectStatusToProjection(context.status),
+        index: { state: context.symbolIndexObservability.state },
+        indexed_count: 0,
+        last_successful_index_at: context.symbolIndexObservability.last_successful_persistence_at,
+        index_observability: { ...context.symbolIndexObservability },
+        operation_queue: getQueueStatus(session),
+    };
+}
+export function peekRegisteredProjectStatus(projectRoot) {
+    const session = projectSessions.get(resolveTsConfigPath(projectRoot));
+    return session ? peekSessionStatus(session) : undefined;
+}
+export async function getProjectStatus(projectRoot, requestContext = NO_REQUEST_CONTEXT) {
+    requestContext.checkpoint();
+    return readProjectStatus(getOrCreateSession(projectRoot, requestContext), requestContext);
+}
+export async function getDiagnosticProjectStatus(projectRoot, requestContext = NO_REQUEST_CONTEXT) {
+    requestContext.checkpoint();
+    const runtimePolicy = getProjectRuntimePolicy();
+    const registered = peekRegisteredProjectStatus(projectRoot);
+    if (registered)
+        return {
+            authority: "registered",
+            runtime_admission: projectRuntimeAdmission,
+            session_capacity: runtimePolicy.maxProjectSessions,
+            status: registered,
+        };
+    if (projectRuntimeAdmission === "closed")
+        return {
+            authority: "unavailable",
+            runtime_admission: "closed",
+            session_capacity: runtimePolicy.maxProjectSessions,
+        };
+    const session = createProjectSession(projectRoot, runtimePolicy, readSymbolIndexPersistencePolicy({ AST_SYMBOL_INDEX_PERSISTENCE: "disabled" }), requestContext, 0n);
+    try {
+        return {
+            authority: "isolated",
+            runtime_admission: projectRuntimeAdmission,
+            session_capacity: runtimePolicy.maxProjectSessions,
+            status: await readProjectStatus(session, requestContext),
+        };
+    }
+    finally {
+        closeProjectSession(session);
+    }
+}
 // Compatibility API for internal scripts. MCP tools should use withProject().
 export function getProject(projectRoot) {
     return createFreshProject(projectRoot).project;

package/dist/services/public-errors.js

@@ -13,6 +13,7 @@ export const PUBLIC_ERROR_CODES = Object.freeze([
     "NOT_FOUND",
     "AMBIGUOUS_TARGET",
     "STALE_WORKSPACE",
+    "INCOMPLETE_EVIDENCE",
     "MUTATION_BLOCKED",
     "CONFLICT",
     "INTERNAL_ERROR",
@@ -35,6 +36,7 @@ const FIXED_PUBLIC_MESSAGES = Object.freeze({
     NOT_FOUND: "The requested target was not found.",
     AMBIGUOUS_TARGET: "The requested target is ambiguous.",
     STALE_WORKSPACE: "The workspace changed. Retry the operation.",
+    INCOMPLETE_EVIDENCE: "The required compiler evidence is incomplete.",
     MUTATION_BLOCKED: "The mutation is blocked.",
     CONFLICT: "The operation conflicts with current state.",
     INTERNAL_ERROR: INTERNAL_ERROR_MESSAGE,
@@ -70,6 +72,10 @@ const LEGACY_MESSAGE_RULES = Object.freeze([
         code: "STALE_WORKSPACE",
         pattern: /^(?:Workspace changed\b|Project (?:configuration|source) changed during synchronization\.)/,
     },
+    {
+        code: "INCOMPLETE_EVIDENCE",
+        pattern: /^Compiler-backed impact evidence is incomplete\.$/,
+    },
     {
         code: "CONFLICT",
         pattern: /^(?:Conflict:|Plan hash mismatch\b|Persisted plan integrity mismatch\b|Operation id collision\b|Applied receipt conflict\b|Postimage recovery conflict\b|Operation target already exists\b|Another AST apply holds\b)/,
@@ -80,7 +86,7 @@ const LEGACY_MESSAGE_RULES = Object.freeze([
     },
     {
         code: "INVALID_INPUT",
-        pattern: /^(?:File path traversal is not allowed\.|Windows absolute paths are not valid on this host\.|Source file resolves outside the configured project root\.|Unsupported (?:UTF-16|non-UTF-8) source encoding\b|Persisted (?:operation|applied operation|prepared operation|project_root|original hash|updated hash|affected_files|diagnostic error delta|blocked status)\b|Scaffold file_path must\b|.{0,1024} is not a valid TypeScript identifier\.|.{0,1024} must (?:be|not)\b|.{0,1024} requires\b|.{0,1024} exceeds \d+ characters\.)/,
+        pattern: /^(?:File path traversal is not allowed\.|Windows absolute paths are not valid on this host\.|Source file resolves outside the configured project root\.|Unsupported (?:UTF-16|non-UTF-8) source encoding\b|Persisted (?:operation|applied operation|prepared operation|project_root|original hash|updated hash|affected_files|diagnostic error delta|blocked status)\b|Scaffold file_path must\b|.{0,1024} is not a valid TypeScript identifier\.|.{0,1024} must (?:be|not|contain)\b|.{0,1024} requires\b|.{0,1024} exceeds \d+ characters\.)/,
     },
 ]);
 export class PublicOperationalError extends Error {

package/dist/services/relationships.js

@@ -1159,6 +1159,110 @@ export function createCompilerRelationshipResolver(project, projectRoot, freshne
         },
     };
 }
+function callLikeExpression(node) {
+    if (Node.isCallExpression(node) || Node.isNewExpression(node))
+        return node.getExpression();
+    if (Node.isTaggedTemplateExpression(node))
+        return node.getTag();
+    return undefined;
+}
+function unwrapInvocationExpression(node) {
+    let current = node;
+    while (Node.isParenthesizedExpression(current) ||
+        Node.isNonNullExpression(current) ||
+        Node.isAsExpression(current) ||
+        Node.isTypeAssertion(current) ||
+        Node.isSatisfiesExpression(current)) {
+        current = current.getExpression();
+    }
+    return current;
+}
+function locatedCallTarget(projectRoot, declaration) {
+    if (Node.isParameterDeclaration(declaration) || Node.isMethodSignature(declaration))
+        return undefined;
+    const sourceFile = declaration.getSourceFile();
+    if (!isProjectScopedFile(projectRoot, sourceFile.getFilePath()))
+        return undefined;
+    const targetNode = Node.isConstructorDeclaration(declaration)
+        ? declaration.getFirstAncestorByKind(SyntaxKind.ClassDeclaration)
+        : declaration;
+    if (!targetNode)
+        return undefined;
+    return (collectSymbols(sourceFile).find((symbol) => symbol.node === targetNode) ??
+        containingSymbol(sourceFile, targetNode));
+}
+export function collectCompilerCallRelationships(project, projectRoot, freshness, options = {}, requestContext = NO_REQUEST_CONTEXT) {
+    const maxEdges = options.max_edges ?? 5_000;
+    const maxWorkItems = options.max_work_items ?? 100_000;
+    if (!Number.isSafeInteger(maxEdges) || maxEdges < 1) {
+        throw new Error("Compiler call max_edges must be a positive safe integer.");
+    }
+    if (!Number.isSafeInteger(maxWorkItems) || maxWorkItems < 1) {
+        throw new Error("Compiler call max_work_items must be a positive safe integer.");
+    }
+    const normalizedFreshness = normalizeFreshness(freshness);
+    const checker = project.getTypeChecker();
+    const edges = new Map();
+    let workItems = 0;
+    let workLimitReached = false;
+    for (const sourceFile of project
+        .getSourceFiles()
+        .sort((left, right) => left.getFilePath().localeCompare(right.getFilePath()))) {
+        sourceFile.forEachDescendant((node, traversal) => {
+            requestContext.checkpoint();
+            if (++workItems > maxWorkItems) {
+                workLimitReached = true;
+                traversal.stop();
+                return;
+            }
+            const expression = callLikeExpression(node);
+            if (!expression)
+                return;
+            const invoked = unwrapInvocationExpression(expression);
+            const caller = containingSymbol(sourceFile, node);
+            if (!caller)
+                return;
+            const signature = checker.getResolvedSignature(node);
+            const implicitConstructSignatures = Node.isNewExpression(node)
+                ? invoked.getType().getConstructSignatures()
+                : [];
+            if (!signature && implicitConstructSignatures.length !== 1)
+                return;
+            const signatureDeclaration = signature?.getDeclaration();
+            const declarations = declarationsForSymbol(invoked.getSymbol());
+            const targets = new Map();
+            for (const declaration of declarations.length > 0
+                ? declarations
+                : signatureDeclaration
+                    ? [signatureDeclaration]
+                    : []) {
+                const target = locatedCallTarget(projectRoot, declaration);
+                if (target)
+                    targets.set(symbolEndpoint(target, projectRoot).selector, target);
+            }
+            if (targets.size !== 1)
+                return;
+            const target = [...targets.values()][0];
+            const edge = createRelationshipEdge({
+                source: symbolEndpoint(caller, projectRoot),
+                target: symbolEndpoint(target, projectRoot),
+                kind: "call",
+                provenance: "compiler",
+                confidence: "exact",
+                resolution: "resolved",
+                freshness: normalizedFreshness,
+            });
+            edges.set(edge.relationship_id, edge);
+        });
+        if (workLimitReached)
+            break;
+    }
+    const ordered = [...edges.values()].sort((left, right) => left.relationship_id.localeCompare(right.relationship_id));
+    return Object.freeze({
+        edges: Object.freeze(ordered.slice(0, maxEdges)),
+        incomplete: workLimitReached || ordered.length > maxEdges,
+    });
+}
 export function collectCompilerRelationships(project, projectRoot, freshness, requestContext = NO_REQUEST_CONTEXT) {
     requestContext.checkpoint();
     const sourceFiles = project