@ltm-alpha/alpha-cs 1.6.0

package/dist/directory.d.ts

@@ -0,0 +1,232 @@
+/**
+ * Directory Management
+ *
+ * Manages the .alpha-cs/ directory structure for Alpha Code Sense data.
+ */
+/**
+ * Resolve the per-project data directory name, honoring the `CODEGRAPH_DIR`
+ * environment override (default `.codegraph`). The override is a single path
+ * segment that lives in the project root.
+ *
+ * Why this exists: two environments that share one working tree must NOT share
+ * one `.alpha-cs/` — most concretely Windows-native and WSL (issue #636). The
+ * daemon lockfile (`.alpha-cs/daemon.pid`) records a platform-specific pid and
+ * socket path (a Windows named pipe vs a WSL Unix socket), and SQLite file
+ * locking across the WSL2 ↔ Windows filesystem boundary is unreliable, so two
+ * daemons sharing one index risks corruption. Setting `CODEGRAPH_DIR=.codegraph-win`
+ * on one side gives each environment its own index in the same tree.
+ *
+ * Read live (not captured at load) so it is both process-accurate and testable.
+ * An override that isn't a plain directory name — empty, containing a path
+ * separator, `.`, `..`/traversal, or absolute — is ignored (we keep the
+ * default) rather than risk writing the index outside the project or into the
+ * project root itself; we warn once to stderr so the misconfiguration is seen.
+ */
+export declare function alphaCsDirName(): string;
+/**
+ * Alpha Code Sense directory name — a load-time snapshot of {@link alphaCsDirName}.
+ * A running process's environment is fixed, so this equals the live value;
+ * it's kept as a stable string export for backward compatibility. Internal code
+ * resolves the name through {@link alphaCsDirName} / {@link getAlphaCsDir}
+ * so the `CODEGRAPH_DIR` override always applies.
+ */
+export declare const CODEGRAPH_DIR: string;
+/**
+ * Is `name` (a single path segment) a Alpha Code Sense data directory? Matches the
+ * default `.codegraph`, the active `CODEGRAPH_DIR` override, and any
+ * `.codegraph-*` sibling. File-watching and the indexer skip ALL of these, so
+ * when two environments share one working tree (Windows + WSL, issue #636)
+ * neither indexes or watches the other's index directory.
+ */
+export declare function isAlphaCsDataDir(name: string): boolean;
+/**
+ * Get the .codegraph directory path for a project
+ */
+export declare function getAlphaCsDir(projectRoot: string): string;
+/**
+ * Check if a project has been initialized with Alpha Code Sense
+ * Requires both .alpha-cs/ directory AND codegraph.db to exist
+ */
+export declare function isInitialized(projectRoot: string): boolean;
+/**
+ * Find the nearest parent directory containing .alpha-cs/
+ *
+ * Walks up from the given path to find an Alpha Code Sense-initialized project,
+ * similar to how git finds .git/ directories.
+ *
+ * @param startPath - Directory to start searching from
+ * @returns The project root containing .alpha-cs/, or null if not found
+ */
+/**
+ * Reason a directory is unsafe to use as an index ROOT, or null when it's fine.
+ *
+ * Indexing your home directory or a filesystem root drags in caches, `Library`,
+ * every other project, etc. — a multi-GB index, constant file-watcher churn, and
+ * (pre-1.0 on macOS) a file-descriptor blowup that exhausted `kern.maxfiles` and
+ * took unrelated apps / the whole machine down (#845). The classic trigger:
+ * running the installer or `codegraph init` from `$HOME`, which auto-indexes the
+ * current directory. These are never intended project roots, so the installer
+ * and `init`/`index` refuse them (overridable with `--force`).
+ *
+ * Pure-ish (reads only `os.homedir()` + realpath) so it's easy to unit-test.
+ * The returned string is a human phrase that slots into "… looks like {reason}".
+ */
+export declare function unsafeIndexRootReason(projectRoot: string): string | null;
+export declare function findNearestAlphaCsRoot(startPath: string): string | null;
+/**
+ * Indexed sub-project roots beneath `root` (bounded breadth-first scan). For
+ * the monorepo case behind #964: the index lives in a CHILD
+ * (`packages/x/.alpha-cs/`), not at the workspace root the agent's cwd points
+ * at. Descent stops at the first indexed directory on a branch (a project's
+ * own sub-dirs aren't separate projects) and is bounded by depth + count so it
+ * never turns into a full-tree crawl on a large repo.
+ */
+export declare function findIndexedSubprojectRoots(root: string, opts?: {
+    maxDepth?: number;
+    max?: number;
+}): string[];
+/** Result of {@link resolveServerRoot}. */
+export interface ServerRootResolution {
+    /** The project root to serve as the default, or null when none resolved. */
+    root: string | null;
+    /** True when `root` was adopted from the down-scan rather than the up-walk. */
+    viaSubScan: boolean;
+    /**
+     * Indexed sub-projects the down-scan saw when it ran but could NOT adopt
+     * (zero or several candidates). Empty when the up-walk resolved or the scan
+     * was skipped. Callers surface these so "no default project" errors can say
+     * what IS reachable (#1607).
+     */
+    candidates: string[];
+}
+/**
+ * Resolve the project root an MCP server should serve as its DEFAULT project
+ * (#1606). Up-walk first (`findNearestAlphaCsRoot` — the common case, and
+ * cheap). When nothing is indexed at or above `searchFrom`, run the bounded
+ * sub-project down-scan `planFrontload` already uses, behind the workspace
+ * gate above: EXACTLY ONE indexed sub-project is unambiguous and is adopted
+ * as the root; zero or several yield no root, with the candidates carried so
+ * the caller can name them instead of failing silently (#1607).
+ *
+ * `opts.subprojectScan: false` skips the down-scan entirely (the per-tool-call
+ * retry path throttles it; the up-walk always runs).
+ */
+export declare function resolveServerRoot(searchFrom: string, opts?: {
+    subprojectScan?: boolean;
+}): ServerRootResolution;
+/**
+ * Does `prompt` contain an explicit structural keyword? A keyword is a strong,
+ * self-contained signal, so the front-load hook fires on it directly — no graph
+ * check needed. (A *code-token* match, by contrast, is only a candidate the
+ * hook verifies against the graph first; see {@link extractCodeTokens}.)
+ * Coverage is multilingual (#994, #1126): the ~29 languages with the largest
+ * developer populations, across Latin, Cyrillic, Greek, CJK, Hangul, Arabic,
+ * Hebrew, Thai, and Devanagari scripts. Languages beyond the keyword table
+ * still fire through the language-agnostic code-token path.
+ */
+export declare function hasStructuralKeyword(prompt: string): boolean;
+/**
+ * Identifier-shaped tokens in `prompt` — camelCase / PascalCase-with-inner-cap,
+ * snake_case, a `name(` call, or the two sides of an `a.b` member access. Naming
+ * a symbol is a code question whatever the surrounding human language, and these
+ * shapes almost never occur in ordinary prose, so they catch the common
+ * "<symbol> 的调用链?" / "where is <symbol> 定義" prompts no keyword list would.
+ *
+ * These are *candidates*, not a verdict: a tech brand like `JavaScript` or
+ * `GitHub` is identifier-shaped too, so the front-load hook checks each token
+ * against the actual index ({@link getNodesByName}) and only fires when one is a
+ * real symbol here — otherwise a brand-name prompt would inject ~16KB of
+ * low-relevance context (issue #994 follow-up). A doc/data filename ("README.md")
+ * is excluded from the member-access form since it's a file reference, not a symbol.
+ */
+export declare function extractCodeTokens(prompt: string): string[];
+/**
+ * Cheap, graph-free candidate gate for the front-load hook: could `prompt` be a
+ * structural / flow / impact / "where-how" question worth front-loading context
+ * for? True on an explicit keyword in any covered language (#994, #1126) OR an
+ * identifier-shaped token. A keyword is sufficient to fire on its own; a
+ * token-only match is only a candidate the hook then verifies against the graph
+ * (a brand name like `JavaScript` is token-shaped but isn't a symbol). Every
+ * non-candidate prompt ("fix this typo", in any language) stays a zero-cost no-op.
+ */
+export declare function isStructuralPrompt(prompt: string): boolean;
+/**
+ * Claude Code persists `UserPromptSubmit` hook stdout above this many
+ * characters to a file and shows the model a ~2 KB preview instead (#1694).
+ * Measured on Claude Code 2.1.261; documented in the hooks reference as a
+ * 10,000-character cap on hook output strings.
+ */
+export declare const CLAUDE_CODE_INLINE_HOOK_OUTPUT_LIMIT = 10000;
+/**
+ * Max characters of explore text injected by `codegraph prompt-hook` before
+ * truncation. Must stay under {@link CLAUDE_CODE_INLINE_HOOK_OUTPUT_LIMIT} so
+ * the host delivers the payload inline. 9,000 leaves ~1k for the
+ * `<codegraph_context>` wrapper and the `projectPath` nudge lines appended
+ * after the cap is applied.
+ */
+export declare const PROMPT_HOOK_INJECTION_MAX = 9000;
+/**
+ * Cap explore text for the prompt-hook injection, preserving the existing
+ * "call codegraph_explore for the rest" notice when truncated.
+ */
+export declare function capPromptHookInjection(text: string, max?: number): string;
+/**
+ * What the front-load hook should do for a prompt issued from a directory.
+ */
+export interface FrontloadPlan {
+    /** Open + explore this project and inject its source as context. `null` when
+     *  there's no single project to front-load (none indexed, or several indexed
+     *  sub-projects with no clear match — see {@link nudgeProjects}). */
+    exploreRoot: string | null;
+    /** Indexed sub-projects to surface in a "pass `projectPath`" nudge: the rest
+     *  of a monorepo's indexed projects alongside `exploreRoot`, or — when no one
+     *  project clearly matches — the full list (with `exploreRoot` null). */
+    nudgeProjects: string[];
+    /** True when the plan came from scanning DOWN into sub-projects (cwd itself
+     *  is not under any index) — the monorepo case, where a follow-up
+     *  `codegraph_explore` needs an explicit `projectPath`. */
+    viaSubScan: boolean;
+}
+/**
+ * Decide what the front-load hook injects for a `prompt` issued from `cwd`,
+ * shaped by where the `.alpha-cs/` index(es) actually are:
+ *   1. **cwd (or an ancestor) is indexed** → front-load that project. The
+ *      normal single-project / nested-file case.
+ *   2. **cwd isn't indexed but looks like a workspace root** → the indexes live
+ *      in sub-projects (the monorepo case behind #964). One indexed
+ *      sub-project → front-load it; several → front-load the one the prompt
+ *      names (by relative path like `packages/api`, or package directory name)
+ *      and nudge about the rest; several with no match → nudge the full list so
+ *      the agent passes `projectPath`, rather than guessing wrong.
+ *   3. **nothing indexed reachable** → do nothing (the agent's own tools apply).
+ */
+export declare function planFrontload(cwd: string, prompt: string): FrontloadPlan;
+/**
+ * Create the .codegraph directory structure
+ * Note: Only throws if codegraph.db already exists, not just if .alpha-cs/ exists.
+ */
+export declare function createDirectory(projectRoot: string): void;
+/**
+ * Remove the .codegraph directory
+ */
+export declare function removeDirectory(projectRoot: string): void;
+/**
+ * Get all files in the .codegraph directory
+ */
+export declare function listDirectoryContents(projectRoot: string): string[];
+/**
+ * Get the total size of the .codegraph directory in bytes
+ */
+export declare function getDirectorySize(projectRoot: string): number;
+/**
+ * Ensure a subdirectory exists within .codegraph
+ */
+export declare function ensureSubdirectory(projectRoot: string, subdirName: string): string;
+/**
+ * Check if the .codegraph directory has valid structure
+ */
+export declare function validateDirectory(projectRoot: string): {
+    valid: boolean;
+    errors: string[];
+};
+//# sourceMappingURL=directory.d.ts.map

package/dist/directory.d.ts.map

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