texlite 0.9.0 → 0.9.2

package/dist/server/history.js

@@ -193,6 +193,23 @@ export class ProjectHistoryService {
             .get(versionId, projectId);
         return row ? parseManifest(row.manifest_json) : null;
     }
+    /**
+     * A short autosave window deliberately coalesces updates into one row. A
+     * client that has been inspecting that row must not restore newer contents
+     * it has not reviewed, so verify the manifest fingerprint immediately
+     * before a restore mutates the project.
+     */
+    assertSnapshotHash(projectId, versionId, expectedHash) {
+        if (!expectedHash)
+            return;
+        const row = this.db.prepare("SELECT manifest_json FROM project_history_versions WHERE id = ? AND project_id = ?")
+            .get(versionId, projectId);
+        if (!row)
+            throw httpError(404, "HISTORY_VERSION_NOT_FOUND");
+        if (historySnapshotHash(row.manifest_json) !== expectedHash) {
+            throw httpError(409, "HISTORY_VERSION_CHANGED");
+        }
+    }
     /**
      * Validate a single-file restore before the project enters maintenance.
      * restore() repeats the target check while the exclusive operation is held
@@ -229,7 +246,7 @@ export class ProjectHistoryService {
         const entry = this.manifest(projectId, versionId)?.files[filePath];
         if (!entry || entry.size > MAX_TEXT_PREVIEW_BYTES)
             return null;
-        return fs.readFileSync(this.objectPath(projectId, entry.digest), "utf8");
+        return this.readStoredObject(projectId, entry.digest, filePath);
     }
     restore(projectId, versionId, filePathInput) {
         const manifest = this.manifest(projectId, versionId);
@@ -245,7 +262,7 @@ export class ProjectHistoryService {
             fs.mkdirSync(path.dirname(target), { recursive: true, mode: 0o700 });
             const temporary = `${target}.history-${randomUUID()}.tmp`;
             try {
-                fs.copyFileSync(this.objectPath(projectId, entry.digest), temporary);
+                this.copyStoredObject(projectId, entry.digest, filePath, temporary);
                 fs.chmodSync(temporary, 0o600);
                 fs.renameSync(temporary, target);
             }
@@ -340,6 +357,35 @@ export class ProjectHistoryService {
             throw new Error("Invalid history object digest");
         return path.join(outputRoot(this.config, projectId), ".texlite", "history", "objects", digest.slice(0, 2), digest);
     }
+    /**
+     * A history manifest can outlive a damaged or manually removed object. Keep
+     * that operational failure distinct from an absent path in the snapshot so
+     * the UI can tell the user why viewing or restoring it is impossible.
+     */
+    readStoredObject(projectId, digest, filePath) {
+        try {
+            return fs.readFileSync(this.objectPath(projectId, digest), "utf8");
+        }
+        catch (error) {
+            this.rethrowHistoryObjectError(error, filePath);
+        }
+    }
+    copyStoredObject(projectId, digest, filePath, target) {
+        try {
+            fs.copyFileSync(this.objectPath(projectId, digest), target);
+        }
+        catch (error) {
+            this.rethrowHistoryObjectError(error, filePath);
+        }
+    }
+    rethrowHistoryObjectError(error, filePath) {
+        const code = typeof error === "object" && error !== null && "code" in error && typeof error.code === "string"
+            ? error.code : "";
+        if (code === "ENOENT" || code === "ENOTDIR" || code === "EISDIR") {
+            throw httpError(410, "HISTORY_OBJECT_MISSING", { path: filePath });
+        }
+        throw error;
+    }
     storedObjectDigests(projectId) {
         const objectsRoot = path.join(outputRoot(this.config, projectId), ".texlite", "history", "objects");
         if (!fs.existsSync(objectsRoot))
@@ -493,7 +539,7 @@ export class ProjectHistoryService {
             for (const [filePath, entry] of Object.entries(manifest.files)) {
                 const target = path.join(temporary, safeRelativePath(filePath));
                 fs.mkdirSync(path.dirname(target), { recursive: true, mode: 0o700 });
-                fs.copyFileSync(this.objectPath(projectId, entry.digest), target);
+                this.copyStoredObject(projectId, entry.digest, filePath, target);
                 fs.chmodSync(target, 0o600);
             }
             fs.renameSync(live, backup);
@@ -581,6 +627,7 @@ function versionJson(row) {
     const files = Object.values(manifest.files);
     return {
         id: row.id,
+        snapshotHash: historySnapshotHash(row.manifest_json),
         reason: row.reason,
         label: row.label,
         createdAt: row.created_at,
@@ -594,3 +641,6 @@ function versionJson(row) {
         totalSize: files.reduce((sum, file) => sum + file.size, 0)
     };
 }
+function historySnapshotHash(manifestJson) {
+    return createHash("sha256").update(manifestJson, "utf8").digest("hex");
+}

package/dist/server/i18n.js

@@ -16,6 +16,7 @@ const enMessages = {
     COMMENT_FILE_NOT_FOUND: "The file for this comment does not exist.",
     COMMENT_NOT_FOUND: "The comment does not exist.",
     COMMENT_RANGE_INVALID: "The comment source range is invalid.",
+    COMMENT_SOURCE_CHANGED: "The source changed while this comment was being prepared. Reselect the passage and try again.",
     COMMENT_UPDATE_EMPTY: "There is no comment change to save.",
     COMPILE_ARTIFACT_NOT_FOUND: "The compiled artifact does not exist.",
     COMPILE_ARTIFACTS_NOT_FOUND: "No compiled artifacts are available yet.",
@@ -45,9 +46,11 @@ const enMessages = {
     GIT_UNAVAILABLE: "Git is not available on this server.",
     HARPER_UNAVAILABLE: "Harper spelling and grammar checking is temporarily unavailable.",
     HISTORY_FILE_NOT_FOUND: "The historical file does not exist.",
+    HISTORY_OBJECT_MISSING: "A stored file for this snapshot is missing. It can no longer be viewed or restored.",
     HISTORY_FILE_PREVIEW_UNSUPPORTED: "This historical file cannot be compared as text.",
     HISTORY_TARGET_CONFLICT: "The historical version cannot be restored to the requested path.",
     HISTORY_VERSION_NOT_FOUND: "The history version does not exist.",
+    HISTORY_VERSION_CHANGED: "The selected project snapshot changed while it was being reviewed. Refresh it before restoring.",
     SELECTION_HISTORY_SOURCE_CHANGED: "The source changed while opening selection history. Wait for synchronization, then select the passage and open its history again.",
     INVALID_PATH: "The file path is invalid.",
     LAST_ADMIN: "At least one active administrator must remain.",
@@ -89,6 +92,7 @@ const enMessages = {
     SOURCE_FLUSH_FAILED: "Some source files could not be saved. The project operation was cancelled.",
     SPELLCHECK_SOURCE_INVALID: "The source to check is invalid.",
     SPELLCHECK_SOURCE_TOO_LARGE: "The source to check is too large.",
+    SPELLCHECK_SUPERSEDED: "A newer writing check replaced this request.",
     SYNCTEX_EXTERNAL_PATH: "SyncTeX returned a source path outside the project.",
     SYNCTEX_NOT_AVAILABLE: "No SyncTeX data is available. Compile the project again.",
     SYMLINK_FORBIDDEN: "Symbolic links are not allowed in project sources.",
@@ -144,6 +148,7 @@ const zhMessages = {
     COMMENT_FILE_NOT_FOUND: "批注对应的文件不存在。",
     COMMENT_NOT_FOUND: "批注不存在。",
     COMMENT_RANGE_INVALID: "批注的源码区间无效。",
+    COMMENT_SOURCE_CHANGED: "准备批注时源码已发生变化。请重新选择文本后再试。",
     COMMENT_UPDATE_EMPTY: "没有可保存的批注修改。",
     COMPILE_ARTIFACT_NOT_FOUND: "编译产物不存在。",
     COMPILE_ARTIFACTS_NOT_FOUND: "尚无可用的编译产物。",
@@ -173,9 +178,11 @@ const zhMessages = {
     GIT_UNAVAILABLE: "服务器未安装 Git。",
     HARPER_UNAVAILABLE: "Harper 拼写与语法检查暂不可用。",
     HISTORY_FILE_NOT_FOUND: "历史文件不存在。",
+    HISTORY_OBJECT_MISSING: "该快照的已存储文件缺失，无法再查看或恢复。",
     HISTORY_FILE_PREVIEW_UNSUPPORTED: "该历史文件不能作为文本比较。",
     HISTORY_TARGET_CONFLICT: "无法将历史版本恢复到所请求的路径。",
     HISTORY_VERSION_NOT_FOUND: "历史版本不存在。",
+    HISTORY_VERSION_CHANGED: "查看期间该项目快照已发生变化。请刷新后再恢复。",
     SELECTION_HISTORY_SOURCE_CHANGED: "打开选区历史时源码已发生变化。请等待同步完成，重新选择文本后再打开历史。",
     INVALID_PATH: "文件路径无效。",
     LAST_ADMIN: "系统必须保留至少一名可用管理员。",
@@ -217,6 +224,7 @@ const zhMessages = {
     SOURCE_FLUSH_FAILED: "部分源码未能保存至磁盘，项目操作已取消。",
     SPELLCHECK_SOURCE_INVALID: "待检查源码格式不正确。",
     SPELLCHECK_SOURCE_TOO_LARGE: "待检查源码过大。",
+    SPELLCHECK_SUPERSEDED: "更新的写作检查已替代此请求。",
     SYNCTEX_EXTERNAL_PATH: "SyncTeX 返回了项目外部的源码路径。",
     SYNCTEX_NOT_AVAILABLE: "尚无可用的 SyncTeX 数据，请重新编译。",
     SYMLINK_FORBIDDEN: "项目源码中不允许使用符号链接。",

package/dist/server/index.js

@@ -6,6 +6,7 @@ import { buildApp } from "./app.js";
 import { assertEnvironment } from "./environment.js";
 import { acquireDataDirectoryLock } from "./instanceLock.js";
 import { LogRotation } from "./logRotation.js";
+import { basePathHref } from "../shared/basePath.js";
 export async function startServer(configPath) {
     const config = loadConfig(configPath);
     const lock = acquireDataDirectoryLock(config);
@@ -23,11 +24,12 @@ export async function startServer(configPath) {
         app = await buildApp(config, db);
         await app.listen({ host: config.host, port: config.port });
         app.log.info(`Environment ready: ${environment.map((item) => `${item.name} ${item.version}`).join(", ")}`);
-        app.log.info(`${config.siteName} running at http://${config.host}:${config.port}`);
+        const address = `http://${config.host}:${config.port}${basePathHref(config.basePath)}`;
+        app.log.info(`${config.siteName} running at ${address}`);
         if (typeof process.send === "function")
             process.send("ready");
         return {
-            address: `http://${config.host}:${config.port}`,
+            address,
             close: async () => {
                 try {
                     if (app)

package/dist/server/instanceLock.js

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { randomUUID } from "node:crypto";
+import { basePathHref } from "../shared/basePath.js";
 export const LOCK_FILE_NAME = ".texlite.lock";
 export function isProcessAlive(pid) {
     if (!Number.isInteger(pid) || pid <= 0)
@@ -45,7 +46,8 @@ export function acquireDataDirectoryLock(config) {
         token: randomUUID(),
         configPath: config.configPath,
         host: config.host,
-        port: config.port
+        port: config.port,
+        basePath: config.basePath
     };
     for (let attempt = 0; attempt < 2; attempt += 1) {
         try {
@@ -103,7 +105,7 @@ export function acquireDataDirectoryLock(config) {
                 throw new Error(`The data directory is already locked by another TexLite instance:\n` +
                     `  - PID: ${existing.pid}\n` +
                     `  - Config: ${existing.configPath}\n` +
-                    `  - Address: http://${existing.host}:${existing.port}\n` +
+                    `  - Address: http://${existing.host}:${existing.port}${basePathHref(existing.basePath ?? "/")}\n` +
                     `  - Started: ${existing.startedAt}\n` +
                     `  - Data directory: ${config.dataDir}\n` +
                     `Do not run multiple TexLite instances with the same data directory.`);

package/dist/server/latexCompletion.js

@@ -1,11 +1,16 @@
 import fs from "node:fs";
 import { listProjectFiles, listProjectFilesAsync, resolveSourcePath } from "./files.js";
+import { commandSnippet, newCommandArguments, xparseCommandArguments, xparseCommandDefinitions } from "../shared/latexCommandSnippets.js";
+import { maskLatexComments, maskLatexLiteralContent } from "../shared/latexLiterals.js";
+import { findLatexReferenceDefinitions } from "../shared/latexReferences.js";
+import { declaredBibliographyPaths, latexDocumentDirectives } from "./latexDocumentGraph.js";
 const textExtensions = /\.(?:tex|sty|cls|def|cfg|bib|bst|fd|dtx|ins)$/i;
 const definitionExtensions = /\.(?:tex|sty|cls|def|cfg|dtx|ins)$/i;
 const maxIndexedFileBytes = 3 * 1024 * 1024;
 const maxIndexedBytes = 24 * 1024 * 1024;
 const maxIndexedFiles = 500;
 const maxCachedProjects = 64;
+const maxCachedRootScopes = 8;
 // Core LaTeX commands are kept in the completion index even when the project
 // has not loaded a package-specific definition yet.  Keep the catalogue
 // grouped by purpose so missing primitives are easy to spot and extend.
@@ -103,11 +108,11 @@ function item(label, detail, kind, source, apply) {
 }
 function createIndex() {
     return {
-        commands: new Map(), environments: new Map(), labels: new Map(), citations: new Map(), packages: new Map(), files: new Map()
+        commands: new Map(), environments: new Map(), labels: new Map(), citations: new Map(), packages: new Map(), classes: new Map(), files: new Map()
     };
 }
 function withoutComments(content) {
-    return content.split("\n").map((line) => line.replace(/(^|[^\\])%.*$/, "$1")).join("\n");
+    return maskLatexComments(maskLatexLiteralContent(content));
 }
 function commandItem(index, name, detail, source, apply) {
     if (!name.startsWith("\\"))
@@ -120,31 +125,23 @@ function commandItem(index, name, detail, source, apply) {
     if (!existing || (existing.source === "LaTeX" && source !== "LaTeX"))
         index.commands.set(name, item(name, detail, "function", source, apply));
 }
-function commandSnippet(name, argumentCount) {
-    if (argumentCount <= 0)
-        return undefined;
-    const placeholder = (index) => `\${${index}}`;
-    return name + Array.from({ length: argumentCount }, (_, index) => `{${placeholder(index + 1)}}`).join("");
-}
-function xparseArgumentCount(specification) {
-    // The common xparse argument types all consume one user supplied value.
-    // Modifiers such as `+` and argument delimiters are intentionally ignored.
-    return [...specification.matchAll(/[moOrRdDsStvb]/g)].length;
-}
 function extractSymbols(index, filePath, original) {
     const content = withoutComments(original);
     const source = filePath;
-    for (const match of content.matchAll(/\\(?:newcommand|renewcommand|providecommand|DeclareRobustCommand)\s*\*?\s*(?:\{\s*)?\\([A-Za-z@][A-Za-z@0-9:_]*)\s*(?:\})?\s*(?:\[(\d+)\])?/g)) {
-        const args = Number.parseInt(match[2] ?? "0", 10);
-        commandItem(index, `\\${match[1]}`, `Project command (${args} argument${args === 1 ? "" : "s"})`, source, commandSnippet(`\\${match[1]}`, args));
+    for (const match of content.matchAll(/\\(?:newcommand|renewcommand|providecommand|DeclareRobustCommand)\s*\*?\s*(?:\{\s*)?\\([A-Za-z@][A-Za-z@0-9:_]*)\s*(?:\})?\s*(?:\[(\d+)\])?(?:\s*(\[[^\]]*\]))?/g)) {
+        const arguments_ = newCommandArguments(Number.parseInt(match[2] ?? "0", 10), Boolean(match[3]));
+        commandItem(index, `\\${match[1]}`, `Project command (${arguments_.length} argument${arguments_.length === 1 ? "" : "s"})`, source, commandSnippet(`\\${match[1]}`, arguments_));
     }
-    for (const match of content.matchAll(/\\(?:NewDocumentCommand|RenewDocumentCommand|ProvideDocumentCommand|DeclareDocumentCommand|DeclareExpandableDocumentCommand|RenewExpandableDocumentCommand|ProvideExpandableDocumentCommand)\s*\{\s*\\([A-Za-z@][A-Za-z@0-9:_]*)\s*\}\s*\{([^}]*)\}/g)) {
-        const args = xparseArgumentCount(match[2]);
-        commandItem(index, `\\${match[1]}`, `Project command (${args} argument${args === 1 ? "" : "s"})`, source, commandSnippet(`\\${match[1]}`, args));
+    for (const definition of xparseCommandDefinitions(content)) {
+        const arguments_ = xparseCommandArguments(definition.specification);
+        const detail = arguments_
+            ? `Project command (${arguments_.length} argument${arguments_.length === 1 ? "" : "s"})`
+            : "Project command";
+        commandItem(index, `\\${definition.name}`, detail, source, arguments_ ? commandSnippet(`\\${definition.name}`, arguments_) : undefined);
     }
     for (const match of content.matchAll(/\\(?:def|gdef|edef|xdef)\s*\\([A-Za-z@][A-Za-z@0-9:_]*)((?:\s*#\d+)*)/g)) {
         const args = [...(match[2] ?? "").matchAll(/#\d+/g)].length;
-        commandItem(index, `\\${match[1]}`, "Project macro", source, commandSnippet(`\\${match[1]}`, args));
+        commandItem(index, `\\${match[1]}`, "Project macro", source, commandSnippet(`\\${match[1]}`, newCommandArguments(args, false)));
     }
     for (const match of content.matchAll(/\\DeclareMathOperator\s*\*?\s*\{?\\([A-Za-z@][A-Za-z@0-9:_]*)\}?/g))
         commandItem(index, `\\${match[1]}`, "Project math operator", source);
@@ -166,8 +163,10 @@ function extractSymbols(index, filePath, original) {
             index.environments.set(name, item(name, "Theorem environment", "keyword", source));
         }
     }
-    for (const match of content.matchAll(/\\(?:label|hypertarget)\s*\{([^}]+)\}/g)) {
-        const label = match[1].trim();
+    for (const definition of findLatexReferenceDefinitions(content, "label")) {
+        if (definition.source !== "label")
+            continue;
+        const label = definition.key;
         if (label && !index.labels.has(label))
             index.labels.set(label, item(label, "Label", "constant", source));
     }
@@ -176,29 +175,24 @@ function extractSymbols(index, filePath, original) {
         if (file)
             index.files.set(file, item(file, "Project file", "text", source));
     }
-    for (const match of content.matchAll(/\\(?:usepackage|RequirePackage|documentclass)\s*(?:\[[^]]*\])?\s*\{([^}]+)\}/g)) {
+    for (const match of content.matchAll(/\\(?:usepackage|RequirePackage|documentclass)\s*(?:\[[^\]]*\])?\s*\{([^}]+)\}/g)) {
         for (const packageName of match[1].split(",").map((value) => value.trim()).filter(Boolean)) {
-            const target = /documentclass|documentstyle/.test(match[0]) ? index.files : index.packages;
+            const target = /documentclass|documentstyle/.test(match[0]) ? index.classes : index.packages;
             if (!target.has(packageName))
-                target.set(packageName, item(packageName, target === index.files ? "Document class" : "Package", "text", source));
+                target.set(packageName, item(packageName, target === index.classes ? "Document class" : "Package", target === index.classes ? "class" : "text", source));
         }
     }
-    for (const match of content.matchAll(/\\(?:cite|citep|citet|parencite|textcite|autocite|footcite)(?:\w*)?\s*(?:\[[^]]*\])?\s*\{([^}]+)\}/g)) {
-        for (const key of match[1].split(",").map((value) => value.trim()).filter(Boolean)) {
-            if (!index.citations.has(key))
-                index.citations.set(key, item(key, "Citation key", "constant", source));
+    // `\\bibitem` suggestions are scoped by the client to the file currently
+    // open in the editor. Keep the server index reserved for standalone
+    // project BibTeX databases, so old cite uses and other source files do
+    // not leak into a citation menu.
+    if (/\.bib$/i.test(filePath)) {
+        for (const definition of findLatexReferenceDefinitions(original, "citation", true)) {
+            const key = definition.key;
+            if (key && !index.citations.has(key))
+                index.citations.set(key, item(key, "BibTeX key", "constant", source));
         }
     }
-    for (const match of content.matchAll(/\\bibitem\s*(?:\[[^]]*\])?\s*\{([^}]+)\}/g)) {
-        const key = match[1].trim();
-        if (key && !index.citations.has(key))
-            index.citations.set(key, item(key, "Bibliography key", "constant", source));
-    }
-    for (const match of content.matchAll(/@(?:\w+)\s*\{\s*([^,\s]+)\s*,/g)) {
-        const key = match[1].trim();
-        if (key && !index.citations.has(key))
-            index.citations.set(key, item(key, "BibTeX key", "constant", source));
-    }
 }
 function sorted(map) {
     return [...map.values()].sort((left, right) => left.label.localeCompare(right.label));
@@ -212,14 +206,21 @@ function standardIndex() {
     for (const packageName of standardPackages)
         index.packages.set(packageName.trim(), item(packageName.trim(), "Package", "text", "LaTeX"));
     for (const className of standardClasses)
-        index.files.set(className, item(className, "Document class", "class", "LaTeX"));
+        index.classes.set(className, item(className, "Document class", "class", "LaTeX"));
     return index;
 }
+function addProjectFile(index, filePath) {
+    index.files.set(filePath, item(filePath, "Project file", "text", "Project"));
+    if (/\.cls$/i.test(filePath)) {
+        const name = filePath.replace(/\.cls$/i, "");
+        index.classes.set(name, item(name, "Document class", "class", filePath));
+    }
+}
 export function buildLatexCompletionIndex(config, projectId) {
     const index = standardIndex();
     const allEntries = listProjectFiles(config, projectId).filter((entry) => entry.type === "file").slice(0, maxIndexedFiles);
     for (const entry of allEntries)
-        index.files.set(entry.path, item(entry.path, "Project file", "text", "Project"));
+        addProjectFile(index, entry.path);
     const entries = allEntries.filter((entry) => textExtensions.test(entry.path));
     let indexedBytes = 0;
     for (const entry of entries) {
@@ -240,33 +241,38 @@ export function buildLatexCompletionIndex(config, projectId) {
     }
     return {
         commands: sorted(index.commands), environments: sorted(index.environments), labels: sorted(index.labels),
-        citations: sorted(index.citations), packages: sorted(index.packages), files: sorted(index.files)
+        citations: sorted(index.citations), packages: sorted(index.packages), classes: sorted(index.classes), files: sorted(index.files)
     };
 }
 /** Reuses extracted symbols for files whose mtime and size did not change. */
 export class LatexCompletionService {
     config;
     cache = new Map();
+    // One project can have several selectable root documents. Keep a small
+    // result cache per project so switching roots does not accidentally reuse
+    // citation keys collected for another manuscript.
     resultCache = new Map();
     pending = new Map();
     constructor(config) {
         this.config = config;
     }
-    build(projectId) {
-        const existing = this.pending.get(projectId);
+    build(projectId, mainFile) {
+        const scope = completionScope(mainFile);
+        const pendingKey = `${projectId}\0${scope}`;
+        const existing = this.pending.get(pendingKey);
         if (existing)
             return existing;
-        const request = this.buildIncremental(projectId)
+        const request = this.buildIncremental(projectId, mainFile)
             // Do not retain a partial per-file cache when a project scan fails.
             .catch((error) => {
             this.invalidate(projectId);
             throw error;
         })
             .finally(() => {
-            if (this.pending.get(projectId) === request)
-                this.pending.delete(projectId);
+            if (this.pending.get(pendingKey) === request)
+                this.pending.delete(pendingKey);
         });
-        this.pending.set(projectId, request);
+        this.pending.set(pendingKey, request);
         return request;
     }
     invalidate(projectId) {
@@ -281,13 +287,14 @@ export class LatexCompletionService {
             cachedFiles: [...this.cache.values()].reduce((total, files) => total + files.size, 0)
         };
     }
-    async buildIncremental(projectId) {
+    async buildIncremental(projectId, mainFile) {
+        const scope = completionScope(mainFile);
         const index = standardIndex();
         const allEntries = (await listProjectFilesAsync(this.config, projectId)).filter((entry) => entry.type === "file").slice(0, maxIndexedFiles);
         const signature = allEntries.map((entry) => `${entry.path}:${entry.size ?? 0}:${entry.mtimeMs ?? 0}`).sort().join("\n");
-        const cachedResult = this.resultCache.get(projectId);
+        const cachedResult = this.resultCache.get(projectId)?.get(scope);
         if (cachedResult?.signature === signature) {
-            this.touch(projectId);
+            this.touch(projectId, scope);
             return cachedResult.index;
         }
         const projectCache = this.cache.get(projectId) ?? new Map();
@@ -297,7 +304,9 @@ export class LatexCompletionService {
             if (!livePaths.has(cachedPath))
                 projectCache.delete(cachedPath);
         for (const entry of allEntries)
-            index.files.set(entry.path, item(entry.path, "Project file", "text", "Project"));
+            addProjectFile(index, entry.path);
+        const indexedFiles = [];
+        const sourceDirectives = new Map();
         let indexedBytes = 0;
         for (const entry of allEntries.filter((candidate) => textExtensions.test(candidate.path))) {
             const size = entry.size ?? 0;
@@ -318,26 +327,68 @@ export class LatexCompletionService {
                 const fileIndex = createIndex();
                 if (definitionExtensions.test(entry.path) || /\.bib$/i.test(entry.path))
                     extractSymbols(fileIndex, entry.path, content);
-                cached = { signature, index: fileIndex };
+                cached = {
+                    signature,
+                    index: fileIndex,
+                    ...(definitionExtensions.test(entry.path) ? { directives: latexDocumentDirectives(content) } : {})
+                };
                 projectCache.set(entry.path, cached);
             }
-            mergeIndex(index, cached.index);
+            if (cached.directives)
+                sourceDirectives.set(entry.path, cached.directives);
+            indexedFiles.push({ path: entry.path, symbols: cached });
+            mergeIndex(index, cached.index, false);
+        }
+        // A project can hold templates, archives, and unrelated bibliography
+        // databases. Citation completion follows the selected root's \input graph
+        // and only includes BibTeX resources it explicitly declares. If a caller
+        // does not provide a root (the backwards-compatible service API), keep the
+        // former project-wide bibliography behavior.
+        const bibPaths = allEntries.filter((entry) => /\.bib$/i.test(entry.path)).map((entry) => entry.path);
+        const selectedBibliographies = mainFile
+            ? declaredBibliographyPaths(sourceDirectives, mainFile, bibPaths)
+            : null;
+        const allowedBibliographies = new Set(selectedBibliographies ?? bibPaths);
+        for (const { path: filePath, symbols } of indexedFiles) {
+            if (!allowedBibliographies.has(filePath))
+                continue;
+            mergeCitations(index, symbols.index);
         }
         const result = {
             commands: sorted(index.commands), environments: sorted(index.environments), labels: sorted(index.labels),
-            citations: sorted(index.citations), packages: sorted(index.packages), files: sorted(index.files)
+            citations: sorted(index.citations), packages: sorted(index.packages), classes: sorted(index.classes), files: sorted(index.files)
         };
-        this.resultCache.set(projectId, { signature, index: result });
-        this.touch(projectId);
+        const projectResults = this.resultCache.get(projectId) ?? new Map();
+        this.resultCache.set(projectId, projectResults);
+        // A root document is user-selectable, so do not let a project with many
+        // standalone examples retain an unbounded number of full completion
+        // result arrays. The per-file symbol cache remains shared by all roots.
+        if (projectResults.has(scope))
+            projectResults.delete(scope);
+        projectResults.set(scope, { signature, index: result });
+        while (projectResults.size > maxCachedRootScopes) {
+            const oldestScope = projectResults.keys().next().value;
+            if (oldestScope === undefined)
+                break;
+            projectResults.delete(oldestScope);
+        }
+        this.touch(projectId, scope);
         this.evictLeastRecentlyUsedProjects();
         return result;
     }
     /** Keep result and per-file symbol caches on the same project-level LRU. */
-    touch(projectId) {
-        const result = this.resultCache.get(projectId);
-        if (result) {
+    touch(projectId, scope) {
+        const results = this.resultCache.get(projectId);
+        if (results) {
+            if (scope !== undefined) {
+                const result = results.get(scope);
+                if (result) {
+                    results.delete(scope);
+                    results.set(scope, result);
+                }
+            }
             this.resultCache.delete(projectId);
-            this.resultCache.set(projectId, result);
+            this.resultCache.set(projectId, results);
         }
         const symbols = this.cache.get(projectId);
         if (symbols) {
@@ -355,10 +406,15 @@ export class LatexCompletionService {
         }
     }
 }
-function mergeIndex(target, source) {
+function completionScope(mainFile) {
+    return mainFile ?? "";
+}
+function mergeIndex(target, source, includeCitations) {
     for (const value of source.commands.values())
         commandItem(target, value.label, value.detail, value.source ?? "Project", value.apply);
-    for (const key of ["environments", "labels", "citations", "packages", "files"]) {
+    for (const key of ["environments", "labels", "citations", "packages", "classes", "files"]) {
+        if (key === "citations" && !includeCitations)
+            continue;
         for (const [label, value] of source[key]) {
             const existing = target[key].get(label);
             if (!existing || (existing.source === "LaTeX" && value.source !== "LaTeX"))
@@ -366,3 +422,10 @@ function mergeIndex(target, source) {
         }
     }
 }
+function mergeCitations(target, source) {
+    for (const [label, value] of source.citations) {
+        const existing = target.citations.get(label);
+        if (!existing || (existing.source === "LaTeX" && value.source !== "LaTeX"))
+            target.citations.set(label, value);
+    }
+}

package/dist/server/latexDocumentGraph.js

@@ -0,0 +1,106 @@
+import path from "node:path";
+import { findLatexBibliographyFiles, findLatexSourceIncludes } from "../shared/latexReferences.js";
+/**
+ * Extract only the small amount of source information needed for project-level
+ * document graph lookups. Keeping this separate from completion symbols means
+ * cached completion data does not need to retain whole source files.
+ */
+export function latexDocumentDirectives(source) {
+    return {
+        includes: findLatexSourceIncludes(source).map((reference) => reference.path),
+        bibliographies: findLatexBibliographyFiles(source).map((reference) => reference.path)
+    };
+}
+/** Return the selected root followed by its reachable \input-style sources. */
+export function documentSourceOrder(sources, mainFile) {
+    if (!mainFile || !sources.has(mainFile))
+        return [];
+    const result = [];
+    const queued = [mainFile];
+    const seen = new Set();
+    while (queued.length) {
+        const current = queued.shift();
+        if (!current || seen.has(current))
+            continue;
+        const directives = sources.get(current);
+        if (!directives)
+            continue;
+        seen.add(current);
+        result.push(current);
+        for (const include of directives.includes) {
+            const resolved = resolveProjectReferencePath(include, current, ".tex", sources, false);
+            if (resolved && !seen.has(resolved))
+                queued.push(resolved);
+        }
+    }
+    return result;
+}
+/**
+ * Return exactly the BibTeX resources declared by a selected root and its
+ * input graph. `null` means the selected root was unavailable to the graph
+ * scanner, so callers can retain a backwards-compatible fallback.
+ */
+export function declaredBibliographyPaths(sources, mainFile, bibPaths) {
+    if (!mainFile || !sources.has(mainFile))
+        return null;
+    const availableBibliographies = new Set(bibPaths);
+    const declared = [];
+    for (const sourcePath of documentSourceOrder(sources, mainFile)) {
+        const directives = sources.get(sourcePath);
+        if (!directives)
+            continue;
+        for (const bibliography of directives.bibliographies) {
+            const resolved = resolveProjectReferencePath(bibliography, sourcePath, ".bib", availableBibliographies, true);
+            if (resolved)
+                declared.push(resolved);
+        }
+    }
+    return uniqueProjectPaths(declared);
+}
+export function resolveProjectReferencePath(rawPath, currentPath, extension, available, rootFirst) {
+    const raw = normalizeReferenceInput(rawPath);
+    if (!raw)
+        return null;
+    const parent = path.posix.dirname(currentPath);
+    // TeX resolves relative files against the file that declared them. A raw
+    // ../ reference is valid when this final candidate remains inside the
+    // project tree (for example chapters/intro.tex -> ../refs.bib).
+    const relative = normalizeProjectPath(parent === "." ? raw : path.posix.join(parent, raw));
+    const root = normalizeProjectPath(raw);
+    const roots = rootFirst ? [root, relative] : [relative, root];
+    const candidates = roots.flatMap((candidate) => {
+        if (!candidate)
+            return [];
+        return candidate.toLowerCase().endsWith(extension)
+            ? [candidate]
+            : [candidate, candidate + extension];
+    });
+    for (const candidate of uniqueProjectPaths(candidates)) {
+        if (available.has(candidate))
+            return candidate;
+    }
+    return null;
+}
+export function uniqueProjectPaths(paths) {
+    const seen = new Set();
+    return paths.filter((entryPath) => {
+        if (!entryPath || seen.has(entryPath))
+            return false;
+        seen.add(entryPath);
+        return true;
+    });
+}
+function normalizeReferenceInput(value) {
+    const trimmed = value.trim().replaceAll("\\", "/");
+    if (!trimmed || trimmed.startsWith("/") || /^[A-Za-z]:\//.test(trimmed) || trimmed.includes("\0"))
+        return null;
+    return trimmed;
+}
+function normalizeProjectPath(value) {
+    const normalized = path.posix.normalize(value);
+    if (normalized === "." || normalized === ".." || normalized.startsWith("../"))
+        return null;
+    if (normalized.split("/").some((segment) => segment.toLowerCase() === ".git"))
+        return null;
+    return normalized;
+}